通用 Claude.md 秘诀：切减输出 Token

一个文件。把它放进你的项目里。它能让回复更简洁，并减少高输出量工作流中的总 token 消耗。

注意：指令文件会在每轮对话中增加输入 token。请保持这个文件简短——如果内容增长过多，它带来的成本可能超过节省的成本。

模型支持：基准测试仅在 Claude 上运行过。这些规则与模型无关，理论上适用于任何能够读取上下文的模型——但尚未在 llama.cpp、Mistral 等本地模型上测试。欢迎社区分享测试结果。

使用 Claude Code 时，Claude 生成的每个词都会消耗 token。大多数人从不控制 Claude 的回复方式——他们只是接受模型自行决定输出的内容。

每次回复都以「Sure!」「Great question!」「Absolutely!」开头。

以「I hope this helps! Let me know if you need anything!」结尾。

使用 em dash（--）、智能引号以及可能导致 parser 出错的 Unicode 字符。

回答之前先复述你的问题。

提供超出你要求范围的主动建议。

对代码进行过度设计，引入你从未要求的抽象。

赞同错误陈述（「You're absolutely right!」）。

所有这些都会浪费 token，却没有带来任何价值。

方案一：在聊天中粘贴规则（快速开始）

将以下规则复制到任意新 session 中：

Rules: Read files first. Write complete solution. Test once. No over-engineering.

立即生效，无须配置，适合一次性任务。

方案二：放入 CLAUDE.md 文件（配置一次，持续生效）

your-project/
└── CLAUDE.md    <- one file, zero setup, no code changes

每条消息都会自动应用。更适合日常工作，规模化使用时效率更高。

请根据你的工作流选择。两种方式都有效。

什么时候有帮助，什么时候没有

这个文件最适合：

• 输出量很高的自动化 pipeline（简历机器人、Agent 循环、代码生成）
• 重复执行的结构化任务，因为 Claude 默认的冗长输出会在数百次调用中不断累积
• 需要在不同 session 之间保持一致、可解析输出格式的团队

这个文件不适合：

• 单次简短查询——每条消息都会把该文件加载到上下文中，因此在低输出量的交互里，token 总量反而会增加
• 偶尔进行的一次性使用——使用量较低时，节省的成本无法抵消额外开销
• 修复虚构实现、架构偏移等深层失败模式——这些问题需要 hook、gate 和机械式强制约束
• 每个任务都会使用多个全新 session 的 pipeline——新 session 无法像持久 session 那样充分摊薄 CLAUDE.md 的额外开销
• 大规模场景下的 parser 可靠性——如果你需要保证输出可解析，应使用 API 内置的 structured outputs（JSON mode、带 schema 的 tool use）。这比依赖 prompt 格式规则更加稳健
• 以讨论、质疑和探索替代方案为核心的探索性或架构设计工作——override 规则允许你随时提出这类要求，但如果这是你的主要工作流，这个文件会显得过于受限

真实的权衡是：CLAUDE.md 文件本身会在每条消息中消耗输入 token。节省来自输出 token 的减少。只有当输出量足以抵消持续产生的输入成本时，净收益才为正。使用量较低时，它消耗的 token 会比节省的更多。

使用相同的 5 个 prompt。先在不使用 CLAUDE.md 的情况下运行（baseline），再使用 CLAUDE.md 运行（optimized）。

每 4 个 prompt 大约减少 295 个词。信息相同，信号零损失。

方法说明：这是一个基于 5 个 prompt 的方向性指标（T1～T3、T5 用于测量词数减少情况；T4 是格式测试），并非经过统计控制的研究。即使 prompt 完全相同，Claude 的输出长度也会自然波动。本次测试没有进行方差控制，也没有重复运行。应将 63% 视为高输出量使用场景中的方向性信号，而不是精确、普适的测量结果。CLAUDE.md 文件本身会在每条消息中增加输入 token——只有输出量足以抵消这项持续成本时，才会产生 token 净节省。

可复现的 token 基准测试（2026-06，通过 benchmark/）

上面的原始表格测量的是单次运行的词数。如需查看在 haiku、sonnet、opus 上以 N=5 测得的真实 output_tokens，请参阅 benchmark/SUMMARY.md 和 benchmark/SEMANTIC.md。使用当前精简版 CLAUDE.md 后，输出 token 的降幅约为：haiku 4%、sonnet 12%、opus 7%。使用更严格的规则配置可以达到 63%——可运行 python3 benchmark/run.py -n 5 --model opus 复现，并查看对应模型的报告。

语义评估还确认，当前模型的 baseline 已经实现了 0% 的前言、谄媚、「as an AI」和智能引号。针对这些行为的规则只会产生输入成本，却不会改变输出。请据此删减规则。

外部基准测试（Issue #1）

一项独立基准测试在 3 个编程挑战上运行了 6 套配置：CSV reporter、SQLite window functions 和 Hono WebSocket counter。所有配置都通过了全部测试，因此比较的完全是 cost-to-green。

我们使用相同的测试 harness、在同一天、使用同一模型，将自己的 v8 配置与此前表现最好的 C-structured 进行了正面对比。

v8 配置使用两个文件，总共 7 行。最大的收益来自 WebSocket：明确的模式规则避免了代价高昂的调试循环。

本 repo 将根目录 CLAUDE.md 保持为一小组高影响力规则，以尽量减少重复产生的输入开销。

不使用 CLAUDE.md——代码审查

Great question! I can see you're working with a loop. Let me take a look at that.
That's a thoughtful piece of code! However, I notice there's actually a subtle bug
here that's worth pointing out. The condition i <= arr.length should be i < arr.length.
Using <= means the loop will run one extra iteration... You might also want to consider
using modern array methods like forEach, map, or for...of which are cleaner...
Great catch on reviewing this - it's always good practice to double-check loop
boundaries! I hope this review was helpful. Feel free to share more code anytime!

使用 CLAUDE.md——相同的 prompt

Bug: <= causes an off-by-one error. On the final iteration arr[arr.length] is undefined.

Fix:
for (let i = 0; i < arr.length; i++)

30 个词。修复方案相同，token 减少 75%。

来自社区的专业建议

将规则限定在你实际遇到的失败模式上，而不是使用泛化规则。「be concise」之类的通用规则确实有帮助，但真正显著的收益来自针对你已经遇到的具体问题。

例如，如果 Claude 会在你的 pipeline 中悄悄吞掉错误，可以添加这样一条规则：「when a step fails, stop immediately and report the full error with traceback before attempting any fix.」

具体规则始终胜过泛化规则。

CLAUDE.md 文件可以组合使用——请利用这一点。Claude 可以同时读取多个 CLAUDE.md 文件：全局文件（~/.claude/CLAUDE.md）、项目级文件和子目录级文件。这意味着：

• 将通用偏好（语气、格式、ASCII 规则）放在全局文件中
• 将项目特定的约束（「never modify /config without confirmation」）放在项目级文件中
• 将任务特定的规则放在子目录文件中

这样可以避免任何单个文件变得过于臃肿，并让规则尽可能靠近其实际生效的位置。

不同类型的项目需要不同程度的压缩。你可以选择基础文件加一个 profile，也可以只使用基础文件。

版本化配置集

profiles/ 目录还包含三套版本化配置，分别代表不同的优化策略。请选择与你的工作流相匹配的一套：

• 如果你需要结构化的多步骤工作流和明确的 Agent 协议，请从 v5 开始
• 如果你希望执行速度更快，并采用严格的「done means done」规则，即不再润色已经通过测试的代码，请使用 v6
• 只有在需要最大化成本效率，且任务足够简单、能够在 20 次 tool call 内完成时，才使用 v8

应用规则的两种方式

方案 A：CLAUDE.md 文件（推荐用于日常使用）

• 将文件放到项目根目录
• 每条消息都会自动应用
• 更适合重复任务和 pipeline

方案 B：将规则写入 prompt（适合一次性 session）

• 将规则复制并粘贴到聊天中
• 可以清楚知道本次 session 应用了哪些规则

在 3 个编程挑战上进行基准测试后的成本对比：

两种方式都通过了全部测试。请根据你的工作流选择。

方案一——通用方式（适用于任何项目）

curl -o CLAUDE.md https://raw.githubusercontent.com/drona23/claude-token-efficient/main/CLAUDE.md

方案二——克隆 repo 并选择一个 profile

git clone https://github.com/drona23/claude-token-efficient
cp claude-token-efficient/profiles/CLAUDE.coding.md your-project/CLAUDE.md

方案三——手动操作

复制此 repo 中 CLAUDE.md 的内容，并将其放入项目根目录。

用户指令始终拥有最高优先级。如果你明确要求详细解释或冗长输出，Claude 会遵循你的指令——这个文件绝不会与你对抗。

发现了 CLAUDE.md 能够修复的行为？请创建一个 issue，并附上：

• 令人困扰的行为，即 Claude 默认会做什么
• 触发该行为的 prompt
• 你建议采用的修复规则

社区提交的内容会在完整署名的情况下纳入下一个版本。

包含优化前后词数的完整基准测试结果：请参阅 BENCHMARK.md。

参考资料与致谢

本项目基于 Claude 社区中的真实抱怨构建。所有提供过修复思路的来源都应获得完整认可：

• GitHub #3382——「Claude 对所有事情都说 You're absolutely right」——获得 350 多个赞
• GitHub #14759——「谄媚行为削弱了其作为编程助手的实用性」
• GitHub #9340——「添加 --quiet flag，以隐藏 tool call 输出」
• GitHub #21818——「Tool 输出过于冗长，造成视觉噪声」
• GitHub #20542——「冗长输出淹没 session，并消耗过多 token」
• The Register——「Claude Code 无休止的谄媚令客户恼火」
• DEV Community——「减少 Claude Code token 用量的 7 种方法」
• Medium——「别再浪费 token：将 Claude Code 的上下文优化 60%」
• Anthropic Docs——减少 hallucination
• PromptHub——「减少 hallucination 的三种 Prompt Engineering 方法」
• GitHub Gist——减少 token 用量的实用工作流
• Token Checkup——免费的 token 消耗模式诊断工具：一个包含 5 个问题的浏览器工具，可以分析你的 Claude Code token 用量并提出优化建议
• Cache Health Checker——根据 /cost 输出诊断 cache 效率：粘贴你的 /cost 输出，检查 prompt caching 是否正常工作
• Claude Code Best Practices——社区资料
• Vaibhav Sisinty——GrowthSchool——AI 技能提升和 Prompt Engineering 最佳实践
• Vaibhav Sisinty on X——持续讨论 Claude prompt 优化和 AI 工作流

MIT——可自由使用、修改和分发。

由 drona23 构建——欢迎提交 PR、issue 和 profile。