新项目刚起步，我兴冲冲地配好了 CLAUDE.md。自以为把 22 个微服务的职责、全量技术栈、甚至公共工具类的用法都塞进去是「专业」，结果刚演示完，就被领导一句话怼了回来：
「你这是在写代码，还是在给 AI 编项目年鉴？」
当时我还没反应过来，觉得文档写得细难道不是好事吗？直到我发现 Agent 每次进任务都要先对着那一坨上下文「加载」半天，我才意识到，我亲手交了一份高昂的「上下文税」。
痛点 1：启动成本高得离谱
很多人没意识到，CLAUDE.md 和 AGENTS.md 属于「启动级指令」。
你把它当成百科全书，AI 就得把它当成必修课。哪怕我只是想改一个简单的 DTO 字段，Agent 也要先吞掉几千 Token 的背景信息。这就好比你让厨师炒个土豆丝，结果非要他在开火前先把《中国烹饪史》背一遍。
这不仅是浪费 Token（那都是真金白银），更严重的是读取效率的断崖式下跌。Agent 在进入真正核心的代码逻辑前，已经在这个「年鉴」里转晕了。
痛点 2：真正重要的规则被「稀释」了
上下文是有容量的。当你往里塞了太多「微服务清单」「技术栈说明」这种背景资料时，真正救命的规则就被淹没了。
比如我写了「严禁跨服务直接依赖实现类」，但因为前后被几百行工具类 Demo 包围，Agent 很容易在复杂的调用链里「忘掉」这条铁律，最后写出一堆违背架构边界的代码。
不是 AI 不聪明，是你给的干扰项太多了。
解决思路：从「项目年鉴」回归「启动索引」
发现问题后，我反思了文档的治理逻辑。翻了翻 Anthropic 和 OpenAI 的官方文档，思路其实非常清晰：
- Claude Code 官方建议：
CLAUDE.md应该具体、简洁，最好控制在 200 行以内。支持 imports 和分层加载。 - Codex 官方建议：
AGENTS.md是分层读取的，越靠近当前目录的规则越有效。根文件应该只放全局硬约束。
核心逻辑就一句话：根指令应该是索引，不应该是百科全书。
我的方案：三步实现指令脱脂
我花了一个下午，把项目里的指令全拆了：
1. 根文件只留「高杠杆」信息
根目录的 CLAUDE.md 只保留：全局硬约束、默认分析顺序、验证要求、以及外部文档的入口。凡是能外置的内容，通通滚出根目录。
2. 详细内容统一外置到 docs/
把「架构总览」「微服务百科」「公共工具手册」全部拆成独立的 Markdown 放在 docs/ 下。Agent 需要时，通过根文件的索引引导它去读。比如：「先读 docs/project-map.md 缩小范围，再进具体模块」。
3. 局部规则局部生效
特定模块的规则（比如 Order 服务的特殊校验），直接丢在 order-service/CLAUDE.md 里。不要让全项目的人为了某个模块的细节去陪跑上下文。
结论
把所有说明都堆进根文件，不叫体系化，那叫懒政。
真正的高手，是让 Agent 每次启动只吃最轻量的上下文，却能精准找到最重的逻辑。
以后配项目指令，先问自己一句：这篇文章，是不是又在写年鉴了？
更多深度内容与完整文章，欢迎关注我的微信公众号：SamLai 效率研习社
主要分享：
AI 编程与开发效率
技术趋势与工程思考
实用工具与工作流
