Claude Code 完全指南：CLAUDE.md

公众号名称：TouchAI

作者名称：zhao zhiming

发布时间：2026-05-13 08:08

关于 Claude Code 中 CLAUDE.md 文件的全面指南，包括其加载方式、编写方法、最佳实践，以及与其他 AI 编程工具中类似文件的比较。

如果绘制一张近年来 AI 编程工具演变的时间线，Claude Code 很可能是其中一个值得单独标注的点。Anthropic 在 2025 年 2 月首次将其带给开发者，当时它还处于早期公开预览阶段。到 2025 年 5 月，它开始接触到更广泛的开发者群体。Claude Code 之所以与众不同，不是因为它又增加了一个聊天式的模型界面，而是因为它首次让 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 将在整个交互过程中遵循它们。

网上有人分享过一个有趣的梗图，基于 2024 年巴黎奥运会射击比赛的对比照片。它开玩笑说 Claude Code 用户分为两类：左边是全副武装、疯狂安装各种插件的参赛者；右边是单手插兜、冷静站立的土耳其射击手，只靠一个 CLAUDE.md 文件：

虽然这只是一个玩笑，但它指出了一个真实的问题：与其花时间折腾花哨的插件配置，不如花时间写好一个 CLAUDE.md。真正在这方面下功夫的用户，往往能获得远超预期的体验，因为 CLAUDE.md 从根本上改变了 AI 与你项目的交互方式。

这里有一个有用的类比：如果把 Claude Code 想象成加入你团队的一名新开发者，那么 CLAUDE.md 就是你的项目 onboarding 手册。没有这本手册，新队友就得反复问一些基本问题：这个项目怎么构建？用哪个测试框架？遵循什么代码风格？有了手册，他们从第一天起就能按照团队的期望高效工作。

_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 命令，让它为你生成第一版草稿：

$ claude
> /init

/init 会查看你的技术栈、目录结构和常用命令，然后生成一个 CLAUDE.md 文件，给你一个基本的起点骨架。但这只解决了如何从空白文件开始的问题，并不意味着你已经有了一个真正适合你项目的 CLAUDE.md。

拿到这份草稿后，你通常至少还需要一轮编辑。原因很简单：/init 倾向于生成宽泛而全面的内容。它会尝试包含所有能检测到的信息，但其中一些信息对你的项目并不重要，另一些信息虽然正确，却不足以有效指导 Claude Code。CLAUDE.md 并不是越长越好。一方面，它会占用上下文窗口空间。另一方面，一旦信息变得过于分散和通用，Claude Code 就更难识别出真正重要的约束。更好的做法是：先删除那些已经在别处文档化了的、低价值的、泛泛的或冗余的信息，然后添加只有你团队才知道的项目知识，尤其是那些最容易导致 Claude Code 犯错的关键细节。

初次编写时，从最有用的信息开始

当你第一次编写 CLAUDE.md 时，不需要一开始就追求完整性。更重要的是从那些最直接影响 Claude Code 表现的信息开始。也就是说，优先考虑缺失后容易出问题的信息，而不是那些仅仅让文件看起来完整的信息。

最应该优先添加的信息通常集中在几类：

常用命令：构建、测试、lint 和本地开发命令，这样 Claude Code 就不用每次都靠猜
项目特有的约束和坑点：哪些目录绝对不能改、哪些表用了软删除、哪些接口必须经过特定中间件
基本工作流：分支命名规范、pre-commit 检查、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 编辑了 DB schema 文件但忘了重新生成底层模块？把依赖关系和必要的构建步骤写清楚

每次你不得不手动纠正 Claude Code 时，这实际上是一个强烈的信号：某条项目知识还没有被写入 CLAUDE.md。如果同一条纠正在整个团队中已经发生了两三次，通常就足以说明这条规则应该变成共享的、长期的记忆了。

使用 /reflection 进行定期复盘

前面的方法仍然依赖于人在使用过程中发现问题，然后想起来去更新规则。而 /reflection 的价值在于，它把这件事变成了一个可重复的、会话结束时的”复盘”步骤。在每个会话结束时，你可以让 Claude Code 总结本次协作中有哪些经验值得添加到 CLAUDE.md 中，然后将这些点转化为更稳定的项目规则。

严格来说，/reflection 并不是什么神秘的 built-in 能力。它本质上就是一个 prompt，被打包成一个可以重复调用的命令。如果你想看它的原始内容，可以直接查看这个 reflection gist(https://gist.github.com/a-c-m/f4cead5ca125d2eaad073dfd71efbcfc)。

该 prompt 的核心思想是让 Claude Code 回顾刚刚结束的会话，判断哪些经验已经足够稳定，可以从”本次会话特定的上下文”转变为”持久的、写在 CLAUDE.md 里的规则”。在用户确认后，Claude Code 会更新 CLAUDE.md，并且不会修改任何其他文件。

设置也很简单。Anthropic 官方文档提到，放在 ～/.claude/commands/ 下的 Markdown 文件会自动成为用户级命令，文件名就是命令名。所以你可以把那个 prompt 保存为：

～/.claude/commands/reflection.md

然后在 Claude Code 中直接运行：

/reflection

Claude Code 会按照那个 prompt 来回顾会话，并用确认后的规则更新 CLAUDE.md。这使 CLAUDE.md 的演进从”人们偶尔想起来做的事情”变成了一个可以在每次会话后执行的稳定步骤。

使用 Insights 报告来优化 CLAUDE.md

与前两种更贴近单个协作会话的方法相比，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 收敛，但它们共享的不仅仅是文件名。它们也倾向于将其作为一个统一的入口点，同时将更高级的能力移到文件之外。对于 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 编程智能体之间切换的成本可能会越来越低。但在目前这个阶段，文件名可能在趋同，但能力模型仍然远未统一。有些工具强调分层记忆，有些强调智能体编排，有些则把 skills、subagents、plugins 和组织级配置都放在指令文件之外。因此，CLAUDE.md 的价值不仅仅是这个文件本身，而是它背后组织项目上下文的整套方式。

总结

本文从 CLAUDE.md 是什么开始，逐步介绍了它的加载方式、编写方法、演进过程、最佳实践，以及它与同类工具指令系统的关系。真正重要的是理解其背后的更广泛的模式：一种组织项目上下文、沉淀协作约束、让 AI 智能体更可靠地参与开发的方式。

在实际使用中，CLAUDE.md 最好的工作方式是：从一个可用的版本开始，然后通过真实协作不断添加、精简、收紧，而不是试图从第一天起就写出一份包罗万象的文档。无论未来文件名和实现在各个工具之间如何演变，其背后的基本思想都将保持价值：将项目经验转化为长久的规则，让 AI 能够更一致地理解上下文。这就是 CLAUDE.md 值得认真理解的原因。

参考资源

How to Write a Good CLAUDE.md File(https://www.builder.io/blog/claude-md-guide)
Writing a good CLAUDE.md (https://www.humanlayer.dev/blog/writing-a-good-claude-md)
Understanding CLAUDE.md Loading in Large Monorepos(https://github.com/shanraisshan/claude-code-best-practice/blob/main/reports/claude-md-for-larger-mono-repos.md)
Manage Claude’s memory(https://code.claude.com/docs/en/memory)
AGENTS.md(https://agents.md/)

内容效果不满意？点此反馈