Claude Code Agent Teams：构建角色化多智能体开发团队

Claude Code Agent Teams构建角色化多智能体开发团队为什么需要 Agent Teams单个 AI 编程助手的问题上下文窗口有限角色混淆无法并行工作。设想一下真实软件开发团队有产品经理、架构师、前端、后端、测试。每个角色有独立的职责边界、独立的知识体系、独立的工作上下文。他们通过文档沟通而不是所有人挤在一间屋子里同时说话。Agent Teams 就是这个思路用多个独立的 AI Agent 模拟一支真实开发团队。核心架构角色驱动的文档协作团队结构用户委托方 │ ▼ PM Agent ──────▶ requirements.md ──────▶ 用户确认 │ ▼ Architect Agent ──▶ architecture.md api-contract.md │ ├──▶ Frontend Agent ──▶ src/frontend/ ├──▶ Backend Agent ──▶ src/backend/ └──▶ QA Agent ──▶ test report三个核心设计决策1. 文档即真相源Single Source of TruthAgent 之间不说话只通过结构化文档传递信息。每个 Agent 有明确的读写边界文档PMArchitect前端后端QArequirements.md写读读读读architecture.md读写读读-api-contract.md读起草参与参与读issues.md写写写写写2. 独立上下文并行执行每个 Agent 通过 Claude Code 的Agent工具启动拥有完全独立的上下文窗口前端 Agent 看不见后端的 prompt后端也看不见前端的前端和后端可以同时开工互不干扰每个 Agent 只拿到它需要的 handoff 文档不看无关信息3. Handoff 交接协议上游 Agent 产出一个精简的 handoff.json作为交接包{ from: Architect, to: Frontend Engineer, summary: React TypeScript 单页应用localStorage 存储, key_decisions: [纯前端无后端, Tailwind 响应式, Recharts 图表], open_questions: [], pointers: { api_contract: api-contract.md §2, data_model: architecture.md §3 } }Handoff 控制 200-500 token下游 Agent 先读 handoff只在必要时深读完整文档的指定段落。这是控制 token 消耗的关键机制。实现阶段的审查机制Phase 3编码阶段嵌入了 subagent-driven-development 的审查循环Implementer Agent │ ├──▶ 自我审查自查遗漏 │ ├──▶ Spec 合规审查独立审查 Agent只对比 spec 和代码 │ └── 不通过 → 回去修复 → 重新审查 │ ├──▶ 代码质量审查独立审查 Agent评估正确性和清晰度 │ └── 有重要问题 → 回去修复 → 重新审查 │ ▼ 通过 → 写 handoff 交接给 QA注意这些审查 Agent 也是独立上下文只看到 spec 代码看不到实现者的思考过程。这样审查结果不会被实现者的考虑所影响。冲突解决1 轮上限Agent 之间有分歧时不走无限辩论决策者 → 宣布决策 ↓ 有人反对 决策者 → 重新评估给出最终结论 理由 ↓ 仍不同意 立即升级给用户裁定。不继续内部争论。理由第二轮是让决策者看到反对意见后自我纠正。如果还不行说明不是信息差而是价值观分歧——只有人能裁定。实际效果用这套流程开发了一个个人记账应用阶段Agent产出token需求PMrequirements.md handoff~800设计Architectarchitecture api-contract handoff~1200实现FrontendReact TS 完整应用~3000实现Backend跳过纯前端~200用户确认2 次需求 架构-总 token 约 5200其中 Agent 间传递的 handoff 总共不到 1000 token。如何使用在 Claude Code 中创建/agent-teamskill位于~/.claude/skills/agent-team/SKILL.md/agent-team 帮我做一个 xxx系统自动按 PM → Architect → FEBE 并行 → QA 的顺序推进关键节点暂停等待确认。关键原则总结原则说明文档驱动Agent 之间不对话只通过文档衔接上下文隔离每个 Agent 独立上下文不互相污染按需深读先读 handoff~300 token必要时才读完整文档并行优先无依赖的 Agent 同时启动1 轮冲突上限内部最多 1 轮讨论超时直接升级用户是最终裁判不假装能替用户做决策局限与展望当前 Claude Code 的限制无文件监听做不到PM 产出后自动唤醒 ArchitectAgent 之间无消息通道必须通过文档文件衔接无法设置持久的角色 Agent每次调用新建上下文但这些限制恰好强化了文档驱动的纪律——你不会想走捷径跨过文档直接对话因为捷径不存在。未来的演进方向真实的 Agent 间消息通道、持久化角色记忆、基于 git 的自动触发机制。