Claude Code 多 Agent 协作与终端工作流实战
背景与痛点
单主 Agent（Single Agent）模式在处理单一文件修改或小范围 Bug 排查时表现优异。但在面对复杂需求时，往往面临两大瓶颈：
- 上下文爆炸（Context Bloat）：查看大量日志、长文件与构建输出后，上下文窗口迅速被占满，模型推理成本增加且容易遗忘早期指令。
- 多任务串行耗时：例如既要调研第三方库 API，又要扫描本地依赖与编写测试用例，串行执行效率低下。
通过将大型任务解耦为父 Agent（协调者）+ 子 Agent（Subagent，专职执行者），可以实现上下文有效隔离与高质量并发协作。
核心架构设计
text
┌──────────────────────────────┐
│ Parent Coordinator Agent │
│ - 制定拆解任务规划 (Plan) │
│ - 调度子 Agent 并汇总结论 │
└──────────────┬───────────────┘
│
┌────────────────┼────────────────┐
▼ ▼
┌────────────────────┐ ┌────────────────────┐
│ Subagent: Research │ │ Subagent: Test Eng │
│ - 独立上下文空间 │ │ - 独立执行沙箱 │
│ - 深入查阅文档/搜索 │ │ - 编写单元测试用例 │
│ - 返回轻量提炼摘要 │ │ - 运行并收集错误码 │
└────────────────────┘ └────────────────────┘1. 为什么上下文隔离至关重要？
子 Agent 在其独立的上下文中搜索了 50 个文件、阅读了 10 篇网络文档，产生了几万 Token 的中间交互。 当子 Agent 执行完毕后，它只向父 Agent 汇报 500 Token 的结构化最终结论。父 Agent 保持了“极其干净的上下文”，专注于全局架构与代码合并。
落地配置与调用模式
1. 定义角色与专业指令
通过给不同 Agent 赋予明确的边界，避免角色混乱：
yaml
# 调研型 Agent (Research Specialist)
role: "Codebase & Documentation Researcher"
permissions: "Read-only"
task: "深入检索项目中的旧接口调用点，输出调用文件路径列表与关键参数形式，禁止执行写操作。"
# 自动化测试 Agent (QA Specialist)
role: "Test Runner & Verifier"
permissions: "Workspace write & execute"
task: "针对修改后的模块运行 vitest，定位断言失败并尝试在测试用例维度进行边界覆盖。"2. 避免上下文泄露的最佳实践
- 明确输入输出格式：给子 Agent 下发任务时，强制要求输出为 JSON 或 Markdown 摘要，不要将未处理的原样 log 全部传回父级。
- 阶段性提交 Git Commit：子 Agent 每完成一个自洽的小步骤，立即提交一次带有清晰语义的 Git commit（如
feat(auth): add token validation），以方便随时回滚。 - 任务完成自动销毁：无需长生命周期的调研任务，完成后释放资源，防止无意义的心跳唤醒消耗 Token。
实战案例：重构旧接口适配
在此前的一次重构实战中，我们处理一个涉及 30+ 文件的工具类迁移：
- 启动 Research Subagent：扫描全局代码库，找出所有引入旧模块的位置，分类汇总依赖类型。
- 父级制定修改批次：将 30 个文件按依赖层次分成 3 个独立批次。
- 并发调用 Worker Subagent：依次对批次进行改写并运行 Lint。
- 统一验收：统一执行全量测试套件并合并改动。
整个过程父 Agent 仅消耗了不到 15k Token，而所有子 Agent 的中间日志在独立会话中完成闭环。
经验总结
- 专人专事：写代码、读文档、跑测试三者分开，各自拥有最适宜的 Prompt 和权限边界。
- 用 Commit 当存盘点：在多 Agent 协同修改文件前，务必保证当前 Git 工作区干净，以便随时 Diff 验收。
- 保持父级的高层视野：父 Agent 永远不应当陷入某一两行变量命名的纠结，把细节交给具体的局部执行者。