编码代理Token预算优化：一个技能吃掉20万token的教训

2026年8月，Anthropic 在 Claude Code 的 changelog 里公布了一次修复：内置的 /claude-api 技能把参考文档整体内联进提示词，一次调用就能吃掉 12 万 token，一句简单提问甚至要烧掉 20 万 token 才开始回答。修复后初始上下文成本降低了至少 85.7%。据 The New Stack 报道，这个案例给所有 AI 编码团队上了一课：Token 预算不是省钱问题，是质量和成本问题。

现代开发工作流中的AI代理

一、事故还原：一个技能如何吃掉20万token

开发者早在 7 月 7 日就发现了问题：Claude Code 2.1.201 的 /claude-api 技能把共享参考文件和检测到的语言文档直接内联进技能体。The New Stack 报道，单次调用就测量到约 12 万 token 的参考资料，其中一份迁移文档自己就占约 3.6 万 token。当技能完整加载后，哪怕只是一行问题，也要消耗约 20 万 token 才会开始回答。

# Before: a skill inlines EVERYTHING into the prompt
# One /claude-api invocation embedded ~120,000 tokens
# of reference material — a single migration doc was ~36,000 tokens
# A one-line question could burn 200,000 tokens before any answer

skill_bundle = {
    "name": "claude-api",
    "mode": "inline_all",          # bad: read all 812 KB
    "reference_files": [
        "migration-guide.md",      # 36,000 tokens alone
        "python-sdk.md",
        "typescript-sdk.md",
        # ... 26 shared markdown files
    ],
}

二、更大的坑：语言检测失败时的降级

8 月 4 日的第二个 bug 报告更夸张：技能检测不到项目语言时，会一次性加载 C#、cURL、Go、Java、PHP、Python、Ruby、TypeScript 八种语言的文档，外加 26 个共享 Markdown 文件，打包目录 812,650 字节。而复现任务真正需要的，只有一个 32,954 字节的文件。内联让代理每次请求都要读完整 812KB，哪怕绝大多数内容毫不相关。

三、为什么「空白支票」时代结束了

Anthropic 自己的最佳实践文档警告：随着上下文窗口被填满，模型更可能丢失早期指令或犯错。The New Stack 的结论更直白：AI 编码的「空白支票」时代正在结束——不受约束的 token 消耗同时伤害质量和成本。上下文越满，回答越差，成本还越高，这是双重打击。

# After: load reference documentation ON DEMAND
# Anthropic cut initial context cost by at least 85.7%
skill_bundle = {
    "name": "claude-api",
    "mode": "lazy_load",           # good: fetch only when needed
    "entry_points": [
        {"trigger": "import anthropic", "load": "python-sdk.md"},
        {"trigger": "import @anthropic-ai/sdk", "load": "typescript-sdk.md"},
    ],
    "fallback": "index.md",        # small file, not all 8 languages
}

四、修复方案：按需加载与懒加载

Anthropic 的修复是把技能的参考文档改为按需加载：只有项目真正 import 了 Anthropic SDK 时才载入对应语言的文档，而不是一次性内联全部。这个思路可以推广到任何团队：把技能/文档拆成入口点，按触发器加载，严格控制默认加载量。目标不是「零文档」，而是「每行文档都要挣得自己的位置」。

# Measure before you optimize: token audit script
# Hidden overhead only surfaces when you actually measure it
import tiktoken

def audit_skill_bundle(bundle_path):
    enc = tiktoken.encoding_for_model("claude-sonnet-4-5")
    total = 0
    for f in bundle_path.rglob("*.md"):
        tokens = len(enc.encode(f.read_text()))
        print(f"{f.name}: {tokens:,} tokens")
        total += tokens
    print(f"TOTAL: {total:,} tokens loaded per request")
    return total

# Real-world finding: 812,650 bytes bundled,
# only one 32,954-byte file was needed up front

五、团队落地：Token 审计与 CI 闸门

三个可执行的落地动作：第一，写一个 token 审计脚本，定期统计技能包和 AGENTS.md 的 token 消耗；第二，给内联内容设预算，比如单技能不超过 1 万 token，超了强制改懒加载；第三，把审计放进 CI，技能包超预算直接让构建失败。看不见的开销，只有量化之后才会被正视。

# CI gate: fail the build when a skill grows too fat
# Keep every line of agent docs earning its place
TOKEN_BUDGET = 10_000   # max tokens inlined per skill

def ci_check():
    total = audit_skill_bundle("skills/")
    if total > TOKEN_BUDGET:
        raise SystemExit(
            f"Skill bundle too large: {total:,} tokens "
            f"(budget {TOKEN_BUDGET:,}). Use lazy loading."
        )
    print("Skill bundle within budget ✅")

六、对开发者的日常启发

这个案例离我们不远：你的 AGENTS.md、CLAUDE.md、自定义技能，每行都会被代理在每个会话里重读。文件越臃肿，每次请求的隐藏成本越高。定期用 token 计数工具检查你的 agent 文档，删掉过时内容，把大文档拆成按需加载的小文件——省下的不只是钱，更是模型注意力。