Back to Details

subagent-driven-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Subagent-Driven Development

Subagent-Driven Development

Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
Core principle: Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
通过为每个任务分配全新的Subagent来执行计划，每个任务完成后进行两阶段评审：首先是合规性评审，然后是代码质量评审。
核心原则： 为每个任务分配全新Subagent + 两阶段评审（先合规性后质量）= 高质量、快速迭代

When to Use

适用场景

dot
digraph when_to_use {
    "Have implementation plan?" [shape=diamond];
    "Tasks mostly independent?" [shape=diamond];
    "Stay in this session?" [shape=diamond];
    "subagent-driven-development" [shape=box];
    "executing-plans" [shape=box];
    "Manual execution or brainstorm first" [shape=box];

    "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
    "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
    "Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
    "Stay in this session?" -> "subagent-driven-development" [label="yes"];
    "Stay in this session?" -> "executing-plans" [label="no - parallel session"];
}
vs. Executing Plans (parallel session):
  • Same session (no context switch)
  • Fresh subagent per task (no context pollution)
  • Two-stage review after each task: spec compliance first, then code quality
  • Faster iteration (no human-in-loop between tasks)
dot
digraph when_to_use {
    "Have implementation plan?" [shape=diamond];
    "Tasks mostly independent?" [shape=diamond];
    "Stay in this session?" [shape=diamond];
    "subagent-driven-development" [shape=box];
    "executing-plans" [shape=box];
    "Manual execution or brainstorm first" [shape=box];

    "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
    "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
    "Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
    "Stay in this session?" -> "subagent-driven-development" [label="yes"];
    "Stay in this session?" -> "executing-plans" [label="no - parallel session"];
}
与Executing Plans（并行会话）的对比：
  • 同一会话（无上下文切换）
  • 为每个任务分配全新Subagent（无上下文污染）
  • 每个任务完成后进行两阶段评审：先合规性，后代码质量
  • 迭代速度更快（任务间无需人工介入）

The Process

执行流程

dot
digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="Per Task";
        "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
        "Implementer subagent asks questions?" [shape=diamond];
        "Answer questions, provide context" [shape=box];
        "Implementer subagent implements, tests, commits, self-reviews" [shape=box];
        "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [shape=box];
        "Spec reviewer subagent confirms code matches spec?" [shape=diamond];
        "Implementer subagent fixes spec gaps" [shape=box];
        "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];
        "Code quality reviewer subagent approves?" [shape=diamond];
        "Implementer subagent fixes quality issues" [shape=box];
        "Mark task complete in TodoWrite" [shape=box];
    }

    "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
    "More tasks remain?" [shape=diamond];
    "Dispatch final code reviewer subagent for entire implementation" [shape=box];
    "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)";
    "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
    "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
    "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
    "Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
    "Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";
    "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
    "Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
    "Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="re-review"];
    "Spec reviewer subagent confirms code matches spec?" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="yes"];
    "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
    "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
    "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
    "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
    "Mark task complete in TodoWrite" -> "More tasks remain?";
    "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
    "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
    "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch";
}
dot
digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="Per Task";
        "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
        "Implementer subagent asks questions?" [shape=diamond];
        "Answer questions, provide context" [shape=box];
        "Implementer subagent implements, tests, commits, self-reviews" [shape=box];
        "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [shape=box];
        "Spec reviewer subagent confirms code matches spec?" [shape=diamond];
        "Implementer subagent fixes spec gaps" [shape=box];
        "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];
        "Code quality reviewer subagent approves?" [shape=diamond];
        "Implementer subagent fixes quality issues" [shape=box];
        "Mark task complete in TodoWrite" [shape=box];
    }

    "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
    "More tasks remain?" [shape=diamond];
    "Dispatch final code reviewer subagent for entire implementation" [shape=box];
    "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)";
    "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
    "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
    "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
    "Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
    "Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";
    "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
    "Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
    "Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="re-review"];
    "Spec reviewer subagent confirms code matches spec?" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="yes"];
    "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
    "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
    "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
    "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
    "Mark task complete in TodoWrite" -> "More tasks remain?";
    "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
    "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
    "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch";
}

Prompt Templates

提示词模板

  • ./implementer-prompt.md
    - Dispatch implementer subagent
  • ./spec-reviewer-prompt.md
    - Dispatch spec compliance reviewer subagent
  • ./code-quality-reviewer-prompt.md
    - Dispatch code quality reviewer subagent
  • ./implementer-prompt.md
    - 分配实现Subagent
  • ./spec-reviewer-prompt.md
    - 分配合规性评审Subagent
  • ./code-quality-reviewer-prompt.md
    - 分配代码质量评审Subagent

Example Workflow

工作流示例

You: I'm using Subagent-Driven Development to execute this plan.

[Read plan file once: docs/plans/feature-plan.md]
[Extract all 5 tasks with full text and context]
[Create TodoWrite with all tasks]

Task 1: Hook installation script

[Get Task 1 text and context (already extracted)]
[Dispatch implementation subagent with full task text + context]

Implementer: "Before I begin - should the hook be installed at user or system level?"

You: "User level (~/.config/superpowers/hooks/)"

Implementer: "Got it. Implementing now..."
[Later] Implementer:
  - Implemented install-hook command
  - Added tests, 5/5 passing
  - Self-review: Found I missed --force flag, added it
  - Committed

[Dispatch spec compliance reviewer]
Spec reviewer: ✅ Spec compliant - all requirements met, nothing extra

[Get git SHAs, dispatch code quality reviewer]
Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.

[Mark Task 1 complete]

Task 2: Recovery modes

[Get Task 2 text and context (already extracted)]
[Dispatch implementation subagent with full task text + context]

Implementer: [No questions, proceeds]
Implementer:
  - Added verify/repair modes
  - 8/8 tests passing
  - Self-review: All good
  - Committed

[Dispatch spec compliance reviewer]
Spec reviewer: ❌ Issues:
  - Missing: Progress reporting (spec says "report every 100 items")
  - Extra: Added --json flag (not requested)

[Implementer fixes issues]
Implementer: Removed --json flag, added progress reporting

[Spec reviewer reviews again]
Spec reviewer: ✅ Spec compliant now

[Dispatch code quality reviewer]
Code reviewer: Strengths: Solid. Issues (Important): Magic number (100)

[Implementer fixes]
Implementer: Extracted PROGRESS_INTERVAL constant

[Code reviewer reviews again]
Code reviewer: ✅ Approved

[Mark Task 2 complete]

...

[After all tasks]
[Dispatch final code-reviewer]
Final reviewer: All requirements met, ready to merge

Done!
你：我正在使用Subagent-Driven Development来执行这个计划。

[读取计划文件一次：docs/plans/feature-plan.md]
[提取所有5个任务的完整文本和上下文]
[创建包含所有任务的TodoWrite]

任务1：钩子安装脚本

[获取已提取的任务1文本和上下文]
[为实现Subagent分配完整任务文本 + 上下文]

实现者：“开始之前 - 钩子应该安装在用户级别还是系统级别？”

你：“用户级别（~/.config/superpowers/hooks/）”

实现者：“明白了。现在开始实现...”
[稍后] 实现者：
  - 完成了install-hook命令的实现
  - 添加了测试，5/5通过
  - 自评审：发现遗漏了--force参数，已添加
  - 提交代码

[分配合规性评审Subagent]
合规性评审者：✅ 符合规范 - 满足所有需求，无额外内容

[获取git SHA，分配代码质量评审Subagent]
代码质量评审者：优势：测试覆盖率良好，代码整洁。问题：无。已批准。

[标记任务1完成]

任务2：恢复模式

[获取已提取的任务2文本和上下文]
[为实现Subagent分配完整任务文本 + 上下文]

实现者：[无问题，直接推进]
实现者：
  - 添加了验证/修复模式
  - 8/8测试通过
  - 自评审：一切正常
  - 提交代码

[分配合规性评审Subagent]
合规性评审者：❌ 问题：
  - 遗漏：进度报告（规范要求“每100个项目报告一次”）
  - 额外：添加了--json参数（未被要求）

[实现者修复问题]
实现者：移除了--json参数，添加了进度报告

[合规性评审者再次评审]
合规性评审者：✅ 现在符合规范

[分配代码质量评审Subagent]
代码质量评审者：优势：基础扎实。问题（重要）：魔法数字（100）

[实现者修复]
实现者：提取为PROGRESS_INTERVAL常量

[代码质量评审者再次评审]
代码质量评审者：✅ 已批准

[标记任务2完成]

...

[所有任务完成后]
[分配最终代码评审者]
最终评审者：所有需求均已满足，可合并

完成！

Advantages

优势

vs. Manual execution:
  • Subagents follow TDD naturally
  • Fresh context per task (no confusion)
  • Parallel-safe (subagents don't interfere)
  • Subagent can ask questions (before AND during work)
vs. Executing Plans:
  • Same session (no handoff)
  • Continuous progress (no waiting)
  • Review checkpoints automatic
Efficiency gains:
  • No file reading overhead (controller provides full text)
  • Controller curates exactly what context is needed
  • Subagent gets complete information upfront
  • Questions surfaced before work begins (not after)
Quality gates:
  • Self-review catches issues before handoff
  • Two-stage review: spec compliance, then code quality
  • Review loops ensure fixes actually work
  • Spec compliance prevents over/under-building
  • Code quality ensures implementation is well-built
Cost:
  • More subagent invocations (implementer + 2 reviewers per task)
  • Controller does more prep work (extracting all tasks upfront)
  • Review loops add iterations
  • But catches issues early (cheaper than debugging later)
与手动执行对比：
  • Subagent自然遵循TDD（测试驱动开发）流程
  • 每个任务拥有全新上下文（无混淆）
  • 支持并行安全（Subagent之间互不干扰）
  • Subagent可以提出问题（工作前和工作中均可）
与Executing Plans对比：
  • 同一会话（无需交接）
  • 持续推进（无需等待）
  • 评审检查点自动化
效率提升：
  • 无文件读取开销（控制器提供完整文本）
  • 控制器精准筛选所需上下文
  • Subagent预先获取完整信息
  • 问题在工作开始前就被提出（而非之后）
质量保障：
  • 自评审在交接前发现问题
  • 两阶段评审：合规性，然后代码质量
  • 评审循环确保问题真正被修复
  • 合规性评审避免过度开发或开发不足
  • 代码质量评审确保实现构建精良
成本说明：
  • 更多Subagent调用（每个任务需要实现者 + 2个评审者）
  • 控制器需要更多准备工作（提前提取所有任务）
  • 评审循环增加迭代次数
  • 但能尽早发现问题（比后期调试成本更低）

Red Flags

注意事项

Never:
  • Start implementation on main/master branch without explicit user consent
  • Skip reviews (spec compliance OR code quality)
  • Proceed with unfixed issues
  • Dispatch multiple implementation subagents in parallel (conflicts)
  • Make subagent read plan file (provide full text instead)
  • Skip scene-setting context (subagent needs to understand where task fits)
  • Ignore subagent questions (answer before letting them proceed)
  • Accept "close enough" on spec compliance (spec reviewer found issues = not done)
  • Skip review loops (reviewer found issues = implementer fixes = review again)
  • Let implementer self-review replace actual review (both are needed)
  • Start code quality review before spec compliance is ✅ (wrong order)
  • Move to next task while either review has open issues
If subagent asks questions:
  • Answer clearly and completely
  • Provide additional context if needed
  • Don't rush them into implementation
If reviewer finds issues:
  • Implementer (same subagent) fixes them
  • Reviewer reviews again
  • Repeat until approved
  • Don't skip the re-review
If subagent fails task:
  • Dispatch fix subagent with specific instructions
  • Don't try to fix manually (context pollution)
绝对禁止：
  • 在未获得用户明确同意的情况下，在main/master分支上开始实现
  • 跳过评审（合规性或代码质量评审）
  • 带着未修复的问题继续推进
  • 并行分配多个实现Subagent（会产生冲突）
  • 让Subagent读取计划文件（应直接提供完整文本）
  • 跳过场景设置上下文（Subagent需要了解任务的定位）
  • 忽略Subagent的问题（在让其继续前先回答）
  • 在合规性评审未通过时接受“差不多”的结果（评审发现问题即未完成）
  • 跳过评审循环（评审发现问题 = 实现者修复 = 再次评审）
  • 用实现者的自评审替代正式评审（两者都需要）
  • 在合规性评审未通过✅前就开始代码质量评审（顺序错误）
  • 在任一评审存在未解决问题时就进入下一个任务
如果Subagent提出问题：
  • 清晰、完整地回答
  • 必要时提供额外上下文
  • 不要催促其开始实现
如果评审发现问题：
  • 由（同一个）实现Subagent修复问题
  • 评审者再次评审
  • 重复直到通过
  • 不要跳过重新评审步骤
如果Subagent任务失败：
  • 分配修复Subagent并提供具体指令
  • 不要尝试手动修复（会造成上下文污染）

Integration

集成说明

Required workflow skills:
  • superpowers:using-git-worktrees - REQUIRED: Set up isolated workspace before starting
  • superpowers:writing-plans - Creates the plan this skill executes
  • superpowers:requesting-code-review - Code review template for reviewer subagents
  • superpowers:finishing-a-development-branch - Complete development after all tasks
Subagents should use:
  • superpowers:test-driven-development - Subagents follow TDD for each task
Alternative workflow:
  • superpowers:executing-plans - Use for parallel session instead of same-session execution
所需工作流技能：
  • superpowers:using-git-worktrees - 必需：开始前设置独立工作区
  • superpowers:writing-plans - 生成本技能执行的计划
  • superpowers:requesting-code-review - 为评审Subagent提供代码评审模板
  • superpowers:finishing-a-development-branch - 所有任务完成后结束开发
Subagent应使用：
  • superpowers:test-driven-development - Subagent为每个任务遵循TDD流程
替代工作流：
  • superpowers:executing-plans - 用于并行会话而非同一会话执行