Howie2099

CLAUDE.md 记忆系统工程

CLAUDE.md 是给无状态模型的入职手册：五层记忆体系、写作三问框架与维护反模式

2026-07-21
AgentAIClaude

🎯 核心主张（一句话）

Claude 每次对话都是"入职第一天"，CLAUDE.md 就是那本自动发到它手上的入职手册——写好它的关键不是写多，而是只写"它必须知道却推断不出"的信息。

📖 正文

问题根源：模型没有会话间记忆

大模型的根本特征是会话间无持久状态：关掉终端再开新会话，Claude 就忘了你的框架选型、忘了 5 分钟前刚被纠正过的错误。它缺的不是能力，是上下文。

没有项目上下文时，Claude 的"默认约定"来自训练数据的统计规律——所以它总选 Express 不选 Fastify、用 npm 不用 pnpm。这些选择在互联网分布上"最主流"，但很可能撞你团队规范的红线。

解法沿用软件工程的老套路：像 .eslintrc、tsconfig.json 一样，把隐性的团队约定外化成机器可读的声明式文件。CLAUDE.md 唯一的不同是读者从编译器换成了大模型——它在每次会话启动时被自动加载，注入上下文最前端。有人会说"Claude 自己会读 package.json"，但主动探查烧工具调用和上下文，而且依赖清单里没有架构决策和团队约定这类深层信息。

五层记忆体系：从铁律到便签

CLAUDE.md 不止一个位置。Claude Code 的记忆分五层，类似 Linux 配置的层层加载：

层级 位置 定位
企业级 /etc/claude-code/CLAUDE.md 或企业管理后台 合规底线，开发者不可绕过（个人用户通常为空）
用户级 ~/.claude/CLAUDE.md 个人偏好：语言、commit 格式、快捷指令映射，跨所有项目
项目级 ./CLAUDE.md（提交进 Git） 团队共识主战场，新人 clone 即生效
规则级 .claude/rules/*.md 按主题拆分的条件化规则，见下
本地级 ./CLAUDE.local.md（自动 gitignore） 私人便签：测试服地址、个人调试心得

冲突处理是"叠加而非覆盖"：所有层级合并进上下文，矛盾时按"具体性优先"裁决——项目级的 2 空格缩进会压过用户级的 4 空格偏好。唯一例外是企业级，它有绝对强制力，下层怎么配都绕不过。

规则级值得单独说：在 .claude/rules/ 下按领域拆文件（testing.md、database.md、api-design.md），文件头用 YAML frontmatter 的 paths 字段声明 Glob 模式，只有操作到匹配路径的文件时规则才被加载。写前端组件时不用背数据库迁移规范——这就是懒加载思想。注意：不配 paths 的规则文件等同于全局无条件加载，跟塞进主 CLAUDE.md 没区别。

<!-- .claude/rules/testing.md -->
---
paths:
  - "**/*.test.ts"
  - "tests/**"
---
# 测试规范
- 用 vitest，禁 jest；mock 统一 vi.mock()
- 测试数据走 factory 函数，禁止硬编码

该写什么：三问框架 + 脆弱性测试

少即是多是有技术依据的：Claude Code 的系统提示词已内置约 50 条指令，用户指令加上去总数一旦突破 150 条左右，遵循质量显著衰减——指令密度与遵循概率成反比。上下文是张面积固定的办公桌，规则堆太多，真正干活的代码和文件就没地方放。

筛选内容用三问框架：

  • WHY（为什么）：只给容易被误解的关键决策写。讲清"选 Fastify 是因为类型安全优先"，Claude 在未明确规定的边缘场景也能按原则推导。
  • WHAT（做什么/禁什么）：最刚性的红线，占大多数。"必须 pnpm，禁止 npm/yarn"，一句话，不解释。
  • HOW（怎么做）：固化常用命令和流程，如 pnpm db:migrate，让模型照做即可。

反面教材是"正确的废话"：代码要写得好一些、测试要全面、遵循最佳实践——对 AI 是零信息量。尤其"遵循最佳实践"最致命：Claude 默认就在遵循它认知里的最佳实践，问题恰恰是那套统计意义上的实践和你团队的约定有偏差。团队人数、立项时间这类元数据同样只是占位噪声。

黄金检验标准（脆弱性测试）：删掉某条规则后 Claude 依然做对，这条就不该存在。 书中三个实战范例（React 前端、Node 后端、Python 数据项目）都控制在二三十行，共同点是只写本项目独有的约定，不解释 Claude 早就懂的通用知识。前端范例里的"状态管理决策树"（服务器状态→TanStack Query，全局客户端状态→Zustand，局部→useState）是好范式：给场景到工具的映射逻辑，比罗列工具名有效得多。

四种操作方式

  • /init：扫描目录结构和依赖配置，自动生成 CLAUDE.md 初稿。能推断出技术栈和常用脚本，但分层约束、命名规范这类只在人脑里的隐性知识必须手动补。
  • /memory：对话中途弹出文件选择器，直接编辑任一层级的记忆文件。发现 Claude 又用了 moment.js？当场追加"日期处理统一 date-fns"，下次会话生效。
  • # 前缀快速添加：输入以 # 开头的内容，Claude Code 会提示选择存入哪个记忆文件，是最轻量的随手记入口。
  • @path import 语法：任何记忆文件里写 @docs/api-conventions.md 即可引入其他文件，支持最多五层嵌套。这让 CLAUDE.md 可以退化成一份"索引总纲"，细节分散到专题文档——大型项目的文档治理方案。

维护策略与常见反模式

CLAUDE.md 是活文档，正确的成长方式是"犯错→纠正→写入记忆→不再犯"的循环，而不是开工前一次性写个大而全。

常见反模式：

  1. 愿望清单式写作：预先猜测所有可能的错误写成规则。结果是文件臃肿、条条被稀释。
  2. 情感抒发式规则：每条规则后跟一大段背景阐述。多数规则只需 WHAT 层面一句话。
  3. 单文件承载一切：所有领域规则塞一个文件，既难维护，又让无关噪声稀释当前任务的注意力——该拆去 .claude/rules/ 条件化加载。
  4. 把团队规范写进个人层（或反之）：必须统一的进项目级，个人口味放用户级或本地级，别用个人偏好污染团队文件。

🧭 业界视角（书外补充）

  • Boris Cherny（Claude Code 创造者）的 100 行标准：他本人的 CLAUDE.md 只有约 100 行，经验上限 200 行——前沿模型能可靠遵循的指令总量约 150-200 条，超出部分会被忽略。这与书中"150 条临界值"互为印证。（来源：howborisusesclaudecode.com）
  • Cherny 的"反应式维护法"：不要预判 Claude 会犯什么错。等它真犯了，再把"能防住这个错"的那一条加进去，并让 Claude 自己动手——"Update your CLAUDE.md so you don't make that mistake again"。同时持续删减，直到错误率可测量地下降。每条规则都应是事故记录的结晶，不是愿望清单。
  • 验证闭环写进 CLAUDE.md：给 Claude 一个自查手段（测试命令、lint、截图对比），产出质量约提升 2-3 倍。所以"常用命令"小节里最值钱的一行往往是测试命令。（来源：Anthropic 官方最佳实践）
  • 分层选型的社区共识：CLAUDE.md 只放"每时每刻都要生效"的规则；提示词模板归 slash command，领域工作流归 Skill，必须 100% 执行的规则归 Hook。最常见的错误不是不会写，而是把对的内容放错了层。

🔗 知识网络