subagent-driven-development

概要

subagent-driven-development とは？

subagent-driven-development は、実装プランを独立したタスクの連なりとして実行するためのエージェントオーケストレーション用スキルです。各タスクごとに、つねに新しい subagent を立ち上げて処理します。各タスクでは次の3つを行います:

1. 専任の implementer subagent を起動する。
2. spec compliance reviewer subagent を実行する。
3. code quality reviewer subagent を実行する。

これら3つの subagent は、現在のタスクだけに集中できるよう厳密に絞り込まれたコンテキストで動作し、メインのセッションはタスク間の調整や意思決定のためにクリアな状態を保てます。

このスキルの対象者

subagent-driven-development は、次のような開発者やチーム向けに設計されています:

• Claude / claude-code などの AI コーディングアシスタントを使っていて、結果の信頼性を高めたい人。
• 細かいタスクに分割された、文章ベースの実装プランに沿って作業している人。
• 1つの AI セッション内で、実装とレビューを構造化された形で繰り返し行いたい人。
• 「とりあえず動くもの」ではなく、仕様の正しさとコード品質の両方を重視する人。

特に、SHA やプランファイル、diff などを subagent に渡せる GitHub 中心のワークフローと相性が良い設計です。

どんな課題を解決する？

このスキルは、単一の AI エージェントにエンドツーエンドの開発を任せたときによく起きる問題に対処します:

• コンテキストの肥大化: 1つのエージェントが履歴を抱え込みすぎて、フォーカスを失う。
• 仕様ドリフト: 実装が徐々に元のプランや要件から逸脱していく。
• レビューの弱さ: コードを書いたのと同じコンテキストがレビューも行うため、ミスを見落としやすい。

subagent-driven-development では、「タスクごとに新しいエージェント」「厳密に絞ったコンテキスト」「仕様レビュー → 品質レビューの2段階チェック」というパターンを徹底します。これにより正しさが向上し、変更範囲も明確になり、実装プランの各ステップを論理的に追いやすくなります。

subagent-driven-development が向いている場面

このスキルが特に有効なのは次のような場合です:

• すでにタスクに分解された実装プランがある。
• タスク同士が主に独立しており、常時クロスタスクの調整を必要としない。
• プランを現在のセッション内で完了させる予定がある（数日にまたがって持ち越さない）。

まだプランがなかったり、タスク同士が密結合で頻繁に変化するような場合は、次のような進め方の方が適していることがあります:

• まず別のスキルや手作業でプランをブレインストーミング・設計する。
• 探索的なフェーズでは、より自由度の高い単一エージェント型のワークフローを使う。

使い方

インストール手順

1. スキルを環境に追加する

obra/superpowers リポジトリから subagent-driven-development スキルをインストールします:

npx skills add https://github.com/obra/superpowers --skill subagent-driven-development

このコマンドにより、スキル定義と関連するプロンプトテンプレートが skills 対応環境に取り込まれ、プラン上の各タスクに対して subagent をオーケストレーションできるようになります。

2. コアファイルを確認する

インストール後、リポジトリ内のスキルディレクトリ（または skills ブラウザ）を開き、次のファイルを確認します:

• SKILL.md – スキルの概要、利用シーン、コアワークフローの説明。
• implementer-prompt.md – implementer subagent 向けテンプレート。
• spec-reviewer-prompt.md – spec compliance reviewer subagent 向けテンプレート。
• code-quality-reviewer-prompt.md – code quality reviewer subagent 向けテンプレート。

これらは、そのまま使うだけでなく、自分の自動化やツール連携に合わせてコピー・調整するためのベースとして扱ってください。

実装プランの準備

1. タスクリストの作成・ブラッシュアップ

subagent-driven-development を使う前に、次の条件を満たすタスクで構成された実装プランを用意します:

• スコープが明確で、テスト可能であること。
• タスク同士が主に独立していること。
• implementer subagent が推測に頼らず動ける程度の具体性があること。

各タスクは、implementer のプロンプト内で “FULL TEXT of task from plan” としてコピペできる粒度にしておきましょう。

2. 作業ディレクトリと Git 戦略を決める

プロンプトテンプレートは、Git ベースのワークフローと具体的な作業ディレクトリを前提にしています:

• implementer が作業する directory を決める。
• 変更履歴の追跡方法（例: 各タスクごとの BASE_SHA と HEAD_SHA）を決める。

これらの値は、spec reviewer と code quality reviewer のプロンプトに渡し、正確なレビューを行うために使います。

タスクごとのワークフロー実行

1. implementer subagent を起動する

各タスク N について、implementer-prompt.md のテンプレートを使って新しい implementer subagent を作成します。

テンプレートのポイント:

• implementer には明示的に「You are implementing Task N: [task name]」と伝える。
• ## Task Description セクションに、タスクの全文を貼り付ける。
• 次の項目を埋める:
  • Context – システム全体の中でそのタスクがどの位置づけか。
  • directory – 変更を行う作業ディレクトリ。

implementer には次のように指示されています:

1. 不明点があれば着手前に質問する。
2. タスクで指定された内容を、余計なことをせず正確に実装する。
3. 適切な場合はテストを作成し、実行する。
4. 実装を検証する。
5. 作業をコミットする。
6. 実施内容を分かりやすくレポートする。

タスクごとに 新しい subagent を作成することで、そのタスクに必要なコンテキストだけを見せることができ、メインセッションの履歴や他タスクの情報を引きずらずに済みます。

2. 仕様準拠レビュー（spec compliance review）を行う

implementer が作業を終えてレポートを返してきたら、spec-reviewer-prompt.md を用いて spec compliance reviewer subagent を起動します。

このテンプレートでは次のように入力します:

• ## What Was Requested に タスクの要件 を貼り付ける。
• ## What Implementer Claims They Built に implementer のレポート を貼り付ける。

spec reviewer には、implementer のレポートを鵜呑みにしないよう明示的に指示されており、次を行います:

• 実際のコードを読む。
• 要件とコードを行レベルで突き合わせる。
• 未実装の要件、余計な実装、不適切な解釈を特定する。

問題が見つかった場合は、同じ implementer か別の subagent に差し戻し、ギャップを埋めてから次に進みます。

3. コード品質レビューを行う

仕様準拠が確認できたら、code-quality-reviewer-prompt.md を用いて code quality reviewer subagent を起動します。

このテンプレートは、次のようなコードレビュータスク形式の入力を想定しています:

Task tool (superpowers:code-reviewer):
  Use template at requesting-code-review/code-reviewer.md

  WHAT_WAS_IMPLEMENTED: [from implementer's report]
  PLAN_OR_REQUIREMENTS: Task N from [plan-file]
  BASE_SHA: [commit before task]
  HEAD_SHA: [current commit]
  DESCRIPTION: [task summary]

reviewer は次の点をチェックします:

• 実装のクリーンさと保守性。
• ファイルごとの責務とインターフェース（可能な限り、1ファイル1責務）。
• 新規・変更ファイルのサイズや分割が妥当かどうか。
• テストカバレッジと、各ユニットを独立して理解・検証できるかどうか。

結果として、長所、課題（Critical / Important / Minor）と、全体的な評価を含む構造化されたフィードバックが返ってきます。

それをもとに、次のどちらに進むかを判断できます:

• 変更をそのまま受け入れる。
• implementer にフォローアップのリファクタリングを依頼する。

自分の環境への適用

1. 自分のスタック向けにプロンプトをカスタマイズする

implementer-prompt.md、spec-reviewer-prompt.md、code-quality-reviewer-prompt.md のテンプレートは、あえて汎用的に作られています。次の点を自分のプロジェクトに合わせて調整してください:

• 使用しているプログラミング言語やフレームワーク。
• テストの慣習（例: pytest, Jest, Go test など）。
• リポジトリ構成や命名規則。

その際も、「タスクごとに新しい subagent」「セクションが整理されたプロンプト」「役割を明示したジョブディスクリプション」というコア構造は保つことをおすすめします。

2. 繰り返し作業を自動化する

パターンに慣れてきたら、スクリプトやツールで自動化すると効率的です:

• implementer → spec reviewer → code quality reviewer の3つの subagent 呼び出しを、タスクごとの単一コマンドにまとめる。
• プランファイルを元に、タスクごとのプロンプトを自動生成する。
• Git メタデータを読み取って BASE_SHA と HEAD_SHA を自動で埋める。

こうすることで、subagent-driven-development をチームの再現性の高いワークフローオートメーションとして運用できます。

3. このスキルが向かないケース

次のような場合は、別のアプローチを検討した方が良いことがあります:

• タスク同士の依存が強く、きれいに分割できない。
• まだ明確な実装プランがない。
• コンテキストを数日にわたって持続させるような長期・継続的な作業が必要。

そのような場合は、まずプランニングやアーキテクチャ設計、長期稼働エージェント向けのスキル・プロセスを使い、タスクが独立した形で実行可能になった段階で subagent-driven-development に切り替えるとよいでしょう。

FAQ

「subagent-driven-development」とは、実際にはどんなやり方ですか？

実務上の subagent-driven-development では、すべてを1つの万能エージェントに任せるのではなく、次のように進めます:

• メインのセッションで全体の調整とコンテキスト管理を行う。
• 各タスクごとに、そのタスクに必要な情報だけを持つ 新しい subagent を構築する。
• その subagent にタスクを実装させ、その後さらに2つの subagent でレビューを行う。

これにより関心事を分離し、コンテキストを管理しやすくし、実装プランの各ステップの信頼性を高めます。

通常の単一エージェントのコーディングセッションと何が違いますか？

単一エージェントの場合、過去の会話やコード編集の履歴が1つのコンテキストに積み重なり、次のような問題が起きがちです:

• 古い要件と新しい要件が混ざって混乱する。
• コーディングとレビューに同じ思考パターンが再利用される。

subagent-driven-development では代わりに次を行います:

• 実装とレビューで プロンプトと役割を分離 する。
• 各 subagent を、セッション全体の履歴ではなく 厳選したコンテキスト だけで開始する。
• レビューの順序を 「まず仕様、次に品質」 として強制する。

その結果、実装の精度が上がり、レビューもより率直で厳密になりやすくなります。

テンプレート通りに使わないといけませんか？

必須ではありません。リポジトリ内のテンプレートは、implementer・spec reviewer・code quality reviewer のプロンプト構成例です。次の点は維持することをおすすめします:

• implementer → spec review → quality review という全体の流れ。
• spec reviewer が実装レポートを信用しすぎず、必ず実際のコードを読む という重要な行動。

そのうえで、文言の調整やプロジェクト固有のガイドラインの追加、自前のツールや慣習との統合などは自由に行って構いません。

Git なしでも subagent-driven-development を使えますか？

code quality reviewer のテンプレートは BASE_SHA や HEAD_SHA など、Git ワークフローに自然な項目を想定していますが、Git は必須ではありません:

• 「新しい subagent」と「2段階レビュー」というコアな考え方は、Git なしでもそのまま適用できます。
• SHAs の代わりに、アーカイブ ID やスナップショットパスなど、自分の環境に合った before/after の参照方法を使えます。

スキル自体が Git を強制することはなく、あくまで Git を前提とした例を提示しているだけです。

このスキルは特定の AI モデルに依存しますか？

リポジトリは特定モデルに厳密に固定されてはいませんが、Anthropic の Claude / claude-code のような、現代的な汎用コードモデルを主なターゲットとしています。次の条件を満たすモデルの利用を推奨します:

• コードやテストを読み解き、論理的に推論できること。
• カスタムプロンプト付きの複数 subagent を起動できる環境で動かせること。

エージェントツールやタスクランナーが利用できるスタックであれば、これらのテンプレートをその仕組みに組み込むことができます。

subagent-driven-development と他の superpowers スキルはどう使い分ければいいですか？

SKILL.md には、どのような場面で subagent-driven-development を選ぶべきかが記載されています。基本的には、実装プランがあり、タスクが主に独立していて、同一セッション内で完結させたい 場合に使うのが適しています。いずれかが当てはまらない場合は、次のような選択肢があります:

• まずプランニングやブレインストーミング系スキルを使ってプランを作成する。
• 複雑に絡み合ったタスクや、複数セッションにまたがる作業には、別の実行・計画パターンを用いる。

リポジトリ内のどこから読み始めればいいですか？

このスキルの導入を検討している場合は、次のファイルから読み始めると全体像をつかみやすくなります:

1. SKILL.md – スキルの背景となる考え方と高レベルのワークフロー。
2. implementer-prompt.md – implementer subagent をどのような前提で動かすか。
3. spec-reviewer-prompt.md – 仕様準拠チェックの観点と流れ。
4. code-quality-reviewer-prompt.md – 追加の品質・構造チェックの観点。

これらを読み込んだうえで、自分のエージェントオーケストレーションやワークフロー自動化の仕組みにテンプレートを取り込み、subagent-driven-development をフル活用してください。