如何编写高质量的 CLAUDE.md

由coder创建，最终由coder更新于2025-12-24 17:41 被浏览 6 用户

作者： Kyle · 日期： 2025年11月25日

注： 本文同样适用于 AGENTS.md，这是用于 OpenCode、Zed、Cursor 和 Codex 等 Agent（智能体）工具框架的开源等效文件

原则：LLM 本质上是（几乎）无状态的

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

同样，像 Claude Code 这样的编码 Agent 框架通常需要你显式地管理 Agent 的记忆。CLAUDE.md（或 AGENTS.md）是默认情况下每一次与 Agent 的对话都会包含的唯一文件。

这带来了三个重要启示：

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

使用 CLAUDE.md 引导 Claude 进入代码库

既然 Claude 在会话开始时是一张白纸，你需要用 CLAUDE.md 来引导（Onboard）它。从高层次来看，该文件应涵盖：

• WHAT（是什么）： 告诉 Claude 相关的技术、技术栈和项目结构。给 Claude 一张代码库的“地图”。这在单一代码仓库（Monorepos）中尤为重要！告诉它有哪些应用、共享包，以及各个部分的作用，以便它知道去哪里查找。
• WHY（为什么）： 告诉 Claude 项目的目的以及仓库中各个部分在做什么。不同项目组件的目标和功能是什么？
• HOW（怎么做）： 告诉 Claude 如何在项目中工作。例如，你是否使用 bun 而不是 node？你需要包含它在项目中开展实际工作所需的所有信息。Claude 如何验证它的更改？如何运行测试、类型检查和编译步骤？

注意： 实现方式很重要！不要试图把 Claude 可能需要运行的每一条命令都塞进 CLAUDE.md —— 这会导致效果不佳。

Claude 经常忽略 CLAUDE.md

无论使用哪种模型，你可能会发现 Claude 经常忽略 CLAUDE.md 的内容。

这其实是有意为之。Claude Code 会在用户消息中注入以下系统提示（System Reminder）：

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

因此，如果 Claude 认为 CLAUDE.md 中的内容与当前任务无关，它就会忽略它。文件中包含的非通用适用的信息越多，Claude 忽略你指令的可能性就越大。

原因推测： 许多用户将此文件视为针对不喜欢行为的“热修复”补丁，添加了大量并不广泛适用的指令。Claude Code 团队可能发现，让模型忽略这些糟糕的指令反而能产生更好的结果。

编写高质量 CLAUDE.md 的最佳实践

以下是基于上下文工程最佳实践的建议。

1. 指令：少即是多 (Less is More)

不要试图将所有可能的命令、代码标准和风格指南都塞进 CLAUDE.md。

相关研究表明：

1. 前沿推理型 LLM（Frontier Thinking LLMs）可以比较稳定地遵循约 150-200 条指令。 模型越小，能遵循的指令越少。
2. 指令数量增加时，小模型的表现会急剧下降（指数级衰减），而大模型则是线性衰减。 因此，不建议使用小模型处理多步骤任务。
3. LLM 偏向于关注提示词边缘的指令： 即最开头（系统提示和 CLAUDE.md）和最末尾（最近的用户消息）。
4. 随着指令数量增加，指令遵循质量会均匀下降。 这意味着如果指令过多，模型不会只忽略后面的指令，而是开始均匀地忽略所有指令。

关键数据： Claude Code 的系统提示本身已经包含了约 50 条指令。这意味着在添加任何规则之前，你的配额已经用了三分之一。因此，CLAUDE.md 应尽可能只包含对你的任务普遍适用的指令。

2. 文件长度与适用性

当上下文窗口充满聚焦的、相关的上下文（包括示例、相关文件、工具调用结果）时，LLM 的表现最佳。

由于 CLAUDE.md 会进入每一个会话，你需要确保其内容尽可能通用。

• 反例： 不要包含关于如何构建新数据库 Schema 的详细指令，除非你一直在做这个。这会分散模型处理其他无关任务时的注意力。
• 长度建议： 普遍共识是 < 300 行 为佳，越短越好。HumanLayer 的根 CLAUDE.md 文件不到 60 行。

3. 渐进式披露 (Progressive Disclosure)

如何在保持简洁的同时让 Claude 知道所有必要信息？利用渐进式披露原则。

不要将构建项目、测试、代码规范等所有指令都放在主文件中，而是将特定任务的指令保存在单独的 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 在开始工作前判断哪些文件是相关的并读取它们。

• 使用引用而非副本： 不要在这些文件中包含代码片段（容易过时），而是使用 file:line 引用指向权威代码。
• 这在概念上类似于 Claude Skills 的工作方式。

4. Claude 不是昂贵的 Linter

最常见的错误是在 CLAUDE.md 中放入代码风格指南。

• 不要派 LLM 去做 Linter（代码检查工具）的工作。 相比传统工具，LLM 非常昂贵且极其缓慢。应尽可能使用确定性工具。
• 风格指南会向上下文窗口添加大量无关指令，降低模型性能。
• LLM 是上下文学习者！ 只要代码库本身有一致的风格，Agent 通常会通过搜索和模仿现有代码来遵循规范。

建议方案：

• 设置一个 Claude Code Stop Hook，运行格式化程序和 Linter，并将错误展示给 Claude 修复。
• 使用可以自动修复问题的 Linter（如 Biome）。
• 创建一个 Slash Command (斜杠命令)，其中包含代码指南并指向版本控制中的更改。

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

虽然很多工具提供自动生成功能，但鉴于 CLAUDE.md 是整个框架中杠杆率最高点（Highest Leverage Point），你应该手动精心编写它。

• 杠杆效应： CLAUDE.md 中的一行错误指令 -> 导致对系统的错误理解（研究阶段）-> 导致错误的实施计划 -> 最终导致大量错误的代码。
• 它影响工作流的每一个阶段。请认真思考放入其中的每一行内容。

总结

1. CLAUDE.md 用于引导 Claude 进入你的代码库，应定义项目的 WHY（目的）、WHAT（结构） 和 HOW（方法）。
2. 少即是多。只包含绝对必要的指令。
3. 内容应保持 简洁且通用适用。
4. 使用 渐进式披露：告诉 Claude 如何找到 信息，而不是直接把所有信息塞给它。
5. Claude 不是 Linter。请使用专业的格式化工具、Hooks 和 Slash Commands。
6. CLAUDE.md 是高杠杆点，避免自动生成，请手动精心打磨。

英文原文：https://www.humanlayer.dev/blog/writing-a-good-claude-md