直觉告诉我们：Agent 需要理解你的项目，就把所有东西都塞进上下文文件。ETH Zurich 研究者今年测试了这个假设，发现它错了——自动生成的上下文文件让任务成功率下降 3%，Token 成本增加 20%。即使是人工精心编写的文件，也只带来 4% 的边际提升。Agent 读到了这些内容，然后变差了。

大多数团队还在按照"塞满它"的假设运作。

指令预算有限

前沿模型的可靠指令遵循上限在 150-200 条离散指令之间。这个天花板不随上下文长度扩展；更大上下文窗口的模型，并不会拥有更大比例的指令预算。超过约 200 条指令后，遵循质量就会下降——即使模型可以完整访问上下文内容。

写 CLAUDE.md 时的假设是你从完整的指令预算开始。事实上不是。Claude Code 自己的 system prompt 在你的文件介入之前已经消耗了大约 50 个指令槽。你的 CLAUDE.md 要和上下文中的代码、打开的文件、积累的对话历史竞争剩余空间。你添加的每条指令都在挤掉其他东西。

指令预算不奖励详尽，惩罚详尽

300 行的文件在同一个代码库上往往比 60 行表现更差。ETH Zurich 数据量化了这个方向：任务完成率下降 3%，Token 成本增加 20%。

大多数开发者以为臃肿的上下文文件只是效率低下，Agent 会绕过噪声找到有用的部分。实际上更烦人：指令遵循质量全面下降。你添加了 50 行明显的目录结构说明，Agent 开始忘记你的"禁止使用 console.log"约束——不是因为约束被埋没了，而是因为 LLM 在整个上下文窗口上分配注意力：更长的文件同等稀释了每条指令的信号，有价值的约束和噪声以同样速度失去保真度。

还有一个研究称为"过于顺从"的第二种失败模式：Agent 不会忽略不必要的指令，它们严格遵循这些指令，以至于让任务变得更难解决。一个过时的文件路径不只是令人困惑。如果你的 CLAUDE.md 说"认证逻辑在 src/auth/handlers.ts"，而那个文件三个月前被重命名了，Agent 每次都会自信地在错误的地方查找。

Vital Few 原则

想象你给一个干了 15 年的能干承包商做简报。你不会解释什么是 React 组件。你告诉他们的是：在这个代码库里，feature flags 要通过配置服务而不是硬编码——因为如果不告诉他们，他们就会搞错。这就是 Vital Few 测试：只写 Agent 无法从代码推断的内容。

值得写的内容：

  • 项目描述。告诉 Agent 产品为谁服务，会影响它命名和推荐 API 的方式。
  • 带版本的技术栈。不带版本，Agent 会幻觉出已变更的 API 方法。ETH Zurich 论文发现：指定具体工具名称（如 uv 而非 pip）而非通用类别，使 Agent 正确使用工具的概率提升 160 倍（从每次 0.01 次用到 1.6 次）。
  • 精确的 CLI 命令。不是"运行测试"，而是"npm test -- --runInBand"（如果有共享数据库状态）或"pytest tests/ -x -v"。
  • Linter 抓不到的约定。比如"feature flags 必须通过配置服务路由"。
  • 硬约束。两三条"禁止"声明：永不提交 secrets，永不在生产代码中使用 console.log，永不从前端直接调用支付 API。

不值得写的内容：

  • 目录树。这就像给有钥匙卡的人打印办公室地图。
  • Linter 可执行的规则。
  • 模糊的 persona。"高级工程师"不会让 Agent 的概率分布产生可验证的偏移；"优先使用命名导出而非默认导出"可以让 Agent 验证自己的输出。
  • 完整 API 文档。只写 URL，不粘贴内容。

写完每条纠正之后

一个习惯：每次纠正 Agent 之后，添加一条能够防止同样错误的指令。直接告诉它："更新 CLAUDE.md，这样你就不会再犯这个错误。"四个月后，文件比开始时更短了。精确的指令挤掉了占位符。

CLAUDE.md 的三层架构

Claude Code 从三个位置读取，按层级叠加：

  1. 全局（~/.claude/CLAUDE.md）：个人偏好，跨所有项目。保持在 15 行以下。
  2. 项目（./CLAUDE.md）：团队共享上下文。检查到 git 里。Vital Few 的所有内容放在这里。
  3. 本地（./CLAUDE.local.md）：gitignore，不提交到仓库。本地 MCP 配置、sandbox URL、开发环境变量在这里。

层级是累加的，不是替代的。

超过 80 行就用 .claude/rules/

当根文件超过 400 行时，可以用 docs/db-conventions.md 这样的路径引用保持根文件简短，同时在 Agent 需要时提供深度。更进一步：用 .claude/rules/ 路径级规则文件，用 YAML frontmatter 指定触发的文件路径。数据库层、API、前端各自一个规则文件，根文件保持在 80 行以下。

Agent 自己的记忆：MEMORY.md

Claude Code 现在维护一个与 CLAUDE.md 分开的 auto-memory 文件（MEMORY.md）。CLAUDE.md 是你为 Agent 写的，MEMORY.md 是 Agent 为自己写的：从跨 session 的纠正中学习的模式和发现，上限 200 行。两者互补：CLAUDE.md 携带你的显式指令，MEMORY.md 携带 Agent 从你的纠正中学到的隐式经验。

检查工具

  • /init（内置）：如果项目已有 CLAUDE.md，它会建议改进而不是覆盖。
  • claude-md-linter（开源）：针对 Agent 配置文件独立 linter，基于官方规范、学术研究和真实故障模式验证 385 条规则。覆盖 CLAUDE.md、AGENTS.md、skill 文件、MCP 配置。
  • /claude-md-improver（Anthropic 官方插件）：五阶段审计——发现、质量评估、带具体 diff 的报告、定向更新、保留文件结构的应用。

一个判断标准：如果一个高级工程师加入你的团队，他能从代码里读到这个，还是必须问人？如果必须问人，就该写进 CLAUDE.md。