如果您绘制近年来AI编码工具的演变时间线，Claude Code可能是值得单独标记的一个节点。Anthropic于2025年2月首次将其带给开发者，当时它仍处于早期公开预览阶段。到2025年5月，它已开始覆盖更广泛的开发者受众。

使其与众不同的不是它添加了另一个用于聊天的模型界面，而是AI代理第一次真正进入终端，能够读取仓库、编辑文件、运行命令、修复问题并推动任务向前发展。从那一刻起，软件开发的重心已经开始悄然转移。

什么是CLAUDE.md

CLAUDE.md是Claude Code在每个会话开始时自动读取的Markdown文件。在这个文件中，您可以编写说明、规则和偏好，Claude Code会在整个后续交互过程中遵循它们。

有人曾经分享过一个有趣的梗图，基于2024年巴黎奥运会射击项目的对比照片，调侃说Claude Code用户分为两组：

• 左边：选手全副武装，疯狂安装各种插件

• 右边：土耳其神枪手平静地站着，一只手插在口袋里，只依靠一个CLAUDE.md

尽管这只是个玩笑，但它指出了一个事实：与其花时间摆弄华丽的插件设置，不如花时间写好一个CLAUDE.md。真正投入精力的用户通常会获得超出预期的体验，因为CLAUDE.md从根本上改变了AI与您项目的交互方式。

CLAUDE.md的核心价值：它将Claude Code从通用AI助手转变为贴合您项目的专属开发工具。

CLAUDE.md的加载方式

CLAUDE.md不是简单地位于项目根目录的Markdown文件。Claude Code通过分层加载模型读取内存和指令。不同位置的CLAUDE.md文件适用于不同的范围：

• 用户级：~/.claude/CLAUDE.md - 影响所有项目

• 项目级：项目根目录的CLAUDE.md - 影响当前仓库

• 子目录级：特定子目录中的CLAUDE.md - 仅在该目录内生效

加载规则

• 当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

快速开始：使用/init命令

最简单的入门方法是在项目根目录运行Claude Code的/init命令，让它为您生成初稿：

$ claude > /init

/init会查看您的技术栈、目录结构和常用命令，然后生成一个CLAUDE.md文件，为您提供基本的起始框架。

第一次写作时，从最有用的信息开始

当您第一次编写CLAUDE.md时，不需要立即追求完整性。更重要的是从最直接影响Claude Code性能的信息开始。

最值得首先添加的信息通常分为几个类别：

• 常用命令：构建、测试、lint和本地开发命令，这样Claude Code就不必每次都猜测

• 项目特定约束和陷阱：哪些目录不能编辑，哪些表使用软删除，哪些接口必须通过特定中间件

• 基本工作流程：分支命名、预提交检查和基准PR要求

• 基本架构上下文：单体仓库中每个目录的职责，以及哪些模块不应跨越某些分层边界

如果一条信息无助于Claude Code更快地理解项目，也不能减少常见错误，那么就没有理由急于将其添加到文件中。

随着文件增长，使用@imports分割

随着项目变得更加复杂和规则不断增长，不要将所有内容都塞进一个文件中。此时，您可以使用@imports将更详细的指南移动到单独的文件中，并从主CLAUDE.md中引用它们。

# 项目说明
有关项目概述，请参见 @README.md。
有关可用命令和脚本，请参见 @package.json。
有关测试约定，请参见 @docs/testing.md。
有关API设计规则，请参见 @docs/api-guidelines.md。

CLAUDE.md的演变

CLAUDE.md不是那种写一次就再也不用碰的文件。它更像是项目不断发展的记忆。真正有价值的部分通常不是您在一次会议中凭空发明的东西，而是通过反复协作、纠正和回顾逐渐完善的内容。

通过协作问题持续改进

您可以从/init生成的草稿开始，但CLAUDE.md后来应该添加的内容通常不是来自想象，而是来自在日常工作中反复发现的具体协作问题。

这些问题通常非常具体：

• Claude Code一直使用npm而不是pnpm？添加规则

• Claude Code一直将生成的测试文件放在错误的目录中？记录正确的测试文件放置规则

• Claude Code编辑了数据库模式文件但忘记重建底层模块？清楚地写下依赖关系和所需的构建步骤

使用/reflection进行定期回顾

/reflection的价值在于它能够将经验转化为可重复的总结步骤。在每个会话结束时，您可以要求Claude Code总结该轮协作中有哪些内容值得添加到CLAUDE.md中，然后将这些要点转化为更稳定的项目规则。

使用Insights报告进行优化

与前两种方法相比，Insights让您可以更全面地查看更长一段时间的使用情况。这样更容易看到哪些问题持续存在，哪些习惯已经稳定，哪些信息值得正式添加到CLAUDE.md中。

CLAUDE.md最佳实践

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

CLAUDE.md本质上是Claude Code的额外上下文。文件越长，消耗的上下文越多，留给实际任务的空间就越少。更重要的是，当文件变得过于杂乱时，模型更有可能将其视为低相关性的背景材料。

具体说明，以便规则实际可执行

很多CLAUDE.md文件表面上看起来很完整，但实际上帮助不大，因为它们的许多陈述指向正确的方向，但没有为实际任务提供具体指导。

真正有帮助的是在可直接遵循的层面上写作：测试应该使用哪个命令，哪些目录不能编辑，提交前是否必须运行lint，API层属于哪个目录，以及在什么情况下必须添加测试。

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

一个好的CLAUDE.md不仅仅列出规则。更重要的是，它帮助Claude Code理解规则背后的意图，因为许多真实任务不会整齐地落在规则检查表的边缘。

例如，如果您只写"不要修改src/generated/下的文件"，那仍然是一条规则。但如果您进一步解释这些文件是从OpenAPI模式自动生成的，并且真正的事实来源是模式和生成工作流，而不是生成的输出，那么Claude Code就能理解为什么存在这种限制，并且在下次相关任务出现时更有可能修改正确的内容。

使用渐进式披露并保持主文件的纪律性

并非所有信息都属于根目录的CLAUDE.md。更好的方法通常是先在主文件中保留最常见、稳定、跨任务的信息，一旦内容增长，就使用@imports或不同目录级别的多个CLAUDE.md文件进行分割。

还有一点值得强调：永远不要在CLAUDE.md中放置API密钥、密码、令牌或任何其他机密，因为它通常会进入版本控制。

与其他AI编码工具中的类似文件比较

在类似于Claude Code的AI编码工具中，大多数现在都有自己的说明文件。但真正值得比较的不仅仅是文件名，更重要的是每个工具如何使用该文件，以及哪些功能保持在文件本身之外。

从说明系统设计的角度来看，Claude Code和Gemini CLI实际上更接近彼此。它们都将这些文件视为注入模型的持久内存或上下文。

Codex、OpenCode和Droid看起来更像是同一进化的不同分支。三者都在向AGENTS.md靠拢，但它们共享的不仅仅是一个通用文件名。

开始形成的趋势

真正值得关注的不再是文件本身，而是这些工具背后的说明系统如何逐渐融合。CLAUDE.md仍然代表着一种非常可识别的内存设计，特别是在分层加载和项目上下文管理方面，它仍然具有明显的优势。

总结

本文从CLAUDE.md是什么开始，介绍了它的加载方式、如何编写、如何演变、最佳实践，以及它与类似工具的说明系统的关系。

在实际使用中，CLAUDE.md最有效的方式是从一个可用版本开始，然后通过真实协作不断添加、修剪和收紧，而不是试图从第一天起就写一个包罗万象的文档。无论未来工具的文件名和实现如何演变，基本理念都将保持价值：将项目经验转化为长期规则，以便AI能够更一致地理解上下文。

这就是为什么CLAUDE.md值得认真理解。