一份好的 CLAUDE.md AGENTS.md，不应该重新介绍整个产品
A good CLAUDE.md shouldn't re-explain the product刚开始使用 Claude Code 时，很容易不断往 CLAUDE.md 里加内容。
Agent 犯一次错，就补一条。
新做一个功能，就把背景复制进去。
架构调整了，再贴一段最新说明。
最后文件越来越长，看起来很完整，Agent 的表现却不一定更稳定。
原因是：
CLAUDE.md 的职责不是保存所有项目知识，而是告诉 Agent 在这个 repo 里应该怎样工作。
它最应该解决什么问题？
一份有用的 Agent instructions，主要解决四件事。
1. 去哪里找正确事实
例如：
- Product definition: docs/PRODUCT.md
- Current feature specs: docs/specs/
- Architecture: docs/ARCHITECTURE.md
- Design rules: docs/DESIGN.md
- Important decisions: docs/adr/
这比把这些文件的内容重新复制一遍更可靠。
因为一旦产品发生变化，只需要维护 canonical source，不需要同时更新五份重复说明。
2. 在这个 repo 里怎样工作
例如：
- 使用什么 package manager
- 常用开发、测试和 lint 命令
- 新文件应该放在哪里
- 哪些模块可以依赖哪些模块
- 数据库 schema 如何变更
- 环境变量如何管理
- 生成文件能不能手动修改
这些内容应该具体到可以执行。
无效规则：
Always write clean, maintainable code.
更有效的规则：
Before completing a task, run: pnpm lint pnpm typecheck pnpm test Do not mark the task complete if any command fails.
3. 哪些事情不能擅自决定
coding agent 经常不是“做不到”，而是发挥过头。
可以明确：
- 不擅自改变产品 scope
- 不重命名核心业务概念
- 不为修复局部问题重构无关模块
- 不删除看似未使用但用途不明的文件
- 不自行修改全局设计 tokens
- 不绕过类型、测试或权限检查
- 不在没有批准时增加新的依赖
边界应该围绕真实风险，而不是把所有可能性都写一遍。
4. 哪些错误已经反复发生
这是最值得持续补充的部分。
例如 Agent 曾经多次：
- 把临时脚本放进项目根目录
- 创建重复组件
- 用 mock data 覆盖真实数据
- 修一个页面时修改全局 CSS
- 更新代码却忘记同步 schema
- 根据文件名猜功能，而不读相关 spec
反复出现的错误，才值得成为长期规则。
一次性的意外，不一定需要永久写进 instructions。
哪些内容不应该放进去？
大段产品背景
产品服务谁、解决什么问题、核心流程是什么，应放在 PRODUCT.md。
Agent instructions 只需要说明什么时候应读取它。
当前功能的详细需求
当前任务应该有独立 spec。
否则功能做完后，这些内容会继续留在 CLAUDE.md 中，成为过期上下文。
所有历史决策
历史原因应放在 decision log 或 ADR。
CLAUDE.md 只保留当前仍需遵守的结论。
复制其他文档
同一条规则维护两份，迟早会不一致。
无法执行的要求
例如：
Make the best possible UX. Think carefully. Write production-quality code.
这些话没有检查标准，也无法解决 repo-specific 问题。
CLAUDE.md 和 AGENTS.md 怎样分工？
同时使用多个 coding agent 时，我更倾向于：
选择某一个保存跨工具通用的工作规则：
- repo 结构
- canonical sources
- 测试要求
- 修改边界
- 通用开发约定
另一个只补充它特有的行为或使用方式。
例如：
- 优先读取哪些目录
- 特定工具调用习惯
- 已知的 Claude/Codex-specific 问题
不要在两个文件里分别维护两套产品事实。
否则 Claude Code、Codex 和人类开发者看到的会是不同版本的项目。
一个够用的结构
# Agent Instructions
## 1. Canonical Sources
## 2. Repository Structure
## 3. Development Commands
## 4. Implementation Rules
## 5. Validation Requirements
## 6. Do Not
## 7. Known Failure Modes
每一条都应该直接影响行为。
例如：
Before editing a feature:
1. Read the relevant spec in docs/specs/.
2. Check related decisions in docs/adr/.
3. Reuse existing components before creating new ones.
4. Run lint, typecheck and relevant tests.
5. Update documentation only when the canonical fact changes.
不要追求“越短越好”
CLAUDE.md 太长会带来噪音，但太短也可能没有约束力。
真正的标准是：
这条信息是否会帮助 Agent 做出不同的决定？
会，就保留。
不会，就删除或移到更合适的文档。
我现在会把 CLAUDE.md 看成一张工作地图，而不是产品百科。
它不需要告诉 Agent 所有答案。
它需要告诉 Agent：
- 正确答案在哪里
- 哪些规则必须遵守
- 哪些事情不能猜
- 完成任务前怎样证明自己没有搞坏项目