如何编写优质的 CLAUDE.md 文件

作者：humanlayer.dev

注：本文同样适用于 AGENTS.md，这是面向 OpenCode、Zed、Cursor 和 Codex 等代理和框架的开源版本。

基本原理：LLM 基本上是无状态的

LLM 是无状态函数。它们的权重在推理时就已经固定，不会随时间学习。模型对你代码库的了解，完全取决于你输入的 token。

同样，Claude Code 这类编码代理框架通常需要你显式管理代理的记忆。CLAUDE.md(或 AGENTS.md)是唯一会默认出现在你与代理的每一次对话中的文件。

这带来三个重要影响：

1. 编码代理在每次会话开始时对你的代码库一无所知。
2. 每次启动会话时，必须告诉代理关于代码库的所有重要信息。
3. CLAUDE.md 是实现这一目标的首选方式。

CLAUDE.md 让 Claude 快速熟悉你的代码库

既然 Claude 在每次会话开始时对你的代码库一无所知，就应该用 CLAUDE.md 来引导它。从宏观层面看，这个文件应该涵盖:

• 是什么(WHAT)：告诉 Claude 你的技术栈、项目结构。给它一张代码库地图。这在 monorepo 中尤其重要！告诉 Claude 有哪些应用、有哪些共享包，以及它们各自的用途，这样它才知道去哪里找东西。
• 为什么(WHY)：告诉 Claude 项目的目的，以及仓库中各部分在做什么。项目不同部分的目的和功能是什么？
• 怎么做(HOW)：告诉 Claude 应该如何在项目上工作。比如，你用的是 bun 而不是 node？你要包含它实际完成有意义工作所需的所有信息。Claude 如何验证自己的修改？如何运行测试、类型检查和编译步骤？

但具体怎么做很重要！不要试图把 Claude 可能需要运行的每个命令都塞进 CLAUDE.md 文件——这会得到次优的结果。

Claude 经常忽略 CLAUDE.md

无论你使用哪个模型，你可能会注意到 Claude 经常忽略 CLAUDE.md 文件的内容。

你可以自己验证这一点:在 claude code CLI 和 Anthropic API 之间使用 ANTHROPIC_BASE_URL 设置一个日志代理。Claude code 会在用户消息中注入以下系统提醒和你的 CLAUDE.md 文件:

<system-reminder>
  重要：这些上下文可能与你的任务相关，也可能无关。除非与你的任务高度相关，
  否则你不应该回应这些上下文。
</system-reminder>

结果就是，如果 Claude 认为 CLAUDE.md 的内容与当前任务无关，它就会忽略。文件中不是普遍适用的信息越多，Claude 忽略你指令的可能性就越大。

*Anthropic 为什么要这样做？*很难确定，但我们可以推测一下。我们见过的大多数 CLAUDE.md 文件都包含了很多并非广泛适用的指令。许多用户把这个文件当作给不喜欢的行为打"热补丁"的地方，不断追加不一定广泛适用的指令。

我们只能假设 Claude Code 团队发现，让 Claude 忽略那些糟糕的指令，框架实际上能产生更好的结果。

创建优质的 CLAUDE.md 文件

以下部分提供了一些建议，教你如何遵循上下文工程最佳实践编写优质的 CLAUDE.md 文件。

*效果因人而异。*这些规则不一定对每种设置都是最优的。和其他事情一样，可以打破规则，前提是...

1. 你理解什么时候、为什么可以打破规则
2. 你有充分的理由这样做

指令越少越好

人们很容易想把 Claude 可能需要运行的每个命令，以及你的代码标准和风格指南都塞进 CLAUDE.md。我们不建议这样做。

虽然这个话题还没有得到非常严格的研究，但已有一些研究表明:

1. 前沿思考型 LLM 能够以合理的一致性遵循约 150-200 条指令。小模型能处理的指令比大模型少，非思考型模型能处理的指令比思考型模型少。
2. 小模型的表现会急剧下降，而且速度快得多。具体来说，随着指令数量增加，小模型的指令遵循性能往往呈指数级衰减，而大型前沿思考模型呈线性衰减(见下图)。因此，我们不建议在多步骤任务或复杂实现计划中使用小模型。
3. LLM 会偏向提示词两端的指令:最开始(Claude Code 系统消息和 CLAUDE.md)和最末尾(最近的用户消息)
4. 随着指令数量增加，指令遵循质量会均匀下降。这意味着当你给 LLM 更多指令时，它不只是忽略新的("文件中靠后的")指令——而是开始均匀地忽略所有指令

我们对 Claude Code 框架的分析表明，Claude Code 的系统提示词包含约 50 条独立指令。根据你使用的模型，这已经占了代理能可靠遵循的指令的近三分之一——而这还是在规则、插件、技能或用户消息之前。

这说明你的 CLAUDE.md 文件应该包含尽可能少的指令——理想情况下只包含普遍适用于你任务的指令。

CLAUDE.md 文件长度和适用性

在其他条件相同的情况下，当 LLM 的上下文窗口充满集中、相关的上下文(包括示例、相关文件、工具调用和工具结果)时，它在任务上的表现会比上下文窗口有大量无关内容时更好。

由于 CLAUDE.md 会出现在每一次会话中，你应该确保其内容尽可能普遍适用。

例如，避免包含关于(比如)如何构建新数据库模式的指令——当你在处理其他不相关的事情时，这不重要，还会分散模型的注意力！

在长度方面，少即是多的原则同样适用。虽然 Anthropic 没有关于 CLAUDE.md 文件应该多长的官方建议，但普遍共识是 < 300 行最好，越短越好。

在 HumanLayer，我们根目录的 CLAUDE.md 文件不到六十行。

渐进式披露

编写一个简洁的 CLAUDE.md 文件，同时涵盖你希望 Claude 知道的所有内容，这可能很有挑战性，尤其是在大型项目中。

为了解决这个问题，我们可以利用渐进式披露原则，确保 Claude 只在需要时才看到特定任务或项目的指令。

我们建议不要把关于构建项目、运行测试、代码约定或其他重要上下文的所有不同指令都包含在 CLAUDE.md 文件中，而是将特定任务的指令保存在项目中某处的单独 markdown 文件中，文件名要有自我描述性。

例如:

agent_docs/
  |- building_the_project.md
  |- running_tests.md
  |- code_conventions.md
  |- service_architecture.md
  |- database_schema.md
  |- service_communication_patterns.md

然后，在你的 CLAUDE.md 文件中，可以包含这些文件的列表和简要描述，并指示 Claude 决定哪些(如果有)是相关的，在开始工作之前阅读它们。或者，让 Claude 先向你展示它想读的文件，征得批准后再阅读。

优先使用指针而非副本。如果可能，不要在这些文件中包含代码片段——它们会很快过时。相反，包含 文件:行号 引用，将 Claude 指向权威的上下文。

从概念上讲，这与 Claude Skills 的工作方式非常相似，尽管 skills 更侧重于工具使用而非指令。

Claude 不是(也不应该是)昂贵的代码检查工具

我们看到人们在 CLAUDE.md 文件中最常放的内容之一就是代码风格指南。永远不要让 LLM 去做代码检查工具的工作。与传统的代码检查工具和格式化工具相比，LLM 相对昂贵，而且速度慢得令人难以置信。我们认为你应该尽可能始终使用确定性工具。

代码风格指南不可避免地会在你的上下文窗口中添加大量指令和大多无关的代码片段，降低 LLM 的性能和指令遵循能力，还会消耗你的上下文窗口。

LLM 是上下文学习者！如果你的代码遵循某套风格指南或模式，你应该会发现，只要对代码库进行几次搜索(或有一份好的研究文档！)，你的代理往往会遵循现有的代码模式和约定，无需明确告知。

如果你对此有强烈的感觉，甚至可以考虑设置一个 Claude Code Stop 钩子，运行你的格式化工具和代码检查工具，并将错误呈现给 Claude 让它修复。不要让 Claude 自己去找格式问题。

额外收获:使用能够自动修复问题的代码检查工具(我们喜欢 Biome)，并仔细调整关于什么可以安全自动修复的规则，以获得最大(安全)覆盖率。

你还可以创建一个斜杠命令，包含你的代码指南，并将 Claude 指向版本控制中的更改，或你的 git status 等。这样，你可以分别处理实现和格式化。因此，两者都会看到更好的结果。

不要使用 /init 或自动生成 CLAUDE.md

Claude Code 和其他使用 OpenCode 的框架都提供了自动生成 CLAUDE.md 文件(或 AGENTS.md)的方法。

因为 CLAUDE.md 会出现在 Claude code 的每一次会话中，它是框架中最具杠杆效应的点之一——好坏取决于你如何使用它。

一行糟糕的代码就是一行糟糕的代码。实现计划中的一行糟糕内容有可能创建大量糟糕的代码。一份误解系统工作原理的研究中的一行糟糕内容，有可能导致计划中出现大量糟糕的内容，进而导致更多糟糕的代码。

但 CLAUDE.md 文件会影响工作流程的每个阶段以及由此产生的每个产物。因此，我们认为你应该花些时间非常仔细地思考放入其中的每一行:

总结

1. CLAUDE.md 用于让 Claude 快速熟悉你的代码库。它应该定义项目的为什么、是什么和怎么做。
2. 指令越少越好。虽然不应该省略必要的指令，但应该在文件中包含尽可能少的指令。
3. 保持 CLAUDE.md 的内容简洁且普遍适用。
4. 使用渐进式披露——不要告诉 Claude 你可能希望它知道的所有信息。相反，告诉它如何找到重要信息，这样它可以找到并使用这些信息，但只在需要时使用，避免膨胀你的上下文窗口或指令数量。
5. Claude 不是代码检查工具。使用代码检查工具和格式化工具，并根据需要使用钩子和斜杠命令等其他功能。
6. CLAUDE.md 是框架中最具杠杆效应的点，所以避免自动生成它。你应该精心制作其内容以获得最佳结果。