CLAUDE.md 与 auto memory 共同位于 prompt cache 的”项目级 / 全局配置前缀”层，是 system prompt 中每次请求都会重新加载、且享受 Anthropic prompt caching 命中折扣的那一段前缀。该层变更发生在两类动作上：CLAUDE.md 由用户或团队成员手动编辑，auto memory 由 Claude 自己写入并由 auto-dream 之类的整理机制定期合并。
一、缓存分层一览
Claude Code 的 system prompt 并不是单一文件，而是按层次拼接得到。不同层级的变更频率、写入主体、共享范围都不一样：
| 层级 | 路径示例 | 写入主体 | 共享范围 | 变更触发 |
|---|---|---|---|---|
| Managed Policy | /etc/claude-code/CLAUDE.md |
IT/DevOps | 组织内全员 | 管理员推送策略 |
| User Global | ~/.claude/CLAUDE.md |
用户本人 | 单机所有项目 | 用户编辑 |
| Project Root | ./CLAUDE.md / ./.claude/CLAUDE.md |
团队 | 通过 Git 共享 | 团队 commit |
| Project Rules | ./.claude/rules/*.md |
团队 | 通过 Git 共享 | 团队 commit |
| Local Override | ./CLAUDE.local.md |
用户本人 | 仅本机本项目 | 用户编辑（应忽略） |
| Auto Memory | ~/.claude/projects/<hash>/memory/ |
Claude 自动 | 单机当前仓库 | Claude 写入 + auto-dream 整理 |
CLAUDE.md 横跨前五层，每一层都是同一个文件的”位置变体”，它们在 system prompt 中按从根到叶的顺序拼接；auto memory 是独立目录，由 MEMORY.md 与若干主题文件组成，前者每次会话固定加载前 200 行（约 25KB 以先到者为准），后者按需加载。
二、CLAUDE.md 层的变更时机
CLAUDE.md 层的变更完全是”显式写入”驱动的，不会被模型自动改写（除非显式让 Claude 用 Edit 工具改）。典型变更场景包括：
- 团队通过 PR 合并一份新的项目级 CLAUDE.md，把约定写进版本控制；
- 用户在本地编辑
~/.claude/CLAUDE.md，调整全局偏好（语言、commit 风格）； - 用户用
/init触发 Claude 扫描仓库并生成初始 CLAUDE.md，再人工修订； /compact之后下一次请求会自动从磁盘重新加载根 CLAUDE.md，sub-directory 的 CLAUDE.md 只在该目录文件被读取时按需重载。
文件体积上，官方建议把单文件控制在 200 行、约 40,000 字符以内。研究型社区共识是有效指令预算在 100–150 条左右；超出后模型不会因 token 不足而失败，而是注意力降级，开始”丢失”部分规则。
三、Auto Memory 层的变更时机
Auto Memory 由 Claude 自身在会话中触发写入。常见入口包括：用户说”记住这个”、Claude 在执行中归纳出可复用模式、Claude 从用户纠正中抽取出偏好。写入路径是 ~/.claude/projects/<repo-hash>/memory/，同一仓库的多个 worktree 共享同一目录。
变更除了”主动写入”还有”被动整理”。社区记录里把这一过程称为 auto-dream：定期把零散主题文件合并、清理陈旧条目、压缩 MEMORY.md 索引。这意味着 auto memory 的内容不一定在每次会话都变化，但整理任务一旦发生，会让下一次会话看到的 MEMORY.md 与上一次明显不同。
| 变更类型 | 触发主体 | 频率 | 可见性 |
|---|---|---|---|
| 用户显式”记住” | 用户提示词 | 每次会话都可能 | 即时 |
| Claude 自我归纳 | 模型 | 任务完成时 | 即时 |
| auto-dream 整理 | 后台机制 | 周期触发 | 下一次会话 |
| 跨 worktree 同步 | 文件系统层 | 实时 | 即时 |
四、变更后对 prompt cache 的影响
CLAUDE.md 与 auto memory 都属于 system prompt 缓存前缀的一部分。Anthropic 的 prompt caching 对 system prompt 类内容有很高的命中折扣：首次请求按全量计费，后续多轮几乎以零增量成本读取。文件被改写后，缓存前缀的哈希会变化，下一次请求会重新计费首段 token，但随后又恢复高命中。
这意味着两个工程结论：其一，CLAUDE.md 改动不宜高频抖动，否则会反复触发首段计费；其二，auto memory 的写入同样会让缓存前缀变化，但它对会话内的成本影响极小，因为同一会话的续接请求依然命中。
// settings.json：关闭 auto memory 并启用项目规则目录
{
"autoMemoryEnabled": false,
"claudeMdExcludes": ["packages/experimental/**"],
"claudeCode": {
"rules": {
"directories": [".claude/rules"]
}
}
}# 关闭 auto memory 的另一种方式
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
claude五、按场景选对变更通道
- 团队要遵守的规范：写入项目根的
CLAUDE.md并提交 Git，让所有人立即看到； - 个人偏好的快捷键（如 commit 风格、回复语言）：写入
~/.claude/CLAUDE.md； - 只在某模块生效的约定：在
src/api/CLAUDE.md写子目录级文件，让模型读该目录文件时按需加载； - 构建命令、调试心得：让 Claude 写入 auto memory，机器本地保留即可；
- 想覆盖项目级规则但仅本机：写
CLAUDE.local.md并加入.gitignore。
六、变更可控性
CLAUDE.md 的可控性来自 Git 的 review 流程：任何改动都经 PR 合并，团队成员有审查权。Auto memory 的可控性相对弱：模型自行写入，整理机制也由模型触发；可用 autoMemoryEnabled: false 或环境变量 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 关闭它，关闭后所有”自动记笔记”行为都会停。
到这里，CLAUDE.md 与 auto memory 所在的缓存分层与变更时机就清楚了：两者都在”项目级 / 全局配置前缀”层，前者由人或团队显式编辑、变更受 Git 约束，后者由模型自动写入并由后台整理机制合并。掌握两者边界，能在”让规则真正生效”与”避免规则互相打架”之间取得平衡。
常见问题（FAQ）
Q1：CLAUDE.md 改了之后多久生效？
下一次请求即生效，根文件随每次请求重新加载，子目录文件在读到该目录文件时按需加载。
Q2：auto memory 能跨机器共享吗？
不能，auto memory 是机器本地的，云端会话也读不到本机记忆。
Q3：怎么关闭 auto memory？
设置环境变量 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1，或在 settings.json 中把 autoMemoryEnabled 设为 false。
