Writing a good CLAUDE.md

本文深入探讨了如何为 AI 编码助手（如 Claude Code、Cursor 等）编写高质量的 CLAUDE.md（或其开源等价物 AGENTS.md）配置文件。核心观点在于，大语言模型（LLM）本质上是无状态的，它们在每次对话开始时对代码库一无所知，而 CLAUDE.md 是唯一会被默认注入到每一次对话中的文件。因此，该文件承担着“入职培训”的关键角色，必须清晰地告知 AI 项目的背景（WHAT）、目的（WHY）以及协作方式（HOW）。

文章强调了“少即是多”的原则。研究表明，前沿 LLM 只能稳定遵循约 150-200 条指令，且随着指令增加，遵循质量会统一下降。为了防止 Claude 忽略指令，CLAUDE.md 应保持精简（建议少于 300 行，甚至少于 60 行），且内容必须具有普适性。

为了解决复杂项目信息量大的问题，作者提出了“渐进式披露”策略，即在 CLAUDE.md 中仅保留核心框架和指向其他详细文档（如测试指南、架构说明）的指针，让 AI 根据任务需要自行读取。此外，文章警告不要将 CLAUDE.md 用作代码检查工具（Linter），而应利用确定性的自动化工具处理格式问题。最后，作者指出 CLAUDE.md 是整个工作流中杠杆率最高的部分，绝不应依赖自动生成，而需开发者精心打磨，以确保 AI 输出的高质量。

主题：CLAUDE.md 的核心角色与“入职”逻辑

大语言模型（LLM）在推理时其权重是固定的，这意味着它们是无状态的函数，不会随着时间的推移自发学习你的代码库。在每一轮新的对话开始时，AI 助手对你的项目处于“零认知”状态。虽然像 Claude Code 这样的工具会尝试管理内存，但 CLAUDE.md 是唯一一个在每次会话中都会被强制推送到 AI 上下文中的文件。这意味着，如果你不通过这个文件告诉 AI 关键信息，它就无法理解你的代码逻辑。

一个优秀的 CLAUDE.md 应该完成 AI 的“入职培训”，具体涵盖三个维度：

WHAT（是什么）：向 AI 介绍技术栈、项目结构和代码地图。这在单体大仓库（Monorepo）中尤为重要，你需要明确哪些是应用，哪些是共享包，以及它们各自的用途，以便 AI 知道去哪里寻找资源。
WHY（为什么）：阐述项目的核心目的。不同部分的功能是什么？为什么要这样设计？理解了“为什么”，AI 才能在修改代码时保持逻辑一致性。
HOW（怎么做）：规定协作规范。例如，你是使用 bun 还是 node？如何运行测试、类型检查或编译？AI 需要这些信息来验证其更改的正确性。

然而，开发者必须意识到，Claude 有时会故意忽略 CLAUDE.md。这是因为系统提示词中包含一条指令，告诉 AI 只有在上下文高度相关时才响应。如果你的 CLAUDE.md 充斥着大量与当前任务无关的琐碎指令，AI 更有可能判定其为“不相关”并将其忽略。因此，该文件的内容必须具备极高的普适性，确保在任何开发场景下都有参考价值。

主题：上下文工程与“少即是多”的指令原则

在编写 CLAUDE.md 时，开发者往往倾向于塞入尽可能多的指令、代码标准和风格指南，但这种做法往往适得其反。根据上下文工程的最佳实践，LLM 的指令遵循能力是有上限的。研究显示，即使是顶尖的思考型 LLM，也只能稳定处理约 150 到 200 条指令。随着指令数量的增加，模型遵循指令的质量会呈现线性下降（对于较小的模型则是指数级下降）。这意味着，你给的指令越多，AI 并不是只忽略后面的指令，而是会开始随机忽略所有指令。

此外，LLM 存在“外围偏见”，即它们更容易注意到提示词开头（如系统消息和 CLAUDE.md）和结尾（最新的用户消息）的内容。考虑到 Claude Code 自身的系统提示词已经占据了约 50 条指令，留给 CLAUDE.md 的空间其实非常有限。

因此，CLAUDE.md 的长度和适用性至关重要。虽然官方没有硬性规定，但行业共识是将其控制在 300 行以内，越短越好。例如，HumanLayer 公司的根目录 CLAUDE.md 甚至不足 60 行。为了保持精简，你应该避免在其中加入特定场景的指令（如“如何构建新的数据库模式”），因为当你在修复 UI Bug 时，这些信息只会干扰 AI 的注意力。只有那些在每个会话中都必须遵守的准则才配出现在这个文件中。

主题：渐进式披露策略与工具集成优化

面对大型项目，如何既保持 CLAUDE.md 精简又能让 AI 获取足够的信息？答案是采用“渐进式披露”（Progressive Disclosure）原则。不要把所有关于构建、测试、架构和规范的细节都塞进一个文件，而是将它们分散在专门的 Markdown 文件中（例如存放在 agent_docs/ 目录下），并在 CLAUDE.md 中提供这些文件的索引和简要描述。

通过这种方式，你可以指示 AI 在开始工作前，先判断哪些文档与当前任务相关，然后按需读取。这种“指针式”的方法不仅节省了初始上下文空间，还避免了信息过载。在引用代码时，应优先使用“文件:行号”的引用方式，而不是直接复制粘贴代码块，以防止文档与实际代码脱节。

另一个常见的误区是将 CLAUDE.md 当作昂贵的“代码检查工具（Linter）”。LLM 处理代码风格和格式问题的速度极慢且成本高昂。你应该使用确定性的自动化工具（如 Biome 或传统的 Linter）来处理这些任务。你可以通过设置 Claude Code 的 Stop 钩子，在 AI 完成修改后自动运行格式化工具，并将错误反馈给 AI 修复，而不是让 AI 凭空记忆复杂的风格指南。

最后，必须强调 CLAUDE.md 是整个 AI 协作体系中杠杆率最高的一环。一行糟糕的代码只是一个 Bug，但 CLAUDE.md 中一条错误的指令可能会导致 AI 在后续的所有研究、计划和编码阶段产生连锁反应式的错误。因此，绝对不要依赖 /init 等命令自动生成该文件，而应该由开发者根据项目的实际需求，深思熟虑地手动编写每一行内容。

问答

问：为什么 LLM 需要 CLAUDE.md 文件？ 答：因为 LLM 是无状态的，每次新对话开始时它们对代码库一无所知。CLAUDE.md 是唯一在每个会话中都会被注入的文件，用于对 AI 进行“入职培训”。

问：一个好的 CLAUDE.md 应该包含哪些核心内容？ 答：应包含项目的 WHAT（技术栈和结构）、WHY（项目目的）和 HOW（开发规范、测试和验证命令）。

问：为什么 CLAUDE.md 不宜过长？ 答：LLM 的指令遵循能力有限（约 150-200 条）。指令越多，AI 遵循指令的质量就越差，且容易因为内容不相关而选择忽略整个文件。建议控制在 300 行以内。

问：什么是“渐进式披露”策略？ 答：不在 CLAUDE.md 中罗列所有细节，而是将其作为索引，引导 AI 根据任务需要去读取存放在其他位置（如 agent_docs/）的详细文档。

问：可以用 AI 自动生成 CLAUDE.md 吗？ 答：不建议。该文件是整个工作流中杠杆率最高的部分，直接影响 AI 的所有输出。开发者应手动精细打磨，以确保其准确性和高效性。

问：如何处理代码风格和格式规范？ 答：不要写在 CLAUDE.md 里。应使用专门的 Linter 和格式化工具，并通过自动化钩子（Hooks）将结果反馈给 AI，而不是让 AI 充当昂贵的代码检查员。