为什么顶级开发者都在维护一个叫 CLAUDE.md 的文件

CLAUDE.md is infrastructure, not documentation. It represents not just what your codebase is, but what Claude has learned about working with it. CLAUDE.md 是基础设施，不是文档。它代表的不只是你的代码库是什么，而是 Claude 学会了如何与它协作。

写在前面

大多数人用 Claude Code 的姿势是这样的：打开IDE，让Claude Code看一遍项目文档和代码，然后再提自己的需求。

Boris Bershansky，Claude Code 的创始人，就不这么做。

他维护了一个叫 CLAUDE.md 的文件，放在项目根目录，Claude 每次启动时会自动读取。团队里所有人共用同一套上下文，这个文件每周更新多次。

有了这个文件，让 AI 永久记住你的项目规范。也就大概 50 到 100 行，就可以不再让人不再重复解释，不再踩同样的坑。

一、CLAUDE.md 是什么？

CLAUDE.md 是一个放在项目根目录的 Markdown 文件。Claude Code 每次启动时自动读取它，把里面的内容作为持久上下文。

它解决的是一个根本问题：Claude 没有记忆。每次开启新会话，它不知道：你的项目用什么技术栈，不知道代码风格和命名规范是什么，不知道有哪些目录或文件，更不知道你上次遇到了哪些坑、怎么解决，也不知道项目进度到哪里了。

CLAUDE.md 的存在，就是把这些信息固化下来，让每一次会话都站在已有积累的基础上开始。

当然，现在 Claude Code 有了存储的 Memory，这种情况也会好一点。

二、放什么进去

Boris 的建议是控制在 50-100 行，用 @imports 引入更详细的分节文件。每一行都问自己一个问题：「去掉这行，Claude 会犯什么错？」。如果答案是不会，就删掉。

填什么呢？

比如，项目基础。包括，技术栈（框架、语言、版本号）、构建和运行命令（npm run dev、pytest 等）、目录结构及各模块职责说明等。

比如，代码规范。包括，命名规范（驼峰/下划线/文件名格式）、注释语言（中文/英文）、禁止使用的模式或依赖等。

比如，项目特有规则。包括，哪些文件或目录只读，不允许修改、环境变量和密钥的处理规范、已知的坑和对应的正确做法等。

比如，错误学习记录。包括，每次 Claude 犯了错被纠正，把规则写进来，以及格式：不要做 X，原因是 Y，正确做法是 Z等。

三、让 Claude 自己维护 CLAUDE.md

Boris 团队有一条规律：每次 Claude 犯错被纠正后，让它把规则写进 CLAUDE.md。

具体操作只需四步：

1. Claude 犯了一个错（比如用了错误的命名规范，或者改动了不该改的文件）
2. 你纠正它
3. 说一句：「把这条规则加到 CLAUDE.md 里」
4. Claude 自动归档，下次启动时这条规则就已经在上下文里了

也就是说：

Anytime we see Claude do something incorrectly, we add it to CLAUDE.md so it doesn't repeat next time. The file is checked into git and updated multiple times a week. 每次我们看到 Claude 做错了什么，就把规则加进 CLAUDE.md，确保下次不再重复。这个文件提交到 git，每周更新多次。

这个闭环的结果就是，CLAUDE.md 越来越完善，Claude 在这个项目里犯的错越来越少，越来越聪明。

四、团队协作：一个文件，全员共享

说完了 CLAUDE.md 的第一层价值，我们来说第二层价值。

比如，新人入职，读一遍 CLAUDE.md，立刻知道这个项目的所有 AI 协作规范，包括技术栈是什么、风格是什么、有哪些坑。不需要口口相传，不需要单独培训，降低了培训成本和时间成本。

Boris 的团队也把 CLAUDE.md 纳入版本控制，和代码一起做 code review、一起迭代。

有人发现新规则，提 PR 更新，全团队受益。

五、CLAUDE.md vs 系统提示词

很多人用 Claude 的习惯是：每次在对话框开头粘贴一段系统提示词。CLAUDE.md 解决的是同一个问题，但方式完全不同：

• 持久性：系统提示词每次手动粘贴；CLAUDE.md 自动加载。
• 版本控制：系统提示词无法追踪变化；CLAUDE.md 由 git 管理。
• 团队共享：系统提示词靠复制粘贴传播；CLAUDE.md 随代码库同步。
• 错误学习：系统提示词需手动维护；CLAUDE.md 可以让 Claude 自动追加规则。

看完这些对比，我们的结论很清楚了：系统提示词是临时方案，CLAUDE.md 是工程化方案。

六、进阶：@imports 管理大型项目

既然是工程化方案，当项目复杂到 100 行装不下的时候，我们该怎么办？

用 @imports 把内容拆分成以下部分：

• CLAUDE.md（主文件，50 行以内，作为索引）
• @docs/architecture.md（架构说明）
• @docs/api-rules.md（API 规范）
• @docs/known-issues.md（已知问题库）

主文件保持精简，Claude 按需读取详细内容。这个结构和代码里的 index 文件是同一个思路。

对国内 AI 创业者的启发

CLAUDE.md 看起来是个小技巧，但背后是一个重要的思维转变：把 AI 当成团队成员来管理，而不是每次从零开始的工具。