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 Truth）

Agent 之间不说话，只通过结构化文档传递信息。每个 Agent 有明确的读写边界：

文档	PM	Architect	前端	后端	QA
requirements.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
需求	PM	requirements.md + handoff	~800
设计	Architect	architecture + api-contract + handoff	~1200
实现	Frontend	React + 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 → FE+BE 并行 → QA 的顺序推进，关键节点暂停等待确认。

关键原则总结

原则	说明
文档驱动	Agent 之间不对话，只通过文档衔接
上下文隔离	每个 Agent 独立上下文，不互相污染
按需深读	先读 handoff（~300 token），必要时才读完整文档
并行优先	无依赖的 Agent 同时启动
1 轮冲突上限	内部最多 1 轮讨论，超时直接升级
用户是最终裁判	不假装能替用户做决策