CLAUDE.md 正确用法：不是项目知识库，而是会话级指令集

大家都在告诉你写一个 CLAUDE.md 文件，却几乎没人告诉你它到底是用来干什么的。于是你创建一个，往里塞进所有能想到的东西，然后看你的 agent 在一周内表现得多漂亮。接着它开始无视你花了一下午写的那份文件，然后某个标题为"CLAUDE.md 到底有什么用？"的帖子收到了 180 条评论——这时候一切都解释通了。

有一个观点值得你静下心来想一想。CLAUDE.md 文件不是你项目的记忆。它是模型在每个会话开始时读取的一组常设指令，你越把它当作产品应该如何运作的持久记录，它就越快地变成一种负担。

CLAUDE.md 文件到底是什么

CLAUDE.md 是一个纯 Markdown 文件，Claude Code 在每个会话开始时自动读取它。它放在项目根目录，由你手动编写，存放的是 agent 原本需要靠猜的东西：你的技术栈、构建和测试命令、你的编码规范、它不应该碰的文件夹。Anthropic 自己的文档把它描述为项目的持久化指令。这里的关键词是 instructions，不是 knowledge。

这个区别就是整篇文章的核心。文件被预置到对话中，所以每个回合都会消耗上下文 token。它不是 agent 需要时查询的数据库。它是一段前导文字，贯穿整个会话，无论当前任务是否需要那些规则。这正是为什么那些真正有效的建议——过了"随便写一个"这个阶段之后——是让它保持简短。

反直觉的地方在于，精简文件往往让 agent 表现更好，而不是更差。一位开发者报告说他砍掉了大约 80% 的 Claude Code 上下文，反而得到了更清晰的结果，这与 Anthropic 自己团队的指导——少即是多——相呼应。这重新定义了文件的作用：不再是囤积上下文的场所，而是一笔你谨慎支出的预算。一份 400 行的 CLAUDE.md 不是文档完善的项目。它是对每个请求征收的 400 行税，过了某个临界点模型就开始略读它，而那正是那个 Reddit 帖子抱怨的行为。

CLAUDE.md 文件里放什么

有用的内容范围窄且稳定。想一想那些今天成立、下个月仍然成立的小集合事实：你使用的框架、运行测试的命令、构建的命令、你强制执行的 linter、你永远不想被违反的那条架构规则（"所有 API 调用都通过 lib/api 里的 client，永远不要直接 fetch"）。这些值得占据一席之地，因为它们变化缓慢且几乎适用于每个任务。

下面是有效文件和腐败文件的对比例子。

腐败："我们上周二迁移了 auth 流程，新端点是 /v2/login，但旧端点暂时还能用，Sarah 这个 sprint 在重构 session 处理，所以在碰它之前先和她确认一下。"

有用："Auth 放在 src/auth。在那里做任何修改后运行 pnpm test:auth。"

第一条是状态更新。一周内就会过时，而当它过时的时候，agent 仍然会自信地按它行事。第二条是关于东西放在哪以及如何验证它们的持久事实。一个是给同事的便签。一个是给机器的规则。

你应该把 CLAUDE.md 提交到 Git 吗？

应该，提交项目级的文件。它的全部价值在于团队中的每个人和每个远程 agent 加载完全相同的规则。把根目录里的 CLAUDE.md 就像你提交 linter 配置一样提交，因为它本质上是同类型的产物：一套共享标准，而非个人偏好。把它 check in 到 Git，你的 agent 无论谁运行、在哪里运行，表现都一样。

你个人的、机器级别的文件（放在 ~/.claude/ 里的那个）则不同。它存放你个人的工作流习惯，位于任何 repo 之外的 home 目录里，应该留在那里。经验法则：项目规则是团队财产，需要提交；个人偏好是你自己的，不需要。

重新定义：指令不是记录

现在是最多数"如何写出一份出色的 CLAUDE.md"帖子错过的地方。开发者们一直在用 CLAUDE.md 或 Claude 的自动记忆功能来解决一个它从来不是为解决而设计的问题：记住产品应该做什么。我们关于 billing 如何运作决定了什么？为什么这个功能按这种方式构建？checkout 流程的完成标准是什么？那不是指令。那是你产品的记录，而把它塞进模型每个回合都会扫过的文件里，就是事情变糟的方式。

一旦你留心，证据无处不在。在最近一个关于是否有人真正使用 Claude 的记忆功能的 r/ClaudeCode 帖子里，四位不同的开发者没有协调就得到了相同的结论。一位说得直白：

我犯了个错误，试图用它来存放项目知识，现在它正在渗透到其他项目里。smh。别学我。

同一帖子里其他人说它"很快就会过时"，说它"完全不透明"地放了一个月才发现一个错误的笔记，还有人说记忆"应该只保留给用户偏好，别无例外。不是用来存放真正的知识。"四个人，一个结论：模型的记忆是一个偏好存储，不是项目记录。它会渗透，会变陈旧，而你看不见里面有什么。

这是不会随着模型改进而消失的能力问题。更好的模型让人更想把持久知识卸载到模型的上下文中，而不是更少，因为 agent 感觉足够聪明到可以信赖。但基于一份陈旧笔记工作的更聪明 agent 不会更可靠。它会更自信地犯错，而且更难调试，因为错误追溯到某个"记住"的东西——那个东西几周前就不再是真的了。模型是无状态的。你的产品不是。（如果你想要关于自动记忆为何会腐坏的更深版本，我们在 state file pattern 里写过了。）

产品记录到底应该放在哪

所以如果指令放在 CLAUDE.md 里，持久知识不属于记忆，那关于产品应该做什么的记录到底应该放在哪？在模型之外，在你拥有并主动更新的东西里。

这就是 BrainGrid 填补的空白。你描述一个功能，规划 agent 把它转化为带有明确验收标准的需求——关于该功能"完成"意味着什么的具体、可检查的陈述。当构建 agent 构建它时，无论是在 BrainGrid Cloud 沙箱里还是通过 MCP 在你自己的 GitHub repo 里用 Claude Code、Cursor 或 Codex 构建，验证都会在功能被算作完成之前根据每一条标准检查结果。所有这些——规格、决策、标准、验证——都按产品积累成一份你可以阅读的记录。

与 CLAUDE.md 文件的区别正是重点。CLAUDE.md 告诉 agent 你如何工作：你的命令、你的约定、你的家规。产品记录存放你决定了什么以及为什么，它不依赖模型记住任何东西。一个是模型读取的前导文字。一个是模型被对照检查的真相来源。你仍然想要一份精简的 CLAUDE.md。只是不要再让它承担它从来不是为承担的东西。这就是上下文工程的核心：决定模型应该在脑子里放什么，以及什么应该放在它之外的记录里。

值得指出的一个权衡

把持久知识放在模型上下文之外有一个真实的代价：前期需要更多工作。写一条验收标准比在聊天里敲一句话然后希望 agent 记住它要慢。懒办法在第一天确实感觉更快。只是当你在调试某个追溯到一条没人知道在那里的笔记的行为上花了一整个下午之后，它就不再感觉更快了。不费力的选项会腐坏。深思熟虑的那个会复利。这就是那个权衡，在你打算保留的任何项目上都值得做出。

如果你现在正在用 Claude Code 或 Cursor 构建一个真正的产品，这意味着你的 CLAUDE.md 应该随时间变短，而不是变长，而你曾经想要塞进去的知识需要一个模型不拥有的家。

CLAUDE.md 是必要的吗？

严格来说不是，但对于任何你会回头看的项目都值得。没有的话，agent 每个会话都要重新猜你的技术栈、命令和规范，而且猜错的频率高到浪费真实时间。一份简短、准确的 CLAUDE.md 消除了这种摩擦。只有在一次性实验（你再也不会打开的项目）上才跳过它。

CLAUDE.md 里放什么？

agent 在几乎每个任务上都需要知道的稳定事实：你的技术栈、运行和测试及构建项目的命令、你核心的编码规范，以及你永远不想被违反的硬规则。保持精简。任何一周一变的东西都去掉，比如当前 sprint 状态或进行中的决策，因为那正是会变陈旧并在后来误导 agent 的东西。

我应该把 CLAUDE.md 提交到 Git 吗？

提交根目录里的项目级 CLAUDE.md，因为它的价值在于每个队友和每个 agent 加载相同的规则。别担心 home 目录里的个人文件（~/.claude/CLAUDE.md）；它位于 repo 之外，存放你的个人偏好，所以按设计是本地保留的。

为什么 Claude 无视我的 CLAUDE.md？

通常是因为文件太长了。CLAUDE.md 里的所有内容都被预置到每个请求中，所以一个臃肿的文件既在每个回合消耗 token，又会被略读而不是遵循。把它削减到最重要的规则，用清晰的指令措辞，模型遵循它们会可靠得多。如果一条规则至关重要，把它放在靠近顶部并直白地陈述会有帮助。

CLAUDE.md 和 agent 记忆是一样的吗？

不一样。CLAUDE.md 是你编写并控制的指令，在每个会话开始时读取。自动记忆是 agent 在后台为自己写的笔记，放在 Claude 特定的位置。你拥有的文件保持准确因为你编辑它；agent 写的笔记容易变陈旧并渗透到其他项目，这就是为什么大多数开发者把记忆留给偏好，把真正的项目知识放在文件里，或者放在完全位于模型之外的产品记录里。

BrainGrid 是计划优先的平台，给你的产品一份模型可以被对照检查的记录，而不只是它读取的指令。在 braingrid.ai 试用。

最初发表于 BrainGrid 博客。