subagent-driven-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

子智能体驱动开发

Subagent-Driven Development

通过为每个任务分派一个全新的子智能体来执行计划，每个任务完成后进行两阶段审查：先审查规格合规性，再审查代码质量。

为什么用子智能体： 你将任务委派给具有隔离上下文的专用智能体。通过精心设计它们的指令和上下文，确保它们专注并成功完成任务。它们不应继承你的会话上下文或历史记录——你要精确构造它们所需的一切。这样也能为你自己保留用于协调工作的上下文。

核心原则： 每个任务一个全新子智能体 + 两阶段审查（先规格后质量）= 高质量、快速迭代

Execute plans by assigning a brand-new subagent to each task, followed by a two-stage review after each task completion: first review specification compliance, then review code quality.

Why Use Subagents: You delegate tasks to specialized agents with isolated contexts. By carefully designing their instructions and context, you ensure they stay focused and successfully complete the task. They should not inherit your session context or history—you precisely construct everything they need. This also preserves your own context for coordinating work.

Core Principles: One new subagent per task + two-stage review (spec first, then quality) = high-quality, fast iteration

何时使用

When to Use

dot

digraph when_to_use {
    "有实现计划?" [shape=diamond];
    "任务基本独立?" [shape=diamond];
    "留在当前会话?" [shape=diamond];
    "subagent-driven-development" [shape=box];
    "executing-plans" [shape=box];
    "手动执行或先头脑风暴" [shape=box];

    "有实现计划?" -> "任务基本独立?" [label="是"];
    "有实现计划?" -> "手动执行或先头脑风暴" [label="否"];
    "任务基本独立?" -> "留在当前会话?" [label="是"];
    "任务基本独立?" -> "手动执行或先头脑风暴" [label="否 - 紧密耦合"];
    "留在当前会话?" -> "subagent-driven-development" [label="是"];
    "留在当前会话?" -> "executing-plans" [label="否 - 并行会话"];
}

与 Executing Plans（并行会话）的对比：

同一会话（无上下文切换）
每个任务全新子智能体（无上下文污染）
每个任务后两阶段审查：先规格合规性，再代码质量
更快的迭代（任务间无需人工介入）

dot

digraph when_to_use {
    "有实现计划?" [shape=diamond];
    "任务基本独立?" [shape=diamond];
    "留在当前会话?" [shape=diamond];
    "subagent-driven-development" [shape=box];
    "executing-plans" [shape=box];
    "手动执行或先头脑风暴" [shape=box];

    "有实现计划?" -> "任务基本独立?" [label="是"];
    "有实现计划?" -> "手动执行或先头脑风暴" [label="否"];
    "任务基本独立?" -> "留在当前会话?" [label="是"];
    "任务基本独立?" -> "手动执行或先头脑风暴" [label="否 - 紧密耦合"];
    "留在当前会话?" -> "subagent-driven-development" [label="是"];
    "留在当前会话?" -> "executing-plans" [label="否 - 并行会话"];
}

Comparison with Executing Plans (Parallel Sessions):

Same session (no context switching)
New subagent per task (no context contamination)
Two-stage review after each task: first specification compliance, then code quality
Faster iteration (no manual intervention between tasks)

流程

Process

dot

digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="每个任务";
        "分派实现子智能体 (./implementer-prompt.md)" [shape=box];
        "实现子智能体有疑问?" [shape=diamond];
        "回答问题，提供上下文" [shape=box];
        "实现子智能体实现、测试、提交、自审" [shape=box];
        "分派规格审查子智能体 (./spec-reviewer-prompt.md)" [shape=box];
        "规格审查子智能体确认代码匹配规格?" [shape=diamond];
        "实现子智能体修复规格差距" [shape=box];
        "分派代码质量审查子智能体 (./code-quality-reviewer-prompt.md)" [shape=box];
        "代码质量审查子智能体通过?" [shape=diamond];
        "实现子智能体修复质量问题" [shape=box];
        "在 TodoWrite 中标记任务完成" [shape=box];
    }

    "读取计划，提取所有任务的完整文本，记录上下文，创建 TodoWrite" [shape=box];
    "还有剩余任务?" [shape=diamond];
    "分派最终代码审查子智能体审查整体实现" [shape=box];
    "使用 superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "读取计划，提取所有任务的完整文本，记录上下文，创建 TodoWrite" -> "分派实现子智能体 (./implementer-prompt.md)";
    "分派实现子智能体 (./implementer-prompt.md)" -> "实现子智能体有疑问?";
    "实现子智能体有疑问?" -> "回答问题，提供上下文" [label="是"];
    "回答问题，提供上下文" -> "分派实现子智能体 (./implementer-prompt.md)";
    "实现子智能体有疑问?" -> "实现子智能体实现、测试、提交、自审" [label="否"];
    "实现子智能体实现、测试、提交、自审" -> "分派规格审查子智能体 (./spec-reviewer-prompt.md)";
    "分派规格审查子智能体 (./spec-reviewer-prompt.md)" -> "规格审查子智能体确认代码匹配规格?";
    "规格审查子智能体确认代码匹配规格?" -> "实现子智能体修复规格差距" [label="否"];
    "实现子智能体修复规格差距" -> "分派规格审查子智能体 (./spec-reviewer-prompt.md)" [label="重新审查"];
    "规格审查子智能体确认代码匹配规格?" -> "分派代码质量审查子智能体 (./code-quality-reviewer-prompt.md)" [label="是"];
    "分派代码质量审查子智能体 (./code-quality-reviewer-prompt.md)" -> "代码质量审查子智能体通过?";
    "代码质量审查子智能体通过?" -> "实现子智能体修复质量问题" [label="否"];
    "实现子智能体修复质量问题" -> "分派代码质量审查子智能体 (./code-quality-reviewer-prompt.md)" [label="重新审查"];
    "代码质量审查子智能体通过?" -> "在 TodoWrite 中标记任务完成" [label="是"];
    "在 TodoWrite 中标记任务完成" -> "还有剩余任务?";
    "还有剩余任务?" -> "分派实现子智能体 (./implementer-prompt.md)" [label="是"];
    "还有剩余任务?" -> "分派最终代码审查子智能体审查整体实现" [label="否"];
    "分派最终代码审查子智能体审查整体实现" -> "使用 superpowers:finishing-a-development-branch";
}

dot

digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="每个任务";
        "Assign Implementation Subagent (./implementer-prompt.md)" [shape=box];
        "Does Implementation Subagent have questions?" [shape=diamond];
        "Answer questions, provide context" [shape=box];
        "Implementation Subagent implements, tests, commits, self-reviews" [shape=box];
        "Assign Specification Review Subagent (./spec-reviewer-prompt.md)" [shape=box];
        "Does Specification Review Subagent confirm code matches specs?" [shape=diamond];
        "Implementation Subagent fixes specification gaps" [shape=box];
        "Assign Code Quality Review Subagent (./code-quality-reviewer-prompt.md)" [shape=box];
        "Does Code Quality Review Subagent approve?" [shape=diamond];
        "Implementation Subagent fixes quality issues" [shape=box];
        "Mark task complete in TodoWrite" [shape=box];
    }

    "Read plan, extract full text of all tasks, record context, create TodoWrite" [shape=box];
    "Are there remaining tasks?" [shape=diamond];
    "Assign Final Code Review Subagent to review overall implementation" [shape=box];
    "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "Read plan, extract full text of all tasks, record context, create TodoWrite" -> "Assign Implementation Subagent (./implementer-prompt.md)";
    "Assign Implementation Subagent (./implementer-prompt.md)" -> "Does Implementation Subagent have questions?";
    "Does Implementation Subagent have questions?" -> "Answer questions, provide context" [label="Yes"];
    "Answer questions, provide context" -> "Assign Implementation Subagent (./implementer-prompt.md)";
    "Does Implementation Subagent have questions?" -> "Implementation Subagent implements, tests, commits, self-reviews" [label="No"];
    "Implementation Subagent implements, tests, commits, self-reviews" -> "Assign Specification Review Subagent (./spec-reviewer-prompt.md)";
    "Assign Specification Review Subagent (./spec-reviewer-prompt.md)" -> "Does Specification Review Subagent confirm code matches specs?";
    "Does Specification Review Subagent confirm code matches specs?" -> "Implementation Subagent fixes specification gaps" [label="No"];
    "Implementation Subagent fixes specification gaps" -> "Assign Specification Review Subagent (./spec-reviewer-prompt.md)" [label="Re-review"];
    "Does Specification Review Subagent confirm code matches specs?" -> "Assign Code Quality Review Subagent (./code-quality-reviewer-prompt.md)" [label="Yes"];
    "Assign Code Quality Review Subagent (./code-quality-reviewer-prompt.md)" -> "Does Code Quality Review Subagent approve?";
    "Does Code Quality Review Subagent approve?" -> "Implementation Subagent fixes quality issues" [label="No"];
    "Implementation Subagent fixes quality issues" -> "Assign Code Quality Review Subagent (./code-quality-reviewer-prompt.md)" [label="Re-review"];
    "Does Code Quality Review Subagent approve?" -> "Mark task complete in TodoWrite" [label="Yes"];
    "Mark task complete in TodoWrite" -> "Are there remaining tasks?";
    "Are there remaining tasks?" -> "Assign Implementation Subagent (./implementer-prompt.md)" [label="Yes"];
    "Are there remaining tasks?" -> "Assign Final Code Review Subagent to review overall implementation" [label="No"];
    "Assign Final Code Review Subagent to review overall implementation" -> "Use superpowers:finishing-a-development-branch";
}

模型选择

Model Selection

使用能胜任每个角色的最低成本模型，以节省开支并提高速度。

机械性实现任务（隔离的函数、清晰的规格、1-2 个文件）：使用快速、便宜的模型。当计划编写得足够详细时，大多数实现任务都是机械性的。

集成和判断类任务（多文件协调、模式匹配、调试）：使用标准模型。

架构、设计和审查类任务：使用最强的可用模型。

任务复杂度信号：

涉及 1-2 个文件且有完整规格 → 便宜模型
涉及多个文件且有集成考虑 → 标准模型
需要设计判断或广泛的代码库理解 → 最强模型

Use the lowest-cost model capable of handling each role to save costs and improve speed.

Mechanical Implementation Tasks (isolated functions, clear specs, 1-2 files): Use fast, cheap models. Most implementation tasks are mechanical when plans are written in sufficient detail.

Integration and Judgment Tasks (multi-file coordination, pattern matching, debugging): Use standard models.

Architecture, Design and Review Tasks: Use the strongest available model.

Task Complexity Signals:

Involves 1-2 files with complete specs → Cheap model
Involves multiple files with integration considerations → Standard model
Requires design judgment or extensive codebase understanding → Strongest model

处理实现者状态

Handling Implementer Status

实现子智能体报告四种状态之一。根据每种状态进行相应处理：

DONE： 进入规格合规性审查。

DONE_WITH_CONCERNS： 实现者完成了工作但标记了疑虑。在继续之前阅读这些疑虑。如果疑虑涉及正确性或范围，在审查前解决。如果只是观察性说明（如"这个文件越来越大了"），记录下来并继续审查。

NEEDS_CONTEXT： 实现者需要未提供的信息。提供缺失的上下文并重新分派。

BLOCKED： 实现者无法完成任务。评估阻塞原因：

如果是上下文问题，提供更多上下文并用同一模型重新分派
如果任务需要更强的推理能力，用更强的模型重新分派
如果任务太大，拆分为更小的部分
如果计划本身有问题，上报给人类

绝不忽略上报或在不做任何更改的情况下让同一模型重试。如果实现者说卡住了，说明有什么东西需要改变。

The Implementation Subagent reports one of four statuses. Handle each status accordingly:

DONE: Proceed to specification compliance review.

DONE_WITH_CONCERNS: The implementer completed the work but flagged concerns. Read these concerns before proceeding. If concerns relate to correctness or scope, resolve them before review. If they are just observational notes (e.g., "This file is getting large"), record them and proceed with review.

NEEDS_CONTEXT: The implementer needs information not provided. Supply the missing context and reassign.

BLOCKED: The implementer cannot complete the task. Evaluate the blocking reason:

If it's a context issue, provide more context and reassign with the same model
If the task requires stronger reasoning, reassign with a stronger model
If the task is too large, split it into smaller parts
If the plan itself has issues, escalate to a human

Never ignore escalations or retry with the same model without making changes. If the implementer says they're stuck, something needs to change.

提示词模板

Prompt Templates

```
./implementer-prompt.md
```
- 分派实现子智能体
```
./spec-reviewer-prompt.md
```
- 分派规格合规审查子智能体
```
./code-quality-reviewer-prompt.md
```
- 分派代码质量审查子智能体

```
./implementer-prompt.md
```
- Assign Implementation Subagent
```
./spec-reviewer-prompt.md
```
- Assign Specification Compliance Review Subagent
```
./code-quality-reviewer-prompt.md
```
- Assign Code Quality Review Subagent

示例工作流

Example Workflow

你：我正在使用子智能体驱动开发来执行这个计划。

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

任务 1：Hook 安装脚本

[获取任务 1 的文本和上下文（已提取）]
[分派实现子智能体，附带完整任务文本 + 上下文]

实现者："在我开始之前——hook 应该安装在用户级别还是系统级别？"

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

实现者："明白了。现在开始实现……"
[稍后] 实现者：
  - 实现了 install-hook 命令
  - 添加了测试，5/5 通过
  - 自审：发现遗漏了 --force 参数，已添加
  - 已提交

[分派规格合规审查]
规格审查者：✅ 符合规格 - 所有需求已满足，无多余内容

[获取 git SHA，分派代码质量审查]
代码审查者：优点：测试覆盖好，代码整洁。问题：无。通过。

[标记任务 1 完成]

任务 2：恢复模式

[获取任务 2 的文本和上下文（已提取）]
[分派实现子智能体，附带完整任务文本 + 上下文]

实现者：[无疑问，直接开始]
实现者：
  - 添加了 verify/repair 模式
  - 8/8 测试通过
  - 自审：一切正常
  - 已提交

[分派规格合规审查]
规格审查者：❌ 问题：
  - 缺失：进度报告（规格要求"每 100 项报告一次"）
  - 多余：添加了 --json 参数（未被要求）

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

[规格审查者再次审查]
规格审查者：✅ 现在符合规格

[分派代码质量审查]
代码审查者：优点：扎实。问题（重要）：魔法数字（100）

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

[代码审查者再次审查]
代码审查者：✅ 通过

[标记任务 2 完成]

...

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

完成！

You: I'm using subagent-driven development to execute this plan.

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

Task 1: Hook Installation Script

[Get Task 1 text and context (already extracted)]
[Assign Implementation Subagent with full task text + context]

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

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

Implementer: "Got it. Starting implementation now..."
[Later] Implementer:
  - Implemented install-hook command
  - Added tests, 5/5 passed
  - Self-review: Missing --force parameter, added it
  - Committed

[Assign Specification Compliance Review]
Spec Reviewer: ✅ Complies with specs - All requirements met, no extra content

[Get git SHA, assign Code Quality Review]
Code Reviewer: Pros: Good test coverage, clean code. Issues: None. Approved.

[Mark Task 1 complete]

Task 2: Recovery Mode

[Get Task 2 text and context (already extracted)]
[Assign Implementation Subagent with full task text + context]

Implementer: [No questions, starts directly]
Implementer:
  - Added verify/repair mode
  - 8/8 tests passed
  - Self-review: All good
  - Committed

[Assign Specification Compliance Review]
Spec Reviewer: ❌ Issues:
  - Missing: Progress reporting (spec requires "report every 100 items")
  - Extra: Added --json parameter (not requested)

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

[Spec Reviewer re-reviews]
Spec Reviewer: ✅ Now complies with specs

[Assign Code Quality Review]
Code Reviewer: Pros: Solid. Issue (important): Magic number (100)

[Implementer fixes]
Implementer: Extracted PROGRESS_INTERVAL constant

[Code Reviewer re-reviews]
Code Reviewer: ✅ Approved

[Mark Task 2 complete]

...

[After all tasks are complete]
[Assign Final Code Review]
Final Reviewer: All requirements met, ready for merge

Done!

优势

Advantages

与手动执行相比：

子智能体自然遵循 TDD
每个任务全新上下文（不会混淆）
并行安全（子智能体不会互相干扰）
子智能体可以提问（工作前和工作中都可以）

与 Executing Plans 相比：

同一会话（无交接）
持续进展（无需等待）
审查检查点自动化

效率提升：

无文件读取开销（控制者提供完整文本）
控制者精确策划所需上下文
子智能体预先获得完整信息
问题在工作开始前就被提出（而非工作结束后）

质量关卡：

自审在交接前发现问题
两阶段审查：规格合规性，然后代码质量
审查循环确保修复确实有效
规格合规防止过度/不足构建
代码质量确保实现良好

成本：

更多子智能体调用（每个任务需要实现者 + 2 个审查者）
控制者需要更多准备工作（预先提取所有任务）
审查循环增加迭代次数
但能及早发现问题（比后期调试更省成本）

Compared to Manual Execution:

Subagents naturally follow TDD
New context per task (no confusion)
Parallel-safe (subagents don't interfere with each other)
Subagents can ask questions (before and during work)

Compared to Executing Plans:

Same session (no handoff)
Continuous progress (no waiting)
Automated review checkpoints

Efficiency Improvements:

No file reading overhead (controller provides full text)
Controller precisely curates required context
Subagents get complete information upfront
Questions are raised before work starts (not after)

Quality Gates:

Self-review catches issues before handoff
Two-stage review: specification compliance, then code quality
Review loops ensure fixes are effective
Specification compliance prevents over/under building
Code quality ensures good implementation

Cost:

More subagent calls (each task needs implementer + 2 reviewers)
Controller needs more preparation (extract all tasks upfront)
Review loops increase iteration count
But catches issues early (cheaper than late debugging)

Red Lines

Never:

Start implementation on main/master branch without explicit user consent
Skip reviews (specification compliance or code quality)
Proceed with unresolved issues
Assign multiple implementation subagents in parallel (causes conflicts)
Let subagents read plan files (should provide full text)
Skip laying out scenario context (subagents need to understand where the task fits)
Ignore subagent questions (answer before letting them proceed)
Accept "close enough" on specification compliance (issues found by spec reviewer = incomplete)
Skip review loops (reviewer finds issue = implementer fixes = re-review)
Let implementer's self-review replace formal review (both are needed)
Start code quality review before specification compliance review passes (wrong order)
Move to next task while any review has unresolved issues

If Subagent Asks Questions:

Answer clearly and completely
Provide additional context if necessary
Don't rush them into implementation

If Reviewer Finds Issues:

Implementer (same subagent) fixes
Reviewer re-reviews
Repeat until approved
Don't skip re-review

If Subagent Fails:

Assign a fix subagent with specific instructions
Don't attempt manual fixes (context contamination)

红线

Integration

绝不：

未经用户明确同意就在 main/master 分支上开始实现
跳过审查（规格合规性或代码质量）
带着未修复的问题继续
并行分派多个实现子智能体（会冲突）
让子智能体读取计划文件（应提供完整文本）
跳过场景铺设上下文（子智能体需要理解任务在哪个环节）
忽视子智能体的问题（在让它们继续之前先回答）
在规格合规性上接受"差不多就行"（规格审查者发现问题 = 未完成）
跳过审查循环（审查者发现问题 = 实现者修复 = 再次审查）
让实现者的自审替代正式审查（两者都需要）
在规格合规性审查通过之前开始代码质量审查（顺序错误）
在任一审查有未解决问题时就进入下一个任务

如果子智能体提问：

清晰完整地回答
必要时提供额外上下文
不要催促它们进入实现阶段

如果审查者发现问题：

实现者（同一子智能体）修复
审查者再次审查
重复直到通过
不要跳过重新审查

如果子智能体失败：

分派修复子智能体并提供具体指令
不要尝试手动修复（上下文污染）

Required Workflow Skills:

superpowers:using-git-worktrees - Required: Set up isolated workspace before starting
superpowers:writing-plans - Create plans for this skill to execute
superpowers:requesting-code-review - Code review templates for review subagents
superpowers:finishing-a-development-branch - Wrap up after all tasks are complete

Subagents Should Use:

superpowers:test-driven-development - Subagents follow TDD for each task

Alternative Workflow:

superpowers:executing-plans - For parallel sessions instead of same-session execution

集成

—

必需的工作流技能：

superpowers:using-git-worktrees - 必需：在开始前建立隔离工作区
superpowers:writing-plans - 创建本技能执行的计划
superpowers:requesting-code-review - 审查子智能体的代码审查模板
superpowers:finishing-a-development-branch - 所有任务完成后收尾

子智能体应使用：

superpowers:test-driven-development - 子智能体对每个任务遵循 TDD

替代工作流：

superpowers:executing-plans - 用于并行会话而非同会话执行

—