很多人以为 Claude Code 的“长期记忆”就是一个 CLAUDE.md。这已经不够了。真正进入团队实战后，你会发现：Claude Code 的效果上限，取决于你怎么设计它的记忆架构。

如果你已经会写 CLAUDE.md，但仍然遇到这些问题：

那你缺的不是再多写几条提示词，而是建立一套分层的记忆系统。

这篇文章不讲入门，而是讲 Claude Code 目前最值得掌握的进阶能力：

  1. CLAUDE.md 到底应该承载什么，什么不该放进去
  2. .claude/rules/ 为什么是大型项目的关键治理工具
  3. auto memory 适合记录什么，不适合记录什么
  4. subagent 的真正价值为什么是“上下文隔离”而不是“并行炫技”
  5. 团队、个人、组织三级指令体系应该怎么分工

一、先纠正一个误区：Claude Code 不是只有一种“记忆”

很多文章把 Claude Code 的记忆能力讲得过于简单：

但从最新官方文档看，Claude Code 至少有 四层长期上下文机制：

层级 载体 谁来写 适合存什么 典型作用
1 CLAUDE.md 人 稳定规则、流程、架构约束 每次会话启动时加载
2 .claude/rules/*.md 人 按主题/路径拆分的细粒度规范 减少主指令膨胀
3 Auto Memory Claude 运行中学到的经验、偏好、命令 跨会话延续经验
4 Subagent Memory Claude / 人共同设计 子代理自己的长期专长与记录 让不同代理各记各的

这四层不是互相替代，而是各司其职。

真正高效的团队，不会把所有东西都塞进一个 CLAUDE.md。

二、CLAUDE.md 的正确定位：只放“每次都应该知道”的东西

官方文档里有一个很关键的提醒：CLAUDE.md 会在每次会话开始时进入上下文窗口。换句话说，它不是免费提示词，而是持续占用上下文预算的常驻内存。

因此 CLAUDE.md 最适合放下面这类内容：

1）Claude 无法从代码里稳定推断出来的规则

比如：

这些东西，Claude 读一遍代码是未必能理解的。

2）项目级架构约束

例如：

3）工作流偏好

比如：

4）少量高价值提醒

好的 CLAUDE.md 不是“百科全书”，而是“高命中率提示”。

官方建议是：尽量简短，控制在 200 行以内更稳妥。

这和很多人习惯完全相反。很多项目的 CLAUDE.md 写成了超长 README，结果不是更聪明，而是更容易失焦。

一个实用判断标准

你可以用一句话筛选每条内容：

删掉这一条后，Claude 是否更容易犯错？

如果答案是否定的，就不应该放进 CLAUDE.md。

三、为什么大型项目一定要上 .claude/rules/

如果你的仓库开始出现下面这些情况：

那继续把规范全堆进一个 CLAUDE.md，迟早会失控。

这时 .claude/rules/ 才是更现代的做法。

1. 它解决的是“主指令过胖”问题

你可以把规则按主题拆分：

.claude/
├── CLAUDE.md
└── rules/
    ├── testing.md
    ├── security.md
    ├── api-design.md
    ├── frontend/
    │   └── react.md
    └── backend/
        └── spring.md

这样做的价值不是“更整齐”，而是：

2. 它支持按路径匹配加载

这是最实用的一点。

规则文件可以用 frontmatter 指定 paths，让某些规则只在特定文件被读取时生效。比如：

---
paths:
  - "src/api/**/*.ts"
---

# API 规则

- 所有接口都必须做输入校验
- 错误响应统一走标准结构
- 必须补 OpenAPI 注释

这意味着：

这本质上是在做“按需加载的项目规则系统”。

3. 它更适合团队协作

团队里最常见的问题，不是“没有规范”，而是“规范没人维护”。

单个超长 CLAUDE.md 的维护成本很高：

拆成 rules 后，不同角色可以维护自己的部分：

这比让一个人维护“总圣经”现实得多。

四、Auto Memory 该怎么用：记录经验，不要记录制度

Claude Code 现在不仅能读你写的规则，还能积累它自己发现的经验，也就是 auto memory。

这层机制最大的价值，不是替代 CLAUDE.md，而是补充“运行中的经验沉淀”。

Auto Memory 适合记录什么？

最适合的是这些“做过一次才知道”的内容：

你会发现，它更像：

工作日志 + 纠错积累 + 项目经验库

Auto Memory 不适合记录什么？

不适合的是：

这些应该写在 CLAUDE.md 或 .claude/rules/，因为它们是显式规则，不是经验型知识。

最佳分工方式

我建议这样理解：

如果你把“宪法”写进经验笔记里，它就不稳定；如果你把所有经验都写成宪法，主上下文又会过载。

五、Subagent 的真正价值：上下文隔离，不只是并行

很多人第一次用 subagent，会把它理解成：

这当然没错，但还不够深。

1. 更核心的价值是隔离上下文污染

官方文档明确强调：subagent 运行在自己的上下文窗口里。

这件事的意义非常大。

因为 Claude Code 的效果，会随着上下文越来越满而下降。你让主会话既负责：

上下文很快就会变得嘈杂。

这时把任务拆给 subagent，本质是在做上下文工程：

结果是：主会话更干净，子任务也更聚焦。

2. 不同子代理可以有不同边界

官方文档里，自定义 subagent 不只是写 prompt，还能指定：

这意味着 subagent 不是“另一份你”，而是“带边界的专业角色”。

例如：

这就把“AI 角色化”从 prompt 层，推进到了权限层和上下文层。

3. worktree 隔离非常适合并行开发

如果多个子代理都要改代码，最容易出现的问题就是相互污染。

官方现在支持给 subagent 配置 worktree 隔离，让它在临时 git worktree 中工作。这个能力特别适合：

它的工程价值远大于“省几个 prompt”。

六、团队实战：怎么设计个人、项目、组织三级记忆体系

真正到团队里，问题从来不是“有没有指令文件”，而是“谁负责写哪层”。

我推荐一个非常实用的三层分工。

第一层：组织级（Managed / 全局政策）

这一层放：

特点是：

比如：

第二层：项目级（CLAUDE.md + .claude/rules/）

这一层放：

这是最核心的一层，也是最应该进版本控制的一层。

第三层：个人级（用户级 CLAUDE.md / 个人规则 / 偏好）

这一层放：

比如：

为什么一定要分层？

因为下面这些东西不应该混在一起：

混在一起的后果就是：

一旦分层，Claude 的行为会稳定很多。

七、GitHub Actions 和自动化场景下，为什么更需要“轻量但稳定”的记忆

到了 CI、PR 审查、自动修复这类自动化场景，很多人第一反应是继续加更多 prompt。

但这类场景真正需要的，其实是：

原因很简单：自动化运行没有人工实时纠偏。

旧思路的问题

很多旧文章喜欢把全部规范塞进 workflow prompt 里，比如：

结果是：

更成熟的做法

应该把稳定规则沉淀到仓库自身：

这样在 GitHub Actions 里，prompt 可以很短：

真正的项目知识，来自仓库自身，而不是每次 workflow 重复灌输。

这也是为什么最近官方 GitHub Actions 文档更强调统一配置和项目内规范，而不是鼓励把所有规则堆进 action 参数里。

八、一套可落地的实践模板

如果你准备把现有项目升级到更成熟的 Claude Code 架构，可以按这个顺序做。

第一步：给 CLAUDE.md 做减法

只保留：

把历史累积但命中率低的内容删掉。

第二步：把专项规范拆进 .claude/rules/

优先拆这几类：

第三步：允许 Claude 通过 auto memory 积累“经验”

尤其是：

第四步：把高频工作角色化为 subagent

例如：

第五步：在自动化场景里减少 prompt 冗余

把共享知识下沉到仓库，把 workflow prompt 收缩为任务意图。

九、什么时候该新增文章，什么时候只该改旧文？

这也是我最近做博客内容维护时的一个判断标准。

如果只是：

那改旧文就够了。

但如果出现的是这种变化：

那就值得写一篇新文章，因为这不是补丁，而是认知升级。

这篇文章写的就是这种升级。

十、总结：真正决定 Claude Code 上限的，是你的“记忆工程能力”

我现在越来越确信一件事：

Claude Code 的效果，不只是模型能力问题，更是上下文架构问题。

同样一个模型，在两种项目里的表现会天差地别：

后者几乎一定更稳、更省 token、更适合团队扩展。

所以，如果你已经过了“会不会用 Claude Code”的阶段，下一步应该思考的不是 prompt 花活，而是：

当你开始这样设计 Claude Code，你就不再是在“使用 AI 工具”，而是在搭建一套可维护、可扩展、可团队协作的 AI 开发操作系统。

延伸阅读

如果说提示词决定 Claude Code 的下限，那么记忆架构决定它的上限。