网上教怎么写 CLAUDE.md 的分享已经不少了：保持简洁、读代码库优先于写新代码、指明规范、验证优先……这些原则都对，照着写基本不会踩大坑。
用 Claude Code 深度开发了几个月后，我发现一个大家很少提到的细节：CLAUDE.md 的写法不只决定 Claude 的回答质量，还直接决定实际的 token 账单。这不是"写得好让 AI 更懂你"这种感觉层面的事，背后是 Anthropic 的 Prompt Caching 机制。搞懂这个机制之后我调整了自己的 CLAUDE.md 结构和使用习惯，账单降了不止一半。
这篇想讲的不是空泛的提示词套路，是从缓存匹配机制切入，看清 CLAUDE.md 到底怎么影响成本，再给几条实战法则。
CLAUDE.md 是怎么进入请求链路的
很多人以为 CLAUDE.md 只是挂在项目根目录的一份说明文档。但 Claude Code 实际发请求时，它被放在了一个挺关键的位置。
一次典型的终端对话请求，发给 API 的内容结构大致是这样：
[全局 system prompt 和工具定义] → [CLAUDE.md 项目规则] → [历史对话 1~N] → [当前用户输入]
Anthropic 服务端要让所有用户共享同一份基础缓存（system prompt、工具定义这些全网一致的静态部分），所以把它们放在最前面。CLAUDE.md 作为项目专属规则，紧跟在后面注入到上下文的前半段。
这意味着 CLAUDE.md 是整条缓存链的锚点：后面所有历史对话能不能命中缓存，取决于它有没有变。
为什么改一个字会引发缓存雪崩
Anthropic Prompt Cache 靠的是精确前缀匹配，从开头逐字比对，某个位置一旦变了，从那往后的所有内容全部失效，要重新计算。
计费差得也很悬殊：命中缓存（cache read）按基础价的 10% 收费；创建缓存（cache write）反而要按 125% 收费，多付四分之一。缓存本身有个 5 分钟的有效期，只要持续对话，每次请求都会把它续上。
设想一个场景：你在终端里聊了 15 轮，攒了 3 万 token 的历史上下文，都已经命中缓存。这时候你突然想起某条规范漏了，顺手在 CLAUDE.md 里加了一句"记得用 pnpm 代替 npm"。
结果是这 3 万 token 原本只要付 10% 读取费，现在全部按 125% 的写入费重新算了一遍，只因为多打了十个字。会话进行到第 20 轮时改一次 CLAUDE.md，这一下的成本可能比前面 19 轮加起来还高。
几条实战法则
理解了前缀匹配机制，网上那些"最佳实践"就不再是经验之谈，是有具体成本依据的判断。
CLAUDE.md 尽量控制在 50 到 100 行左右。它越长，每次新开会话建立首次缓存的开销就越大。详细的架构文档、API 字段说明放到 docs/ 目录里，CLAUDE.md 里只留一句索引，比如"API 规范参阅 docs/api_style.md"，Claude Code 需要时会自己去读。
会话进行到中途，不要去改 CLAUDE.md。发现漏写了什么，就在当次消息里口头提一句，只影响这一轮；等 session 结束，或者用 /clear 开新的，再把规则正式补进去。
不要把会频繁变动的内容写进 CLAUDE.md，比如"今日 TODO"、临时的 bug 备注、版本号。这类内容天生就会被反复改，放在缓存链最靠前的位置等于反复引爆雪崩，写在对话里或者别的文件里都更合适。
规则该分层放：个人的全局偏好放全局配置，项目通用的规范放项目根目录的 CLAUDE.md，模块特有的细节放子目录文档里。范围划得越窄，一次改动牵连失效的内容就越少。
我自己踩过的坑
以前有个习惯：写着代码突然想起某个约定没写进 CLAUDE.md，就顺手加一行。聊到第十几轮的时候，想起"这个项目要用 pnpm 不用 npm"，就去补一句。
当时没觉得有什么，只多了一行字。后来查账单才发现，那次改动让前面十几轮的历史对话缓存全部失效，那一轮的输入 token 花费比平时高了一个量级。
后来改成：项目开始前先想清楚有哪些约定，一次性写进去；对话中发现漏了什么，先记着，等这个 session 结束、开新的再统一补。这个改变不复杂，省下来的钱是实打实的。
怎么验证缓存到底有没有生效
不用凭感觉，看请求返回的 usage 字段就知道：
{
"usage": {
"input_tokens": 120,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 15420,
"output_tokens": 350
}
}
cache_creation_input_tokens 是新写入缓存的部分，按 125% 计费；cache_read_input_tokens 是命中缓存的部分，按 10% 计费；input_tokens 是没进缓存的增量部分，按全价算。
连续对话的第一轮，creation 应该较大，read 接近 0，因为刚在建缓存。第二轮往后，read 应该远大于 input，creation 接近 0。如果某一轮 read 突然归零、creation 又暴增，说明前缀被破坏了，去查是不是改了 CLAUDE.md、换了模型，或者用了什么重写 prompt 的指令。
顺带一提，如果是通过第三方中转接入 Claude API，这几个字段也能用来判断对方是否透明转发。我自己日常在用灵眸AI（api.lmuai.com），cache_read_input_tokens 会完整透传，用上面的方法就能验证到。市面上有些中转会把缓存字段直接剥离甚至隐性按全价扣费，usage 里能不能看到完整的 cache_read_input_tokens，基本就是判断标准。
小结
CLAUDE.md 该写哪些内容，网上已经有不少靠谱的分享。想说的是另一层：这些最佳实践背后有一个具体、可验证的技术原因，就是 Prompt Cache 的前缀匹配机制。理解了这一点，"为什么要简洁""为什么别中途改"就不再是经验之谈。
回头打开自己的 CLAUDE.md 看看：是不是写得太长了，有没有经常变动的临时规则。把这两个地方堵上，比换模型、换接入方式更立竿见影。
文中涉及的 Prompt Cache 计费比例基于 Anthropic 官方文档整理，具体计费标准请以官方最新公示为准。
