subagent-driven-development
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSubagent-Driven Development
子Agent驱动开发
Overview
概述
This skill orchestrates implementation through dedicated subagents with built-in quality gates. Each task is implemented by an implementer subagent, then reviewed by two specialized reviewer agents (spec compliance and code quality) before acceptance. Failed reviews trigger iterative fix cycles with a maximum of 3 retries before escalation. This ensures consistent quality at scale while maximizing parallel throughput.
Announce at start: "I'm using the subagent-driven-development skill to dispatch implementation tasks with two-stage review gates."
该技能通过配备内置质量门的专属子Agent来编排实现流程。每个任务由实现子Agent完成开发，随后在验收前经过两个专业评审Agent（规范合规和代码质量）的审查。评审未通过会触发迭代修复周期，最多重试3次，仍失败则升级处理。该机制可在规模化场景下保障质量一致性，同时最大化并行吞吐量。
启动时声明： "我正在使用子Agent驱动开发技能来派发实现任务，并配备两阶段评审门。"
Trigger Conditions
触发条件
- Plan has 3+ tasks that can be implemented independently
- Tasks have well-specified acceptance criteria suitable for delegation
- Speed of execution is a priority
- Tasks have few interdependencies
- Quality gates are needed for delegated work
- 计划包含3个及以上可独立实现的任务
- 任务具备明确的、适合委托的验收标准
- 执行速度是优先级要求
- 任务间依赖极少
- 委托的工作需要设置质量门
Phase 1: Task Preparation
阶段1：任务准备
Goal: Ensure every task is fully specified before dispatching to any subagent.
目标： 确保每个任务在派发给任意子Agent前都已完成完整的规范定义。
Task Specification Requirements (7 Sections)
任务规范要求（7个模块）
Every task dispatched to a subagent MUST include ALL of these:
| Section | Content | Example |
|---|---|---|
| 1. Task description | Clear, unambiguous statement | "Implement JWT token generation with RS256 signing" |
| 2. Files to create/modify | Explicit list | |
| 3. Acceptance criteria | Specific, testable conditions | "Tokens expire after 1 hour", "Invalid keys throw AuthError" |
| 4. TDD requirements | Tests to write, behaviors to cover | "Test: valid token generation, expired token rejection, invalid key handling" |
| 5. Quality standards | Code style, patterns, conventions | "Follow existing service pattern in src/services/, use Result type for errors" |
| 6. Context | Relevant code, interfaces, deps | "Logger API: logger.info(msg, meta). Import from ../utils/logger" |
| 7. Constraints | What NOT to do | "Do NOT modify existing auth middleware. Do NOT add new dependencies." |
派发给子Agent的每个任务必须包含以下所有模块：
| 模块 | 内容 | 示例 |
|---|---|---|
| 1. 任务描述 | 清晰无歧义的说明 | "Implement JWT token generation with RS256 signing" |
| 2. 待创建/修改的文件 | 明确的列表 | |
| 3. 验收标准 | 可测试的具体条件 | "Tokens expire after 1 hour", "Invalid keys throw AuthError" |
| 4. TDD要求 | 需要编写的测试、需要覆盖的行为 | "Test: valid token generation, expired token rejection, invalid key handling" |
| 5. 质量标准 | 代码风格、模式、约定 | "Follow existing service pattern in src/services/, use Result type for errors" |
| 6. 上下文 | 相关代码、接口、依赖 | "Logger API: logger.info(msg, meta). Import from ../utils/logger" |
| 7. 约束 | 禁止执行的操作 | "Do NOT modify existing auth middleware. Do NOT add new dependencies." |
Pre-Dispatch Checklist
派发前检查清单
- Task spec has all 7 sections filled
- Task is independent (no unresolved dependencies on in-progress tasks)
- Acceptance criteria are specific and testable
- Files to modify are identified and accessible
- Relevant context has been gathered and included in the spec
- 任务规范已填写完整7个模块
- 任务是独立的（对正在进行的任务没有未解决的依赖）
- 验收标准具体且可测试
- 待修改的文件已识别且可访问
- 已收集相关上下文并包含在规范中
Task Independence Decision Table
任务独立性决策表
| Dependency Type | Can Dispatch? | Action |
|---|---|---|
| No dependencies | Yes | Dispatch immediately |
| Depends on completed task | Yes | Include completed task's output as context |
| Depends on in-progress task | No | Wait for dependency to complete |
| Shared file with another task | No | Serialize — one task at a time for that file |
| Shared interface only | Yes | Include interface definition as context |
STOP — Do NOT dispatch until:
- All 7 spec sections are complete
- Independence is verified
- Acceptance criteria are testable
| 依赖类型 | 是否可以派发？ | 操作 |
|---|---|---|
| 无依赖 | 是 | 立即派发 |
| 依赖已完成的任务 | 是 | 将已完成任务的输出作为上下文包含 |
| 依赖进行中的任务 | 否 | 等待依赖任务完成 |
| 和其他任务共享文件 | 否 | 串行执行——该文件同一时间只处理一个任务 |
| 仅共享接口 | 是 | 将接口定义作为上下文包含 |
停止——满足以下条件前请勿派发：
- 所有7个规范模块均已完成
- 独立性已验证
- 验收标准可测试
Phase 2: Implementation Dispatch
阶段2：实现任务派发
Goal: Send the task to an implementer subagent with full context.
- Prepare the implementer prompt using template
implementer-prompt.md - Include the full task specification (all 7 sections)
- Include relevant code context (existing files, interfaces, types)
- Dispatch the implementer subagent
- Collect the implementation output
Dispatch mechanism: Use thetool withAgentand include the implementer prompt (fromsubagent_type="general-purpose") in theimplementer-prompt.mdparameter. Setpromptto a short task label.description
目标： 将任务和完整上下文发送给实现子Agent。
- 使用模板准备实现者提示词
implementer-prompt.md - 包含完整的任务规范（全部7个模块）
- 包含相关代码上下文（现有文件、接口、类型）
- 派发实现子Agent
- 收集实现输出
派发机制： 使用工具，设置Agent，并将实现者提示词（来自subagent_type="general-purpose"）放入implementer-prompt.md参数中。将prompt设置为简短的任务标签。description
Implementer Expectations
实现子Agent要求
The implementer subagent MUST:
- Follow the TDD cycle (RED-GREEN-REFACTOR)
- Write tests before production code
- Only modify files listed in the task spec
- Follow the quality standards specified
- Report any questions or blockers encountered
- Document all assumptions made
实现子Agent必须：
- 遵循TDD周期（红-绿-重构）
- 在生产代码之前编写测试
- 仅修改任务规范中列出的文件
- 遵循指定的质量标准
- 上报遇到的所有问题或阻塞点
- 记录所有做出的假设
Question Handling Protocol
问题处理协议
| Question Type | During Implementation | Action |
|---|---|---|
| Non-blocking | Can proceed with reasonable assumption | Note assumption, continue, flag in output |
| Blocking | Cannot proceed without answer | STOP immediately, escalate to orchestrator |
| Scope question | Asks about work outside assigned task | Report it, do NOT fix it |
STOP — Do NOT proceed to review until:
- Implementer has returned complete output
- All listed files have been created/modified
- Tests exist for every acceptance criterion
- Any assumptions are documented
| 问题类型 | 实现阶段状态 | 操作 |
|---|---|---|
| 非阻塞 | 可基于合理假设继续推进 | 记录假设，继续推进，在输出中标记 |
| 阻塞 | 无答案无法继续推进 | 立即停止，升级给编排者 |
| 范围问题 | 询问分配任务之外的工作 | 上报该问题，不要自行处理 |
停止——满足以下条件前请勿进入评审阶段：
- 实现子Agent已返回完整输出
- 所有列出的文件均已创建/修改
- 每个验收标准都有对应的测试
- 所有假设都已记录
Phase 3: Spec Review Gate
阶段3：规范评审门
Goal: Verify the implementation matches the original task specification.
- Prepare the spec reviewer prompt using template
spec-reviewer-prompt.md - Provide the original task specification AND the implementer's output
- Dispatch the spec-reviewer subagent
- Collect the review result
Dispatch mechanism: Use thetool with the spec-reviewer prompt (fromAgent) in thespec-reviewer-prompt.mdparameter.prompt
目标： 验证实现是否符合原始任务规范。
- 使用模板准备规范评审者提示词
spec-reviewer-prompt.md - 提供原始任务规范和实现子Agent的输出
- 派发规范评审子Agent
- 收集评审结果
派发机制： 使用工具，将规范评审者提示词（来自Agent）放入spec-reviewer-prompt.md参数中。prompt
Spec Review Criteria
规范评审标准
| Criterion | Assessment | What to Check |
|---|---|---|
| All acceptance criteria met | PASS / FAIL per criterion | Each criterion individually verified |
| Tests cover specified behaviors | PASS / FAIL | Test file contains tests for all behaviors |
| Files modified match spec | PASS / FAIL | No unauthorized file modifications |
| No out-of-scope changes | PASS / FAIL | Only listed files touched |
| Implementation matches intent | PASS / FAIL | Behavior is correct, not just syntactically valid |
| All constraints respected | PASS / FAIL | None of the "do NOT" items violated |
| 标准 | 评估结果 | 检查项 |
|---|---|---|
| 所有验收标准均满足 | 每个标准分别标注通过/不通过 | 逐一验证每个验收标准 |
| 测试覆盖指定行为 | 通过/不通过 | 测试文件包含所有行为的测试用例 |
| 修改的文件符合规范 | 通过/不通过 | 无未授权的文件修改 |
| 无超出范围的变更 | 通过/不通过 | 仅修改了列出的文件 |
| 实现符合预期意图 | 通过/不通过 | 行为正确，而非仅语法有效 |
| 所有约束均被遵守 | 通过/不通过 | 没有违反任何“禁止”项 |
Gate Decision
评审门决策
| Result | Action |
|---|---|
| All PASS | Proceed to Phase 4 (quality review) |
| Any FAIL | Return to implementer with specific failure details |
STOP — Do NOT proceed to quality review if any spec criterion fails.
| 结果 | 操作 |
|---|---|
| 全部通过 | 进入阶段4（质量评审） |
| 任何项不通过 | 将具体的失败详情返回给实现子Agent |
停止——如果任何规范标准不通过，请勿进入质量评审阶段。
Phase 4: Quality Review Gate
阶段4：质量评审门
Goal: Verify code meets quality standards independent of spec compliance.
- Prepare the quality reviewer prompt using template
code-quality-reviewer-prompt.md - Provide the implementation code, test code, and project quality standards
- Dispatch the quality-reviewer subagent
- Collect the review result
Dispatch mechanism: Use thetool with the quality-reviewer prompt (fromAgent) in thecode-quality-reviewer-prompt.mdparameter.prompt
目标： 独立于规范合规性，验证代码是否符合质量标准。
- 使用模板准备质量评审者提示词
code-quality-reviewer-prompt.md - 提供实现代码、测试代码和项目质量标准
- 派发质量评审子Agent
- 收集评审结果
派发机制： 使用工具，将质量评审者提示词（来自Agent）放入code-quality-reviewer-prompt.md参数中。prompt
Quality Review Areas
质量评审维度
| Area | What to Check |
|---|---|
| Code quality | Readability, naming, structure, complexity |
| Pattern compliance | Follows project patterns and conventions |
| Security | No injection vulnerabilities, proper validation, safe defaults |
| Performance | No unnecessary allocations, efficient algorithms, no N+1 queries |
| Error handling | All error paths handled, meaningful error messages |
| Test quality | Tests are meaningful, not testing implementation details |
| 维度 | 检查项 |
|---|---|
| 代码质量 | 可读性、命名、结构、复杂度 |
| 模式合规性 | 遵循项目模式和约定 |
| 安全性 | 无注入漏洞、验证合规、默认配置安全 |
| 性能 | 无不必要的内存分配、算法高效、无N+1查询 |
| 错误处理 | 所有错误路径都被处理、错误消息有意义 |
| 测试质量 | 测试有实际意义，不测试实现细节 |
Issue Severity Classification
问题严重程度分类
| Severity | Definition | Action Required |
|---|---|---|
| Critical | Security vulnerability, data loss risk, incorrect behavior | MUST fix before acceptance |
| Important | Performance issue, maintainability concern, missing error handling | SHOULD fix (escalate to user for decision) |
| Suggestion | Style improvement, alternative approach, documentation | MAY fix, at developer's discretion |
| 严重程度 | 定义 | 所需操作 |
|---|---|---|
| 严重 | 安全漏洞、数据丢失风险、行为错误 | 验收前必须修复 |
| 重要 | 性能问题、可维护性隐患、缺少错误处理 | 应该修复（升级给用户决策） |
| 建议 | 风格改进、替代实现方案、文档优化 | 可以修复，由开发者自行决定 |
Gate Decision
评审门决策
| Result | Action |
|---|---|
| No Critical or Important issues | PASS — proceed to acceptance |
| Any Critical issues | FAIL — must fix and re-review |
| Only Important issues | Conditional — escalate to user for decision |
| 结果 | 操作 |
|---|---|
| 无严重或重要问题 | 通过——进入验收阶段 |
| 存在任何严重问题 | 不通过——必须修复后重新评审 |
| 仅存在重要问题 | 有条件通过——升级给用户决策 |
Phase 5: Fix and Re-Review Cycle
阶段5：修复和重评审周期
Goal: Iteratively fix review failures with a bounded retry limit.
目标： 在有限的重试次数内迭代修复评审失败项。
Fix Cycle Process
修复周期流程
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 user1. 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 userRetry Decision Table
重试决策表
| Attempt | Spec Review | Quality Review | Action |
|---|---|---|---|
| 1 | FAIL | — | Return to implementer with failure details |
| 2 | FAIL | — | Return with additional context/examples |
| 3 | FAIL | — | Escalate to user |
| 1 | PASS | FAIL | Return to implementer with quality issues |
| 2 | PASS | FAIL | Return with project patterns as reference |
| 3 | PASS | FAIL | Escalate to user |
| 尝试次数 | 规范评审 | 质量评审 | 操作 |
|---|---|---|---|
| 1 | 不通过 | — | 将失败详情返回给实现子Agent |
| 2 | 不通过 | — | 补充上下文/示例后返回 |
| 3 | 不通过 | — | 升级给用户 |
| 1 | 通过 | 不通过 | 将质量问题返回给实现子Agent |
| 2 | 通过 | 不通过 | 提供项目模式作为参考后返回 |
| 3 | 通过 | 不通过 | 升级给用户 |
Escalation Report Format
升级报告格式
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.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.Phase 6: Acceptance and Integration
阶段6：验收和集成
Goal: After both gates pass, integrate the work and verify no regressions.
- Run the full project test suite (not just the new tests)
- Run all verification commands (lint, type-check, build)
- Confirm no regressions were introduced
- Mark the task as complete
- Proceed to next task or report completion
目标： 两个评审门都通过后，集成工作并验证无回归问题。
- 运行完整的项目测试套件（不只是新测试）
- 运行所有验证命令（lint、类型检查、构建）
- 确认没有引入回归问题
- 标记任务为已完成
- 推进到下一个任务或上报完成
Multi-Task Orchestration
多任务编排
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 complete1. 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 completeAnti-Patterns / Common Mistakes
反模式/常见错误
| Anti-Pattern | Why It Fails | Correct Approach |
|---|---|---|
| Dispatching without complete task spec | Implementer makes wrong assumptions | Fill out all 7 spec sections first |
| Skipping spec review ("code looks right") | Spec deviations accumulate | Always run both review gates |
| Accepting despite Critical issues | Security/correctness compromised | Critical issues must be fixed |
| Letting implementer review its own code | Bias, blind spots | Separate agents for implementation and review |
| Dispatching dependent tasks in parallel | Race conditions, integration failures | Only parallelize independent tasks |
| Ignoring questions from implementer | Wrong assumptions baked into code | Address all questions before proceeding |
| More than 3 fix cycles without escalating | Diminishing returns, same mistakes | Escalate to user for direction |
| Skipping verification after acceptance | Regressions go unnoticed | Always run full verification |
| Vague acceptance criteria | Reviewer cannot assess objectively | Specific, testable criteria only |
| Not including constraints | Implementer touches files it should not | Explicit "do NOT" list in every spec |
| 反模式 | 失败原因 | 正确做法 |
|---|---|---|
| 未完成任务规范就派发 | 实现者做出错误假设 | 先填写完整7个规范模块 |
| 跳过规范评审（“代码看起来没问题”） | 规范偏差累积 | 始终运行两个评审门 |
| 存在严重问题仍验收 | 安全性/正确性受损 | 严重问题必须修复 |
| 让实现者评审自己的代码 | 存在偏见、盲点 | 实现和评审使用不同的Agent |
| 并行派发有依赖的任务 | 竞态条件、集成失败 | 仅并行派发独立任务 |
| 忽略实现者的问题 | 错误假设被固化到代码中 | 推进前解决所有问题 |
| 超过3次修复周期仍不升级 | 收益递减、重复犯相同错误 | 升级给用户获取指示 |
| 验收后跳过验证 | 回归问题未被发现 | 始终运行完整验证 |
| 验收标准模糊 | 评审者无法客观评估 | 仅使用具体、可测试的标准 |
| 不包含约束 | 实现者修改了不应触碰的文件 | 每个规范中明确列出“禁止”项 |
Anti-Rationalization Guards
反合理化防护
<HARD-GATE>
Do NOT skip either review gate. Do NOT accept implementations with Critical issues. Do NOT dispatch tasks without complete specifications. Both review gates must PASS before any task is marked complete.
</HARD-GATE>
If you catch yourself thinking:
- "The implementation looks good enough..." — Run both review gates. Always.
- "The spec review is just a formality..." — Spec deviations cause integration failures. Run it.
- "Three retries is too many, just accept it..." — If it fails 3 times, escalate. Do not lower the bar.
<HARD-GATE>
请勿跳过任何一个评审门。请勿接受存在严重问题的实现。请勿派发规范不完整的任务。任何任务标记为完成前，两个评审门都必须通过。
</HARD-GATE>
如果你发现自己有以下想法：
- “这个实现看起来已经够好了…” —— 始终运行两个评审门。
- “规范评审只是走个流程…” —— 规范偏差会导致集成失败。必须运行。
- “三次重试太多了，直接接受吧…” —— 如果失败3次，升级处理。不要降低标准。
Integration Points
集成点
| Skill | Relationship | When |
|---|---|---|
| Upstream — provides approved plan with tasks | Task source |
| Upstream — may delegate to this skill | For independent tasks in plan |
| Per-task — implementer follows TDD | Phase 2 implementation |
| Post-acceptance — final verification | Phase 6 integration |
| Complementary — quality review gate | Phase 4 quality review |
| Complementary — parallelization strategy | When dispatching independent tasks |
| On failure — retry strategies | When fix cycles exhaust |
| Tracking — task status management | Progress tracking |
| Dispatch mechanism for all subagent phases |
| 技能 | 关系 | 触发时机 |
|---|---|---|
| 上游——提供已批准的任务计划 | 任务来源 |
| 上游——可委托给该技能 | 处理计划中的独立任务时 |
| 单任务级——实现者遵循TDD | 阶段2实现阶段 |
| 验收后——最终验证 | 阶段6集成阶段 |
| 互补——质量评审门 | 阶段4质量评审 |
| 互补——并行策略 | 派发独立任务时 |
| 失败时——重试策略 | 修复周期耗尽时 |
| 跟踪——任务状态管理 | 进度跟踪 |
| 所有子Agent阶段的派发机制 |
Concrete Examples
具体示例
Example: Task Spec for Subagent
示例：子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 filesTASK 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 filesPrompt Templates
提示词模板
This skill uses three prompt templates:
| Template | Purpose | File |
|---|---|---|
| Implementer Prompt | Dispatches implementation work | |
| Spec Reviewer Prompt | Reviews against task specification | |
| Quality Reviewer Prompt | Reviews code quality | |
Each template provides a structured format for the subagent interaction. See the individual files for details.
该技能使用三个提示词模板：
| 模板 | 用途 | 文件 |
|---|---|---|
| 实现者提示词 | 派发实现工作 | |
| 规范评审者提示词 | 对照任务规范评审 | |
| 质量评审者提示词 | 评审代码质量 | |
每个模板都提供了子Agent交互的结构化格式。详情请查看对应文件。
Skill Type
技能类型
RIGID — Follow this process exactly. All 7 spec sections are mandatory. Both review gates are mandatory. The 3-retry escalation limit is mandatory. No shortcuts.
刚性 —— 严格遵循该流程。所有7个规范模块都是必填项。两个评审门都是必填项。3次重试升级限制是必填项。不允许走捷径。