加载中…
一句话：入门 Claude Code 不难，把它跑成"团队级生产力"才是分水岭。本文不再讲怎么装、怎么配 API Key，而是聚焦进阶工程化：多代理编排、MCP 服务器集成、Hooks 高级用法、Prompt Cache 与阶梯倍率配合的成本优化、可观测性建设。读完能把 Claude Code 从"AI 助手"用成"AI 工程团队"。
单代理跑长任务有两个固有问题：上下文窗口有限（即使百万级也不是免费的），以及任务"分工不清晰"会让一个会话同时背架构决策、单元测试、文档撰写多重身份。
子代理（sub-agent）的价值在于：
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（Model Context Protocol）是 Anthropic 开放的工具扩展协议。一个 MCP 服务器对外暴露工具（tools）、资源（resources）、prompts，Claude Code 在会话里直接调用。MCP 让 Claude Code 不再局限于"读写文件 + 跑 shell"，而是能挂：
以 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 服务器（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 数据。
场景 | 推荐做法 |
|---|---|
团队 wiki 查询 | 包装成 MCP，主代理自动检索 |
客户数据归因 | MCP + 数据库连接，按需查 |
跨产品发布同步 | MCP 调度 GitHub / Slack / Linear |
内部 LLM 路由 | MCP 包装专长模型，按需路由 |
不仅可以"阻断"，也可以"修改"。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);
});
"{
"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 看到错误并尝试修。
{
"hooks": {
"Stop": [
{ "command": "pnpm test --silent" },
{ "command": "pnpm build" },
{ "command": "git status --short" }
]
}
}会话结束前自动跑测试、构建、列改动。漏的事少很多。
Skill 写规范、Hook 兜底执行。例如团队约定"所有 Python 文件必须有类型注解"：
mypy，没过就把错误抛回给 Claude Code 重写两层叠加才能从"建议"变"约束"。
--printclaude --print "读 docs/PRD.md 拆任务到 docs/tasks.md"适合在脚本、Makefile、CI 里跑。会一次性输出后退出，不进入交互。
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.mdCI 里跑 Claude Code 强烈建议：
ci-<repo>依赖 cron 或者编排系统（GitHub Actions 的 schedule、Linear 自动化），一样把 claude --print 当 CLI 工具调度。常见任务：
Claude API 支持显式标记可缓存的 prompt 块（system prompt、长文档上下文）。首次请求时缓存写入（费用与正常 input 相近，略高），后续相同 prefix 命中后输入 token 计费降到约 10%。Anthropic 官方文档Prompt caching有完整规则。
Claude Code 的 system prompt + 长 Skills 内容 + 大文件上下文，正好都是适合缓存的对象。在网关层（CodeGateway 或 Anthropic 直连）开启 prompt caching 后，长会话里同一个 system prompt + Skills 内容的 input 成本能降到原本的 10–30%，实际节省取决于会话长度。
.claude/skills/ 内，被命中的概率高。claude --print 跑批量任务时，把共享 prompt 放在前面、变量放在后面，充分 prefix 命中。任务类型 推荐模型 原因
========================================
架构决策 / 数据库迁移 Opus 一次性深度推理，时长短
日常重构 / 代码生成 Sonnet 平衡 + 编码强
子代理 / 批量 lint Haiku 便宜 + 够用
工具型小任务 / OCR Haiku 便宜 + 时延短
长 chain 推理 + 大量上下文 Sonnet + cache 打开 cache 后摊销极低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 天累计算。多人共享一个账号没意义（前面说过），所以打低倍率的核心是单账号产生足够稳定的月度消耗。两条路径：
主代理走 Sonnet，子代理走 Haiku，深度任务临时切 Opus。把这种路由做到 Skill 里：
# .claude/skills/cost-aware-llm/SKILL.md
---
name: cost-aware-llm-pipeline
description: 默认主代理 Sonnet，子代理 Haiku；只有当任务涉及"多服务架构 / 数据库迁移 / 复杂调试"时切到 Opus。
---挂上之后 Claude Code 会按规则选模型，避免"全程 Opus 跑成本爆掉"。
CodeGateway Dashboard → Overview / Logs。值得关注的视角：
Logs 页支持时间范围筛选（Today / 7d / 30d / 90d / All）+ 按 Key / 模型 / 状态码筛。把"昨天某个 CI 任务失败"定位到具体请求只需要 30 秒。
如果要把指标拉到内部 Grafana / Datadog：
claude --print 的最终 token usage 抛到自己的指标平台.claude/settings.json、.claude/skills/、.claude/mcp.json、.claude/hooks/ 全部 commit。
尽量不要 commit：
.gitignore 里加：
.claude/secrets.json
.claude/.env
.claude/cache/Key 用途 | 命名 | 限流 | 主人 |
|---|---|---|---|
个人开发机 |
| 无 | 本人 |
CI 主仓库 |
| RPM 60 | 平台组 |
文档 / Demo |
| RPM 30、月预算 $20 | 平台组 |
客户 demo 临时 |
| 设过期时间 | 销售组 |
每个 Key 注释清楚，泄露/离职时一秒旋转。
把"PR 前应跑的检查"写进 Skill：
- 跑测试，全部通过
- 跑 lint，零 warning
- 跑 build，无错误
- 跑 git diff，确保不包含 secrets / debug 语句
- 阅读改动，是否引入了向后不兼容的 API挂到 pre-pr-check Skill 里，团队 Claude Code 在准备发 PR 时按这个清单走。
法务合同、PRD、研究报告这种 30+ 页文档，主代理读完后起子代理：
主代理收口写最终摘要。Prompt cache 命中率高，长文档放在 cache 块里，多次问答都按 10% 价。
字段名从 userId 改 accountId，影响 6 个仓库 30+ 文件。
并行跑下来 30 分钟级，串行的话 2-3 小时。
线上报警 → 把日志、监控截图、相关代码塞给 Opus 主代理。
Go → Rust 重写。
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 分钟整体超时，参见连接超时排查。
进阶不是堆功能，是搞清楚"哪种任务对应哪种模式"。把上面六块（多代理 / MCP / Hooks 高级 / 工作流 / Cache + 倍率 / 可观测性）做成肌肉记忆，Claude Code 就能从"AI 助手"升级为"AI 工程团队"。