Hacker and Geeker's Way

如果把近几年 AI 编程工具的发展画成一条时间线，Claude Code 大概是最值得单独标记的节点之一。Anthropic 在 2025 年 2 月第一次把它带到开发者面前，那时它还处在一个对外开放的早期试用阶段，到了 2025 年 5 月，它开始正式走向更大范围的开发者。它最不寻常的地方，不是又多了一个能聊天的模型界面，而是第一次让一个 AI agent 真正住进 terminal，去读仓库、改文件、跑命令、修问题、推进任务。那一刻开始，软件开发的重心就已经悄悄变了。过去很长一段时间里，开发者的主要工作是亲手实现，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 在后续的交互中会遵循这些指令来工作。

有网友发过一张很有意思的梗图，用 2024 巴黎奥运会射击比赛的对比图来调侃 Claude Code 的用户分为两类，左边是全副武装、疯狂安装各种插件的选手，右边是单手插兜、只靠一个 CLAUDE.md 就淡定搞定一切的土耳其神射手：

虽然这只是一个玩笑，但它揭示了一个事实：与其折腾各种花哨的插件配置，不如花时间写好一个 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.md 本身。

加载规则

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 命令，让它先帮你生成一个初稿：

1
2

$ 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 引进来。

1
2
3
4
5
6

# 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 修改了 DB schema 文件，却没有重新构建底层模块？把这条依赖关系和构建要求写清楚

每次遇到需要手动纠正 Claude Code 的情况，其实都是一个很强的信号，说明这里存在一条还没有被写进 CLAUDE.md 的项目知识，如果同样的纠正已经在团队里出现了两三次，那基本就说明，这件事应该被整理成大家共享的长期记忆。

用 /reflection 定期复盘

如果说前面那种做法，还是依赖人在使用过程中边发现问题边补规则，那么 /reflection 的价值就在于，它把这件事变成了一个可以固定执行的收尾动作。每次会话结束后，都可以让 Claude Code 回头总结这一轮协作里有哪些内容值得沉淀进 CLAUDE.md，再把它整理成更稳定的项目规则。

严格来说，/reflection 并不是什么神秘的内置能力，它本质上就是一段提示词，只不过这段提示词被包装成了一个可以重复调用的命令。如果你想看它的原始内容，可以直接看这个 reflection gist。

这段提示词的核心思路，是让 Claude Code 在会话结束时回头审视刚刚这轮协作，判断哪些经验已经足够稳定，值得从这次聊天内容中提炼成 CLAUDE.md 里的长期规则，用户确认后就会去更新 CLAUDE.md，不会改其他文件。

使用方式也很简单，Anthropic 官方文档里提到，放在 ~/.claude/commands/ 目录下的 Markdown 文件，会自动变成用户级命令，文件名就是命令名，所以你可以把这段提示词保存为：

1

~/.claude/commands/reflection.md

然后在 Claude Code 里直接执行：

1

/reflection

它就会按这段提示词的要求，回顾本次会话，并把确认后的规则更新到 CLAUDE.md 里，这样一来，CLAUDE.md 的演进就不再只是靠人临时想起来再去补，而是变成了每个会话结束后都能稳定执行的一步。

利用 Insights 报告优化

相比前面两种更贴近单次协作的方式，通过 Insights 这种方式，你可以把视角拉长到一段时间的整体使用过程，再去看哪些问题反复出现，哪些习惯已经稳定，哪些内容值得正式写进 CLAUDE.md。

Insights 是 Claude Code v2.1.x 新增的一个分析命令，主要用来分析你使用 Claude Code 的历史记录，并生成一份报告，其中有一部分内容会直接给出针对 CLAUDE.md 的修改建议，这其实就是 CLAUDE.md 持续演进的一个很重要的方向。

它的使用方式也很直接，进入 Claude Code 之后，执行 /insights 命令即可，命令运行完成后，你就可以在 ~/.claude/usage-data 目录下看到生成好的 HTML 报告，再从里面去看这段时间的使用情况和相关建议。

比如，你可能会发现自己经常重复提醒 Claude Code 使用某一套测试命令，经常要求它不要碰某些生成目录，或者经常在同一种任务里补充同一类背景信息，这些内容如果已经在多次会话里稳定出现，那它们就很可能不该继续停留在聊天记录里，而应该被整理进 CLAUDE.md。

所以对我们来说，Insights 报告更像一个帮助 CLAUDE.md 持续演进的工具，尤其是其中给出的修改建议，可以帮助你判断哪些内容已经值得正式沉淀下来。

一个更有效的演进节奏

如果把前面这些方法串起来，一个比较自然的演进节奏大概会是这样：

1. 先用 /init 起步，快速得到一个可用的初稿
2. 在日常协作里记录问题，把反复纠正的内容写回 CLAUDE.md
3. 在会话结束时运行 /reflection，把本次会话里值得沉淀的规则整理回 CLAUDE.md
4. 定期看 Insights 报告，从一段时间的使用记录里找重复模式
5. 持续删改和收紧内容，把过时、重复、低价值的规则清出去

这样演进出来的 CLAUDE.md，通常会比一开始就试图写得面面俱到的版本更有用，因为它不是凭空设计出来的，而是从真实协作里一点点打磨出来的。

CLAUDE.md 最佳实践

很多人以为 CLAUDE.md 没生效，是因为它没有被加载，但在真实使用中更常见的情况是，Claude Code 虽然看到了这份文件，却判断其中不少内容和当前任务关系不大，于是没有真正依赖它。也就是说，问题往往不只是加载机制，而是你写进去的内容，到底够不够相关、够不够具体、够不够值得被长期保留。所以这一节更想讨论的，不是如何继续往里面补充更多规则，而是怎样判断什么内容更值得留下。

保持简洁，优先保留高价值信息

CLAUDE.md 本质上是在给 Claude Code 提供额外上下文，这意味着它写得越长，占用的上下文就越多，真正留给当前任务的空间就越少，更重要的是，信息一旦太杂，模型反而更容易把它判断成低相关背景。

所以主文件里最值得留下来的，通常是这些内容：高频命令、项目的核心约束、容易踩坑的历史经验、以及那些每次进入仓库都可能用得上的背景信息。至于只在少数场景才成立、或者说了也没有明确执行方式的内容，宁可不写，也不要为了看起来完整就硬塞进去。

写具体，让规则真正可执行

很多 CLAUDE.md 看起来很完整，但真正能帮上忙的内容并不多，因为里面有不少表述虽然方向没错，却很难直接指导具体任务。像注意代码质量、遵守项目规范、修改前先理解上下文这类表述，听起来没有问题，但几乎不能帮助 Claude Code 在具体任务里做出更好的判断。

真正有用的内容，应该尽量写到可以直接执行的程度，比如测试要跑哪条命令、哪些目录不能改、提交前要不要跑 lint、接口层统一放在哪个目录、什么情况下必须补测试。你写得越具体，Claude Code 在实际工作里就越容易理解你的真实要求。

传达意图，而不仅仅是罗列规则

好的 CLAUDE.md 不只是把规则列出来，更重要的是让 Claude Code 理解这些规则背后的意图，因为很多真实任务都不会刚好落在规则清单的边界里，只有当它明白团队为什么这么设计，为什么要遵守这些约束，它在遇到新情况时才更容易做出接近你预期的判断。

比如你只写不要修改 src/generated/ 下面的文件，这当然也是一条规则，但如果你进一步说明，这些文件是根据 OpenAPI schema 自动生成的，真正需要修改的是 schema 和生成流程，而不是生成结果本身，那 Claude Code 在后续处理相关任务时，就更容易理解这个限制为什么存在，也更容易沿着正确路径去修改代码了。

采用渐进式披露，主文件保持克制

不是所有信息都适合放在根目录的主 CLAUDE.md 里，更合理的做法通常是，先把最常用、最稳定、跨任务都成立的内容留在主文件里，等内容逐渐变多，再通过 @imports 或不同层级的 CLAUDE.md 做拆分。前者主要是为了让内容结构更清晰，后者则可以让某些更局部的规则只在进入对应目录时再参与当前任务。

这样做的好处，不只是让文件看起来更整洁，更关键的是能减少无关信息在每次会话一开始就一股脑的进入上下文。主文件保持克制，细节按需展开，这样 CLAUDE.md 才更像一份有判断力的协作说明，而不是一个不断膨胀的知识堆栈。

另外还有一点必须记住，绝对不要在 CLAUDE.md 里放 API key、密码、token 或任何敏感凭据，因为CLAUDE.md 往往会进入版本控制，一旦写进去，就等于把这些信息暴露给所有能访问仓库的人。

CLAUDE.md 同类

在和 Claude Code 同类型的 AI 编程工具里，大多数工具都有各自对应的指令文件，不过发展到今天，它们之间真正值得比较的，已经不只是文件名的不同，更重要的是这些工具如何使用这些文件，又把哪些能力继续放到了文件之外。

指令文件对比

不只是名字不同，机制也不一样

如果从指令系统的设计来看，Claude Code 和 Gemini CLI 其实更接近，它们都把这类文件当成持续注入模型上下文的 memory/context 来处理。区别在于，Claude Code 的特点是 CLAUDE.md 的层级结构更清晰，可以在项目目录中组合多个 context 文件；而 Gemini CLI 虽然也可以从项目目录读取多个 GEMINI.md 作为上下文，但通常是简单拼接后一起提供给模型，而且还允许你把默认文件名改成 AGENTS.md，因此它在生态兼容性上更开放一些。

Codex、OpenCode 和 Droid 则更像另一条路线，它们都在向 AGENTS.md 靠拢，但共同点并不只是一份同名文件，而是都把它当成统一入口，再把更复杂的能力拆到规则文件之外。对 Codex 来说，重点在于把 AGENTS.md 变成跨工具可复用的通用格式，对 OpenCode 和 Droid 来说，重点则更偏向围绕 AGENTS.md 继续扩展更完整的协作能力。换句话说，在这条路线上，AGENTS.md 更像起点，而不是全部。

一个正在形成的趋势

真正值得关注的已经不是文件本身，而是背后的指令体系正在如何收敛。CLAUDE.md 仍然代表着一套很有辨识度的 memory 设计，尤其是在分层加载和项目上下文管理上依然有自己的优势，但与此同时，AGENTS.md 也正在变成一个越来越强的跨工具格式。OpenAI 在 2025 年底已经把 AGENTS.md 贡献给了 Agentic AI Foundation，并明确把它描述成一个简单、开放、可互操作的标准，Gemini CLI、OpenCode、Droid 等工具也都在不同程度上向这套约定靠拢。

这意味着，未来你在不同 AI coding agent 之间切换时，维护成本大概率会继续下降，但在当下这个阶段，文件名可能会逐渐趋同，功能模型却还没有真正统一。有的工具更强调 memory 分层，有的工具更强调 agent 编排，有的工具则把技能、子代理、插件和组织级配置拆到了指令文件之外，所以 CLAUDE.md 的价值并不只是文件本身，而是它背后那套完整的上下文组织方式。

总结

本文从 CLAUDE.md 是什么开始，依次梳理了它的加载机制、编写方式、演进节奏、最佳实践，以及它和其他同类工具指令体系之间的关系。真正重要的，是理解它背后那套组织项目上下文、沉淀协作约束、让 AI agent 更稳定参与开发的方式。

在实际使用里，CLAUDE.md 更适合从一个可用版本开始，再随着真实协作不断补充、删改和收紧，而不是一开始就试图写得面面俱到。无论未来不同工具在文件名和实现方式上如何继续演化，把项目经验整理成长期规则、让 AI 更稳定理解上下文的思路都不会过时，这也是 CLAUDE.md 值得认真理解的原因。

参考

• How to Write a Good CLAUDE.md File
• Writing a good CLAUDE.md
• Understanding CLAUDE.md Loading in Large Monorepos
• Manage Claude’s memory
• AGENTS.md

关注我，一起学习各种最新的 AI 和编程开发技术，欢迎交流，如果你有什么想问想说的，欢迎在评论区留言。