CLAUDE.md 作为代码库 API：为什么你的 Agent 指令文件是你写过的最具杠杆效应的文档

大多数团队对待 CLAUDE.md 的方式和对待 README 一样：写一次，然后忘掉它的存在，最后疑惑为什么什么都不好使。但 CLAUDE.md 不是文档。它是你的代码库和每一个接触它的 AI agent 之间的 API 契约。写对了，每一次 AI 辅助的提交都遵循你的架构。写错了——或者更糟，让它腐化——你实际上是在每次会话中让你的 agent 变得更笨。

AGENTbench 研究在 12 个代码库中测试了 138 个真实编码任务，发现自动生成的上下文文件实际上降低了 agent 的成功率，甚至不如完全没有上下文文件。三个月积累的指令，其中一半描述的代码库已经面目全非，不会指导 agent——它们会误导 agent。

指令预算比你想象的要小

每个 AI 编程 agent 都有有限的指令遵循能力。对前沿 LLM 的研究表明，它们大约能可靠地遵循 150-200 条指令并保持合理的一致性。这听起来很慷慨，直到你意识到仅 Claude Code 的系统提示就消耗了大约 50 个这样的槽位。Cursor 的 agent 基础设施同样会吃掉一部分预算。你的 CLAUDE.md 只能用剩下的部分。

这创造了一个大多数团队忽视的硬约束。一个 500 行的 CLAUDE.md，塞满了风格指南、架构决策、调试技巧和团队惯例，不是全面——而是噪音。LLM 表现出"中间遗失"效应，长文档中间部分的指令会被系统性地忽略。随着指令数量增加，所有指令的遵循质量都会均匀下降，而不仅仅是新增的指令。

实际上限大约是 300 行，而将文件保持在 60 行以下的团队报告了最一致的 agent 行为。60 行文件和 500 行文件的区别不是后者覆盖更多——而是后者什么都不能可靠覆盖。

什么该放在文件里（什么不该）

最高杠杆的内容遵循严格的优先顺序：

构建和测试命令排在第一位。这是你能放在上下文文件中最有价值的东西。不是"运行测试"而是 yarn test --coverage 或 make test-api。一个知道确切调用命令的 agent 可以验证自己的工作。一个被告知"运行测试"的 agent 会猜，而且会猜错。

技术栈及版本紧随其后。不是"我们用 React"而是"Next.js 15（App Router），TypeScript 5.7（严格模式），PostgreSQL 16 配合 Drizzle ORM"。具体性防止 agent 为错误的框架版本生成代码——当 agent 默认使用训练数据中最普遍的版本时，这是一个令人惊讶的常见失败模式。

架构约束很重要，但只有非显而易见的那些。如果你的项目使用带有薄控制器的仓储模式，说出来。如果业务逻辑绝不能存在于路由处理器中，说出来。agent 可以通过阅读代码推断很多，但它无法推断关于东西应该放在哪里的组织决策。

不该放的东西：

• 风格规则。 永远不要让 LLM 做 linter 的工作。如果你在意 4 空格缩进或 React 组件中不用箭头函数，配置 ESLint 和 Prettier。用宝贵的指令预算来处理格式化是浪费。
• agent 已经正确执行的事情。 如果 Claude 不用告知就已经在写 TypeScript，这条指令就是死重。把它转化为钩子或删除它。
• 特定任务的指导。 关于特定功能或迁移的指令属于提示词，而不是永久上下文文件。每次会话都会为 CLAUDE.md 中的每一行支付 token 成本，无论它是否相关。

没人用的文件层级

大多数开发者创建一个单独的根级 CLAUDE.md 就完事了。但每个主要的 AI 编程工具都支持从宽泛到具体加载的层级结构，更具体的指令覆盖更宽泛的指令。

加载顺序通常是：先企业策略，然后用户级偏好，然后项目根目录，然后子目录级文件。这意味着你可以有一个覆盖项目范围惯例的根 CLAUDE.md，和一个 src/api/CLAUDE.md 来添加 API 特定约束——比如"所有端点必须用 Zod schema 验证输入"——而不会让根文件膨胀。

这个层级优雅地解决了 monorepo 问题。共享服务目录可以强制执行与前端应用目录不同的模式，全部在同一个仓库内。约束预算在本地而非全局消耗。

新兴的跨工具架构看起来像这样：

AGENTS.md          (通用基础——被 60,000+ 项目支持)
├── CLAUDE.md      (仅 Claude 特定的补充)
├── copilot-instructions.md  (Copilot 特定)
└── .cursor/rules/ (Cursor 范围规则)

加载中…