《Claude Code 工程化实战》第 31 讲 Claude Code 性能优化

📌本讲摘要· Claude Code 性能优化不是"加机器"的问题，而是"用对模型、管好上下文、复用连接、善用回滚"的系统工程。本讲从模型分级选型、上下文压缩、Token 经济、Checkpointing 回滚、MCP 连接复用、实战调优剧本六个维度，系统拆解"省时间、省钱、少返工"的工程方法论。学完本讲，你应该能针对一个真实项目的月账单做出可量化的优化方案，并在 5 步之内把单次任务的 Token 消耗压到原来的 30% 以下。

1. 模型分级选型：不是每件事都需要 Opus

Claude Code 支持四种模型档位，合理选型是性能优化里 ROI 最高的一招。

实战代码块 1 — 用 haiku 跑轻量任务。把"模型选择"变成项目级约定，而不是每次手动指定。

# .claude/skills/lint-fast/SKILL.md --- name: lint-fast description: 跑 ESLint + Prettier 校验，用 haiku 模型秒回。触发关键词：lint, format, check style, 格式化, 检查代码风格。 model: haiku tools: [Bash, Read] --- # Lint Fast Skill 只跑以下命令，不做任何修改： ```bash pnpm run lint:check

返回结果时：

• 通过 → 简短回复 “LGTM ✓”
• 失败 → 列出错误文件 + 行号，不在此 Skill 中自动修复

把 Skill 的 `model` 字段显式锁死，子代理或 Hook 在调用 lint 时就永远走最便宜的模型。即使父 Agent 正在用 opus 处理复杂任务，子代理也能并行用 haiku 校验代码风格，总耗时反而更短——因为不必等主对话让出 quota。 回想第 8 讲讲的"并行不悖"——子代理天然适合跑轻量模型。一个典型组合： - **主 Agent** (opus)：负责架构设计、跨文件推理、写复杂业务逻辑 - **子 Agent 1** (haiku)：负责 lint、格式化、单测生成 - **子 Agent 2** (sonnet)：负责单文件 bug 定位、简单改写 三档模型同时跑，主对话只承担最贵的部分，总账单立刻降一半以上。 > ⚠️ **坑 1** · 以为"默认 inherit 就够"——很多企业账户默认 inherit 走的是 opus 档，如果不在 Skill 里显式锁 `model: haiku`，你可能在不知不觉中烧掉 10× 的钱。 ## 2. 上下文压缩：Token 才是最贵的资源 Claude Code 的对话是"上下文窗口"的累积游戏，聊得越久，Token 越多，响应越慢，账单越贵。三个常用压缩手段： | 手段 | 触发方式 | 保留什么 | 丢弃什么 | |---|---|---|---| | `/clear` | 用户手动输入命令 | CLAUDE.md、项目记忆 | 整段对话历史 | | 摘要压缩 | 自动（每 50 轮触发）或 `/compact` | 关键决策、文件路径、错误信息 | 过程性输出、已读文件内容 | | Skill 渐进式披露 | 自动（按需加载） | 当前任务需要的 Skill 正文 | 未触发的 Skill 全文 | **实战代码块 2 — 自动摘要压缩脚本**。如果你想让团队每个人都用上 `/compact`，可以做成一个 pre-commit hook： ```bash # scripts/auto-compact-reminder.sh #!/usr/bin/env bash # 检测当前会话对话轮数，超过 40 轮时提醒 compact set -euo pipefail TURNS_FILE=".claude/.session-turns" mkdir -p .claude if [ ! -f "$TURNS_FILE" ]; then echo "0" > "$TURNS_FILE" fi CURRENT=$(cat "$TURNS_FILE") NEXT=$(CURRENT + 1) echo "$NEXT" > "$TURNS_FILE" if [ "$NEXT" -ge 40 ] && [ "$NEXT" -lt 42 ]; then echo "⚠️ 本会话已对话 ${NEXT} 轮，Token 累积较多。" echo "建议执行：claude> /compact" echo "或：claude> /clear (完全重置，保留 CLAUDE.md)" fi

把这个脚本挂到 Hook 的UserPromptSubmit事件上（参考第 17 讲），每次用户提交就自增一次计数，到阈值时弹个提醒。这比让用户自己记"该 compact 了"靠谱得多。

2.1 上下文压缩的边界

摘要压缩会丢失"过程性细节"——比如你让 Agent 改 10 个文件，它读完这 10 个文件的内容会留在上下文里；压缩后只剩"修改了哪些文件 + 改了什么"，内容本身没了。如果接下来还要基于这些文件的内容继续工作，就别压缩，改成开新会话（用 CLAUDE.md 衔接）。

⚠️坑 2· 在长任务中间无脑/compact——压缩后 Agent 忘了刚才读过的文件内容，会重新去读，反而多花一次 Read 工具调用的 Token。原则：任务有连续性就别 compact，有阶段切换就果断 clear。

3. Token 经济：批处理 + 并行 + 工具裁剪

Token 消耗有三大来源：模型推理（输出）、工具调用（输入+输出）、系统提示（每次会话固定）。我们能压的主要是前两项。

实战代码块 3 — 批处理多文件 review。不要让 Agent 一次只读一个文件，而是让它"一次性把整个目录的 diff 拉过来"：

# 错误做法：让 Agent 一个个文件地问 User: "请 review src/ 下的所有文件" # Agent 会调 30 次 Read，每次都是独立工具调用 # 每次 Read 都把"工具描述 + 文件路径"塞进上下文，浪费 1000+ Token # 正确做法：让 Agent 一次性看全 User: "请用 git diff HEAD~1 -- src/ 看今天改了什么，review 一遍" # 一次 Bash 调用，把所有 diff 拉到一个输出里 # Agent 直接基于这个 diff 写 review，Token 消耗 -60%

三个具体技巧：

• grep 优于 Read：要看 30 个文件里是否包含某 pattern，直接grep -rn pattern src/，不要让 Agent 一个个 Read
• git diff 优于 file 全文：review 改动只关心 diff，不用看未改的部分
• 批处理优于循环：一个 Bash 里跑 5 个命令，比 5 个 Bash 调用便宜 5 倍（因为系统提示只算一次）

⚠️坑 3· 在 prompt 里堆"请严格按照以下 12 条要求……"——每条要求都是 Token，而且模型对长 prompt 的遵从度反而下降。原则：prompt 短一点 + Skill 长一点（让 Skill 按需加载）。

4. Checkpointing 与回滚：用对方法少返工

Claude Code 的/rewind命令（或者用 git stash/branch 配合）能在 Agent 改坏文件时一键回退，这是性能优化里"省时间"维度最被低估的一招。

实战代码块 4 — 性能监控片段。建议每个项目都开一个轻量监控，看自己实际跑得怎么样：

# .claude/hooks/log-usage.sh#!/usr/bin/env bash# 每次 Agent 完成任务时，记录耗时与 Token 估算# 挂到 Stop 事件set-euopipefailLOG=".claude/usage.log"TIMESTAMP=$(date-Iseconds)TURNS=$(cat.claude/.session-turns2>/dev/null||echo"0")# 简单估算：每轮平均 2000 tokenEST_TOKENS=$(TURNS *2000)echo"${TIMESTAMP}turns=${TURNS}est_tokens=${EST_TOKENS}">>"$LOG"# 周报：统计过去 7 天的总 Token 估算if["$(date+%u)"="1"];thenecho"📋 本周 Token 估算："awk'{sum+=$NF} END {print sum " token"}'"$LOG"|tail-7fi

1. 改文件前先 commit：让 Agent 改之前先git add -A && git commit -m "before: $TASK"，这样改坏了git checkout一秒回退
2. 大改前先开分支：跨 20+ 文件的重构，新开git checkout -b refactor/xxx，失败就git checkout main && git branch -D
3. 用/rewind处理误操作：Agent 误删文件、跑错命令时，直接/rewind回到上一步，比手动回退快 10×

回滚的"性能意义"在于：Agent 返工一次的成本，通常比"小心翼翼地慢慢改"高 5×。大胆改、快回滚，反而是最高效的节奏。

⚠️坑 4· 让 Agent 改文件之前没有 commit——改坏了一脸懵，不知道哪一步出错，只能让 Agent 自己修复，陷入"修一个 bug 引入三个 bug"的死循环。

5. MCP 连接复用：别每个会话都重握手

每个 MCP server 第一次连接时都要握手、鉴权、加载工具列表，这一下可能花掉 3–5 秒 + 几千 Token。如果你在同一个项目里反复开会话，可以用以下方式复用：

• Skill 化 MCP 配置：把常用 MCP server 的配置写到 Skill 的mcpServers字段，首次加载后缓存工具列表
• 用--continue续接：claude --continue会复用上次的 MCP 连接，而不是重新握手
• 长期任务用 SDK：Agent SDK 里的ClaudeCodeOptions.mcp_servers可以在进程内复用连接，适合跑长链路任务

MCP 复用是"省时间"维度收益最大的优化之一。一个本来 30 秒启动的任务，复用后 3 秒启动，体感像"本地应用"。

6. 实战调优剧本：从月账单到周预算

如果你的 Claude Code 月账单开始"超出预期"，按这个剧本做 5 步优化，通常能把成本压到原来的 30–50%：

🚀 性能调优剧本 · 5 步法

注意区分"基线"和"优化"——基线是"达成业务目标所需要的最低成本"，优化是"在基线之上锦上添花"。如果你的 Agent 经常返工，先解决返工问题（改 prompt、加测试、明确边界），再做 Token 优化。否则省下来的 Token 都会被返工吃掉。

7. 一句话备忘

⚙️ 性能优化的本质不是"让模型变快"，而是"让对的模型，在对的时间，处理对的事"。