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

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

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

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

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

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

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

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

作者：CodeGateway 团队 · 实测于 2026-05

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

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

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

为什么要起子代理

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

子代理（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

实操：四种调用方式

text

# 直接在交互会话里
/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 为例：

bash

# 全局安装（也可项目级）
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 适用场景

场景	推荐做法
团队 wiki 查询	包装成 MCP，主代理自动检索
客户数据归因	MCP + 数据库连接，按需查
跨产品发布同步	MCP 调度 GitHub / Slack / Linear
内部 LLM 路由	MCP 包装专长模型，按需路由

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

PreToolUse 修改参数

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

bash

# 把所有 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 串联多步质量门

json

{
  "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：兜底验证

json

{
  "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`

bash

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

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

CI 集成（GitHub Actions 例）

yaml

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 阶梯倍率回顾

90 天累计消耗	倍率
$0 – $10	1.5x
$10 – $50	1.4x
$50 – $200	1.3x
$200 – $500	1.2x
$500+	1.2x（至少，长期稳定）

新用户起步 1.5x，赠送 $2 起步额度 ≈ 44 万 Sonnet 4.6 输入 tokens。详见阶梯倍率详解。

团队怎么把倍率打到至少

倍率按账号 90 天累计算。多人共享一个账号没意义（前面说过），所以打低倍率的核心是单账号产生足够稳定的月度消耗。两条路径：

个人开发者长期用：按月度 $50–$100 的稳健消耗，3–6 个月稳定停在 1.2x。
企业账号 + 多 Key：企业账号下创建 N 个 Key 给团队成员，所有 Key 用量都汇总到企业账号 90 天累计，更快打到 1.2x。

模型路由

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

yaml

# .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 用途	命名	限流	主人
个人开发机	`dev-<name>-<host>`	无	本人
CI 主仓库	`ci-<repo>`	RPM 60	平台组
文档 / Demo	`demo-<scenario>`	RPM 30、月预算 $20	平台组
客户 demo 临时	`tmp-<customer>-<date>`	设过期时间	销售组

每个 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 进阶技巧与最佳实践：子代理、MCP、成本优化

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

目录

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

为什么要起子代理

编排模式：四种典型拓扑

实操：四种调用方式

子代理选模型：成本视角

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

MCP 是什么

安装一个公开 MCP 服务器

写一个自定义 MCP

MCP 适用场景

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

PreToolUse 修改参数

PostToolUse 串联多步质量门

Stop Hook：兜底验证

Hook 与 Skill 的协作

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

非交互式：--print

CI 集成（GitHub Actions 例）

定时任务

Prompt Cache 与成本优化

Prompt Cache 工作机制

Claude Code 怎么用上

实操建议

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

阶梯倍率与模型路由策略

CodeGateway 阶梯倍率回顾

团队怎么把倍率打到至少

模型路由

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

Dashboard 关键指标

日志范围筛选

自建监控

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

配置 commit 进仓库

Key 治理表

Pre-PR Checklist

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

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

模式 2：跨服务大重构

模式 3：根因分析

模式 4：跨语言迁移

FAQ

相关资料

非交互式：`--print`