目录一、角色总览二、角色详细说明三、协作流程四、通信协议五、执行顺序六、设计原理一、角色总览1.1 六种角色一览表#角色名称英文名生命周期主要职责触发时机1主智能体Main Agent整个会话编排协调、技能调度会话开始2实现者子代理Implementer Subagent单个任务编码、测试、自审每个任务开始3规格审查子代理Spec Compliance Reviewer单次审查验证需求符合性任务实现完成后4质量审查子代理Code Quality Reviewer单次审查验证代码质量规格审查通过后5最终审查代理Final Code Reviewer单次审查整体功能评估所有任务完成后6并行调查代理Parallel Investigation Agents各自独立并行调查独立问题多个独立问题时1.2 角色关系图用户Developer │ 指令/需求 ↓ ┌────────────────────────────────┐ │ 【1】主智能体Orchestrator │ │ • 技能调度 │ │ • 上下文管理 │ │ • 工作流控制 │ └────────┬────────────────────────┘ │ ├───调度──→ 【2】实现者子代理 │ ↓ 完成 ├───调度──→ 【3】规格审查子代理 │ ↓ 通过 ├───调度──→ 【4】质量审查子代理 │ ↓ 批准 ├───调度──→ 【5】最终审查代理 │ └───并行调度──→ 【6】并行调查代理 × N二、角色详细说明2.1 主智能体Main Agent定位整个系统的大脑和指挥官核心职责1. 技能发现和激活 - 检测用户意图 - 匹配适用的技能 - 加载技能内容到上下文 2. 子代理生命周期管理 - 创建spawn - 调度dispatch - 监控monitor - 销毁terminate 3. 上下文提取和注入 - 从项目文件提取信息 - 构建完整的上下文包 - 注入到子代理 prompt 4. 工作流状态跟踪 - TodoWrite 更新 - 进度报告 - 错误处理 5. 决策路由 - 选择执行策略 - 处理子代理提问 - 转发用户决策生命周期会话启动 ↓ ┌──────────────────────────────┐ │ 初始化 │ │ • 加载技能索引 │ │ • 注入 using-superpowers │ └────────┬─────────────────────┘ ↓ ┌──────────────────────────────┐ │ 活跃状态 │ │ • 接收用户输入 │ │ • 激活技能 │ │ • 调度子代理 │ │ • 处理结果 │ │ 循环直到会话结束 │ └────────┬─────────────────────┘ ↓ 会话结束关键特征✅持久性整个会话期间存在✅完整上下文拥有所有对话历史✅编排能力协调多个子代理⚠️上下文污染风险因此需要子代理隔离示例交互用户帮我实现用户登录功能 主智能体内部处理 1. 检测关键词实现、功能 → 匹配到 brainstorming 技能 2. 激活 brainstorming 技能 3. 加载技能内容 4. 执行设计讨论 5. 用户批准设计后 → 激活 writing-plans 技能 6. 生成详细计划 7. 用户批准计划后 → 激活 subagent-driven-development 技能 8. 读取计划提取所有任务 9. 创建 TodoWrite 10. 开始任务循环 For each task: - 调度实现者子代理 - 调度规格审查子代理 - 调度质量审查子代理 - 更新 TodoWrite2.2 实现者子代理Implementer Subagent定位“执行者”负责具体编码工作核心职责1. 需求澄清 - 读取任务规格 - 如有疑问提问Before implementing 2. 编码实现 - 遵循 TDD 流程 - 编写生产代码 - 遵循项目约定 3. 测试编写 - 单元测试 - 集成测试 - 确保覆盖率 4. 自我审查 - 检查完整性 - 检查质量 - 检查 YAGNI 合规 5. 提交和报告 - Git commit - 总结完成内容 - 报告问题或顾虑Prompt 模板# implementer-prompt.md简化版 You are implementing Task N: [task name] ## Task Description [完整任务文本 - 主智能体粘贴无需子代理自己读文件] ## Context [项目架构、技术栈、依赖关系] ## Before You Begin If you have questions about: - Requirements or acceptance criteria - Implementation approach - Dependencies or assumptions **Ask them now.** Raise concerns before starting work. ## Your Job 1. Implement exactly what the task specifies 2. Write tests (following TDD if required) 3. Verify implementation works 4. Commit your work 5. Self-review 6. Report back Work from: [directory] While you work: If you encounter something unexpected, ask questions. Dont guess or make assumptions. ## Self-Review Checklist Before reporting: - [ ] Did I fully implement everything in the spec? - [ ] Did I miss any requirements? - [ ] Is this my best work? - [ ] Did I avoid overbuilding (YAGNI)? - [ ] Do tests actually verify behavior? ## Report Format - What you implemented - What you tested and test results - Files changed - Any issues or concerns生命周期任务开始 ↓ ┌──────────────────────────────┐ │ 创建Spawn │ │ • 新鲜上下文 │ │ • 无历史包袱 │ └────────┬─────────────────────┘ ↓ ┌──────────────────────────────┐ │ 澄清阶段 │ │ • 读取完整 prompt │ │ • 识别疑问点 │ │ • 向主智能体提问 │ └────────┬─────────────────────┘ ↓ ┌──────────────────────────────┐ │ 实现阶段 │ │ • 编写代码 │ │ • 编写测试TDD │ │ • 运行验证 │ └────────┬─────────────────────┘ ↓ ┌──────────────────────────────┐ │ 自审阶段 │ │ • 检查完整性 │ │ • 检查质量 │ │ • 必要时自行修复 │ └────────┬─────────────────────┘ ↓ ┌──────────────────────────────┐ │ 报告和提交 │ │ • Git commit │ │ • 生成报告 │ │ • 返回给主智能体 │ └────────┬─────────────────────┘ ↓ 销毁Terminate关键特征✅新鲜上下文无历史偏见✅专注单任务不会分心✅可提问遇到不清楚的主动澄清⚠️短生命周期任务完成即销毁真实案例任务实现用户注册接口 实现者子代理执行过程 [收到 prompt包含完整规格和上下文] 实现者Before I begin - should password validation be strict (8 chars, numbersletters) or lenient (6 chars)? 主智能体/用户Strict (8 chars, numbersletters) 实现者Got it. Implementing now... [30 分钟后] 实现者报告 ✅ 完成 实现内容 - 创建 POST /api/auth/register 端点 - 添加 Zod 验证 schema8 字符数字字母 - 密码使用 bcrypt 加密salt rounds10 - 邮箱唯一性检查 - 成功返回 JWT token 测试 - 12/12 单元测试通过 - 3/3 集成测试通过 - 覆盖率96% 文件变更 - src/routes/auth.ts新增 - src/validators/register.ts新增 - src/services/auth.service.ts新增 - tests/auth.test.ts新增 自审发现 - 初始实现忘记了邮箱格式验证已补充 - 错误消息已本地化i18n 顾虑 - 当前 rate limiting 缺失建议后续任务添加 [报告完成子代理终止]2.3 规格审查子代理Spec Compliance Reviewer定位“质检员”确保做对了事核心职责1. 需求对比 - 逐条检查规格 - 验证所有需求已实现 2. 过度实现检测 - 查找未要求的功能 - 识别 YAGNI 违规 3. 理解偏差检测 - 验证实现意图正确 - 识别曲解需求的情况 4. 独立验证 - 不信任实现者报告 - 亲自读代码确认 5. 具体问题报告 - 文件:行号引用 - 缺失/多余功能列表 - 明确的修复指导Prompt 模板# spec-reviewer-prompt.md简化版 You are reviewing whether an implementation matches its specification. ## What Was Requested [完整任务需求 - 原始规格] ## What Implementer Claims They Built [实现者的报告] ## CRITICAL: Do Not Trust the Report The implementer finished suspiciously quickly. Their report may be incomplete, inaccurate, or optimistic. You MUST verify everything independently. **DO NOT:** - Take their word for what they implemented - Trust their claims about completeness - Accept their interpretation of requirements **DO:** - Read the actual code they wrote - Compare actual implementation to requirements line by line - Check for missing pieces they claimed to implement - Look for extra features they didnt mention ## Your Job Read the implementation code and verify: **Missing requirements:** - Did they implement everything that was requested? - Are there requirements they skipped or missed? - Did they claim something works but didnt actually implement it? **Extra/unneeded work:** - Did they build things that werent requested? - Did they over-engineer or add unnecessary features? - Did they add nice to haves that werent in spec? **Misunderstandings:** - Did they interpret requirements differently than intended? - Did they solve the wrong problem? **Verify by reading code, not by trusting report.** Report: - ✅ Spec compliant (if everything matches after code inspection) - ❌ Issues found: [list specifically with file:line references]审查流程接收任务 ↓ ┌──────────────────────────────┐ │ 1. 读取原始需求 │ │ 不是实现者的解读 │ └────────┬─────────────────────┘ ↓ ┌──────────────────────────────┐ │ 2. 读取实现代码 │ │ 不信任报告亲自验证 │ └────────┬─────────────────────┘ ↓ ┌──────────────────────────────┐ │ 3. 逐项对比 │ │ 需求 1 → 检查代码实现 │ │ 需求 2 → 检查代码实现 │ │ ... │ └────────┬─────────────────────┘ ↓ ┌──────────────────────────────┐ │ 4. 检查多余功能 │ │ 代码中有需求外的东西吗 │ └────────┬─────────────────────┘ ↓ ┌──────────────────────────────┐ │ 5. 生成报告 │ │ ✅ 符合 或 │ │ ❌ 问题列表具体到行号 │ └──────────────────────────────┘真实案例任务需求 实现用户注册包含 - 邮箱验证 - 密码强度检查8 字符 - 发送验证邮件 实现者报告 ✅ 完成 - 邮箱验证 ✓ - 密码强度检查 ✓ - 验证邮件发送 ✓ 规格审查子代理实际检查 [读取 src/routes/auth.ts] 发现 1. 邮箱验证仅检查格式未发送确认邮件 ❌ 2. 密码强度硬编码 6 位需求要求 8 位 ❌ 3. 验证邮件Mock 实现未实际发送 ❌ 规格审查报告 ❌ 规格不符合 问题 1. **缺失**邮箱确认流程auth.ts:45-50 - 只验证了格式未发送确认邮件 - 需求发送验证邮件 - 修复添加邮件发送逻辑 2. **偏差**密码最小长度错误validators/register.ts:12 - 当前min(6) - 需求8 字符 - 修复改为 min(8) 3. **Mock 实现**验证邮件未实际发送services/email.ts:23 - 当前console.log(Send email...) - 需求实际发送邮件 - 修复集成真实邮件服务如 SendGrid [返回给主智能体触发修复循环]2.4 质量审查子代理Code Quality Reviewer定位“高级工程师”确保做好了事核心职责1. 架构评估 - SOLID 原则 - 设计模式使用 - 可扩展性 2. 代码质量 - 可读性 - 可维护性 - 命名规范 - DRY 合规 3. 测试评估 - 覆盖率 - 测试质量是否真测逻辑 - 边界情况 4. 安全审查 - 常见漏洞SQL 注入、XSS 等 - 认证/授权 - 敏感数据处理 5. 性能考量 - 明显的性能问题 - 资源泄漏 - 不必要的计算 6. 问题分级 - Critical必须修复 - Important应该修复 - Minor建议优化审查清单## Code Quality Checklist **架构** - [ ] 清晰的关注点分离 - [ ] 合理的抽象层次 - [ ] 适当的设计模式 **代码** - [ ] 命名清晰准确 - [ ] 函数单一职责 - [ ] DRY 原则遵守 - [ ] 避免 Magic Number **测试** - [ ] 测试真正验证逻辑不是 Mock 行为 - [ ] 边界情况覆盖 - [ ] 集成测试适当 - [ ] 覆盖率 80% **安全** - [ ] 输入验证 - [ ] SQL 注入防护 - [ ] XSS 防护 - [ ] 敏感数据加密 **性能** - [ ] N1 查询避免 - [ ] 不必要的循环 - [ ] 内存泄漏风险 **生产就绪** - [ ] 错误处理完善 - [ ] 日志记录适当 - [ ] 向后兼容 - [ ] 文档完整输出格式### Strengths [具体优点带文件:行号] ### Issues #### Critical必须修复 [Bug、安全问题、数据丢失风险] #### Important应该修复 [架构问题、缺失功能、测试不足] #### Minor可选优化 [代码风格、优化机会、文档改进] ### Recommendations [改进建议] ### Assessment **Ready to merge?** Yes/No/With fixes **Reasoning:** [技术评估 1-2 句]真实案例任务实现用户认证中间件 质量审查子代理报告 ### Strengths - 清晰的 JWT 验证逻辑auth.middleware.ts:15-35 - 完整的错误处理auth.middleware.ts:40-55 - 良好的测试覆盖率94% ### Issues #### Critical 1. **JWT Secret 硬编码**auth.middleware.ts:8 - 文件const SECRET my-secret-key - 问题泄露风险无法轮换 - 修复使用环境变量 process.env.JWT_SECRET 2. **Missing Token Expiry 检查**auth.middleware.ts:25 - 当前只验证签名 - 问题过期 token 也能通过 - 修复添加 exp claim 验证 #### Important 1. **Rate Limiting 缺失** - 文件整个 middleware - 问题暴力破解风险 - 建议添加 express-rate-limit 2. **测试未覆盖过期场景** - 文件auth.test.ts - 缺失expired token 测试用例 - 修复添加测试 #### Minor 1. **Magic Number**auth.middleware.ts:18 - if (parts.length ! 2) 应提取为常量 - 建议const BEARER_PARTS 2 ### Recommendations - 考虑添加 refresh token 机制 - 日志记录认证失败安全审计 ### Assessment **Ready to merge:** With fixes **Reasoning:** 核心逻辑正确且测试充分但 Critical 安全问题硬编码 secret、未检查过期必须修复后才能合并。 [触发修复循环]2.5 最终审查代理Final Code Reviewer定位“总工程师”整体功能把关核心职责1. 计划对齐性检查 - 所有计划任务已完成 - 实现符合原始设计 - 无范围蔓延Scope Creep 2. 整体架构一致性 - 各任务代码风格统一 - 架构决策一致 - 无互相矛盾的实现 3. 集成测试验证 - 端到端流程测试 - 各模块集成正常 - 无集成问题 4. 生产就绪性评估 - 性能满足要求 - 安全合规 - 监控和日志 - 文档完整 5. 最终决策 - Ready to merge可以合并 - Needs fixes需要修复 - Needs rework需要返工审查范围与单任务审查的区别 单任务质量审查 - 范围单个任务的代码 - 视角微观函数、类 - 关注代码质量细节 最终审查 - 范围整个功能的所有代码 - 视角宏观系统、架构 - 关注整体一致性和集成审查清单## Final Review Checklist **计划对齐** - [ ] 所有计划任务完成 - [ ] 实现符合设计文档 - [ ] 无未经批准的变更 **整体架构** - [ ] 各模块职责清晰 - [ ] 接口设计一致 - [ ] 依赖关系合理 **集成** - [ ] 端到端测试通过 - [ ] 无集成问题 - [ ] API 契约遵守 **质量** - [ ] 整体代码风格统一 - [ ] 错误处理一致 - [ ] 日志记录规范 **生产就绪** - [ ] 性能测试通过 - [ ] 安全审计通过 - [ ] 文档完整且更新 - [ ] 数据库迁移如有安全 **后续工作** - [ ] 技术债务记录 - [ ] 后续改进建议2.6 并行调查代理Parallel Investigation Agents定位“专家团队”并行解决独立问题使用场景适用多个独立问题需要同时调查 示例场景 1. 3 个测试文件同时失败 → 调度 3 个并行代理每个负责 1 个文件 2. 5 个不同模块的 Bug → 调度 5 个并行代理每个负责 1 个模块 3. 多平台兼容性问题 → 调度 N 个代理每个负责 1 个平台 不适用问题之间有依赖关系调度策略// 决策逻辑何时使用并行代理functionshouldUseParallelAgents(problems:Problem[]):boolean{// 条件 1至少 2 个问题if(problems.length2){returnfalse;}// 条件 2问题相互独立for(leti0;iproblems.length;i){for(letji1;jproblems.length;j){if(areDependent(problems[i],problems[j])){returnfalse;// 有依赖不能并行}}}// 条件 3无共享状态constsharedResourcesfindSharedResources(problems);if(sharedResources.length0){returnfalse;// 会产生冲突}returntrue;// 可以并行}并行执行流程检测到 N 个独立问题 ↓ ┌──────────────────────────────────────┐ │ 主智能体分析问题 │ │ • 验证独立性 │ │ • 检查资源冲突 │ └────────┬─────────────────────────────┘ ↓ ┌──────────────────────────────────────┐ │ 同时调度 N 个并行代理 │ │ │ │ 代理 1 代理 2 ... 代理 N │ │ ↓ ↓ ↓ │ │ 调查问题 1 调查问题 2 调查问题 N │ │ ↓ ↓ ↓ │ │ 提出解决方案 提出解决方案 解决方案 │ │ ↓ ↓ ↓ │ │ 实施修复 实施修复 实施修复 │ └────────┬─────────┬──────────┬────────┘ │ │ │ ↓ ↓ ↓ ┌──────────────────────────────────────┐ │ 主智能体收集结果 │ │ • 检查冲突是否修改了相同代码 │ │ • 合并修复 │ │ • 验证整体测试 │ └──────────────────────────────────────┘真实案例场景3 个测试文件失败 主智能体分析 - auth.test.ts: 5 failures - user.test.ts: 3 failures - api.test.ts: 7 failures 问题独立性检查 - auth.test.ts 失败原因Mock 配置错误 - user.test.ts 失败原因数据库未初始化 - api.test.ts 失败原因API 端点变更 → 无依赖关系可以并行 资源冲突检查 - auth.test.ts 修改src/mocks/auth.mock.ts - user.test.ts 修改src/db/setup.ts - api.test.ts 修改src/routes/api.ts → 无共享文件无冲突 主智能体决策使用并行调查代理 ───────────────────────────────────── 【并行执行】 代理 1auth.test.ts 调查 auth.test.ts 失败... 发现Mock 配置缺少 userId 字段 修复添加 userId: test-123 到 mock 验证5/5 测试通过 ✓ 代理 2user.test.ts 调查 user.test.ts 失败... 发现beforeEach 未初始化数据库 修复添加 await db.sync() 到 beforeEach 验证3/3 测试通过 ✓ 代理 3api.test.ts 调查 api.test.ts 失败... 发现API 从 /api/v1/users 改为 /api/v2/users 修复更新测试 URL 验证7/7 测试通过 ✓ ───────────────────────────────────── 主智能体收集结果 检查冲突 - 代理 1 修改src/mocks/auth.mock.ts - 代理 2 修改src/db/setup.ts - 代理 3 修改src/routes/api.ts → 无冲突 ✓ 合并修复 git add src/mocks/auth.mock.ts src/db/setup.ts src/routes/api.ts git commit -m fix: resolve test failures in 3 files 验证整体 npm test → 15/15 测试通过 ✓ 总耗时15 分钟并行 vs 串行45 分钟3 × 15 分钟 效率提升3 倍三、协作流程3.1 典型工作流Subagent-Driven Development用户批准计划 ↓ ┌────────────────────────────────────────┐ │ 主智能体读取计划提取所有任务 │ └────────┬───────────────────────────────┘ │ ↓ Task 1 ┌────────────────────────────────────────┐ │ 实现者子代理实现 测试 自审 │ └────────┬───────────────────────────────┘ │ ↓ ┌────────────────────────────────────────┐ │ 规格审查子代理验证需求符合 │ └────────┬───────────────────────────────┘ │ 符合│ ├─ NO → 修复循环 → 重新审查 │ ↓ YES ┌────────────────────────────────────────┐ │ 质量审查子代理验证代码质量 │ └────────┬───────────────────────────────┘ │ 合格│ ├─ NO → 修复循环 → 重新审查 │ ↓ YES ┌────────────────────────────────────────┐ │ 主智能体标记 Task 1 完成 │ └────────┬───────────────────────────────┘ │ ↓ Task 2重复上述流程 ↓ Task 3 ↓ ... ↓ Task N ↓ ┌────────────────────────────────────────┐ │ 最终审查代理整体功能审查 │ └────────┬───────────────────────────────┘ │ ↓ ┌────────────────────────────────────────┐ │ 主智能体完成分支合并/PR │ └────────────────────────────────────────┘3.2 修复循环详解规格审查修复循环规格审查 → 发现问题 → 通知实现者 → 修复 → 重新审查 示例 规格审查缺少邮箱验证功能 ↓ 主智能体通知实现者需要补充邮箱验证 ↓ 实现者同一个子代理添加邮箱验证逻辑 ↓ 规格审查子代理重新审查 ↓ 规格审查现在符合 ✓质量审查修复循环质量审查 → 分级问题 → 修复 Critical/Important → 重新审查 示例 质量审查 - Critical: JWT Secret 硬编码 - Important: Rate Limiting 缺失 - Minor: Magic Number ↓ 实现者修复 Critical 和 Important ↓ 质量审查子代理重新审查 ↓ 质量审查Critical 和 Important 已修复 ✓ Minor 问题可接受四、通信协议4.1 消息格式主智能体 → 实现者子代理{tool:Task,subagent_type:general-purpose,description:Implement Task 1: User Model,prompt:You are implementing Task 1: Create User Model ## Task Description [完整规格粘贴] ## Project Context - Database: PostgreSQL - ORM: TypeORM - Test Framework: Jest ## Existing Patterns See src/entities/Post.ts for reference ## Your Job 1. Create User entity 2. Write migration 3. Write tests 4. Commit and report}实现者子代理 → 主智能体提问{type:question,content:Should the hook install at user or system level?}主智能体 → 实现者子代理回答{type:answer,content:User level (~/.config/superpowers/hooks/)}实现者子代理 → 主智能体完成报告{type:completion_report,status:completed,summary:✅ User model implemented,details:{implemented:[User entity with email, password fields,bcrypt password hashing,Database migration],tests:{total:12,passed:12,coverage:0.94},files_changed:[src/entities/User.ts,src/migrations/1234_create_users.ts,tests/user.test.ts],self_review_findings:[Initially forgot email index, now added],concerns:[Rate limiting not implemented (suggest future task)]}}4.2 状态同步TodoWrite 更新流程Task 开始 主智能体 → TodoWrite: markInProgress(taskId) → 用户看到[→] 实现用户模型中... Task 完成 主智能体 → TodoWrite: markCompleted(taskId) → 用户看到[✓] 实现用户模型 Task 失败 主智能体 → TodoWrite: markFailed(taskId) → 用户看到[✗] 实现用户模型失败五、执行顺序5.1 完整时间线5 个任务的功能T0: 会话启动 → 主智能体初始化 → 加载技能索引 T5min: 用户提出需求 → 主智能体激活 brainstorming 技能 → 设计讨论10-15 分钟 T20min: 设计确认 → 主智能体激活 writing-plans 技能 → 生成计划5-10 分钟 T30min: 计划批准 → 主智能体激活 subagent-driven-development 技能 → 提取 5 个任务创建 TodoWrite ──── 自动化执行开始 ──── T35min: Task 1 开始 → 调度实现者子代理 1 → 实现者提问可选 → 实现 测试15-20 分钟 T55min: Task 1 实现完成 → 调度规格审查子代理 → 审查2-3 分钟 T58min: 规格审查通过 → 调度质量审查子代理 → 审查3-5 分钟 T63min: 质量审查通过 → 主智能体标记 Task 1 完成 → 自动进入 Task 2 T65min: Task 2 开始 → 调度实现者子代理 2新鲜上下文 → ...重复流程 T90min: Task 2 完成 T92min: Task 3 开始 → ... T120min: Task 3 完成 T122min: Task 4 开始 → ... T150min: Task 4 完成 T152min: Task 5 开始 → ... T180min: Task 5 完成 ──── 自动化执行结束 ──── T182min: 所有任务完成 → 调度最终审查代理 → 整体审查5-10 分钟 T192min: 最终审查通过 → 主智能体激活 finishing-a-development-branch 技能 → 向用户展示 4 个选项 T193min: 用户选择合并方式 → 主智能体执行合并 → 完成 ✅ 总时间约 3 小时 人工参与约 30 分钟设计 计划 最终确认 自动执行约 2.5 小时无需人工值守六、设计原理6.1 为什么需要 6 种角色单一智能体的问题单一智能体模式 Task 1 → Task 2 → Task 3 → Task 4 → Task 5 问题 1. 上下文累积 → Task 5 受 Task 1-4 的偏见影响 2. 缺少审查 → 错误累积到最后才发现 3. 质量不稳定 → 无系统化保证多角色解决方案主智能体编排 ↓ 实现者子代理执行 - 新鲜上下文专注实现 ↓ 规格审查第一道关- 确保做对了 ↓ 质量审查第二道关- 确保做好了 ↓ 最终审查整体把关- 确保协调一致6.2 为什么是两阶段审查一次性审查的问题 方向错了质量再高也白搭 示例 需求实现用户登录Session 实现者实现了 JWT 认证理解错误 一次性审查 代码写得很好架构清晰测试完善 ✓ → 但做错了功能 两阶段审查 阶段 1 规格审查 ❌ 需求是 Session你实现的是 JWT → 立即发现方向性错误 阶段 2 质量审查 只有阶段 1 通过后才执行 ✓ Session 实现正确代码质量高6.3 为什么实现者能提问刻板执行 vs 智能澄清 刻板执行 实现者任务说实现认证我不知道用什么方式 → 猜测随便选了 JWT → 结果可能不符合用户期望 智能澄清 实现者任务说实现认证应该用 JWT 还是 Session 主智能体/用户用 Session 实现者好的实现 Session 认证 → 结果符合期望6.4 为什么需要并行调查代理串行 vs 并行 串行调查3 个问题 问题 1 调查15 分钟 问题 2 调查15 分钟 问题 3 调查15 分钟 总耗时45 分钟 并行调查3 个代理 代理 1 调查问题 115 分钟 ┐ 代理 2 调查问题 215 分钟 ├ 并行 代理 3 调查问题 315 分钟 ┘ 总耗时15 分钟 效率提升3 倍七、总结7.1 角色分工表角色核心职责类比生命周期主智能体指挥官项目经理整个会话实现者子代理执行者程序员单个任务规格审查子代理质检员QA 测试员单次审查质量审查子代理高级工程师Tech Lead单次审查最终审查代理总工程师架构师单次审查并行调查代理专家团队专项小组各自独立7.2 关键设计洞察1. 职责分离 → 专注提升质量 2. 新鲜上下文 → 避免偏见累积 3. 分层审查 → 系统化质量保证 4. 智能澄清 → 减少理解偏差 5. 并行能力 → 提升效率
Superpowers 角色体系：六种智能体协作详解
目录一、角色总览二、角色详细说明三、协作流程四、通信协议五、执行顺序六、设计原理一、角色总览1.1 六种角色一览表#角色名称英文名生命周期主要职责触发时机1主智能体Main Agent整个会话编排协调、技能调度会话开始2实现者子代理Implementer Subagent单个任务编码、测试、自审每个任务开始3规格审查子代理Spec Compliance Reviewer单次审查验证需求符合性任务实现完成后4质量审查子代理Code Quality Reviewer单次审查验证代码质量规格审查通过后5最终审查代理Final Code Reviewer单次审查整体功能评估所有任务完成后6并行调查代理Parallel Investigation Agents各自独立并行调查独立问题多个独立问题时1.2 角色关系图用户Developer │ 指令/需求 ↓ ┌────────────────────────────────┐ │ 【1】主智能体Orchestrator │ │ • 技能调度 │ │ • 上下文管理 │ │ • 工作流控制 │ └────────┬────────────────────────┘ │ ├───调度──→ 【2】实现者子代理 │ ↓ 完成 ├───调度──→ 【3】规格审查子代理 │ ↓ 通过 ├───调度──→ 【4】质量审查子代理 │ ↓ 批准 ├───调度──→ 【5】最终审查代理 │ └───并行调度──→ 【6】并行调查代理 × N二、角色详细说明2.1 主智能体Main Agent定位整个系统的大脑和指挥官核心职责1. 技能发现和激活 - 检测用户意图 - 匹配适用的技能 - 加载技能内容到上下文 2. 子代理生命周期管理 - 创建spawn - 调度dispatch - 监控monitor - 销毁terminate 3. 上下文提取和注入 - 从项目文件提取信息 - 构建完整的上下文包 - 注入到子代理 prompt 4. 工作流状态跟踪 - TodoWrite 更新 - 进度报告 - 错误处理 5. 决策路由 - 选择执行策略 - 处理子代理提问 - 转发用户决策生命周期会话启动 ↓ ┌──────────────────────────────┐ │ 初始化 │ │ • 加载技能索引 │ │ • 注入 using-superpowers │ └────────┬─────────────────────┘ ↓ ┌──────────────────────────────┐ │ 活跃状态 │ │ • 接收用户输入 │ │ • 激活技能 │ │ • 调度子代理 │ │ • 处理结果 │ │ 循环直到会话结束 │ └────────┬─────────────────────┘ ↓ 会话结束关键特征✅持久性整个会话期间存在✅完整上下文拥有所有对话历史✅编排能力协调多个子代理⚠️上下文污染风险因此需要子代理隔离示例交互用户帮我实现用户登录功能 主智能体内部处理 1. 检测关键词实现、功能 → 匹配到 brainstorming 技能 2. 激活 brainstorming 技能 3. 加载技能内容 4. 执行设计讨论 5. 用户批准设计后 → 激活 writing-plans 技能 6. 生成详细计划 7. 用户批准计划后 → 激活 subagent-driven-development 技能 8. 读取计划提取所有任务 9. 创建 TodoWrite 10. 开始任务循环 For each task: - 调度实现者子代理 - 调度规格审查子代理 - 调度质量审查子代理 - 更新 TodoWrite2.2 实现者子代理Implementer Subagent定位“执行者”负责具体编码工作核心职责1. 需求澄清 - 读取任务规格 - 如有疑问提问Before implementing 2. 编码实现 - 遵循 TDD 流程 - 编写生产代码 - 遵循项目约定 3. 测试编写 - 单元测试 - 集成测试 - 确保覆盖率 4. 自我审查 - 检查完整性 - 检查质量 - 检查 YAGNI 合规 5. 提交和报告 - Git commit - 总结完成内容 - 报告问题或顾虑Prompt 模板# implementer-prompt.md简化版 You are implementing Task N: [task name] ## Task Description [完整任务文本 - 主智能体粘贴无需子代理自己读文件] ## Context [项目架构、技术栈、依赖关系] ## Before You Begin If you have questions about: - Requirements or acceptance criteria - Implementation approach - Dependencies or assumptions **Ask them now.** Raise concerns before starting work. ## Your Job 1. Implement exactly what the task specifies 2. Write tests (following TDD if required) 3. Verify implementation works 4. Commit your work 5. Self-review 6. Report back Work from: [directory] While you work: If you encounter something unexpected, ask questions. Dont guess or make assumptions. ## Self-Review Checklist Before reporting: - [ ] Did I fully implement everything in the spec? - [ ] Did I miss any requirements? - [ ] Is this my best work? - [ ] Did I avoid overbuilding (YAGNI)? - [ ] Do tests actually verify behavior? ## Report Format - What you implemented - What you tested and test results - Files changed - Any issues or concerns生命周期任务开始 ↓ ┌──────────────────────────────┐ │ 创建Spawn │ │ • 新鲜上下文 │ │ • 无历史包袱 │ └────────┬─────────────────────┘ ↓ ┌──────────────────────────────┐ │ 澄清阶段 │ │ • 读取完整 prompt │ │ • 识别疑问点 │ │ • 向主智能体提问 │ └────────┬─────────────────────┘ ↓ ┌──────────────────────────────┐ │ 实现阶段 │ │ • 编写代码 │ │ • 编写测试TDD │ │ • 运行验证 │ └────────┬─────────────────────┘ ↓ ┌──────────────────────────────┐ │ 自审阶段 │ │ • 检查完整性 │ │ • 检查质量 │ │ • 必要时自行修复 │ └────────┬─────────────────────┘ ↓ ┌──────────────────────────────┐ │ 报告和提交 │ │ • Git commit │ │ • 生成报告 │ │ • 返回给主智能体 │ └────────┬─────────────────────┘ ↓ 销毁Terminate关键特征✅新鲜上下文无历史偏见✅专注单任务不会分心✅可提问遇到不清楚的主动澄清⚠️短生命周期任务完成即销毁真实案例任务实现用户注册接口 实现者子代理执行过程 [收到 prompt包含完整规格和上下文] 实现者Before I begin - should password validation be strict (8 chars, numbersletters) or lenient (6 chars)? 主智能体/用户Strict (8 chars, numbersletters) 实现者Got it. Implementing now... [30 分钟后] 实现者报告 ✅ 完成 实现内容 - 创建 POST /api/auth/register 端点 - 添加 Zod 验证 schema8 字符数字字母 - 密码使用 bcrypt 加密salt rounds10 - 邮箱唯一性检查 - 成功返回 JWT token 测试 - 12/12 单元测试通过 - 3/3 集成测试通过 - 覆盖率96% 文件变更 - src/routes/auth.ts新增 - src/validators/register.ts新增 - src/services/auth.service.ts新增 - tests/auth.test.ts新增 自审发现 - 初始实现忘记了邮箱格式验证已补充 - 错误消息已本地化i18n 顾虑 - 当前 rate limiting 缺失建议后续任务添加 [报告完成子代理终止]2.3 规格审查子代理Spec Compliance Reviewer定位“质检员”确保做对了事核心职责1. 需求对比 - 逐条检查规格 - 验证所有需求已实现 2. 过度实现检测 - 查找未要求的功能 - 识别 YAGNI 违规 3. 理解偏差检测 - 验证实现意图正确 - 识别曲解需求的情况 4. 独立验证 - 不信任实现者报告 - 亲自读代码确认 5. 具体问题报告 - 文件:行号引用 - 缺失/多余功能列表 - 明确的修复指导Prompt 模板# spec-reviewer-prompt.md简化版 You are reviewing whether an implementation matches its specification. ## What Was Requested [完整任务需求 - 原始规格] ## What Implementer Claims They Built [实现者的报告] ## CRITICAL: Do Not Trust the Report The implementer finished suspiciously quickly. Their report may be incomplete, inaccurate, or optimistic. You MUST verify everything independently. **DO NOT:** - Take their word for what they implemented - Trust their claims about completeness - Accept their interpretation of requirements **DO:** - Read the actual code they wrote - Compare actual implementation to requirements line by line - Check for missing pieces they claimed to implement - Look for extra features they didnt mention ## Your Job Read the implementation code and verify: **Missing requirements:** - Did they implement everything that was requested? - Are there requirements they skipped or missed? - Did they claim something works but didnt actually implement it? **Extra/unneeded work:** - Did they build things that werent requested? - Did they over-engineer or add unnecessary features? - Did they add nice to haves that werent in spec? **Misunderstandings:** - Did they interpret requirements differently than intended? - Did they solve the wrong problem? **Verify by reading code, not by trusting report.** Report: - ✅ Spec compliant (if everything matches after code inspection) - ❌ Issues found: [list specifically with file:line references]审查流程接收任务 ↓ ┌──────────────────────────────┐ │ 1. 读取原始需求 │ │ 不是实现者的解读 │ └────────┬─────────────────────┘ ↓ ┌──────────────────────────────┐ │ 2. 读取实现代码 │ │ 不信任报告亲自验证 │ └────────┬─────────────────────┘ ↓ ┌──────────────────────────────┐ │ 3. 逐项对比 │ │ 需求 1 → 检查代码实现 │ │ 需求 2 → 检查代码实现 │ │ ... │ └────────┬─────────────────────┘ ↓ ┌──────────────────────────────┐ │ 4. 检查多余功能 │ │ 代码中有需求外的东西吗 │ └────────┬─────────────────────┘ ↓ ┌──────────────────────────────┐ │ 5. 生成报告 │ │ ✅ 符合 或 │ │ ❌ 问题列表具体到行号 │ └──────────────────────────────┘真实案例任务需求 实现用户注册包含 - 邮箱验证 - 密码强度检查8 字符 - 发送验证邮件 实现者报告 ✅ 完成 - 邮箱验证 ✓ - 密码强度检查 ✓ - 验证邮件发送 ✓ 规格审查子代理实际检查 [读取 src/routes/auth.ts] 发现 1. 邮箱验证仅检查格式未发送确认邮件 ❌ 2. 密码强度硬编码 6 位需求要求 8 位 ❌ 3. 验证邮件Mock 实现未实际发送 ❌ 规格审查报告 ❌ 规格不符合 问题 1. **缺失**邮箱确认流程auth.ts:45-50 - 只验证了格式未发送确认邮件 - 需求发送验证邮件 - 修复添加邮件发送逻辑 2. **偏差**密码最小长度错误validators/register.ts:12 - 当前min(6) - 需求8 字符 - 修复改为 min(8) 3. **Mock 实现**验证邮件未实际发送services/email.ts:23 - 当前console.log(Send email...) - 需求实际发送邮件 - 修复集成真实邮件服务如 SendGrid [返回给主智能体触发修复循环]2.4 质量审查子代理Code Quality Reviewer定位“高级工程师”确保做好了事核心职责1. 架构评估 - SOLID 原则 - 设计模式使用 - 可扩展性 2. 代码质量 - 可读性 - 可维护性 - 命名规范 - DRY 合规 3. 测试评估 - 覆盖率 - 测试质量是否真测逻辑 - 边界情况 4. 安全审查 - 常见漏洞SQL 注入、XSS 等 - 认证/授权 - 敏感数据处理 5. 性能考量 - 明显的性能问题 - 资源泄漏 - 不必要的计算 6. 问题分级 - Critical必须修复 - Important应该修复 - Minor建议优化审查清单## Code Quality Checklist **架构** - [ ] 清晰的关注点分离 - [ ] 合理的抽象层次 - [ ] 适当的设计模式 **代码** - [ ] 命名清晰准确 - [ ] 函数单一职责 - [ ] DRY 原则遵守 - [ ] 避免 Magic Number **测试** - [ ] 测试真正验证逻辑不是 Mock 行为 - [ ] 边界情况覆盖 - [ ] 集成测试适当 - [ ] 覆盖率 80% **安全** - [ ] 输入验证 - [ ] SQL 注入防护 - [ ] XSS 防护 - [ ] 敏感数据加密 **性能** - [ ] N1 查询避免 - [ ] 不必要的循环 - [ ] 内存泄漏风险 **生产就绪** - [ ] 错误处理完善 - [ ] 日志记录适当 - [ ] 向后兼容 - [ ] 文档完整输出格式### Strengths [具体优点带文件:行号] ### Issues #### Critical必须修复 [Bug、安全问题、数据丢失风险] #### Important应该修复 [架构问题、缺失功能、测试不足] #### Minor可选优化 [代码风格、优化机会、文档改进] ### Recommendations [改进建议] ### Assessment **Ready to merge?** Yes/No/With fixes **Reasoning:** [技术评估 1-2 句]真实案例任务实现用户认证中间件 质量审查子代理报告 ### Strengths - 清晰的 JWT 验证逻辑auth.middleware.ts:15-35 - 完整的错误处理auth.middleware.ts:40-55 - 良好的测试覆盖率94% ### Issues #### Critical 1. **JWT Secret 硬编码**auth.middleware.ts:8 - 文件const SECRET my-secret-key - 问题泄露风险无法轮换 - 修复使用环境变量 process.env.JWT_SECRET 2. **Missing Token Expiry 检查**auth.middleware.ts:25 - 当前只验证签名 - 问题过期 token 也能通过 - 修复添加 exp claim 验证 #### Important 1. **Rate Limiting 缺失** - 文件整个 middleware - 问题暴力破解风险 - 建议添加 express-rate-limit 2. **测试未覆盖过期场景** - 文件auth.test.ts - 缺失expired token 测试用例 - 修复添加测试 #### Minor 1. **Magic Number**auth.middleware.ts:18 - if (parts.length ! 2) 应提取为常量 - 建议const BEARER_PARTS 2 ### Recommendations - 考虑添加 refresh token 机制 - 日志记录认证失败安全审计 ### Assessment **Ready to merge:** With fixes **Reasoning:** 核心逻辑正确且测试充分但 Critical 安全问题硬编码 secret、未检查过期必须修复后才能合并。 [触发修复循环]2.5 最终审查代理Final Code Reviewer定位“总工程师”整体功能把关核心职责1. 计划对齐性检查 - 所有计划任务已完成 - 实现符合原始设计 - 无范围蔓延Scope Creep 2. 整体架构一致性 - 各任务代码风格统一 - 架构决策一致 - 无互相矛盾的实现 3. 集成测试验证 - 端到端流程测试 - 各模块集成正常 - 无集成问题 4. 生产就绪性评估 - 性能满足要求 - 安全合规 - 监控和日志 - 文档完整 5. 最终决策 - Ready to merge可以合并 - Needs fixes需要修复 - Needs rework需要返工审查范围与单任务审查的区别 单任务质量审查 - 范围单个任务的代码 - 视角微观函数、类 - 关注代码质量细节 最终审查 - 范围整个功能的所有代码 - 视角宏观系统、架构 - 关注整体一致性和集成审查清单## Final Review Checklist **计划对齐** - [ ] 所有计划任务完成 - [ ] 实现符合设计文档 - [ ] 无未经批准的变更 **整体架构** - [ ] 各模块职责清晰 - [ ] 接口设计一致 - [ ] 依赖关系合理 **集成** - [ ] 端到端测试通过 - [ ] 无集成问题 - [ ] API 契约遵守 **质量** - [ ] 整体代码风格统一 - [ ] 错误处理一致 - [ ] 日志记录规范 **生产就绪** - [ ] 性能测试通过 - [ ] 安全审计通过 - [ ] 文档完整且更新 - [ ] 数据库迁移如有安全 **后续工作** - [ ] 技术债务记录 - [ ] 后续改进建议2.6 并行调查代理Parallel Investigation Agents定位“专家团队”并行解决独立问题使用场景适用多个独立问题需要同时调查 示例场景 1. 3 个测试文件同时失败 → 调度 3 个并行代理每个负责 1 个文件 2. 5 个不同模块的 Bug → 调度 5 个并行代理每个负责 1 个模块 3. 多平台兼容性问题 → 调度 N 个代理每个负责 1 个平台 不适用问题之间有依赖关系调度策略// 决策逻辑何时使用并行代理functionshouldUseParallelAgents(problems:Problem[]):boolean{// 条件 1至少 2 个问题if(problems.length2){returnfalse;}// 条件 2问题相互独立for(leti0;iproblems.length;i){for(letji1;jproblems.length;j){if(areDependent(problems[i],problems[j])){returnfalse;// 有依赖不能并行}}}// 条件 3无共享状态constsharedResourcesfindSharedResources(problems);if(sharedResources.length0){returnfalse;// 会产生冲突}returntrue;// 可以并行}并行执行流程检测到 N 个独立问题 ↓ ┌──────────────────────────────────────┐ │ 主智能体分析问题 │ │ • 验证独立性 │ │ • 检查资源冲突 │ └────────┬─────────────────────────────┘ ↓ ┌──────────────────────────────────────┐ │ 同时调度 N 个并行代理 │ │ │ │ 代理 1 代理 2 ... 代理 N │ │ ↓ ↓ ↓ │ │ 调查问题 1 调查问题 2 调查问题 N │ │ ↓ ↓ ↓ │ │ 提出解决方案 提出解决方案 解决方案 │ │ ↓ ↓ ↓ │ │ 实施修复 实施修复 实施修复 │ └────────┬─────────┬──────────┬────────┘ │ │ │ ↓ ↓ ↓ ┌──────────────────────────────────────┐ │ 主智能体收集结果 │ │ • 检查冲突是否修改了相同代码 │ │ • 合并修复 │ │ • 验证整体测试 │ └──────────────────────────────────────┘真实案例场景3 个测试文件失败 主智能体分析 - auth.test.ts: 5 failures - user.test.ts: 3 failures - api.test.ts: 7 failures 问题独立性检查 - auth.test.ts 失败原因Mock 配置错误 - user.test.ts 失败原因数据库未初始化 - api.test.ts 失败原因API 端点变更 → 无依赖关系可以并行 资源冲突检查 - auth.test.ts 修改src/mocks/auth.mock.ts - user.test.ts 修改src/db/setup.ts - api.test.ts 修改src/routes/api.ts → 无共享文件无冲突 主智能体决策使用并行调查代理 ───────────────────────────────────── 【并行执行】 代理 1auth.test.ts 调查 auth.test.ts 失败... 发现Mock 配置缺少 userId 字段 修复添加 userId: test-123 到 mock 验证5/5 测试通过 ✓ 代理 2user.test.ts 调查 user.test.ts 失败... 发现beforeEach 未初始化数据库 修复添加 await db.sync() 到 beforeEach 验证3/3 测试通过 ✓ 代理 3api.test.ts 调查 api.test.ts 失败... 发现API 从 /api/v1/users 改为 /api/v2/users 修复更新测试 URL 验证7/7 测试通过 ✓ ───────────────────────────────────── 主智能体收集结果 检查冲突 - 代理 1 修改src/mocks/auth.mock.ts - 代理 2 修改src/db/setup.ts - 代理 3 修改src/routes/api.ts → 无冲突 ✓ 合并修复 git add src/mocks/auth.mock.ts src/db/setup.ts src/routes/api.ts git commit -m fix: resolve test failures in 3 files 验证整体 npm test → 15/15 测试通过 ✓ 总耗时15 分钟并行 vs 串行45 分钟3 × 15 分钟 效率提升3 倍三、协作流程3.1 典型工作流Subagent-Driven Development用户批准计划 ↓ ┌────────────────────────────────────────┐ │ 主智能体读取计划提取所有任务 │ └────────┬───────────────────────────────┘ │ ↓ Task 1 ┌────────────────────────────────────────┐ │ 实现者子代理实现 测试 自审 │ └────────┬───────────────────────────────┘ │ ↓ ┌────────────────────────────────────────┐ │ 规格审查子代理验证需求符合 │ └────────┬───────────────────────────────┘ │ 符合│ ├─ NO → 修复循环 → 重新审查 │ ↓ YES ┌────────────────────────────────────────┐ │ 质量审查子代理验证代码质量 │ └────────┬───────────────────────────────┘ │ 合格│ ├─ NO → 修复循环 → 重新审查 │ ↓ YES ┌────────────────────────────────────────┐ │ 主智能体标记 Task 1 完成 │ └────────┬───────────────────────────────┘ │ ↓ Task 2重复上述流程 ↓ Task 3 ↓ ... ↓ Task N ↓ ┌────────────────────────────────────────┐ │ 最终审查代理整体功能审查 │ └────────┬───────────────────────────────┘ │ ↓ ┌────────────────────────────────────────┐ │ 主智能体完成分支合并/PR │ └────────────────────────────────────────┘3.2 修复循环详解规格审查修复循环规格审查 → 发现问题 → 通知实现者 → 修复 → 重新审查 示例 规格审查缺少邮箱验证功能 ↓ 主智能体通知实现者需要补充邮箱验证 ↓ 实现者同一个子代理添加邮箱验证逻辑 ↓ 规格审查子代理重新审查 ↓ 规格审查现在符合 ✓质量审查修复循环质量审查 → 分级问题 → 修复 Critical/Important → 重新审查 示例 质量审查 - Critical: JWT Secret 硬编码 - Important: Rate Limiting 缺失 - Minor: Magic Number ↓ 实现者修复 Critical 和 Important ↓ 质量审查子代理重新审查 ↓ 质量审查Critical 和 Important 已修复 ✓ Minor 问题可接受四、通信协议4.1 消息格式主智能体 → 实现者子代理{tool:Task,subagent_type:general-purpose,description:Implement Task 1: User Model,prompt:You are implementing Task 1: Create User Model ## Task Description [完整规格粘贴] ## Project Context - Database: PostgreSQL - ORM: TypeORM - Test Framework: Jest ## Existing Patterns See src/entities/Post.ts for reference ## Your Job 1. Create User entity 2. Write migration 3. Write tests 4. Commit and report}实现者子代理 → 主智能体提问{type:question,content:Should the hook install at user or system level?}主智能体 → 实现者子代理回答{type:answer,content:User level (~/.config/superpowers/hooks/)}实现者子代理 → 主智能体完成报告{type:completion_report,status:completed,summary:✅ User model implemented,details:{implemented:[User entity with email, password fields,bcrypt password hashing,Database migration],tests:{total:12,passed:12,coverage:0.94},files_changed:[src/entities/User.ts,src/migrations/1234_create_users.ts,tests/user.test.ts],self_review_findings:[Initially forgot email index, now added],concerns:[Rate limiting not implemented (suggest future task)]}}4.2 状态同步TodoWrite 更新流程Task 开始 主智能体 → TodoWrite: markInProgress(taskId) → 用户看到[→] 实现用户模型中... Task 完成 主智能体 → TodoWrite: markCompleted(taskId) → 用户看到[✓] 实现用户模型 Task 失败 主智能体 → TodoWrite: markFailed(taskId) → 用户看到[✗] 实现用户模型失败五、执行顺序5.1 完整时间线5 个任务的功能T0: 会话启动 → 主智能体初始化 → 加载技能索引 T5min: 用户提出需求 → 主智能体激活 brainstorming 技能 → 设计讨论10-15 分钟 T20min: 设计确认 → 主智能体激活 writing-plans 技能 → 生成计划5-10 分钟 T30min: 计划批准 → 主智能体激活 subagent-driven-development 技能 → 提取 5 个任务创建 TodoWrite ──── 自动化执行开始 ──── T35min: Task 1 开始 → 调度实现者子代理 1 → 实现者提问可选 → 实现 测试15-20 分钟 T55min: Task 1 实现完成 → 调度规格审查子代理 → 审查2-3 分钟 T58min: 规格审查通过 → 调度质量审查子代理 → 审查3-5 分钟 T63min: 质量审查通过 → 主智能体标记 Task 1 完成 → 自动进入 Task 2 T65min: Task 2 开始 → 调度实现者子代理 2新鲜上下文 → ...重复流程 T90min: Task 2 完成 T92min: Task 3 开始 → ... T120min: Task 3 完成 T122min: Task 4 开始 → ... T150min: Task 4 完成 T152min: Task 5 开始 → ... T180min: Task 5 完成 ──── 自动化执行结束 ──── T182min: 所有任务完成 → 调度最终审查代理 → 整体审查5-10 分钟 T192min: 最终审查通过 → 主智能体激活 finishing-a-development-branch 技能 → 向用户展示 4 个选项 T193min: 用户选择合并方式 → 主智能体执行合并 → 完成 ✅ 总时间约 3 小时 人工参与约 30 分钟设计 计划 最终确认 自动执行约 2.5 小时无需人工值守六、设计原理6.1 为什么需要 6 种角色单一智能体的问题单一智能体模式 Task 1 → Task 2 → Task 3 → Task 4 → Task 5 问题 1. 上下文累积 → Task 5 受 Task 1-4 的偏见影响 2. 缺少审查 → 错误累积到最后才发现 3. 质量不稳定 → 无系统化保证多角色解决方案主智能体编排 ↓ 实现者子代理执行 - 新鲜上下文专注实现 ↓ 规格审查第一道关- 确保做对了 ↓ 质量审查第二道关- 确保做好了 ↓ 最终审查整体把关- 确保协调一致6.2 为什么是两阶段审查一次性审查的问题 方向错了质量再高也白搭 示例 需求实现用户登录Session 实现者实现了 JWT 认证理解错误 一次性审查 代码写得很好架构清晰测试完善 ✓ → 但做错了功能 两阶段审查 阶段 1 规格审查 ❌ 需求是 Session你实现的是 JWT → 立即发现方向性错误 阶段 2 质量审查 只有阶段 1 通过后才执行 ✓ Session 实现正确代码质量高6.3 为什么实现者能提问刻板执行 vs 智能澄清 刻板执行 实现者任务说实现认证我不知道用什么方式 → 猜测随便选了 JWT → 结果可能不符合用户期望 智能澄清 实现者任务说实现认证应该用 JWT 还是 Session 主智能体/用户用 Session 实现者好的实现 Session 认证 → 结果符合期望6.4 为什么需要并行调查代理串行 vs 并行 串行调查3 个问题 问题 1 调查15 分钟 问题 2 调查15 分钟 问题 3 调查15 分钟 总耗时45 分钟 并行调查3 个代理 代理 1 调查问题 115 分钟 ┐ 代理 2 调查问题 215 分钟 ├ 并行 代理 3 调查问题 315 分钟 ┘ 总耗时15 分钟 效率提升3 倍七、总结7.1 角色分工表角色核心职责类比生命周期主智能体指挥官项目经理整个会话实现者子代理执行者程序员单个任务规格审查子代理质检员QA 测试员单次审查质量审查子代理高级工程师Tech Lead单次审查最终审查代理总工程师架构师单次审查并行调查代理专家团队专项小组各自独立7.2 关键设计洞察1. 职责分离 → 专注提升质量 2. 新鲜上下文 → 避免偏见累积 3. 分层审查 → 系统化质量保证 4. 智能澄清 → 减少理解偏差 5. 并行能力 → 提升效率
