CLAUDE.md 完全指南：从入门到最佳实践
如果你要给 AI 编码工具的演进画一条时间线，Claude Code 大概是值得单独标注的一个节点。Anthropic 在 2025 年 2 月首次把它带给开发者，那时还是早期公开预览版，到 2025 年 5 月，它已经开始触及更广泛的开发者群体。它的特别之处不在于又多了一个聊天的模型界面，而在于这是 AI 智能体第一次真正进入终端——读取仓库、编辑文件、运行命令、修复问题、推动任务前进。从那一刻起，软件开发的中心就已经在悄悄移动了。
很长一段时间里，开发者的主要工作是手动实现，而 IDE 主要是代码补全、搜索和分析的辅助工具。Claude Code 把这个边界推得更远。越来越多的时候，我们不再从”下一行代码应该写什么”开始思考，而是从”目标是什么、约束是什么、哪些文件可以改、什么算完成”出发。开发过程正在从逐行手写代码转向通过清晰意图和 AI 协作来驱动实现。这不是一个小功能升级，而是一次真正的工作方式重组。这也是为什么它是许多开发者第一次真正感受到 AI 能自主完成编程任务背后的原因。
正因为如此，我想写一系列关于如何真正用好 Claude Code 的文章。网上已经有很多好文章了，官方文档也绝对值得读，但我还是想写这一系列。一个原因是 Claude Code 迭代太快，很多旧经验很快就过时了。另一个原因是，我想把真实使用中学到的东西整理下来，包括踩过的坑和思考方式上的变化。写下来也是重新构建自己学习路径的好方式，让我对 Claude Code 的理解更扎实。
作为这个系列的第一篇文章，我想从 CLAUDE.md 开始。因为它是 Claude Code 理解项目的入口，它为 AI 提供了所需的背景和约定，往往直接决定了模型在你的代码库中工作的准确性和可靠性。
什么是 CLAUDE.md
CLAUDE.md 是一个 Markdown 文件，Claude Code 在每个会话开始时自动读取它。在这个文件里，你可以写下指令、规则和偏好，Claude Code 会在后续交互中遵循这些内容。
网上有人分享过一个有趣的 meme，基于 2024 年巴黎奥运会射击比赛的一张对比照片。它调侃说 Claude Code 用户分为两类：左边是全副武装、疯狂安装各种插件的选手，右边是手插口袋、淡定站着的土耳其射击手，靠的只是一份 CLAUDE.md：
虽然这只是个玩笑，但它指向了一个真实的现象：与其把时间花在摆弄花哨的插件上，不如花时间写好一份 CLAUDE.md。真正投入精力去写的人，往往能得到远超预期的体验，因为 CLAUDE.md 从根本上改变了 AI 与你的项目交互的方式。
这里有一个有用的类比：如果把 Claude Code 想象成一个刚加入团队的新开发者，那么 CLAUDE.md 就是这个项目的入职手册。没有手册，新队友只能一遍又一遍地问同样的问题：这个项目怎么构建？用哪个测试框架？代码风格是怎样的？有了手册，他们从第一天起就能用团队期望的方式高效工作。
CLAUDE.md 的核心价值：把 Claude Code 从一个通用 AI 助手，变成贴合你项目的专属开发工具。
CLAUDE.md 如何加载
很多人初次接触 CLAUDE.md 时，以为它就是项目根目录下的一个 Markdown 文件。实际上并非如此。Claude Code 通过分层加载模型来读取记忆和指令。不同位置的 CLAUDE.md 文件作用于不同的范围，有的影响你所有项目，有的只影响当前仓库，有的只在特定子目录内生效。
这也是为什么实际使用中经常有人搞不清楚：为什么同一条规则在项目 A 中有效，在项目 B 中就被覆盖了？为什么明明写了规则，Claude Code 在某个目录下还是忽略掉了？这些问题归根结底都要回到 CLAUDE.md 的加载方式上。
文件层级
先看核心文件类型：
日常使用中，最常见的通常是项目级的 ./CLAUDE.md，因为它通过版本控制共享，定义了 Claude Code 在该仓库内的默认行为。~/.claude/CLAUDE.md 更像你的全局个人偏好文件，而 CLAUDE.local.md 则适合那些你不想提交但希望在当前项目中生效的笔记。
有些团队还会把规则拆分到 .claude/rules/ 目录下，以获得更模块化的组织方式，但这已经属于更高级的配置了。
加载规则
Claude Code 读取这些文件时，大致遵循以下规则：
- Claude Code 启动时，会先读取与当前工作目录相关的 CLAUDE.md 文件
- 用户级的
~/.claude/CLAUDE.md也会被加载，作为更高层级的默认偏好层 - 子目录中的 CLAUDE.md 文件不会一次性全部加载，而是当 Claude Code 实际读取该目录的内容时才加载
- 当多个 CLAUDE.md 文件同时生效时，最近范围原则通常适用——离当前任务越近、范围越窄的指令优先级越高
- 同一层内，越明确、越具体的规则，越容易被一致地遵循
冲突解决
当不同 CLAUDE.md 文件的内容冲突时，最容易理解的规则就是最近范围原则。规则离当前任务越近、适用范围越窄，优先级通常越高。
举个例子：如果用户级的 CLAUDE.md 说用 4 空格缩进，但项目根目录的 CLAUDE.md 明确说用 2 空格缩进，那么在该项目中，Claude Code 会遵循 2 空格缩进。
理解这一点很重要——仅仅知道多个 CLAUDE.md 文件可以存在还不够，你还需要知道它们各自作用于什么范围，以及冲突时谁覆盖谁。
如何编写 CLAUDE.md
用 /init 快速开始
最简单的入门方式是在项目根目录运行 Claude Code 的 /init 命令，让它生成初稿：
$ claude
> /init
/init 会查看你的技术栈、目录结构和常用命令，生成一个 CLAUDE.md 文件作为基本框架。但这只解决了从空白文件开始的问题，不代表你已经有了一个真正适合项目的 CLAUDE.md。
拿到初稿后，通常至少需要一轮编辑。原因很简单：/init 倾向于生成面面俱到的内容，它试图包含所有能检测到的信息，但有些信息对你的项目并不重要，有些虽然是正确的，但不够有用——无法有效引导 Claude Code。CLAUDE.md 并不是越长越好。一方面它占用上下文窗口，另一方面信息过于分散和通用时，Claude Code 反而难以识别哪些是真正重要的约束。
更好的做法是先删掉那些低价值、通用性高、或者已在别处记录过的信息，然后补充只有你的团队才知道的项目知识，特别是那些最有可能导致 Claude Code 出错的关键细节。
第一次编写时，从最有用的信息开始
第一次写 CLAUDE.md 时，不需要追求一步到位。更重要的是从那些最直接影响 Claude Code 表现的信息入手。换句话说，优先写那些缺失了容易出问题的事情，而不是那些仅仅为了让文件看起来完整的内容。
最有价值的信息通常属于以下几类：
- 常用命令：构建、测试、lint 和本地开发命令，这样 Claude Code 不需要每次都猜
- 项目特定的约束和陷阱：哪些目录不能修改、哪些表用了软删除、哪些接口必须经过特定中间件
- 基本工作流：分支命名、预提交检查、PR 的基本要求
- 必要的架构上下文：monorepo 中每个目录的职责，哪些模块不能跨越某些层次边界
如果一条信息不能帮助 Claude Code 更快理解项目，也不能减少常见错误，那就没有必要急着写进文件。CLAUDE.md 的价值不在于覆盖一切，而在于清楚地传达最重要的项目事实和协作约束。
文件变大后，用 @imports 拆分
随着项目变得复杂，规则不断增加，不要把所有内容都塞进一个文件。此时可以用 @imports 将更详细的指导移到单独的文件中，然后在主 CLAUDE.md 中引用它们：
# Project Instructions
See @README.md for project overview.
See @package.json for available commands and scripts.
See @docs/testing.md for testing conventions.
See @docs/api-guidelines.md for API design rules.
这样做的好处是：主文件可以继续存放最常用、最需要优先看到的信息，而更详细的标准、工作流和约定可以分别维护。至于模块化到什么程度、哪些内容值得拆分出来，后面在最佳实践部分会进一步讨论。
CLAUDE.md 如何演进
CLAUDE.md 不是那种写一次就再也不动的文件。它更像是项目的演进记忆。真正有价值的部分通常不是一次想出来的，而是在反复协作、纠错和回顾中逐步打磨出来的。
通过协作中的问题不断完善
当然，你可以从 /init 生成的草稿开始，但之后 CLAUDE.md 应该补充什么，通常不是靠想象出来的，而是来自日常工作中不断发现的具体协作问题。它不应该依赖某个人偶尔随手记几笔，而应该成为整个团队持续记录和沉淀项目经验的地方。
这些问题通常非常具体：
- Claude Code 一直用 npm 而不是 pnpm？加一条规则
- Claude Code 总把生成的测试文件放错目录？记录正确的测试文件放置规则
- Claude Code 改了数据库 schema 文件但忘了重新构建底层模块？把依赖关系和必要的构建步骤写清楚
每次你不得不手动纠正 Claude Code，这其实就是一个强烈的信号——某条项目知识还没有被写进 CLAUDE.md。如果同样的纠正已经在团队中出现两三次了，基本就说明这个规则应该转化为共享的长期记忆了。
用 /reflection 定期回顾
前面的做法仍然依赖于人在使用中发现问题，然后记得去更新规则。/reflection 的价值在于，它把这个过程变成了一个可重复的收尾步骤。每次会话结束时，你可以让 Claude Code 总结本次协作中哪些经验值得写进 CLAUDE.md，然后把它们转化为更稳定的项目规则。
严格来说，/reflection 并不是什么神秘的内置能力，本质上它只是一个提示词，被封装成了可重复调用的命令。如果你想查看它的原始内容，可以直接看这个 reflection gist。
那段提示的核心思路是让 Claude Code 回顾刚结束的会话，判断哪些经验已经足够稳定，可以从会话级别的特定上下文转化为 CLAUDE.md 中的持久规则。用户确认后，Claude Code 就会更新 CLAUDE.md，并且不修改其他任何文件。
设置也很简单。Anthropic 官方文档提到，放在 ~/.claude/commands/ 下的 Markdown 文件会自动成为用户级命令，文件名就是命令名。所以可以把那段提示保存为：
~/.claude/commands/reflection.md
然后在 Claude Code 中直接运行：
/reflection
Claude Code 就会按照提示词回顾本次会话，并根据确认后的规则更新 CLAUDE.md。这就把 CLAUDE.md 的演进从偶尔想起来才做的事情，变成了每次会话后都可以执行的稳定步骤。
用 Insights 报告来优化
与前两种方法都更贴近单次协作会话不同，Insights 让你能从更长的时间跨度上审视使用情况。这样更容易看到哪些问题反复出现、哪些习惯已经稳定、哪些信息值得正式加入 CLAUDE.md。
Insights 是 Claude Code v2.1.x 引入的一项分析命令，主要用于分析你的 Claude Code 使用历史并生成报告。报告的一部分直接包含了对如何改进 CLAUDE.md 的建议，这使得它成为持续演进路径中尤其重要的一环。
使用方式很简单。在 Claude Code 中运行 /insights 命令，完成后在 ~/.claude/usage-data 目录下可以找到生成的 HTML 报告，你可以查看一段时间内的使用模式和相关建议。
例如，你可能会注意到自己经常提醒 Claude Code 使用某组测试命令，经常告诉它不要动某些生成目录，或者经常为同一类任务重复提供同样的背景信息。如果这些事情已经在多个会话中稳定出现，那么它们就不应该还埋在对话历史中，而应该提升到 CLAUDE.md 里。
从这个角度看，Insights 报告最好的理解方式是——它是帮助 CLAUDE.md 持续演进的工具。它提供的修改建议尤其有助于判断哪些内容已经成熟到可以正式记录下来。
更有效的演进节奏
如果把以上方法串联起来，一个自然的演进节奏通常如下：
- 从
/init开始，快速获得可用的初稿 - 记录日常协作中的问题，把反复出现的纠正写回 CLAUDE.md
- 每次会话结束时运行
/reflection，将会话经验转化为项目规则 - 定期查看 Insights 报告，识别更长时间跨度上的重复模式
- 持续精简文件，删除过时、冗余或低价值的规则
这样演进而来的 CLAUDE.md，通常比试图从第一天就面面俱到的版本有用得多——因为它不是凭空设计的，而是从真实协作中一步步打磨出来的。
CLAUDE.md 最佳实践
很多人以为 CLAUDE.md 没生效是因为文件没被加载，但实际使用中更常见的情况是：Claude Code 确实读到了这个文件，但判断其中的很大一部分内容与当前任务相关性不高，因此没有真正依赖它。换句话说，真正的问题往往不是加载机制，而是你写的内容是否足够相关、足够具体、足够有价值。
保持简洁，优先高价值信息
CLAUDE.md 本质上是 Claude Code 的额外上下文。这意味着文件越长，消耗的上下文越多，留给实际任务的空间就越少。更关键的是，当文件过于臃肿时，模型更可能将其视为低相关性的背景材料。
因此，最值得保留在主文件中的内容通常是一份简短列表：高频命令、核心项目约束、容易踩坑的历史教训，以及每次进入仓库时都可能需要的背景信息。而那些只在极少数情况下才适用的内容，或者听起来不错但没有明确执行路径的陈述，与其塞进去让文件显得全面，不如直接省略。
规则要具体，确保可执行
很多 CLAUDE.md 文件表面上看起来完整，但实际帮助不大，因为里面大量的陈述方向正确但缺乏对具体任务的指导。像”注意代码质量”、”遵守项目规范”、”修改前先理解上下文”——这些话听着没问题，但几乎无法帮助 Claude Code 在具体场景中做出更好的决策。
真正有帮助的是将规则写到可直接遵循的粒度：测试用哪个命令、哪些目录不可修改、提交前是否必须运行 lint、API 层放在哪个目录、什么情况下必须补充测试。越具体，Claude Code 在日常工作中越能理解你的真实意图。
传达意图，不只是列出规则
一个好的 CLAUDE.md 不仅仅罗列规则，更重要的是帮助 Claude Code 理解规则背后的意图。因为很多实际任务不会刚好落在规则清单的边界上。只有理解了为什么团队这样设计、为什么存在这个约束，它才能在新的场景中做出更接近你预期的判断。
举个例子，如果你只写”不要修改 src/generated/ 下的文件”，这仍然是一条规则。但如果进一步说明：这些文件是从 OpenAPI schema 自动生成的，真正的数据源是 schema 和生成工作流而不是生成结果——这样 Claude Code 就能理解这个限制的原因，下次遇到相关任务时更有可能去修改正确的地方。
渐进式披露，保持主文件精简
并非所有信息都属于根目录的 CLAUDE.md。更好的做法通常是把最常用、最稳定、跨任务的信息放在主文件中，然后在内容增长后，用 @imports 或多个不同目录级别的 CLAUDE.md 来拆分。前者改善结构和可维护性，后者让某些局部规则仅在 Claude Code 实际进入相关目录时才生效。
这样做的好处不仅仅是文件看起来更整洁。更重要的是，它减少了每次会话开始时被倒入上下文的无关信息量。保持主文件精炼，让细节只在需要时展开——这才是 CLAUDE.md 开始像一个贴心的协作指南，而不是不断堆积项目琐事的文件。
还有一点值得强调：永远不要把 API 密钥、密码、令牌或其他任何机密信息放在 CLAUDE.md 中，因为它通常会被纳入版本控制。你把凭据写进去的那一刻，就等于把它们暴露给了所有能访问仓库的人。
与 CLAUDE.md 类似的文件
在类似 Claude Code 的 AI 编码工具中，现在大多数都有自己的指令文件。但到了这一步，真正值得比较的已经不只是文件名了。更重要的是每个工具如何使用这个文件，以及它把哪些能力放在了文件之外。
指令文件对比
不只是名字不同，机制也不同
从指令系统的设计来看，Claude Code 和 Gemini CLI 其实更接近彼此。它们都把这些文件视为注入模型的持久记忆或上下文。区别在于，Claude Code 的 CLAUDE.md 有更清晰的层级结构，更容易在项目中组合多个上下文文件。Gemini CLI 也可以读取项目中的多个 GEMINI.md 文件，但更常见的是以更简单的方式拼接在一起，而且它允许把默认文件名改成 AGENTS.md，在生态兼容性上更开放。
Codex、OpenCode 和 Droid 则更像是同一演进路线的不同分支。三者都在向 AGENTS.md 靠拢，但它们共享的不只是一个文件名——它们都倾向于把 AGENTS.md 作为一个统一的入口，而把更高级的能力放在文件之外。对 Codex 来说，重点是让 AGENTS.md 成为可跨工具复用的指令格式。对 OpenCode 和 Droid 来说，重点更多是在 AGENTS.md 周围扩展更丰富的协作能力。在这条路线上，AGENTS.md 更像是一个起点，而不是整个系统。
正在形成的趋势
真正值得关注的已经不是文件本身，而是这些工具背后的指令系统正在逐渐趋同。CLAUDE.md 仍然代表一种非常有辨识度的记忆设计，尤其是在分层加载和项目上下文管理方面，它依然有明显的优势。同时，AGENTS.md 正在成为一个越来越强的跨工具格式。到 2025 年底，OpenAI 已经将 AGENTS.md 贡献给了 Agentic AI Foundation，并明确将其描述为一个简单、开放、可互操作的标准。Gemini CLI、OpenCode、Droid 等也在不同程度地向这个约定靠拢。
这意味着未来在不同的 AI 编码智能体之间切换，成本很可能会越来越低。但在目前阶段，文件名可能正在趋同，而能力模型还远未统一——有的强调分层记忆，有的强调智能体编排，有的把技能、子智能体、插件和组织级配置放在指令文件之外。所以 CLAUDE.md 的价值不仅仅是文件本身，更是它背后整个组织项目上下文的方式。
总结
本文从 CLAUDE.md 是什么开始，依次介绍了它的加载方式、编写方法、演进策略、最佳实践，以及与同类工具指令系统的关系。真正重要的是理解它背后更大的模式：一种组织项目上下文、保存协作约束、让 AI 智能体更可靠地参与开发的方式。
在实际使用中，CLAUDE.md 最好的工作方式是：从一个可用的版本开始，然后在真实协作中不断补充、精简和打磨，而不是试图从第一天就写出包罗万象的文档。无论未来工具间的文件名和实现方式如何演变，这个基本思路会一直有价值——把项目经验转化为长期规则，让 AI 能更一致地理解上下文。这就是为什么 CLAUDE.md 值得认真理解。