CLAUDE.md 的修改不会立刻在当前对话里生效，根因在它所在的”项目上下文层”缓存策略：项目级指令与会话状态绑定，启动会话时一次性加载到上下文缓存，中途改动文件不会影响已激活的会话。下一轮对话或重启进程时才会重新读取。理解这一层缓存的更新规则，是写指令、排查”我明明改了 CLAUDE.md 为啥不生效”的前提。
一、为什么”改了不生效”
Claude Code 的提示词缓存不是单一整体，而是按稳定性和来源分成若干层。CLAUDE.md 的内容属于”项目上下文层”，它在会话启动时由 Claude Code 从磁盘读取并放入上下文缓存，标记为”启动后只读”。这层缓存的设计目的是避免每次调用都重新读文件带来的延迟和不稳定。
具体表现是：
- 用
claude命令启动会话、看到欢迎信息的那一刻，CLAUDE.md 的内容已经被加载到上下文里 - 之后的整段对话里，Claude 看到的是这份快照，不是磁盘上的最新内容
- 在会话进行中用文本编辑器修改 CLAUDE.md，当前会话的 Claude 不会察觉到任何变化
- 关闭会话重新打开（或者使用
/clear之类的命令清空上下文），下一轮才会重新读盘加载
这一点和 MEMORY.md 不一样。MEMORY.md 是会话内的”工作记忆”，会在特定点被重新加载；而 CLAUDE.md 是会话启动时的”项目档案”，整个会话期间被视为固定不变。
二、缓存的层级结构与各类指令的位置
Claude Code 的提示词缓存大致分为四层，每层有不同的更新时机：
| 层级 | 内容来源 | 更新时机 | 修改后立即生效？ |
|---|---|---|---|
| 系统层 | 模型自身的安全与行为规则 | 随模型版本升级 | 不适用（用户不可改） |
| 系统提示层 | Claude Code 内置指令、工具描述、输出样式 | 启动时读一次，/config 切换样式需重开会话 |
否 |
| 项目上下文层 | CLAUDE.md、.claude/CLAUDE.md、嵌套目录里的同类文件 |
启动时一次性加载，会话内只读 | 否（须新会话） |
| 工作记忆层 | MEMORY.md、auto memory、对话历史 | 周期性或显式命令触发 | 是（下次注入时即生效） |
把指令写在工作记忆层（比如直接告诉 Claude “从这个项目起你只用 TypeScript”），效果是即时的；写在 CLAUDE.md 则要等下一轮对话。理解这一区分，能避免”我把规则写进 CLAUDE.md 了为啥 Claude 不听话”这类常见困惑。
三、规则”不生效”的实际原因与排查
看到 claude 启动信息里显示 CLAUDE.md 已加载、但 Claude 仍然不遵守其中某条规则时，按下面顺序排查：
- 确认规则写在项目级而非用户级目录：项目级 CLAUDE.md 加载优先级高、覆盖用户级同名文件
- 确认没有同名文件覆盖：你编辑的是
.claude/CLAUDE.md，但用户级目录~/.claude/CLAUDE.md存在同名段并覆盖了你的修改 - 确认指令可被直接执行：模糊动词（”尽量”、”差不多”）和嵌套条件（”如果 A 则 B，否则 C”）会让 Claude 倾向忽略
- 确认当前会话启动时规则已存在：会话在改之前启动的，整段对话的上下文快照都是改之前的版本
- 确认不是被系统层或工具行为覆盖：例如”绝不使用 shell 工具”会被工具层的安全护栏重新启用
绝大多数”改了不生效”的报告，最终排查结果都是第 1-3 条，尤其是第 4 条最容易踩——用户常常以为 Claude 实时读盘，但实际只在启动时读一次。
四、让规则”立即生效”的三种做法
CLAUDE.md 修改后，想让它在当前或下一轮对话里被遵守，标准做法有三种：
- 重开会话：关闭当前
claude进程，新开一个，新会话启动时会重新读盘 - 使用
/clear或类似命令：清空当前上下文的项目上下文层，让下一轮重新加载 - 把关键规则直接写进对话：临时性强、需要立即生效的规则，可以直接以自然语言在对话里告诉 Claude，例如”从现在起请用 TypeScript 写所有文件”
第三种做法的代价是规则只存在于工作记忆层、退出对话就消失。正式的项目级约束还是应当写在 CLAUDE.md，靠重开会话来激活。
下面是一段项目级 CLAUDE.md 写法示例，对比”低遵循率”与”高遵循率”两种风格：
# 低遵循率（不推荐）
# 写代码时尽量保持风格统一，类型注解能加就加
# 高遵循率（推荐）
# [scope: all] 必须用 TypeScript 写所有 .ts 与 .tsx 文件。
# [scope: tests] 禁止修改 tests/ 目录下的任何文件。
# [scope: api] 所有 HTTP 处理器必须包含 try/catch 与错误响应。高遵循率版本用祈使句、明确动词、带 scope 标签、低级约束与高级约束分离，Claude 在项目上下文层加载时更容易识别并执行。
五、设计 CLAUDE.md 的工程化建议
为了让规则在项目上下文层真正发挥作用，写法上有几条硬性建议：
- 指令用动词开头的祈使句，避免”建议”或”尽量”——Claude 对祈使句的遵循率显著更高
- 每条规则单独成行，不要把多条塞进一个长段落，方便 Claude 逐条识别
- 避免嵌套条件，”A 情况下做 X，B 情况下做 Y”这种结构容易被简化为”A 做 X”
- 重要的强约束加 scope 标签，例如
[scope: tests] 不要修改tests/下任何文件`，明确告诉 Claude 这条只对哪个范围生效 - 不要把安全相关约束写进 CLAUDE.md——这类约束应当依赖系统层和工具层，CLAUDE.md 里的安全指令会被工具的安全护栏覆盖
- 项目级与用户级分工：个人偏好放用户级（
~/.claude/CLAUDE.md），团队共识放项目级（仓库根目录的 CLAUDE.md）
把 CLAUDE.md 当作”项目档案”而不是”临时通知”，写的时候假设它要在每次会话启动时被读一次——这个心智模型能让规则从一开始就写得更稳。
常见问题（FAQ）
Q1：改了 CLAUDE.md 一定要重开会话吗？
是的。当前会话已加载旧版快照，必须重开或 /clear 后才会重新读盘。如果只是临时改一条规则用，直接在对话里说更快。
Q2：怎么确认当前会话加载的是哪份 CLAUDE.md？
启动时 Claude Code 会打印加载路径，常见的有项目根 .claude/CLAUDE.md、用户目录 ~/.claude/CLAUDE.md、嵌套目录里的同名文件，重名按优先级加载。
Q3：CLAUDE.md 里的安全相关约束为什么总是被覆盖？
工具自身的安全护栏（危险操作拦截、敏感文件保护等）优先级高于任何 CLAUDE.md 指令。把安全约束写进 CLAUDE.md 反而会让人误以为它生效。
Q4：项目上下文层缓存会失效吗？
会话退出、崩溃、或显式触发清理命令时该层失效。下一轮新会话的首次调用，会重新读盘加载。
