高效Claude.md文件编写指南：核心原则与最佳实践

引言：为什么Claude.md如此重要

在使用Claude Code等AI编程智能体时，有一个文件的杠杆效应远超其他——那就是claude.md文件（或其开源等效文件agents.md，适用于OpenCode、Zest、Cursor、Codex等工具）。

大语言模型本质上是无状态函数。它们的权重在推理时已经固定，不会随时间推移而学习。模型对你代码库的唯一了解，仅限于你输入给它的那些token。这意味着：

• 每个会话开始时，编程智能体对你的代码库一无所知
• 每次开始会话时，必须告诉智能体关于代码库的重要信息
• claude.md是实现这一点的首选方式

简单来说，开启新对话时，你想让大语言模型知道的、了解的、遵守的内容，都应该放到claude.md文件里。

Claude.md应该包含什么内容

从宏观层面来看，claude.md需要回答三个核心问题：What（是什么）、Why（为什么）和How（怎么做）。

What：项目的基本信息

• 技术栈：告诉Claude你使用的相关技术
• 项目结构：为Claude提供一份代码库地图，说明哪些是应用、哪些是共享包、每部分的功能
• 代码规范：贯穿项目不变的总体要求

在大型项目中，这份"地图"尤为重要，它能帮助智能体快速定位所需内容。

Why：项目的目的

告诉Claude项目的目的，以及仓库中各项内容的具体作用。项目不同部分的用途和功能是什么？这些上下文信息能帮助智能体做出更合理的决策。

How：工作方式

告诉Claude应该如何在这个项目上工作：

• 你是否使用Bun而非Node来构建项目？
• Claude如何验证自己的更改？
• 如何运行测试、类型检查和编译步骤？

为什么Claude会"忽略"你的指令

这是很多开发者困惑的问题：明明写了claude.md，Claude却经常不遵守里面的规则。

官方的"过滤机制"

Claude Code在发送给智能体的用户消息中，会将claude.md文件与一个System Reminder一同注入。这个提示中包含了一句关键信息：如果claude.md的内容与当前任务不高度相关，Claude可以忽略其中的内容。

为什么Anthropic要这样设计

原因在于很多程序员把claude.md当成了"万能补丁包"：

• 昨天Claude写错了一个循环 → 加一句"永远不要用for循环"
• 今天缩进不对 → 加一句"必须用四个空格"

久而久之，文件里塞满了各种针对特定小问题的、甚至有点极端的琐碎规则。Anthropic发现，如果强迫Claude死磕这些内容，它反而会变得畏首畏尾，甚至因为陈旧或奇怪的指令把当前任务搞砸。

结论：官方给了Claude一个"如果觉得没用就可以无视"的特权，目的是保证智能体的整体表现不被琐碎指令拉低。

核心原则：指令越精简，效果越好

已有研究揭示了以下关键发现：

指令遵循的硬性限制

• 前沿思考型LLM（如Claude 3.5 Sonnet）能以较高一致性遵循约150-200条指令
• 小模型能处理的指令比大模型少
• 非思考型模型能处理的指令比思考型模型少
• LLM偏向于位于提示词边缘的指令（最开头和最末尾）
• 随着指令数量增加，遵循质量会整体下降——不是忽略靠后的指令，而是开始无差别忽略所有指令

Claude Code的指令预算

Claude Code的系统提示词已经包含了约50条独立指令，这已经占到了智能体能可靠遵循指令数的近三分之一。加上项目规则、插件、技能和用户消息，留给claude.md的"预算"其实非常有限。

长度建议

虽然Anthropic官方没有正式建议，但社区普遍共识是：

• 少于300行
• 越短越好
• Human Layer团队的根目录claude.md文件不足60行

渐进式披露：解决信息量与简洁性的矛盾

拆分为独立文件

不要将所有关于构建、测试、代码规范的指令都塞进claude.md。建议将特定任务的指令保存在项目中具有自描述名称的独立Markdown文件中，然后在claude.md中列出这些文件并附上简短说明。

你可以：

• 指示Claude自行判断哪些文件相关，在开始工作前阅读
• 或要求Claude先展示它想阅读的文件列表，经你审批后再阅读

优先使用指针而非副本

尽可能不要在文件中包含代码片段——它们很快就会过时。相反，应包含file:filename:line_number这样的引用，引导Claude查看权威的源代码内容。

Claude不是Linter：别让它做格式化的活

我们看到人们在claude.md中放入最多的内容之一就是代码风格指南。这是一个常见但值得纠正的做法。

为什么不应该这样做

• 与传统Linter相比，LLM既昂贵又极其缓慢
• 风格指南会向上下文窗口添加大量无关指令和代码片段
• 降低LLM的性能和指令遵循能力
• 吞噬宝贵的上下文空间

更好的替代方案

1. 依赖代码库本身：LLM通过上下文学习，只要对代码库搜索几次，智能体往往会自动遵循现有的代码模式
2. 设置Stop Hook：运行格式化工具和Linter，将错误呈现给Claude修复
3. 使用自动修复Linter：如Biome，仔细调整规则确定哪些可以安全自动修复
4. 创建斜杠命令：包含代码指南并引导Claude查看git状态，将实现和格式化分开处理

不要自动生成Claude.md

最后一个重要建议：不要使用/init命令或自动生成工具来创建claude.md文件。

claude.md是工具链中杠杆效应最高的地方之一。一行糟糕的实施方案可能产生大量糟糕的代码，而claude.md会影响你工作流的每一个阶段以及由此产生的每一个产物。

因此，应该花时间仔细思考claude.md文件中的每一行内容，确保每条指令都是经过深思熟虑的、普遍适用的、对智能体真正有帮助的。