编写高质量的 CLAUDE.md

注意：本文也适用于 AGENTS.md，这是相当于开源版 CLAUDE.md 的文件，主要用于 OpenCode、Zed、Cursor 和 Codex 等 Agent 与工具。

## 原则：LLMs (极大程度上) 是无状态的

LLMs 是无状态函数。它们的权重在用于推理时已被冻结，因此它们不会随时间推移而学习。模型对你的代码库的了解仅限于你输入的 token。

同样，像 Claude Code 这样的编程智能体工具通常需要你显式地管理智能体的记忆。CLAUDE.md（或 AGENTS.md）是默认情况下唯一会被包含在你与智能体进行的每一次对话中的文件。

这有三个重要的含义：

## CLAUDE.md 帮助 Claude 快速上手你的代码库

由于 Claude 在每次会话开始时对你的代码库都一无所知，你应该使用 CLAUDE.md 来引导 Claude 熟悉你的项目。概括来说，该文件应该包含以下内容：

但是，你执行此操作的方式很重要！不要试图把你认为 Claude 可能需要运行的每一条命令都塞进你的 CLAUDE.md 文件中——这样效果反而不理想。

## Claude 经常忽略 CLAUDE.md

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

你可以通过 ANTHROPIC_BASE_URL 在 claude code CLI 和 Anthropic API 之间设置一个日志代理来亲自调查这一点。Claude code 会将包含你 CLAUDE.md 文件的以下系统提醒注入到发送给智能体（agent）的用户消息中：

<system-reminder>
      IMPORTANT: this context may or may not be relevant to your tasks. 
      You should not respond to this context unless it is highly relevant to your task.
</system-reminder>

结果就是，如果 Claude 认为 CLAUDE.md 的内容与当前任务无关，它就会忽略这些内容。文件中包含的非普遍适用于你正让它处理的任务的信息越多，Claude 就越有可能忽略你在文件中的指令。

Anthropic 为什么要加入这个？ 虽然很难断言，但我们可以推测一下。我们遇到的大多数 CLAUDE.md 文件都包含大量并不具有广泛适用性的指令。许多用户把这个文件当作一种添加“热修补丁”的方式，用来纠正他们不喜欢的行为，结果附加了大量未必普遍适用的指令。

我们只能假设，Claude Code 团队发现，通过告诉 Claude 忽略那些糟糕的指令，这个工具实际上能产出更好的结果。

## 创建优秀的 CLAUDE.md 文件

下文将基于上下文工程的最佳实践 ，就如何编写优质的 CLAUDE.md 文件提供一系列建议。

具体情况可能因人而异。 并非所有规则都一定适用于每种设置。就像做任何事情一样，一旦你满足以下条件，大可不必拘泥于这些规则……

### 少即是多（的指令）

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

虽然对这个话题尚未进行极为严谨的调查，但已有一些研究表明了以下几点：

我们对 Claude Code 利用架构（harness）的分析表明，Claude Code 的系统提示词包含了约 50 条独立指令 。根据你使用的模型不同，这可能已经占据了你的智能体（agent）所能可靠遵循的指令总数的近三分之一——而这还没算上规则、插件、技能或用户消息。

这意味着你的 CLAUDE.md 文件应包含尽可能少的指令——理想情况下，只保留那些对你的任务普遍适用的指令。

### CLAUDE.md 文件的长度与适用性

在其他条件相同的情况下， 如果 LLM 的上下文窗口中充满了诸如示例、相关文件、工具调用和工具结果等聚焦且相关的内容，它在任务上的表现将会更好 ，而如果其上下文窗口中充斥着大量不相关的内容，表现则会相对较差。

由于 CLAUDE.md 会进入每一个会话 ，你应该确保其内容具有尽可能广泛的适用性。

例如，要避免包含（举个例子）关于如何构建新数据库模式的指令——因为当你处理其他不相关的工作时，这些内容不仅无关紧要，还会干扰模型的注意力！

在长度方面， 少即是多的原则同样适用。虽然 Anthropic 对于 CLAUDE.md 文件的长度没有官方建议，但普遍的共识是最好控制在 300 行以内，而且越短越好。

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

### 渐进式披露 (Progressive Disclosure)

编写一份既简洁又能涵盖 Claude 所需全部知识的 CLAUDE.md 文件可能具有挑战性，尤其是在大型项目中。

为了解决这个问题，我们可以利用渐进式披露（Progressive Disclosure） 原则，确保 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 去做代码检查工具（Linter）该做的工作 。相比传统的代码检查工具和格式化工具，LLMs 的成本相当高昂，而且速度极其缓慢。我们认为，只要有可能，你应该始终使用确定性的工具 。

代码风格指南不可避免地会在你的上下文窗口中加入一堆指令和大部分不相关的代码片段，这会降低 LLM 的性能和指令遵循能力，并消耗宝贵的上下文窗口空间。

LLMs 是上下文学习者 ！如果你的代码遵循特定的风格指南或模式，你应该会发现，通过对代码库进行几次搜索（或参考一份好的研究文档！），你的智能体（agent）往往会倾向于遵循现有的代码模式和约定，而无需额外指示。

如果你对此非常在意，甚至可以考虑设置一个 Claude Code Stop 钩子 ，用于运行格式化程序和代码检查工具（linter），并将错误展示给 Claude 让其修复。不要让 Claude 自己去查找格式问题。

加分项 ：使用一个能够自动修复问题的代码检查工具（我们喜欢 Biome），并仔细调整你的规则，确定哪些内容可以安全地被自动修复，从而实现最大程度的（安全）覆盖。

你也可以创建一个 Slash Command（斜杠命令），在其中包含你的代码规范，并指示 Claude 关注版本控制中的变更，或者你的 git status 等内容。通过这种方式，你可以将功能实现与格式调整分开处理。 这样一来，你在两方面都会看到更好的结果 。

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

Claude Code 和其他使用 OpenCode 的工具都提供了自动生成 CLAUDE.md 文件（或 AGENTS.md）的方法。

因为 CLAUDE.md 会进入 Claude Code 的每一个会话中，所以它是该工具杠杆率最高的关键点之一——至于是好是坏，则取决于你如何使用它。

一行糟糕的代码仅仅是一行糟糕的代码。但在实施计划中哪怕出现一句糟糕的描述，都有可能导致生成大量糟糕的代码。而在调研阶段，如果对系统工作原理产生了一句误解，则可能导致计划中出现大量错误描述，进而最终导致生成更多糟糕的代码。

但是，CLAUDE.md 文件会影响你工作流程的每一个环节以及由此产生的所有生成物。因此，我们认为你应该花点时间，非常仔细地推敲写入其中的每一行内容：

## 结语