CoCoWork: Instructions file for Claude Code

Global User Preferences

1. Prefer production-grade, industry-standard solutions over quick fixes or ad hoc hacks. When a widely accepted standard approach exists, use it instead of inventing a custom workaround.
2. 所有任务动手前都需要先描述步骤/方案，等用户审批后再编写代码。对于架构设计、模块搭建、技术选型等复杂任务，代码方案需额外经过一轮审批后才能写入文件。
3. If the user's request is ambiguous or missing key details, ask clarifying questions before writing code.
4. 每次开始新任务时，如果存在 docs/context.md，先读取它。
5. 每次完成有意义的项目改动后，更新 docs/context.md，同步最新的当前状态。
6. 保持 docs/context.md 精简：优先重写摘要，只保留最近迭代，并将更早内容压缩进历史摘要。
7. 记笔记 触发词：当我说「记笔记」时，把当前对话里值得沉淀的概念 / 决策 / 踩坑写进学习笔记。判断值不值得记，只看 notes/README.md 定的三条目标：复习自测 / 防遗忘 / 面试备忘 —— 即「将来我复习这个项目、或别人针对这个项目问起时用得上」，不是「离开这个项目还成立的通用道理」；沟通方式、Claude 自己的思维过程一律不记。笔记模块固定在项目根目录下的 notes/（notes/backend/<模块>/ 或 notes/frontend/<模块>/，每个模块含 notes.md + qa.md，遵循既有 frontmatter + TL;DR + 编号要点 / QA 风格），不用每次现找目录。写之前先列出「打算记哪些条目」让我审批，审批通过再落盘，不要直接写。优先追加到已有模块笔记、避免重复，不轻易新建目录。
8. 代码默认生产级最终版：每次落盘的首版即架构 / 命名 / 扩展性 / 类型 / 异常一次到位；不分"先简后繁"、不写阶段化占位（P0/P1、# TODO 这版先这样）。小步迭代是任务分段，不是代码风格分段。

代码分工（谁动文件）

所有代码都由 Claude 落盘（Write/Edit），用户不手敲。 但前后端的审批方式不同：

后端 —— 必须看代码。 落盘前把完整代码贴在对话里，按下面「给代码的方式」带用户读一遍，用户点头之后才动文件。未经审批不许落盘。

前端 —— 不看代码。 落盘前只说清「要做什么、动哪几个文件」，得到许可即可直接写，不要把前端代码贴出来（用户不 review 前端）。

单元测试例外：写完直接跑，只汇报结果，不必事先申请。

数据库迁移：禁止手写迁移文件正文 —— 先改 model，再 uv run tortoise makemigrations -n xxx 用 CLI 生成，生成结果给用户过目。

拿不准归哪类时，先问，不要默认落盘。

给代码的方式（不给孤立函数）—— 只适用于后端

给我看后端代码时，按「我要顺着你的话在文件里找到它」来写，不要甩一段孤立函数让我自己找位置：

1. 先说打开哪个文件、改哪一段（带行号锚点）。

2. 已有文件一律给「原来长这样 → 改成这样」，前后留几行原代码当路标；只有新增文件才给完整全文。

3. 说清为什么改这里，以及它跟谁有关系（谁调它、参数从哪来、改完谁受影响）。

4. 贴完代码，再用自然语言把这段逻辑讲一遍 —— 按执行顺序说清每一步在干 什么、失败会怎样、为什么是这个顺序。讲在对话里，不许塞进代码注释： 注释密度保持原样，讲述是给我看的、不是给代码看的。

   理由：我现在看不下去纯代码细节了。第 1-3 条解决「这段代码在哪」， 第 4 条解决「这段代码在干嘛」—— 后者才是我真正在审的那一份。

目的：后端代码全部由 Claude 落盘，所以「审」是我唯一一次看见它的机会 —— 我是这个项目唯一的维护者，出了 bug 得自己知道去哪儿看。审不明白等于没写。

CoCoWork — Claude Code 指南

AI Agent 管理平台（暂定方向，随开发推进持续演化）：基于 LangGraph + FastAPI + PostgreSQL（pgvector）+ Redis 构建后端，React 19 + shadcn/ui 构建前端。核心能力包括：多 Agent 编排与调度、RAG 混合检索（向量 + 全文检索 + 重排序）、Skill 技能市场、知识库管理；支持语音交互（ASR/TTS）与视觉理解多模态输入输出；提供多层 RBAC 权限管控与资源隔离。定位为可管理、可编排、可扩展的一站式 Agent 平台。