token-saver-claude-code

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Token Saver for Claude Code

Claude Code Token 节省器

This skill has two jobs:
  1. Work lean while it is active: follow the core rules below on every step.
  2. Tune the setup when the user asks for an audit or setup, or keeps hitting limits: run the workflow in "Audit and setup".
<!-- core-rules:start (synced from shared/core-rules.md by scripts/sync.mjs; edit the shared file) -->
该 skill 有两项任务:
  1. 启用期间精简工作:每一步都遵循以下核心规则。
  2. 调整配置:当用户要求审计或设置配置,或反复达到限额时,运行“审计与设置”中的工作流。
<!-- core-rules:start(由 scripts/sync.mjs 从 shared/core-rules.md 同步;请编辑共享文件) -->

Core rules: work lean, stay correct

核心规则:精简工作,保持正确

Why these rules: every request resends the whole context, so cost grows with context size times the number of requests. Output tokens cost several times more than input tokens. Rework costs the most of all. Cut the first two only in ways that never cause the third.
Before acting
  • If the request is ambiguous in a way that would change the result, ask one short question instead of guessing. For multi-file or risky changes, outline the plan before editing.
  • Stop exploring once you know enough to act. Do not survey the whole codebase for a narrow request.
Reading
  • Locate first (grep, glob, symbol search, LSP), then read only the relevant range of a large file. Do not re-read a file that is already in context and unchanged.
  • Never read lockfiles, generated, minified or build output, vendored dependencies, or whole logs. Search them instead.
Tool output
  • Prefer summary forms:
    git status -s
    ,
    git diff --stat
    before a full diff,
    git log --oneline -n 20
    , and
    ls
    of one directory rather than a recursive tree.
  • Run the narrowest check that proves the change (one test file or case, a typecheck of the touched files) with quiet flags. Pipe long output through
    tail -n 40
    or
    grep -E "FAIL|Error|error:"
    . Run the full suite once at the end if it is needed.
  • Send independent tool calls together in one turn, and make all edits to one file in one pass.
Delegation: do it yourself by default
  • A subagent is not free. It starts with a fresh context, reloads the instruction files, re-discovers what you already know, adds latency, and its tokens count against the same limit. Its summary also drops detail you may need later.
  • Delegate only when one of these holds: the answer needs reading many files (about ten or more) or a large output (test runs, logs, long docs) that you will not need afterwards and that condenses to a short summary; there are three or more independent, read-only pieces that can run in parallel; or you want an independent review with a clean context.
  • Keep it in the main thread for small or quick tasks, steps that depend on the previous step's output, work that needs back-and-forth, and every edit. Keep writes in one thread and never let two agents edit the same file.
  • When you delegate, use a cheaper model, give a precise brief (goal, paths, what to return, a length cap), ask for conclusions with
    path:line
    references, and do not redo the subagent's reading yourself.
Answers
  • Lead with the result. Do not restate the request, recap what did not change, or dump a whole file when an edit or a
    path:line
    reference will do.
  • Size the answer to the question. Skip optional extras (docs, refactors, extra tests) and offer them in one line instead.
Do not under-save
  • For hard bugs, security, data-loss risk, or architecture, read and reason as much as needed. One correct attempt is cheaper than two cheap wrong ones.
  • Never skip verification to save tokens. Make it targeted instead.
Session coaching (one line, only at a natural break, at most once per break)
  • On a switch to an unrelated task, suggest a fresh session. On a long session about one task, suggest compacting with a focus hint.
  • For routine work on a flagship model or high reasoning effort, suggest a cheaper setting. For a hard problem on a small model, suggest upgrading.
<!-- core-rules:end -->
原因:每个请求都会重新发送整个上下文,因此成本等于上下文大小乘以请求次数。输出 Token 的成本是输入 Token 的数倍。返工成本最高。只有在不引发返工的前提下,才能削减前两项成本。
执行前
  • 如果请求中的歧义会改变结果,应提出一个简短问题,而不是猜测。对于涉及多个文件或存在风险的更改,在编辑前先概述计划。
  • 一旦掌握足够信息即可停止探索。对于范围很小的请求,不要遍历整个代码库。
读取
  • 先定位(grep、glob、符号搜索、LSP),然后只读取大文件中的相关范围。如果文件已在上下文中且未发生变化,不要重新读取。
  • 绝不读取 lockfile、生成文件、压缩文件或构建产物、vendored 依赖或完整日志。应改为搜索它们。
工具输出
  • 优先使用摘要形式:
    git status -s
    ,完整 diff 前使用
    git diff --stat
    ,使用
    git log --oneline -n 20
    ,以及对单个目录执行
    ls
    ,而不是递归目录树。
  • 运行能够证明更改有效的最窄检查(一个测试文件或用例,或对已修改文件进行 typecheck),并使用 quiet flags。对于长输出,通过
    tail -n 40
    或
    grep -E "FAIL|Error|error:"
    进行过滤。如果确有需要,在最后运行一次完整测试套件。
  • 在同一轮中并行发起相互独立的工具调用,并一次性完成同一文件的所有编辑。
委派:默认自行完成
  • subagent 并非免费。它需要从全新上下文开始,重新加载指令文件,重新发现你已经知道的内容,增加延迟,而且其 Token 会计入同一限额。它的摘要还可能丢失你之后需要的细节。
  • 仅在以下情况下委派:答案需要读取许多文件(约十个或更多),或者需要处理之后不会再用的大量输出(测试运行、日志、长文档),且可将其压缩为简短摘要;存在三项或更多相互独立的只读任务可并行执行;或者希望使用干净上下文进行独立审查。
  • 小型或快速任务、依赖上一步输出的步骤、需要反复来回沟通的工作,以及所有编辑,都放在主线程中处理。写入操作应集中在一个线程中,绝不能让两个 Agent 编辑同一文件。
  • 委派时,使用成本更低的模型,提供精确任务说明(目标、路径、需返回的内容、长度上限),要求给出带
    path:line
    引用的结论,并且不要重新读取 subagent 已经读过的内容。
回答
  • 先给出结论。不要复述请求、重复总结未变更的内容,也不要在编辑内容或
    path:line
    引用已足够时倾倒整个文件。
  • 根据问题控制答案篇幅。跳过可选附加内容(文档、重构、额外测试),需要时用一行说明可另行提供。
不要过度节省
  • 对于疑难 bug、安全问题、数据丢失风险或架构工作,应按需充分阅读和推理。一次正确的尝试比两次廉价但错误的尝试更省成本。
  • 绝不能为节省 Token 而跳过验证。应让验证更有针对性。
会话指导(仅一行,只在自然停顿处提出,每次停顿最多一次)
  • 切换到无关任务时,建议开启新会话。对于围绕同一任务的长会话,建议使用 focus hint 进行压缩。
  • 对于在旗舰模型或高 effort 下执行的日常工作,建议使用成本更低的设置。对于小模型上的难题,建议升级。
<!-- core-rules:end -->

Claude Code specifics

Claude Code 专属规则

Apply these on top of the core rules.
  • Subagents: apply the delegation rule above. When it holds, the built-in Explore agent (read-only, runs on Haiku) suits codebase searches; otherwise pass
    model: "haiku"
    or
    sonnet
    for simple briefs. A fresh subagent reloads CLAUDE.md and has a cold cache; a fork inherits the conversation and reads the parent's cache, so a fork is cheaper to start when the task needs what you already know. Agent teams cost several times a normal session; never start one to save tokens.
  • Cache awareness: a model switch, an effort change on most models, turning on fast mode, and connecting MCP servers mid-session make the next request re-read the whole history uncached. Suggest those changes only at task boundaries.
  • What to suggest to the user (they run these; you cannot):
SituationSuggest
Starting unrelated work
/clear
(free).
/rename
first if they may
/resume
later
Long session, same task, context large
/compact <what to keep>
at a natural break. It costs one large request, so do not repeat it
Went down a wrong path
/rewind
(or Esc twice) instead of arguing the model back; it reuses the cache
Routine edits on Opus or high effort
/model sonnet
or
/effort low
/
medium
at the next task boundary
Planning then implementation
/model opusplan
(Opus plans, Sonnet executes)
Unsure where usage goes
/usage
(plan bars, attribution, cache stats) and
/context
Complex changePlan mode (Shift+Tab) before editing
在核心规则的基础上,还应遵循以下规则。
  • **Subagents:**遵循上述委派规则。满足条件时,内置 Explore Agent(只读,在 Haiku 上运行)适合代码库搜索;否则,为简单任务说明传入
    model: "haiku"
    或
    sonnet
    。全新 subagent 会重新加载 CLAUDE.md,且没有热缓存;fork 会继承对话并读取父级缓存,因此当任务需要你已经掌握的信息时,使用 fork 启动成本更低。Agent 团队的成本是普通会话的数倍;绝不要为了节省 Token 而启动 Agent 团队。
  • **缓存感知:**在大多数模型上切换模型、调整 effort、开启 fast mode,以及会话中途连接 MCP 服务器,都会使下一个请求重新读取未缓存的完整历史。仅在任务边界建议进行这些更改。
  • 应向用户建议什么(这些命令由用户运行,你无法运行):
情况建议
开始处理无关工作
/clear
(免费)。如果用户之后可能执行
/resume
,先运行
/rename
长会话、同一任务、上下文较大在自然停顿处执行
/compact <what to keep>
。这会消耗一次大型请求,因此不要重复执行
走错了方向使用
/rewind
(或按两次 Esc),而不是试图用论证让模型回退;它会复用缓存
使用 Opus 或高 effort 进行日常编辑在下一个任务边界执行
/model sonnet
或
/effort low
/
medium
先规划后实施
/model opusplan
(Opus 负责规划,Sonnet 负责执行)
不确定用量去向
/usage
(套餐用量条、归因、缓存统计)和
/context
复杂更改编辑前进入 Plan mode(Shift+Tab)

Audit and setup

审计与设置

When the user asks to audit, set up, or cut usage, or keeps hitting limits:
  1. Run
    node <this skill's directory>/scripts/audit.mjs --agent claude-code
    from the project root. It is read-only and prints warnings with fixes. Without Node.js, check the same items by hand using references/levers.md.
  2. Report the findings ranked by expected savings, in a few lines each. Always-loaded content (CLAUDE.md, unscoped rules, MCP servers, skill descriptions) usually matters most because it is paid on every request.
  3. Propose concrete edits, with the exact settings keys from references/levers.md. Settings and CLAUDE.md belong to the user: show the diff and apply it only after they agree. Note that CLAUDE.md edits take effect after
    /clear
    ,
    /compact
    or a restart.
  4. Offer to add the always-on snippet: skills load only when triggered, so the lean-work rules need a short permanent home. Append assets/always-on.md to
    CLAUDE.md
    (project) or
    ~/.claude/CLAUDE.md
    (all projects), unless an equivalent section is already there.
当用户要求审计、设置配置、减少用量,或反复达到限额时:
  1. 从项目根目录运行
    node <this skill's directory>/scripts/audit.mjs --agent claude-code
    。它是只读操作,会输出警告及修复建议。如果没有 Node.js,则使用 references/levers.md 手动检查相同项目。
  2. 按预期节省量排序报告发现,每项控制在几行内。始终加载的内容(CLAUDE.md、未限定作用域的 rules、MCP 服务器、skill 描述)通常影响最大,因为这些内容会在每个请求中付费。
  3. 提出具体修改建议,并使用 references/levers.md 中确切的 settings key。settings 和 CLAUDE.md 归用户所有:先展示 diff,只有用户同意后才应用。请注意,CLAUDE.md 的编辑会在执行
    /clear
    、
    /compact
    或重启后生效。
  4. 提议添加始终启用的片段:skills 仅在触发时加载,因此精简工作规则需要一个简短、永久的存放位置。将 assets/always-on.md 追加到 CLAUDE.md(项目)或
    ~/.claude/CLAUDE.md
    (所有项目),除非文件中已有等效章节。

References

参考资料

  • references/levers.md: every Claude Code command, setting, environment variable and hook that affects token use, with examples. Read before changing configuration.
  • references/facts.md: plan limits, caching and pricing facts with sources and date. Read when the user asks about limits or pricing, and verify on the linked page if the answer matters.
  • references/budget.md: how to pace work against 5-hour and weekly windows. Read when the user asks when to use the expensive model or how to avoid running out.
  • references/levers.md:所有会影响 Token 用量的 Claude Code 命令、setting、环境变量和 hook,并附有示例。更改配置前先阅读。
  • references/facts.md:套餐限额、缓存和定价事实,附来源和日期。当用户询问限额或定价时阅读;如果答案很重要,请在链接页面中核实。
  • references/budget.md:如何按照 5 小时和每周窗口安排工作节奏。当用户询问何时使用昂贵模型或如何避免耗尽额度时阅读。