CLAUDE.md 的作用以及使用技巧：让 Claude 更懂你的项目

如果把 Claude Code 看成一位会不断加入新项目的工程搭档, 那么 CLAUDE.md 就是它进入项目后的“长期说明书”。它不是一次性提示词, 而是一份会在每次会话开始时被读取的持久指令文件, 用来告诉 Claude 这个项目怎么工作、哪些规范最重要、什么事情必须优先遵守。

从官方文档来看, Claude Code 主要通过两种方式跨会话记住信息: 一种是你手动编写的 CLAUDE.md, 另一种是 Claude 自己沉淀的自动记忆。理解 CLAUDE.md 的定位, 本质上就是理解你应该把哪些内容明确写成规则, 让 Claude 在每次开始工作前就“带着说明书上岗”。

什么是 CLAUDE.md, 它到底有什么用

CLAUDE.md 是一个 Markdown 文件, 可以为项目、个人工作流或整个组织提供持久指令。它适合承载这几类信息:

• 构建和测试命令
• 编码规范和命名约定
• 项目架构和目录约束
• 团队约定的工作流
• Claude 不容易从代码里自行推断出来的隐性规则

它最大的价值, 不是替你“记笔记”, 而是把原本散落在 README、口头约定、团队习惯里的要求, 固化成 Claude 每次都会读取的上下文。这样做能明显减少重复解释, 也能提高 Claude 在不同会话里输出的一致性。

举个很实际的例子: 如果你的项目要求“提交前必须运行 npm test”“接口处理器统一放在 src/api/handlers/”“前端统一使用 2 空格缩进”, 这些都适合写进 CLAUDE.md。相比每次临时补一句, 固定规则会稳定得多。

CLAUDE.md 和自动记忆有什么区别

很多人第一次接触 Claude Code 时, 容易把 CLAUDE.md 和自动记忆混在一起。它们都能跨会话保留信息, 但角色完全不同。

CLAUDE.md 是你写给 Claude 的明确规则, 更像“操作手册”; 自动记忆是 Claude 根据纠正、偏好和工作过程自己积累的笔记, 更像“工作经验”。前者适合放你希望它稳定遵守的要求, 后者适合沉淀调试结论、构建命令、代码风格偏好和一些反复出现的项目经验。

这也意味着一个很实用的判断标准:

• 想让 Claude 明确按你的方式做事, 写进 CLAUDE.md
• 想让 Claude 逐步记住某些经验和偏好, 交给自动记忆

官方还特别提到, 自动记忆默认开启, 且需要 Claude Code v2.1.59 或更高版本。自动记忆中的 MEMORY.md 只会在会话开始时加载前 200 行, 而 CLAUDE.md 会完整加载。不过, 完整加载不代表越长越好, 过长文件会占用更多上下文, 也可能让遵守效果下降。

CLAUDE.md 应该放在哪里

官方给了三类典型位置, 分别对应三种作用域:

• 项目级: ./CLAUDE.md 或 ./.claude/CLAUDE.md
• 用户级: ~/.claude/CLAUDE.md
• 组织级: 系统托管位置, 例如 macOS 的 /Library/Application Support/ClaudeCode/CLAUDE.md

一个很好记的原则是: 越具体, 优先级越高。项目规则应该尽量写在项目里, 个人偏好放在用户级, 公司统一的安全或合规要求放在组织级。这样做的好处是边界清楚, 也更容易维护。

如果你刚开始搭建, 可以直接运行 /init。Claude 会分析代码库并生成一份起始版 CLAUDE.md, 通常会包含构建命令、测试方式和它观察到的项目约定。这个功能很适合用来快速起步, 但真正有价值的内容, 往往还是你后续补进去的“项目隐性知识”。

如何写出更有效的 CLAUDE.md

根据官方说明, CLAUDE.md 的内容本质上会作为上下文提供给 Claude, 而不是绝对强制配置。因此, 写法本身会直接影响遵守效果。

1. 尽量具体, 不要写成口号

“正确格式化代码”这种描述太模糊, Claude 很难判断什么算“正确”。而“使用 2 空格缩进”“提交前运行 npm test”这种规则就更容易执行, 也更容易验证。

2. 控制长度, 每个文件尽量在 200 行以内

这里要特别注意一个常见误解: 官方并不是说超过 200 行就失效, 而是建议把单个 CLAUDE.md 控制在 200 行以下, 因为文件越长, 占用的上下文越多, Claude 的遵守度可能越低。

3. 用结构化写法提高可读性

使用 Markdown 标题、小节和项目符号来组织内容, 比把规则堆成一大段文字更有效。Claude 读取结构化内容的方式和人差不多, 分区清楚会更容易抓住重点。

4. 定期清理冲突规则

如果不同层级的 CLAUDE.md 或规则文件里出现冲突, Claude 可能会在不同规则之间摇摆。对团队来说, 定期审查过时内容和重复要求, 比一味加新规则更重要。

几个高频使用技巧

用 @ 导入外部资料, 避免把主文件写得过大

CLAUDE.md 支持 @path/to/import 语法导入其他文件, 比如 @README、@package.json 或项目里的工作流说明。这样可以把主文件保留为“规则索引”, 把详细内容拆到更适合维护的位置。

这个能力尤其适合两类场景:

• 项目概览、脚本命令已经写在现有文件里, 不想重复维护
• 你希望共享项目规则, 但某些个人偏好不想提交到仓库

官方也提到, 你可以在共享 CLAUDE.md 中导入主目录下的个人文件, 比如 @~/.claude/my-project-instructions.md。这让“团队共识”和“个人习惯”可以并存, 而不是互相污染。

用 .claude/rules/ 拆分规则, 让规则按需生效

当项目变大时, 不建议把所有规范都塞进一个 CLAUDE.md。更合适的做法是把规则拆到 .claude/rules/ 目录下, 每个文件只负责一个主题, 比如测试规范、API 设计、安全要求等。

如果某条规则只对特定文件生效, 还可以给规则文件加 paths frontmatter。这样 Claude 只有在处理匹配文件时才会加载这条规则, 既减少噪音, 也节省上下文空间。对于 monorepo 或前后端混合项目, 这会非常实用。

理解加载顺序, 避免“我明明写了, 为什么没生效”

Claude Code 会从当前工作目录向上遍历, 加载沿途目录中的 CLAUDE.md。而子目录中的 CLAUDE.md 不会在启动时全部加载, 只有当 Claude 读取这些目录中的文件时才会按需带入。

这意味着一个常见现象: 你把规则写在某个深层子目录里, 但 Claude 当前还没有碰到该目录的文件, 那么这条规则暂时就不会进入上下文。理解这一点后, 很多“看起来像失效”的情况其实只是加载时机不同。

在大型仓库里主动排除无关规则

官方提供了 claudeMdExcludes 配置, 可以在大型 monorepo 中跳过和当前工作无关的 CLAUDE.md 或规则目录。如果一个仓库里存在多个团队的说明文件, 这个配置能帮助你减少无关上下文, 提高 Claude 聚焦当前任务的概率。

常见问题与排查思路

如果你感觉 Claude 没有遵循 CLAUDE.md, 可以按下面的顺序排查:

1. 先确认文件到底有没有被加载

最直接的方法是运行 /memory。官方说明里提到, 这个命令会列出当前会话已加载的 CLAUDE.md 和规则文件。如果文件根本不在列表里, 问题就不是“Claude 不听话”, 而是“Claude 没看到它”。

2. 检查文件位置和作用域是否合理

有些问题来自放错位置。比如本来是项目规则, 却写进了个人文件; 或者你在 --add-dir 引入的额外目录里写了规则, 但没有设置 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 去加载它们。

3. 把模糊要求改成可执行要求

“代码写漂亮一点”“保持项目整洁”这类描述很难稳定执行。把它们改写成可检查的规则后, 往往就会明显改善。

4. 排查不同规则文件之间的冲突

如果项目级、用户级和规则目录里对同一件事给出不同说法, Claude 可能会摇摆。尤其在多人协作项目里, 这类冲突比“缺少规则”更常见。

5. 需要更强约束时, 不要误用 CLAUDE.md

官方明确指出, CLAUDE.md 是作为用户消息传递的上下文, 不是系统提示本身。如果你要的是系统提示级别的强约束, 更适合使用 --append-system-prompt。这类方式更适合脚本和自动化场景, 不一定适合日常交互。

一个适合团队落地的维护建议

如果你准备让 CLAUDE.md 在团队里长期发挥作用, 一个实用的做法是把它拆成三层:

• 主 CLAUDE.md 只保留核心协作规则和索引
• .claude/rules/ 放按主题拆分的项目规则
• 用户级 ~/.claude/CLAUDE.md 或 ~/.claude/rules/ 存放个人偏好

这样既能保证团队规则被版本控制共享, 也不会把每个人的习惯混进项目仓库。对大型团队或多项目协作来说, 这是比“把一切都写进一个文件”更可持续的方式。

结语

CLAUDE.md 的本质, 不是“给 AI 多塞一点提示词”, 而是把项目里的关键协作知识长期结构化。写得好的 CLAUDE.md, 能让 Claude 更快进入状态、减少重复沟通、提高输出一致性; 写得差的 CLAUDE.md, 则可能因为冗长、冲突和模糊而适得其反。

如果你只记住一条经验, 那就是: 把 CLAUDE.md 写成一份简洁、具体、可执行的项目协作说明书, 而不是一份面面俱到的大而全文档。这样 Claude 才更有机会真正“懂你的项目”。