Claude Code Memory 实战：把一次性对话变成可累积的工程上下文

很多团队在用 Claude Code 一段时间后都会遇到同一个问题：单次会话效果不错，但跨会话一致性不稳定。根因通常不在模型能力，而在“记忆系统”没有被工程化使用。

官方文档给出的答案很明确：Claude Code 不是只有一种记忆，而是两套互补机制。

1. CLAUDE.md：你写规则，定义期望行为。
2. Auto Memory：Claude 写笔记，沉淀可复用经验。

二者都会在会话开始时参与上下文，但它们都属于“上下文输入”，不是强制配置。也就是说，写法是否具体、结构是否清晰，会直接影响遵循率。

如果只把它当“提示词文件”，很快会失控；把它当“持续维护的工程资产”，才会有复利。

CLAUDE.md 适合放稳定、可审计、跨成员共享的约束，例如：

1. 构建和测试命令。
2. 代码目录约定与分层边界。
3. 提交前检查流程。
4. 安全与合规要求。

文档强调了几个高价值实践：

1. 单文件尽量控制在约 200 行内，过长会占用上下文并降低遵循率。
2. 规则要具体，不要抽象口号。
3. 冲突规则会显著降低稳定性，需要定期清理。
4. 大项目要拆分到 .claude/rules/，按主题和路径组织。

路径化规则是一个关键能力。你可以只在 src/api/**/*.ts 生效 API 规则，把前端规则留给 src/components/**，减少无关噪音和 token 消耗。

Auto Memory 默认开启，会在项目维度自动记录值得复用的信息，例如调试结论、构建细节、偏好约定。

目录形态大致是：

~/.claude/projects/<project>/memory/
├── MEMORY.md
├── debugging.md
├── api-conventions.md
└── ...

机制要点：

1. 会话启动时仅加载 MEMORY.md 前 200 行。
2. 主题文件按需读取，不会在启动时全部塞进上下文。
3. 同一 Git 仓库下的 worktrees 共享同一份 Auto Memory。
4. 这是本机本地数据，不会自动跨机器同步。

这套设计本质上是在做“热记忆 + 冷记忆”分层：启动时保证关键索引可见，细节在需要时再读取。

推荐把治理分成两条流水线：

1. 规则流水线（CLAUDE.md / .claude/rules/）
2. 经验流水线（memory/）

落地顺序建议：

1. 先最小化主规则文件，只保留高频且可验证的规则。
2. 按路径拆分子规则，避免单文件膨胀。
3. 用 /memory 定期审阅 Auto Memory，把高价值、稳定结论提升为显式规则。
4. 对过时记忆做清理，避免历史噪音影响后续推理。

这一步很重要：Auto Memory 里“经常复用且长期正确”的结论，应回灌到 CLAUDE.md。否则经验只会停留在个人本机，不会成为团队资产。

优先检查三件事：

1. /memory 里是否真的加载到了目标文件。
2. 规则是否与其他层级文件冲突。
3. 规则是否可执行、可验证。

这是典型的上下文挤占问题。处理方式是拆分：

1. 主文件保留原则和入口。
2. 细节迁移到 @path 引用文件或 .claude/rules/。

如果内容只在会话聊天里出现，而未写入文件，压缩后当然不会保留。需要把长期指令落盘到 CLAUDE.md 或 memory 文件。

Claude Code 的记忆能力，真正改变的不是“回答更聪明”，而是把上下文管理从临场手工操作，转成可维护的工程系统。

对于团队而言，核心目标不应是积累更多文本，而是持续提升三件事：

1. 规则清晰度。
2. 经验可复用度。
3. 记忆噪音控制能力。

做到这三点，AI 协作会从“偶尔惊艳”变成“稳定可预期”。