subagent-driven-development

サブエージェント駆動開発

タスクごとに新しいサブエージェントを割り当てて計画を実行し、各タスクの後に2段階のレビューを行います。まず仕様準拠をレビューし、次にコード品質をレビューします。

基本原則： タスクごとに新しいサブエージェントを割り当て、2段階のレビューを行うことで、分離性とフィードバックを改善できます。実際の品質、レイテンシ、コストを検証してください。

使用するタイミング

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"];
}

「計画の実行」（並列セッション）との比較：

• 同じセッションを使います（コンテキストの切り替えがありません）
• タスクごとに新しいサブエージェントを使います（コンテキストが汚染されません）
• 各タスクの後に2段階のレビューを行います。まず仕様準拠を確認し、次にコード品質を確認します
• タスク間に人間が介在しないため、イテレーションが速くなります

ホストと権限の前提条件

このタスクで実際に利用可能で、許可されている委任ツールのみを使用してください。以下に記載されている Task、TodoWrite、superpowers という名前はホスト固有の例であり、同梱されている機能ではありません。3つのローカルプロンプトテンプレートは同梱されていますが、その他の superpowers スキル／テンプレートは外部依存関係です。利用できない場合は、同等のタスクトラッカーと独立したコードレビュー／仕様レビューを直接使い、サブエージェントを実行したと主張しないでください。全体の同時実行数、コスト、時間の上限とキャンセルを設定してください。サブエージェントが権限を拡張することはできません。コミットには、確立されたリポジトリのワークフローと割り当てられたブランチが必要です。レビュアーの承認は、プッシュ、マージ、公開の許可にはなりません。完了前に、レビュー対象の正確なヘッドで実際のファイルとコマンドの証拠を確認してください。

プロセス

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";
}

プロンプトテンプレート

• ./implementer-prompt.md - 実装担当サブエージェントを割り当てます
• ./spec-reviewer-prompt.md - 仕様準拠レビュアーのサブエージェントを割り当てます
• ./code-quality-reviewer-prompt.md - コード品質レビュアーのサブエージェントを割り当てます

ワークフローの例

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!

メリット

手動での実行との比較：

• 関連するテストを明示的に要求します。サブエージェントは自動的にTDDに従うわけではありません
• タスクごとに新しいコンテキストを使います（混乱しません）
• コンテキストが分離されていても、ファイルは分離されません。担当範囲を重複しないよう割り当てるか、分離されたチェックアウトを使用してください
• サブエージェントは作業の前だけでなく、作業中にも質問できます

「計画の実行」との比較：

• 同じセッションを使います（引き継ぎがありません）
• 継続的に進捗します（待ち時間がありません）
• レビューチェックポイントが自動化されています

効率の向上：

• ファイルを読むオーバーヘッドがありません（コントローラーが全文を提供します）
• コントローラーが必要なコンテキストだけを選別します
• サブエージェントは最初に必要な情報をすべて受け取ります
• 作業開始後ではなく、開始前に質問が明らかになります

品質ゲート：

• セルフレビューにより、引き継ぎ前に問題を発見できます
• 2段階のレビューを行います。仕様準拠の後にコード品質を確認します
• レビューの反復により、修正が実際に機能することを確認します
• 仕様準拠を確認することで、過剰な実装や不足した実装を防ぎます
• コード品質を確認することで、適切に構築された実装を実現します

コスト：

• サブエージェントの呼び出し回数が増えます（タスクごとに実装担当1回、レビュアー2回）
• コントローラーの準備作業が増えます（すべてのタスクを事前に抽出します）
• レビューの反復が追加されます
• ただし、問題を早期に発見できます（後からデバッグするより低コストです）

注意すべき点

次のことは決して行わないでください：

• レビューを省略する（仕様への準拠またはコード品質）
• 未修正の問題があるまま進める
• 複数の実装サブエージェントを並行して起動する（競合が発生します）
• サブエージェントに計画ファイルを読ませる（代わりに全文を渡してください）
• 背景となる状況を説明しない（サブエージェントがタスクの位置付けを理解できるようにしてください）
• サブエージェントからの質問を無視する（作業を続けさせる前に回答してください）
• 仕様への準拠について「だいたい問題ない」と受け入れる（仕様レビューで問題が見つかった場合、完了ではありません）
• レビューの反復を省略する（レビュアーが問題を見つける＝実装者が修正する＝再レビューする）
• 実装者のセルフレビューで実際のレビューを代用する（どちらも必要です）
• 仕様への準拠が✅になる前にコード品質レビューを開始する（順序が間違っています）
• いずれかのレビューに未解決の問題が残ったまま、次のタスクに進む

サブエージェントから質問があった場合：

• 明確かつ十分に回答してください
• 必要に応じて追加の背景情報を提供してください
• 実装を急がせないでください

レビュアーが問題を見つけた場合：

• 実装者（同じサブエージェント）が修正します
• レビュアーが再レビューします
• 承認されるまで繰り返します
• 再レビューを省略しないでください

サブエージェントがタスクに失敗した場合：

• 具体的な指示を添えて修正担当のサブエージェントを起動します
• より明確な場合、またはサブエージェントを利用できない場合は、コントローラーが直接修正してもかまいません。ただし、レビューと検証の要件は維持してください。

統合

必須のワークフロースキル：

• superpowers:writing-plans - このスキルが実行する計画を作成します
• superpowers:requesting-code-review - レビュー担当サブエージェント向けのコードレビューテンプレートです
• superpowers:finishing-a-development-branch - すべてのタスク完了後に開発を完了します

サブエージェントが使用するスキル：

• superpowers:test-driven-development - サブエージェントは各タスクでTDDに従います

代替ワークフロー：

• superpowers:executing-plans - 同一セッション内での実行の代わりに、並行セッションで使用します

制限事項

• タスクが上記の説明範囲に明確に該当する場合にのみ、このスキルを使用してください。
• 環境固有の検証、テスト、専門家によるレビューの代わりとして、出力を扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認してください。