Claude Code 进阶技巧与最佳实践：子代理、MCP、成本优化

Claude Code 进阶技巧与最佳实践：子代理、MCP、成本优化

一句话：入门 Claude Code 不难，把它跑成"团队级生产力"才是分水岭。本文不再讲怎么装、怎么配 API Key，而是聚焦进阶工程化：多代理编排、MCP 服务器集成、Hooks 高级用法、Prompt Cache 与统一 1.07× 倍率配合的成本优化、可观测性建设。读完能把 Claude Code 从"AI 助手"用成"AI 工程团队"。

目录

1. 多代理编排：从单代理到团队拓扑
2. MCP 服务器集成：扩展工具与数据源
3. Hooks 高级用法：拦截、变更、组合
4. 工作流自动化：脚本化 / CI / 定时任务
5. Prompt Cache 与成本优化
6. 倍率与模型路由策略
7. 可观测性：用量、费用、错误的归因
8. 团队协作进阶：配置标准化与 Key 治理
9. 真实场景案例：四个高价值工程化模式
10. FAQ
11. 相关资料

多代理编排：从单代理到团队拓扑

为什么要起子代理

单代理跑长任务有两个固有问题：上下文窗口有限（即使百万级也不是免费的），以及任务"分工不清晰"会让一个会话同时背架构决策、单元测试、文档撰写多重身份。

子代理（sub-agent）的价值在于：

• 上下文隔离：每个子代理只看到与自己任务相关的上下文，不污染主会话。
• 并行加速：独立任务并行跑，整体时长降到串行的 1/N。
• 角色专精：每个子代理可以挂不同 Skills、不同模型、不同 Hooks。

编排模式：四种典型拓扑

1) 单层并行
   主代理
   ├── sub-A：跑 grep + 列待改清单
   ├── sub-B：写后端服务改动
   ├── sub-C：写前端调用改动
   └── sub-D：跑全量测试 + 收集失败

2) 两层流水
   主代理 → sub-Planner（出方案）→ sub-Builder（执行）→ sub-Verifier（验收）

3) GAN 风格对抗
   主代理
   ├── sub-Generator：出实现
   └── sub-Critic：挑刺、提改进意见
   循环 N 轮直到 Critic 评分达标

4) 风扇 + 收口
   主代理
   ├── sub-FrontEnd
   ├── sub-Backend
   ├── sub-DataPipeline
   └── 主代理收口写 release notes

实操：四种调用方式

# 直接在交互会话里
/agents

# 主代理写自然语言
"起一个子代理跑 ESLint 修复，再起一个跑测试覆盖率统计，并行"

# Skill 模板内含子代理调度逻辑
/skill multi-frontend

# 通过 MCP 暴露子代理为工具，给其他系统调用
（详见下一节 MCP 集成）

子代理选模型：成本视角

子代理频繁调用，建议默认走 Haiku。Sonnet 留给主代理决策。Opus 仅限"一次性深度推理"任务（架构评审、复杂数据库迁移规划），用完就停。

MCP 服务器集成：扩展工具与数据源

MCP 是什么

MCP（Model Context Protocol）是 Anthropic 开放的工具扩展协议。一个 MCP 服务器对外暴露工具（tools）、资源（resources）、prompts，Claude Code 在会话里直接调用。MCP 让 Claude Code 不再局限于"读写文件 + 跑 shell"，而是能挂：

• 数据库连接（PostgreSQL / ClickHouse / 自家 BI）
• 第三方 SaaS（GitHub / Linear / Jira / Slack）
• 私有知识库（公司 wiki、产品文档、客户列表）
• 外部 LLM（专长模型、领域模型、上下文增强）

安装一个公开 MCP 服务器

以 GitHub MCP 为例：

# 全局安装（也可项目级）
npm install -g @modelcontextprotocol/server-github

# .claude/mcp.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    }
  }
}

启动 Claude Code 后，会话里就可以"读 PR #123 的 review、把高优 issue 列出来、按里程碑分组"。

写一个自定义 MCP

小可运行的 MCP 服务器（Node.js + TypeScript SDK）大概 30 行代码。模板：

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  { name: "internal-billing", version: "0.1.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "get_customer_usage",
      description: "查询某客户最近 30 天 token 用量",
      inputSchema: {
        type: "object",
        properties: { customerId: { type: "string" } },
        required: ["customerId"],
      },
    },
  ],
}));

server.setRequestHandler("tools/call", async (req) => {
  const { name, arguments: args } = req.params;
  if (name === "get_customer_usage") {
    const usage = await queryUsage(args.customerId);
    return { content: [{ type: "text", text: JSON.stringify(usage) }] };
  }
});

await server.connect(new StdioServerTransport());

把这个 MCP 注册到 .claude/mcp.json，Claude Code 在做客户支持任务时就能直接读公司 BI 数据。

MCP 适用场景

Hooks 高级用法：拦截、变更、组合

PreToolUse 修改参数

不仅可以"阻断"，也可以"修改"。Hook stdin 拿到 tool input，stdout 输出修改后的 JSON 即可：

# 把所有 Edit 工具的 file_path 强制限定到当前工作目录子集
node -e "
let d='';process.stdin.on('data',c=>d+=c);
process.stdin.on('end',()=>{
  const i=JSON.parse(d);
  if(i.tool_input?.file_path && !i.tool_input.file_path.startsWith(process.cwd())){
    console.error('[Hook] 拒绝跨目录写入');
    process.exit(2);
  }
  console.log(d);
});
"

PostToolUse 串联多步质量门

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Write|Edit", "command": "ruff check --fix \"$FILE_PATH\"" },
      { "matcher": "Write|Edit", "command": "ruff format \"$FILE_PATH\"" },
      { "matcher": "Write|Edit", "command": "mypy --quiet \"$FILE_PATH\" || true" }
    ]
  }
}

顺序：format → lint → 类型检查。某一步失败可让 Claude Code 看到错误并尝试修。

Stop Hook：兜底验证

{
  "hooks": {
    "Stop": [
      { "command": "pnpm test --silent" },
      { "command": "pnpm build" },
      { "command": "git status --short" }
    ]
  }
}

会话结束前自动跑测试、构建、列改动。漏的事少很多。

Hook 与 Skill 的协作

Skill 写规范、Hook 兜底执行。例如团队约定"所有 Python 文件必须有类型注解"：

• Skill 在文档层面写明
• Hook 在 PostToolUse 跑 mypy，没过就把错误抛回给 Claude Code 重写

两层叠加才能从"建议"变"约束"。

工作流自动化：脚本化 / CI / 定时任务

非交互式：--print

claude --print "读 docs/PRD.md 拆任务到 docs/tasks.md"

适合在脚本、Makefile、CI 里跑。会一次性输出后退出，不进入交互。

CI 集成（GitHub Actions 例）

name: AI Code Review
on:
  pull_request:
    branches: [main]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm install -g @anthropic-ai/claude-code
      - name: AI review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.CODEGATEWAY_KEY }}
          ANTHROPIC_BASE_URL: https://api.codegateway.dev
        run: |
          claude --print "对当前 git diff 跑 review，关注 CRITICAL/HIGH/MEDIUM/LOW，输出 markdown 到 review.md"
      - name: Comment on PR
        run: gh pr comment ${{ github.event.pull_request.number }} -F review.md

CI 里跑 Claude Code 强烈建议：

• 单独申请 Key，命名 ci-<repo>
• 设置 RPM / 月预算上限
• 用 Haiku（CI 任务大多简单），把 Sonnet 留给本地

定时任务

依赖 cron 或者编排系统（GitHub Actions 的 schedule、Linear 自动化），一样把 claude --print 当 CLI 工具调度。常见任务：

• 周一早把上周失败的测试归因 + 出 ticket
• 每天凌晨扫一遍 dependabot 提议，自动评估升级风险
• 每月生成 changelog 草稿

Prompt Cache 与成本优化

Prompt Cache 工作机制

Claude API 支持显式标记可缓存的 prompt 块（system prompt、长文档上下文）。首次请求时缓存写入（费用与正常 input 相近，略高），后续相同 prefix 命中后输入 token 计费降到约 10%。Anthropic 官方文档Prompt caching有完整规则。

Claude Code 怎么用上

Claude Code 的 system prompt + 长 Skills 内容 + 大文件上下文，正好都是适合缓存的对象。在网关层（CodeGateway 或 Anthropic 直连）开启 prompt caching 后，长会话里同一个 system prompt + Skills 内容的 input 成本能降到原本的 10–30%，实际节省取决于会话长度。

实操建议

• 长 Skills 文档放在 .claude/skills/ 内，被命中的概率高。
• 每次会话尽量少跨工作目录切换 —— 切换会让 cache 失效。
• 用 claude --print 跑批量任务时，把共享 prompt 放在前面、变量放在后面，充分 prefix 命中。

模型选择 × 任务密度的成本表

任务类型                 推荐模型      原因
========================================
架构决策 / 数据库迁移      Opus          一次性深度推理，时长短
日常重构 / 代码生成        Sonnet        平衡 + 编码强
子代理 / 批量 lint        Haiku         便宜 + 够用
工具型小任务 / OCR        Haiku         便宜 + 时延短
长 chain 推理 + 大量上下文 Sonnet + cache  打开 cache 后摊销极低

倍率与模型路由策略

CodeGateway 倍率回顾

全部账户统一按 1.07× 倍率计费：不随 90 天消耗或充值金额变化，也不存在 Tier 档位。

新用户绑定支付方式后可获得起步额度（折算购买力随所选模型价格变动，以 /models 定价页折算为准）。详见统一倍率说明。

团队用量与倍率

倍率对所有账户固定为 1.07×，不随 90 天消耗变化。多人共享一个账号不会改变倍率（前面说过），所以团队协作的核心是单账号产生足够稳定的月度消耗。两条路径：

1. 个人开发者长期用：无论月消耗多少，倍率始终是 1.07×。
2. 企业账号 + 多 Key：企业账号下创建 N 个 Key 给团队成员，所有 Key 用量汇总到同一账户，统一按 1.07× 倍率计费。

模型路由

主代理走 Sonnet，子代理走 Haiku，深度任务临时切 Opus。把这种路由做到 Skill 里：

# .claude/skills/cost-aware-llm/SKILL.md
---
name: cost-aware-llm-pipeline
description: 默认主代理 Sonnet，子代理 Haiku；只有当任务涉及"多服务架构 / 数据库迁移 / 复杂调试"时切到 Opus。
---

挂上之后 Claude Code 会按规则选模型，避免"全程 Opus 跑成本爆掉"。

可观测性：用量、费用、错误的归因

Dashboard 关键指标

CodeGateway Dashboard → Overview / Logs。值得关注的视角：

• Total Tokens 卡片：当日 / 7 天 / 30 天 token 总量
• 按模型拆分：Opus 占比是否过高（高于 10% 就值得检查）
• 按 Key 拆分：哪个 Key 用量异常增长
• 错误率：4xx 异常突增是否对应配置变更
• 首字节延迟：突增可能对应链路异常

日志范围筛选

Logs 页支持时间范围筛选（Today / 7d / 30d / 90d / All）+ 按 Key / 模型 / 状态码筛。把"昨天某个 CI 任务失败"定位到具体请求只需要 30 秒。

自建监控

如果要把指标拉到内部 Grafana / Datadog：

• CodeGateway 暂未开放 metrics API（roadmap 中）
• 临时方案：CI 任务结束时把 claude --print 的最终 token usage 抛到自己的指标平台

团队协作进阶：配置标准化与 Key 治理

配置 commit 进仓库

.claude/settings.json、.claude/skills/、.claude/mcp.json、.claude/hooks/ 全部 commit。

尽量不要 commit：

• API Key
• 任何含 token 的 env 文件

.gitignore 里加：

.claude/secrets.json
.claude/.env
.claude/cache/

Key 治理表

每个 Key 注释清楚，泄露/离职时一秒旋转。

Pre-PR Checklist

把"PR 前应跑的检查"写进 Skill：

- 跑测试，全部通过
- 跑 lint，零 warning
- 跑 build，无错误
- 跑 git diff，确保不包含 secrets / debug 语句
- 阅读改动，是否引入了向后不兼容的 API

挂到 pre-pr-check Skill 里，团队 Claude Code 在准备发 PR 时按这个清单走。

真实场景案例：四个高价值工程化模式

模式 1：长文档摘要与抽取

法务合同、PRD、研究报告这种 30+ 页文档，主代理读完后起子代理：

• sub-Extractor：按 schema 抽取要素（金额、日期、违约条款）
• sub-Risker：按风险维度评估
• sub-Drafter：生成内部 review 文档

主代理收口写最终摘要。Prompt cache 命中率高，长文档放在 cache 块里，多次问答都按 10% 价。

模式 2：跨服务大重构

字段名从 userId 改 accountId，影响 6 个仓库 30+ 文件。

• sub-Scout：grep 列清单
• sub-Editor-A/B/C：分别改不同仓库
• sub-Tester：跑测试 + 收集失败
• 主代理：协调失败修复 + 写 PR 描述

并行跑下来 30 分钟级，串行的话 2-3 小时。

模式 3：根因分析

线上报警 → 把日志、监控截图、相关代码塞给 Opus 主代理。

• 主代理：起初步假设
• sub-Validator：跑 grep + 读相关代码 + 写复现脚本
• sub-Fixer：基于验证结果出 PR
• 主代理：写 incident review

模式 4：跨语言迁移

Go → Rust 重写。

• sub-Translator：按文件批量转
• sub-Tester：跑生成的测试 + 比对原行为
• sub-Reviewer：按 Rust 习惯改写 unidiomatic 部分
• 主代理：负责整体节奏与 commit 划分

FAQ

Q：子代理之间能不能直接通信？

A：不能直接通信。Claude Code 的多代理架构是树形拓扑，子代理只与主代理对话。需要"共享状态"时，写到文件系统或 MCP 暴露的中间存储里。

Q：MCP 服务器会拖慢会话吗？

A：看实现质量。轻量 MCP（包装 GitHub API、本地文件检索）几十毫秒级；重量 MCP（跑机器学习模型、查大规模数据库）会拉长 tool call 等待。建议把慢工具加 timeout，挂 PreToolUse Hook 提示用户切换。

Q：Prompt Cache 在 CodeGateway 上启用了吗？

A：启用了。任何客户端走 CodeGateway 网关都自动支持 cache header 透传与计费折扣。具体折扣按 Anthropic 官方规则。

Q：所有团队成员共享一个 CI Key 安全吗？

A：单仓库 + 严格限流（RPM、月预算）下相对可控；多团队多仓库共用是反模式。建议每个仓库一个 Key，CI 失败 / 异常报警挂在 Key 维度。

Q：Opus 真的比 Sonnet 贵很多吗？

A：Opus 输入输出价格大约是 Sonnet 的 5x（具体见 Anthropic 价格页）。但有些任务（多服务架构、复杂数据库迁移）Sonnet 给出的方案需要 3 轮反复 + 几次返工，单次 Opus 直接通过反而更省。判断标准：任务"思考"占比是否 ≥ 70%，是的话切 Opus。

Q：Hooks 失败会怎样？

A：PreToolUse 返回 exit code 2 会阻断该工具调用，Claude Code 看到错误信息后会尝试调整。PostToolUse 失败默认不阻断，但错误日志会进 Claude Code 上下文。Stop Hook 失败也不阻断退出。

Q：能不能同时连多个 MCP 服务器？

A：可以。.claude/mcp.json 里写多个服务器即可。Claude Code 启动时并行 spawn，所有工具一起进入工具列表。注意命名冲突时主代理会按命名空间区分。

Q：长任务跑到一半中断怎么办？

A：Claude Code 默认会保留会话状态。再次启动 claude 会从最后的 checkpoint 续。配合 git commit 习惯（每完成一个子任务就 commit），中断后恢复几乎无损。如果是网关侧 10 分钟整体超时，参见连接超时排查。

相关资料

• Claude Code 完整配置指南 —— 入门到中级
• Claude Code 连接超时排查指南
• Claude Code 5 分钟快速配置
• 充值费用指南
• 统一倍率说明
• Anthropic 官方文档：Prompt caching
• Anthropic 官方文档：Sub-agents
• Anthropic 官方文档：Model Context Protocol
• Cloudflare Workers Runtime：Worker Runtime APIs

进阶不是堆功能，是搞清楚"哪种任务对应哪种模式"。把上面六块（多代理 / MCP / Hooks 高级 / 工作流 / Cache + 倍率 / 可观测性）做成肌肉记忆，Claude Code 就能从"AI 助手"升级为"AI 工程团队"。