你的 CLAUDE.md 写错了：为什么指令越多，AI 越笨？

一月 29, 2026

0 条评论

本文永久链接 – https://tonybai.com/2026/01/29/write-a-good-claude-md

大家好，我是Tony Bai。

在使用 Claude Code、Cursor 或 Gemini Cli 等 AI 编程工具时，你是否遇到过这样的情况：

明明在项目根目录写了 CLAUDE.md（或 AGENTS.md），洋洋洒洒列了几十条项目规范：“使用 TypeScript”、“不要用 any”、“单元测试覆盖率要达标”……

但 AI 就像个叛逆的实习生，经常对这些指令视而不见，反复犯同样的低级错误。

是你写的 Prompt 不够严厉吗？还是模型不够聪明？

最近，HumanLayer 团队发布的一篇深度分析文章揭示了真相：

问题恰恰在于你写得太多了。

Claude Code 的内部机制会给模型注入一条系统级提醒：

“IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant.”
（重要：此上下文可能与您的任务无关。除非高度相关，否则请忽略。）

这意味着，你的 CLAUDE.md 越臃肿，包含的无关信息越多，它被系统判定为“噪音”并整体忽略的概率就越大。

今天，我们来聊聊如何用工程化的思维，重构你的 AI 上下文管理。

第一性原理：AI 是无状态的“新员工”

要写好 CLAUDE.md，首先要理解 LLM 的本质：它是无状态的（Stateless）。

每次你开启一个新的 Session，对于 AI 来说，都是入职第一天。它对你的代码库一无所知。CLAUDE.md 是它唯一的“入职手册”和“长期记忆”。

但这并不意味着你要把公司历史全塞给它。一个优秀的入职手册应该包含什么？

HumanLayer 的文章中总结了 “The Trinity”（三要素）：

WHAT（地图）： 技术栈是什么？项目结构是怎样的？（特别是 Monorepo，告诉它哪里是 App，哪里是 Lib）。
WHY（目标）： 这个项目的核心价值是什么？核心模块的职责边界在哪里？
HOW（工具）： 怎么构建？怎么跑测试？用 npm 还是 bun？

除此之外的任何废话，都是在消耗 AI 宝贵的注意力。

最佳实践一：少即是多 (Less is More)

研究表明，即便是最前沿的推理模型（Thinking Models），能稳定遵循的指令上限也就在 150-200 条左右。而小模型（如 Haiku 或 GPT-4o-mini）的遵循能力随着指令数量增加呈指数级下降。

更糟糕的是 “位置偏见（Position Bias）”。LLM 高度关注开头（System Prompt）和结尾（最新对话），夹在中间的 CLAUDE.md 如果过长，极易沦为“被遗忘的中间层”。

因此，请遵循以下黄金法则：

不要试图涵盖所有边缘情况。
将根目录的 CLAUDE.md 控制在 300 行以内，HumanLayer 的生产环境甚至控制在 60 行以内。
每一行都要问自己：“如果没有这句话，AI 真的干不了活吗？”

最佳实践二：渐进式披露 (Progressive Disclosure)

如果你确实有很多规范要交代，怎么办？

答案是：不要把所有鸡蛋放在一个篮子里。

想象一下，HR 会在入职第一天把 500 页的《数据库运维手册》扔给一个前端开发吗？不会。

你需要构建一套“渐进式”的文档体系：

1. 建立文档库：

在项目中创建一个 .ai/docs/ 目录，存放特定领域的指南：

testing.md：详细的测试编写与运行指南。
database.md：Schema 定义与迁移规范。
architecture.md：核心架构图与数据流。

2. 建立索引：

在主 CLAUDE.md 中，只保留“触发器”：

“编写或运行测试前，请务必阅读 .ai/docs/testing.md。”

“涉及数据库变更时，请参考 .ai/docs/database.md。”

这样，当 AI 只是在写一个前端组件时，它的上下文窗口就不会被无关的后端 Schema 污染。保持注意力的纯净，是提升 AI 智商的关键。

最佳实践三：别把 AI 当 Linter 用

这是最常见的资源浪费：在 CLAUDE.md 里写了 50 行关于代码风格的规定——“缩进用 2 个空格”、“花括号不换行”、“变量名用驼峰”……

请记住：LLM 是昂贵的推理引擎，不是廉价的格式化工具。

让 AI 去关注缩进，就像让法拉利去送外卖，既贵又慢。而且，AI 即使知道规则，也经常因为概率性生成而“手滑”。

正确的解法是：Tooling > Prompting。

配置工具： 使用 Prettier, Biome, ESLint, govet 等确定性工具来处理格式。
设置 Hook： 配置 Claude Code 的 Stop Hook。如果 AI 生成的代码格式不对，让 Linter 报错，把错误信息喂回给 AI。
- AI: (生成代码)
- System: “Lint Error: Missing semicolon.”
- AI: “Ah, fixing it.”

AI 极其擅长修复报错，但并不擅长凭空遵守“隐形的规则”。