CLAUDE.md 会消耗多少 token，该写多长

CLAUDE.md 是一份 Markdown 常驻指令文件，Claude Code 在会话开始时将它加载进上下文窗口。它不是系统提示的一部分：Claude Code 把它作为紧随系统提示的用户消息发送，Claude 将其视为指导，而非强制配置。

模型在请求之间不保留记忆，所以 Claude Code 每次调用都会重发完整上下文：系统提示、项目上下文、先前每条消息和工具结果。每轮工具使用都是一次新调用。因此，即使你只发了一条提示，只要 Claude 读了五个文件并运行测试，就会产生多次请求，每次都携带完整的 CLAUDE.md。

简言之，每一行都在每次请求中计费。缓存有效时价格有折扣；重建缓存时，价格还高于普通输入。文件应保持简短，不必每轮加载的内容应移到按需读取的文件。

哪些文件会加载，何时加载

Claude Code 会拼接找到的所有记忆文件，一份不会取代另一份。以 2026 年 9 月的 Claude Code 文档为准，来源包括：

• →托管策略：由组织的 IT 部署、全员适用的 CLAUDE.md，例如 Linux 上的 /etc/claude-code/CLAUDE.md。无法排除。
• →用户级：~/.claude/CLAUDE.md 和 ~/.claude/rules/ 中的规则，适用于这台机器上的所有项目。
• →项目级：./CLAUDE.md 或 ./.claude/CLAUDE.md，以及 .claude/rules/ 中没有 paths 字段的文件，通过版本控制共享。
• →本地级：./CLAUDE.local.md，只用于一个项目的个人笔记，通常加入 .gitignore。
• →自动记忆：Claude 为仓库维护的 MEMORY.md 索引，最多读取前 200 行或 25KB。索引指向的专题文件只在需要时读取。

工作目录及其上层目录中的文件会在启动时加载。子目录的 CLAUDE.md 只有在 Claude 读取该目录中的文件时才加载；带 paths 的规则也只在读取适用文件时加载。导入容易造成误判：@path/to/file 会在启动时引入该文件，最多深入四层。把长文件拆成导入只会让它看起来整齐，不会省下一个 token。

为什么缓存不等于免费

提示缓存会比较每次请求的开头与近期处理过的内容，相同部分按较低价格计费。Claude Code 将较少变化的内容排在前面：系统提示和工具定义、项目上下文（记忆文件），然后才是对话。普通一轮请求里，CLAUDE.md 通常由缓存读取。

按 Anthropic 于 2026 年 9 月公布的 API 价格，多数 Claude 模型的缓存读取价格是基本输入价格的十分之一，少数较新模型更低。五分钟有效期的缓存写入是基本价格的 1.25 倍，一小时有效期则是 2 倍。每当必须重写前缀，CLAUDE.md 的计费就会高于普通输入。发生次数可能比你想的多：

• →暂停时间超过缓存有效期：Claude 订阅所含用量中的主对话是一小时，使用 API 密钥时默认五分钟。
• →切换模型（每个模型有独立缓存），或在多数模型上改变推理强度。
• →排在它前面的工具定义改变，例如会话中途连接了一个预先加载工具的 MCP 服务器。
• →每个内置 Explore、Plan 以外的子代理：它们把你的 CLAUDE.md 加载到自己的上下文，建立自己的缓存，即使用订阅，默认有效期也是五分钟。
• →在不同 worktree 或目录启动会话，因为缓存实际上按目录隔离。

缓存改变价格，不改变大小。文件每次请求都占用窗口，让对话在自动压缩前剩下更少空间。文件越长，规则越难被稳定遵循，因为每条规则获得的注意力更少。订阅用户虽然没有逐次账单，同一份上下文仍会消耗套餐用量。

如何查看自己的文件花了多少

打开新会话，在输入任何内容前先看看窗口里已经有什么：

$/context

/memory 会列出记忆文件，也能在编辑器中打开它们。从 Claude Code v2.1.251 起，/usage 增加 Prompt cache (main) 一行，显示从缓存读取的输入比例和未命中次数。未命中次数持续增加，说明包含记忆文件在内的前缀正反复重写。

哪些内容该放进去

Anthropic 对每一行的判断标准是：删掉它会不会让 Claude 犯错？不会就删。真正需要保留的内容通常很短：

• →Claude 无法自行推断的构建、测试和代码检查命令。
• →有别于默认值的代码风格规则，而非格式化工具已经强制执行的规则。
• →仓库协作约定，例如分支命名、提交和拉取请求规范。
• →这个项目特有的架构决定。
• →环境中特别需要注意的地方，例如必需的变量或必须运行的服务。
• →已经让人浪费过时间、又不容易看出的陷阱。

把每条规则写得可检查。‘提交前运行 npm test’有效，‘测试你的修改’则不够具体。文档建议每个文件少于 200 行。

哪些内容应移走，移到哪里

臃肿的 CLAUDE.md 中，多数内容本身并没有错，只是放错了位置。不同内容有成本更低的去处：

• →Claude 能从代码中读出的内容，例如目录结构、依赖清单、逐文件说明：删除。
• →较长的参考资料，例如 API 文档或风格指南：单独存成文件，只写路径而不加 @，让 Claude 在任务需要时才打开。
• →多步骤流程，例如发布清单：写成技能。会话开始时只加载技能的简短描述，其余内容在使用时才加载。
• →只适用于部分代码的规则：写进带 paths 模式的 .claude/rules/ 文件，或该子目录的 CLAUDE.md。两者都只在 Claude 读取适用文件时加载。
• →每次都必须发生的动作，例如编辑后格式化：使用 hook。只要没有返回输出，hook 不占上下文，而且它会强制执行。

如何精简文件

先用 Claude Code 自带的检查功能。从 v2.1.206 起，/doctor 会对已纳入版本控制的 CLAUDE.md 提出删减建议：去掉 Claude 可从代码推断的内容，保留陷阱、原因和有别于工具默认值的约定，并把剩余的常驻指引转移到按需加载的技能及嵌套文件。

$/doctor

然后再手工检查几遍：

• →删除 Claude 本就会遵守的规则：去掉那一行，观察行为是否改变。
• →把写给维护者看的说明改为块级 HTML 注释。Claude Code 会在内容到达模型前移除 <!-- ... --> 块。
• →消除矛盾。两条互相冲突的规则要付两份成本，Claude 还可能遵守任意一条。
• →在 monorepo 中用 claudeMdExcludes 设置跳过其他团队的文件。
• →不需要这些指令的自定义子代理，可在定义中设置 omitClaudeMd: true（v2.1.271 或更新版本）。

AGENTS.md 与 Codex CLI

Codex CLI 读取的是 AGENTS.md。按其 2026 年 9 月的文档，它每次运行建立一次指令链，在交互界面中通常每个会话建立一次：

• →全局：在 ~/.codex 或设置了 CODEX_HOME 时的对应目录中，优先使用 AGENTS.override.md，否则使用 AGENTS.md。
• →项目：从项目根目录（通常是 Git 根目录）到启动目录，每层最多取一个文件，依次查找 AGENTS.override.md、AGENTS.md，再查找 project_doc_fallback_filenames 列出的名称。
• →从根目录往下拼接，跳过空文件；合计内容达到 project_doc_max_bytes 后不再追加，默认阈值为 32 KiB。

结果进入会话首轮，之后的请求也会携带。Codex 自己给出的延长用量上限的建议，包括缩短 AGENTS.md，并把文件放到其适用目录。以 2026 年 9 月为准，它的积分价目表按新输入十分之一的价格计算缓存输入，没有单独的缓存写入费用。若要查看模型实际收到的指令，可运行：

$codex debug prompt-input

同一份文件可以服务两个代理。从 v2.1.277 起，如果工作目录及其上层没有 CLAUDE.md 或 CLAUDE.local.md，Claude Code 会把 AGENTS.md 作为项目指令读取。否则，可在 CLAUDE.md 顶部加入 @AGENTS.md。Claude Code 不读取 AGENTS.override.md。

固定成本与可变成本

精简指令文件，可以降低每轮请求的固定成本。其余成本来自每项任务额外读取的文件、命令输出和对话历史。直接点名目标文件，并为每项任务开启新会话，可以压低这部分。

如需为这部分设定硬上限，capsul 可驱动你已经登录的 Claude Code 或 Codex CLI，按你设定的 token 预算发送任务所需内容，并告知哪些内容未被纳入。测量结果见基准测试页。