subagent-driven-development

子 Agent 驱动开发

概述

此技能通过专用子 Agent 编排实现流程，并内置质量关卡。每项任务都由实现子 Agent 完成，然后由两个专门的审查 Agent（规范合规性和代码质量）进行审查，通过后方可验收。审查失败时会启动迭代修复流程，最多重试 3 次，之后升级处理。这种方式既能大规模保持质量一致，又能最大限度地提高并行处理能力。

开始时说明：“我正在使用子 Agent 驱动开发技能，通过两阶段审查关卡分派实现任务。”

触发条件

• 计划包含 3 项或更多可独立实现的任务
• 任务具有明确的验收标准，适合委派
• 执行速度优先
• 任务之间的依赖关系较少
• 委派工作需要设置质量关卡

---

阶段 1：任务准备

**目标：**确保每项任务在分派给任何子 Agent 之前都已完整明确。

任务规范要求（7 个部分）

分派给子 Agent 的每项任务都必须包含以下全部内容：

部分	内容	示例
1. 任务描述	清晰、明确的说明	“实现使用 RS256 签名的 JWT 令牌生成”
2. 要创建或修改的文件	明确列出	src/auth/jwt.ts、tests/auth/jwt.test.ts
3. 验收标准	具体、可测试的条件	“令牌在 1 小时后过期”“无效密钥会抛出 AuthError”
4. TDD 要求	要编写的测试及需覆盖的行为	“测试：有效令牌生成、拒绝过期令牌、处理无效密钥”
5. 质量标准	代码风格、模式、约定	“遵循 src/services/ 中现有的服务模式，使用 Result 类型处理错误”
6. 上下文	相关代码、接口、依赖项	“Logger API：logger.info(msg, meta)。从 ../utils/logger 导入”
7. 约束	不要做的事	“不要修改现有的身份验证中间件。不要添加新依赖。”

分派前检查清单

• 任务规范已填写全部 7 个部分
• 任务相互独立（不依赖正在进行且尚未解决的任务）
• 验收标准具体且可测试
• 已确定要修改的文件，且这些文件可访问
• 已收集相关上下文并将其纳入规范

任务独立性决策表

依赖类型	可以分派吗？	操作
无依赖	可以	立即分派
依赖已完成的任务	可以	将已完成任务的输出作为上下文
依赖正在进行的任务	不可以	等待依赖任务完成
与另一项任务共用文件	不可以	串行处理——该文件一次只分派一项任务
仅共用接口	可以	将接口定义作为上下文

停止——在满足以下条件之前不要分派：

• 7 个规范部分均已完整填写
• 已确认任务相互独立
• 验收标准可测试

---

阶段 2：实现分派

**目标：**将完整上下文随任务一同发送给实现子 Agent。

1. 使用 implementer-prompt.md 模板准备实现者提示词
2. 纳入完整的任务规范（全部 7 个部分）
3. 纳入相关代码上下文（现有文件、接口、类型）
4. 分派实现子 Agent
5. 收集实现输出

**分派机制：**使用 Agent 工具，设置 subagent_type="general-purpose"，并将实现者提示词（来自 implementer-prompt.md）放入 prompt 参数。将 description 设置为简短的任务标签。

实现者要求

实现子 Agent 必须：

• 遵循 TDD 循环（RED-GREEN-REFACTOR）
• 先编写测试，再编写生产代码
• 仅修改任务规范中列出的文件
• 遵循指定的质量标准
• 报告遇到的任何问题或阻碍
• 记录所有作出的假设

问题处理协议

问题类型	实施期间	操作
非阻塞	可以基于合理假设继续	记录假设，继续执行，并在输出中标明
阻塞	没有答案就无法继续	立即停止，并上报给协调器
范围问题	询问分配任务之外的工作	报告此问题，切勿修复

停止——在以下条件满足之前，不要继续评审：

• 实施者已返回完整输出
• 所有列出的文件均已创建或修改
• 每项验收标准都有对应测试
• 已记录所有假设

---

阶段 3：规范评审关卡

目标： 验证实现是否符合原始任务规范。

1. 使用 spec-reviewer-prompt.md 模板准备规范评审者提示词
2. 提供原始任务规范和实施者的输出
3. 调用规范评审子 Agent
4. 收集评审结果

调用机制： 使用 Agent 工具，并在 prompt 参数中传入规范评审者提示词（来自 spec-reviewer-prompt.md）。

规范评审标准

标准	评估	检查内容
满足所有验收标准	每项标准均为 PASS / FAIL	逐项验证每项标准
测试覆盖指定行为	PASS / FAIL	测试文件包含针对所有行为的测试
修改的文件符合规范	PASS / FAIL	没有未经授权的文件修改
没有超出范围的更改	PASS / FAIL	仅修改列出的文件
实现符合预期	PASS / FAIL	行为正确，而不仅仅是语法有效
遵守所有约束	PASS / FAIL	未违反任何“不得”事项

关卡决策

结果	操作
全部 PASS	进入阶段 4（质量评审）
任意 FAIL	将具体失败详情反馈给实施者

停止——如果任何规范评审标准未通过，就不要继续进行质量评审。

---

阶段 4：质量评审关卡

目标： 独立于规范合规性，验证代码是否符合质量标准。

1. 使用 code-quality-reviewer-prompt.md 模板准备质量评审者提示词
2. 提供实现代码、测试代码和项目质量标准
3. 调用质量评审子 Agent
4. 收集评审结果

调用机制： 使用 Agent 工具，并在 prompt 参数中传入质量评审者提示词（来自 code-quality-reviewer-prompt.md）。

质量评审范围

领域	检查内容
代码质量	可读性、命名、结构、复杂度
模式合规性	是否遵循项目模式和约定
安全性	是否存在注入漏洞、是否进行了适当验证、默认设置是否安全
性能	是否存在不必要的内存分配、算法是否高效、是否存在 N+1 查询
错误处理	是否处理了所有错误路径、错误消息是否有意义
测试质量	测试是否有意义，是否避免测试实现细节

问题严重程度分类

严重程度	定义	所需操作
严重	安全漏洞、数据丢失风险、行为不正确	接受前必须修复
重要	性能问题、可维护性问题、缺少错误处理	应当修复（上报用户决定）
建议	风格改进、替代方案、文档	可由开发者酌情修复

关卡决策

结果	操作
没有严重或重要问题	通过——继续验收
存在任何严重问题	未通过——必须修复并重新评审
仅存在重要问题	有条件通过——上报用户决定

---

阶段 5：修复和重新评审循环

目标： 在有限重试次数内，迭代修复评审未通过的问题。

修复循环流程

1. Collect all failure details from the failing review gate
2. Send failures back to implementer subagent with specific instructions
3. Implementer fixes the specific issues (not a full rewrite)
4. Re-run ONLY the failing review gate
5. If still failing: repeat (max 3 cycles)
6. After 3 failed cycles: escalate to user

重试决策表

尝试次数	规范审查	质量审查	操作
1	FAIL	—	将问题详情反馈给实施者
2	FAIL	—	反馈问题并补充背景信息／示例
3	FAIL	—	升级给用户
1	PASS	FAIL	将质量问题反馈给实施者
2	PASS	FAIL	提供项目模式作为参考并反馈问题
3	PASS	FAIL	升级给用户

升级报告格式

ESCALATION: REPEATED REVIEW FAILURE
====================================
Task: [task description]
Review Gate: [spec / quality]
Attempts: 3

Failure Pattern:
  Attempt 1: [what failed and why]
  Attempt 2: [what failed and why]
  Attempt 3: [what failed and why]

Root Cause Assessment: [why the implementer cannot resolve this]

Options:
  A. Simplify the task specification
  B. Provide additional context/examples
  C. Break into smaller sub-tasks
  D. Implement manually (skip subagent)

Awaiting direction.

---

阶段 6：验收与集成

目标： 两道审核关卡均通过后，集成工作成果并确认没有引入回归问题。

1. 运行完整的项目测试套件（不只是新测试）
2. 运行所有验证命令（lint、类型检查、构建）
3. 确认没有引入回归问题
4. 将任务标记为已完成
5. 开始下一个任务或报告完成情况

多任务编排

1. Identify independent tasks (no dependencies on each other)
2. For each independent task: run Phases 2-6
3. After all independent tasks complete:
   a. Run full test suite
   b. Run all verification commands
   c. Checkpoint review
4. Identify next set of tasks (now that dependencies are met)
5. Repeat until all tasks complete

---

反模式／常见错误

反模式	失败原因	正确做法
未提供完整的任务规范便进行派发	实施者会做出错误假设	先填写全部 7 个规范章节
跳过规范审查（“代码看起来没问题”）	规范偏差会不断累积	始终执行两道审核关卡
明知存在严重问题仍予以接受	安全性／正确性受到影响	必须修复所有严重问题
让实施者审查自己的代码	存在偏见和盲点	让不同的 Agent 分别负责实施和审查
并行派发存在依赖关系的任务	会产生竞态条件和集成失败	仅并行处理互不依赖的任务
忽略实施者提出的问题	错误假设会被写入代码	继续之前先处理所有问题
不升级处理，连续修复超过 3 轮	收益递减，错误不断重现	请用户指示后续方向
验收后跳过验证	回归问题会被忽略	始终运行完整的验证流程
验收标准含糊不清	审查者无法客观评估	只使用具体、可测试的标准
未列出约束条件	实施者可能会修改不应修改的文件	在每份规范中明确列出“禁止事项”

---

防止自我合理化

不要跳过任何一道审核关卡。不要接受存在严重问题的实现。不要在未提供完整规范的情况下派发任务。两道审核关卡都必须通过，任务才能标记为已完成。

如果你发现自己在想：

• “这个实现看起来已经够好了……”——执行两道审核关卡，一次也不能少。
• “规范审查只是走个形式……”——规范偏差会导致集成失败，务必执行审查。
• “重试三次太多了，还是直接接受吧……”——失败 3 次就升级处理，不要降低标准。

---

集成点

技能	关系	时机
planning	上游——提供已批准的计划和任务	任务来源
executing-plans	上游——可能会委派任务给此技能	处理计划中的独立任务
test-driven-development	每个任务——实施者遵循 TDD	阶段 2 实施
verification-before-completion	验收后——最终验证	阶段 6 集成
code-review	互补——质量审查关卡	阶段 4 质量审查
dispatching-parallel-agents	互补——并行化策略	派发独立任务时
resilient-execution	失败时——重试策略	修复轮次耗尽时
task-management	跟踪——任务状态管理	进度跟踪
Agent 工具	所有子 Agent 阶段的派发机制

---

具体示例

示例：子 Agent 任务规范

TASK SPECIFICATION
==================
1. Description: Implement user registration endpoint with email validation

2. Files:
   - Create: src/routes/auth/register.ts
   - Create: tests/routes/auth/register.test.ts
   - Modify: src/routes/index.ts (add route import)

3. Acceptance Criteria:
   - POST /api/auth/register accepts { email, password, name }
   - Returns 201 with user object (no password) on success
   - Returns 400 if email format is invalid
   - Returns 409 if email already exists
   - Password is hashed before storage

4. TDD Requirements:
   - Test: valid registration returns 201
   - Test: invalid email returns 400
   - Test: duplicate email returns 409
   - Test: password is not in response body
   - Test: password is hashed in database

5. Quality Standards:
   - Follow route pattern in src/routes/auth/login.ts
   - Use Zod for input validation (existing pattern)
   - Use Result<T, E> type for service errors

6. Context:
   - Auth service: src/services/auth.ts (has hashPassword method)
   - Route pattern: see src/routes/auth/login.ts
   - Zod schemas: see src/schemas/auth.ts

7. Constraints:
   - Do NOT modify auth service
   - Do NOT add new dependencies
   - Do NOT create migration files

---

提示词模板

此技能使用三个提示词模板：

模板	用途	文件
实施者提示词	分派实施工作	implementer-prompt.md
规范审查者提示词	根据任务规范进行审查	spec-reviewer-prompt.md
质量审查者提示词	审查代码质量	code-quality-reviewer-prompt.md

每个模板都为子 Agent 交互提供了结构化格式。详情请参阅各个文件。

---

技能类型

RIGID — 必须严格遵循此流程。所有 7 个规范章节均为必填项。两道审查关卡均为必需项。3 次重试的升级限制为强制要求。不得走捷径。