CLAUDE.md 为什么总“不听话”?从源码看懂真实优先级
Source: http://x.com/i/article/2040445432443400192
大多数人写 CLAUDE.md 的方式是:写几条“感觉对”的规则,然后发现效果不稳定,最后放弃。
问题不在你不会写,而在很多人一开始就理解错了它的工作位置。
我把源码逻辑整理成一句话:
CLAUDE.md 不是 System Prompt,它是以“首条 user context”的形式注入到对话里。
这件事很关键,因为它直接决定了三件事:
- 它的优先级天然低于 system 规则
- 模型会被提示“这段上下文可能不相关”
- 你写得越抽象,越容易被忽略;越具体、越可验证,越容易执行
所以,别再写“尽量简洁”“注意代码质量”这种话。 改成可执行规则,比如:
- 回答不超过 3 句话
- 不要给未修改代码补注释
- 函数不超过 30 行
- commit message 使用中文,50 字以内
第二个关键点:CLAUDE.md 不是只看项目根目录。 Claude Code 会从当前目录一路向上遍历到根目录,并加载多来源规则(企业级、用户级、项目级、本地级)。而且“后加载”的通常更容易被模型关注,也就是离你当前目录更近的规则,通常权重更高。
第三个关键点:把规则模块化,不要把所有内容塞进一个大文件。 推荐结构:
- 根 CLAUDE.md 只做索引(@include)
- .claude/rules/ 按主题拆分(code-style / git / testing)
- ~/.claude/CLAUDE.md 放个人偏好(语言、输出风格)
- 子目录放局部规则(如 frontend/CLAUDE.md)
第四个关键点:Memory 和 CLAUDE.md 是两套系统。 Memory 在 system dynamic 层;CLAUDE.md 在 user message 层。 前者更像系统记忆,后者更像用户上下文。不要混用职责。
第五个关键点:缓存会影响成本和稳定性。 CLAUDE.md 虽不在 system prompt 中,但它作为用户消息也会参与缓存。频繁改动会降低命中率,所以规则定下来后不要天天改。
最后给一个实操模板:
# CLAUDE.md(项目根)
@.claude/rules/code-style.md
@.claude/rules/git-workflow.md
@.claude/rules/testing.md
每个规则文件控制在 50 行内,一条规则一句话,必须可检查、可验收。
总结: CLAUDE.md 不是“写给你自己看的备忘录”,而是“写给模型执行的操作协议”。