2 min read

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 不是“写给你自己看的备忘录”,而是“写给模型执行的操作协议”。