如何编写优秀的 CLAUDE.md

image

注意：这篇文章同样适用于 AGENTS.md，这是 CLAUDE.md 的开源等价物，适用于 OpenCode、Zed、Cursor 和 Codex 等代理和工具。

原则：大语言模型（绝大部分）是无状态的

大语言模型（LLM）是无状态的函数。它们的权重在进行推理时是固定的，因此它们不会随时间学习。模型对你代码库的唯一了解，来源于你输入给它的 token。

image

同样，像 Claude Code 这样的编码代理工具通常需要你显式地管理代理的记忆。CLAUDE.md（或 AGENTS.md）是唯一一个默认会包含在你与代理的每一次对话中的文件。

这有三个重要的含义：

  1. 编码代理在每次会话开始时对你的代码库一无所知。

  2. 每次开始会话时，必须告知代理关于你代码库的重要信息。

  3. CLAUDE.md 是实现这一点的首选方式。

CLAUDE.md 帮助 Claude 入门你的代码库

image

由于 Claude 在每次会话开始时对你的代码库一无所知，你应该使用 CLAUDE.md 来帮助 Claude 熟悉你的代码库。从高层次来看，这意味着它应该涵盖：

  • WHAT（是什么）：告诉 Claude 关于技术、你的技术栈、项目结构的信息。给 Claude 一张代码库的地图。这在单一代码库（monorepo）中尤为重要！告诉 Claude 应用程序有哪些，共享包有哪些，以及每样东西的用途，以便它知道去哪里找东西。

  • WHY（为什么）：告诉 Claude 项目的目的以及仓库中每样东西的作用。项目不同部分的目标和功能是什么？

  • HOW（怎么做）：告诉 Claude 它应该如何在项目上工作。例如，你是否使用 bun 而不是 node？你需要包含它在项目上进行有意义工作所需的所有信息。Claude 如何验证它的更改？它如何运行测试、类型检查和编译步骤？

image

但是，你如何做这件事很重要！不要试图把 Claude 可能需要运行的每条命令都塞进你的 CLAUDE.md 文件里——你会得到次优的结果。

Claude 经常忽略 CLAUDE.md

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

你可以通过在 claude code CLI 和 Anthropic API 之间放置一个日志代理（使用 ANTHROPIC_BASE_URL）来亲自调查这一点。Claude Code 会在给代理的用户消息中注入以下系统提醒（system reminder）连同你的 CLAUDE.md 文件：

XML

<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 文件的建议。

你的情况可能会有所不同。并非所有这些规则对每个设置都是最优的。像其他任何事情一样，一旦你理解了何时以及为什么可以打破规则，并且你有充分的理由这样做，就尽管打破规则吧。

少即是多（关于指令）

image

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

image

虽然这个话题还没有经过非常严格的调查，但已有一些研究表明：

  • 前沿的思维型 LLM 可以保持合理一致性地遵循约 150-200 条指令。

  • 较小的模型比较大的模型能处理的指令更少，非思维型模型比思维型模型能处理的指令更少。较小的模型表现会迅速恶化。具体来说，随着指令数量的增加，较小模型的指令遵循性能往往呈现指数级衰减，而较大的前沿思维型模型则呈现线性衰减。

  • 因此，我们不建议使用较小的模型来处理多步骤任务或复杂的实施计划。

  • LLM 偏向于关注提示（prompt）边缘的指令：最开始的部分（Claude Code 系统消息和 CLAUDE.md）和最末尾的部分（最近的用户消息）。

  • 随着指令数量的增加，指令遵循的质量会均匀下降。这意味着当你给 LLM 更多指令时，它不会简单地忽略较新的（“文件下方”）指令——它会开始均匀地忽略所有指令。

指令遵循

我们需要意识到：我们对 Claude Code 工具的分析表明，Claude Code 的系统提示（system prompt）已经包含了约 50 条独立指令。取决于你使用的模型，这已经占用了代理能够可靠遵循的指令的近三分之一——这还是在规则、插件、技能或用户消息之前。

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

CLAUDE.md 文件长度与适用性

在其他条件相同的情况下，当 LLM 的上下文窗口充满聚焦的、相关的上下文（包括示例、相关文件、工具调用和工具结果）时，其在任务上的表现要优于上下文窗口包含大量不相关上下文时。

由于 CLAUDE.md 会进入每一个会话，你应该确保其内容尽可能普遍适用。

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

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

在 HumanLayer，我们的根 CLAUDE.md 文件不到 60 行。

渐进式披露 (Progressive Disclosure)

编写一个简洁且涵盖你想让 Claude 知道的所有内容的 CLAUDE.md 文件可能具有挑战性，特别是在大型项目中。

image

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

与其将所有关于构建项目、运行测试、代码规范或其他重要上下文的指令都包含在 CLAUDE.md 文件中，我们建议将特定于任务的指令保存在项目中某个位置的单独 Markdown 文件中，并使用自描述的文件名。

例如：

Plaintext

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 在阅读之前先向你展示它想要阅读的文件以获得批准。

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

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

Claude (不) 是一个昂贵的 Linter

我们看到人们放入 CLAUDE.md 文件的最常见内容之一是代码风格指南。永远不要派 LLM 去做 Linter 的工作。 与传统的 Linter 和格式化程序相比，LLM 相对昂贵且速度极慢。我们认为只要可以，你就应该始终使用确定性工具。

image

代码风格指南将不可避免地向你的上下文窗口添加大量指令和大部分不相关的代码片段，从而降低 LLM 的性能和指令遵循能力，并吞噬你的上下文窗口。

LLM 是上下文学习者！如果你的代码遵循一套特定的风格指南或模式，你应该会发现，只需对代码库进行几次搜索（或一份好的研究文档！），你的代理就会倾向于遵循现有的代码模式和惯例，而无需被告知。

如果你对此非常坚持，你甚至可以考虑设置一个 Claude Code Stop 钩子（hook），运行你的格式化程序和 Linter，并将错误展示给 Claude 让其修复。不要让 Claude 自己去发现格式问题。

加分项：使用可以自动修复问题的 Linter（我们喜欢 Biome），并仔细调整你的规则，确定哪些可以安全地自动修复，以获得最大的（安全）覆盖率。

你还可以创建一个 Slash Command（斜杠命令），其中包含你的代码指南，并指向版本控制中的更改、你的 git status 或类似内容。这样，你可以将实现和格式化分开处理。结果你会发现两者的效果都更好。

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

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

image

因为 CLAUDE.md 会进入与 Claude Code 的每一次会话，它是该工具最高杠杆率的点之一——取决于你如何使用它，结果可能更好也可能更坏。

一行糟糕的代码就是一行糟糕的代码。实施计划中糟糕的一行有可能会产生大量糟糕的代码。一项研究中对系统工作原理理解错误的一行，有可能会导致计划中出现大量糟糕的行，进而导致更多糟糕的代码。

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

结论

CLAUDE.md 用于帮助 Claude 入门你的代码库。它应该定义你项目的 WHY（为什么）、WHAT（是什么） 和 HOW（怎么做）。

image

  • 少（指令）即是多。 虽然不应省略必要的指令，但应在文件中包含尽可能少的指令。

  • 保持 CLAUDE.md 的内容简洁且普遍适用。

  • 使用渐进式披露——不要告诉 Claude 你想让它知道的所有信息。相反，告诉它如何找到重要信息，以便它可以找到并使用它，但仅在需要时才这样做，以避免通过膨胀你的上下文窗口或指令计数。

  • Claude 不是 Linter。 使用 Linter 和代码格式化程序，并在必要时使用 Hooks 和 Slash Commands 等其他功能。

  • CLAUDE.md 是工具的最高杠杆点，因此避免自动生成它。你应该精心编写其内容以获得最佳结果。

今天先到这儿，希望对AI，云原生，技术领导力， 企业管理，系统架构设计与评估，团队管理, 项目管理, 产品管理，信息安全，团队建设 有参考作用 , 您可能感兴趣的文章:
微服务架构设计
视频直播平台的系统架构演化
微服务与Docker介绍
Docker与CI持续集成/CD
互联网电商购物车架构演变案例
互联网业务场景下消息队列架构
互联网高效研发团队管理演进之一
消息系统架构设计演进
互联网电商搜索架构演化之一
企业信息化与软件工程的迷思
企业项目化管理介绍
软件项目成功之要素
人际沟通风格介绍一
精益IT组织与分享式领导
学习型组织与企业
企业创新文化与等级观念
组织目标与个人目标
初创公司人才招聘与管理
人才公司环境与企业文化
企业文化、团队文化与知识共享
高效能的团队建设
项目管理沟通计划
构建高效的研发与自动化运维
某大型电商云平台实践
互联网数据库架构设计思路
IT基础架构规划方案一(网络系统规划)
餐饮行业解决方案之客户分析流程
餐饮行业解决方案之采购战略制定与实施流程
餐饮行业解决方案之业务设计流程
供应链需求调研CheckList
企业应用之性能实时度量系统演变

如有想了解更多软件设计与架构, 系统IT,企业信息化, 团队管理 资讯，请关注我的微信订阅号：

_thumb_thumb_thumb_thumb_thumb_thumb

作者：Petter Liu
出处：http://www.cnblogs.com/wintersun/
本文版权归作者和博客园共有，欢迎转载，但未经作者同意必须保留此段声明，且在文章页面明显位置给出原文连接，否则保留追究法律责任的权利。 该文章也同时发布在我的独立博客中-Petter Liu Blog。

posted on 2025-12-11 21:47  PetterLiu  阅读(8)  评论(0)    收藏  举报
博客园  ©  2004-2025
浙公网安备 33010602011771号 浙ICP备2021040463号-3