subagent-driven-development

subagent-driven-development skill の概要

subagent-driven-development が実際にすること

subagent-driven-development skill は、実装計画をそのまま実行に落とし込むためのワークフローです。作業を独立したタスクに分割し、それぞれを新しい subagent に割り当て、さらに各成果物を「仕様準拠」と「コード品質」の2段階でレビューします。価値の本質は単に「より多くの agent を使う」ことではありません。各担当者に、そのタスク・要件・ローカルなコード文脈だけを意図的に渡すことで、コンテキストを分離して使う点にあります。

この skill が特に合うケース

この subagent-driven-development skill は、すでに計画があり、今のセッション内でそれを確実に実装へ変えたい人に向いています。特に次の条件では相性が良いです。

• タスク同士が概ね独立している
• coordinator agent はオーケストレーションに集中させたい
• 要件のズレと雑な実装の両方を見逃したくない
• 一発のコーディング指示ではなく、繰り返せるレビューの流れがほしい

解決するジョブ

ユーザーが subagent-driven-development for Agent Orchestration を採用するのは、通常の「この計画を実装して」というプロンプトが、予測できる形で失敗し始めたときです。たとえば agent が複数タスクを混ぜる、制約を忘れる、作り込みすぎる、あるいはそれっぽいコードは出すが仕様を満たしていない、といった問題です。この skill は、そうした失敗を減らすために、引き渡しとレビューの手順を規律ある形にします。

汎用プロンプトと何が違うのか

主な違いは、どれも実務的な点です。

• タスクごとに新しい subagent を使う：ノイズの多い履歴を引きずる単一の長寿命 agent にしない
• 明示的な task packet を渡す：要件を散在するファイルから推測させず、完全なタスク文面をそのまま貼り付ける
• 実装前の質問を必須にする：曖昧な要件を早い段階で表面化させる
• 2段階レビューに分ける：「仕様どおりか」と「コードとして良いか」を別々に判定する

この分離は重要です。多くのチームはスコープ確認より先に品質レビューをしてしまいますが、その順番だと、作りすぎ・作り足りない実装を見抜きにくくなります。

この skill を選ばないほうがよい場面

まだ具体的な実装計画がない場合、タスク同士が強く結びついている場合、あるいはこのセッションではなく別の並列実行フローに載せるべき作業なら、subagent-driven-development から始めるべきではありません。そうしたケースでは、まず計画立案か、別の実行系 skill を選ぶほうが適切です。

subagent-driven-development skill の使い方

subagent-driven-development skill をインストールする

このリポジトリから Skills CLI で skill を導入する場合は、次を使います。

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

インストール後は、最初に走らせる前に、導入された skill 本体と補助の prompt template を開いて確認してください。

最初に読むべきファイル

素早く使い始めるなら、次の順番で読むのがおすすめです。

1. SKILL.md
2. implementer-prompt.md
3. spec-reviewer-prompt.md
4. code-quality-reviewer-prompt.md

この順番なら、まずワークフロー全体を把握し、その後に implementer と2つのレビュー段階で使うプロンプトの具体形を追えます。

始める前に呼び出しパターンを理解する

実際の subagent-driven-development usage は、ひとつの魔法のコマンドではありません。あなた自身が coordinator として次の流れを回します。

1. 計画から1つのタスクを取り出す
2. スコープを絞ったプロンプトで新しい implementer subagent を起動する
3. 結果報告を必須にする
4. 実際のコードに対して spec reviewer を走らせる
5. spec を通過した場合のみ code quality reviewer を走らせる
6. 受け入れる、修正する、または再度投げ直す

このレビューの関門を飛ばすなら、もはや設計どおりにこの skill を使っているとは言えません。

この skill に必要な入力

どの subagent を投げる前にも、次の入力を用意しておきます。

• 計画書に書かれた正確なタスク文面
• 受け入れ条件または要件
• 関連するアーキテクチャ文脈
• 作業対象のディレクトリまたは repo の範囲
• 依存関係や実行順のメモ
• レビュー差分の基準になる baseline commit または SHA
• 追跡用のタスク番号とタスク名

元の template からも強く読み取れるのは、「計画ファイルを読んで」と言うのではなく、タスク全文をプロンプトに貼り込むべきだということです。

曖昧な依頼を強い implementer prompt に変える

弱いプロンプトは、こうです。

• 「計画の task 4 を実装して」

より強い subagent-driven-development guide 向けのプロンプトには、次の要素が入ります。

• タスク名とタスク番号
• タスクの全文
• このタスクが存在する理由
• repo のどこを触るか
• ファイル構成上の制約
• テストが必要かどうか
• 前提の置き方が必要になったときの対応
• 実装前に質問することを必須にする指示

この形が重要なのは、この skill が repo 全体を自律的に解釈させる設計ではなく、制御されたコンテキストを前提にしているからです。

より良い task packet の例

implementer に投げるときは、次のような構造にすると安定します。

• Task N: [name]
• FULL TEXT of task from plan
• Context: where this fits, dependencies, architecture
• Work from: [directory]
• Requirements: implement exactly what is specified
• If anything is unclear, ask before starting
• Write tests if required by task
• Commit, self-review, and report back

広く探索させるよりも、こうした形のほうが信頼できます。この skill では、依頼内容を適切にパッケージする責任は coordinator 側にある前提だからです。

なぜ品質レビューより先に spec review を行うのか

これは subagent-driven-development install を検討するうえでも価値の高いポイントで、順番には明確な意図があります。

まず spec reviewer で確認するのは次の点です。

• 依頼された内容を本当に実装しているか
• 要件を取りこぼしていないか
• 依頼されていない作業を追加していないか
• タスク理解を誤っていないか

その後に code quality reviewer を実行し、保守性、分割の妥当性、ファイルの責務、変更の粒度を見ます。順序を逆にすると、見栄えの良いコードがスコープの誤りを隠してしまいます。

spec reviewer をうまく使う方法

spec-reviewer-prompt.md の template はかなり率直です。reviewer に対して、implementer の報告を鵜呑みにせず、実コードを行単位で確認するよう求めています。これを自分用に調整するときも、そのトーンは保ったほうがよいです。reviewer に必要なのは次の情報です。

• 要件の全文
• implementer が主張している成果
• 変更されたコードへのアクセス

目的は丁寧な追認ではなく、独立した検証です。

code quality reviewer をうまく使う方法

この code quality review は、一般的なスタイル指摘ではありません。この skill で重視しているのは次の点です。

• 1ファイル1責務が明確か
• インターフェースがきちんと定義されているか
• 理解しやすい単位に分解されているか
• 想定されたファイル構成に沿っているか
• このタスクの実装で、新規ファイルが大きくなりすぎていないか、既存ファイルを膨らませすぎていないか

最後の確認は特に有効です。subagent は、ひとつの変更に詰め込んでタスクを片づけがちだからです。

実際の repo でのおすすめワークフロー

実務的な subagent-driven-development usage のループは、次のようになります。

1. 次の独立タスクを選ぶ
2. 現在の commit を baseline として記録する
3. タスク全文を含めて implementer を起動する
4. その要約と変更ファイルを回収する
5. 要件とコードを突き合わせて spec review を行う
6. spec に落ちたら、具体的な不足点を implementer に返す
7. spec を通過したら code quality review を行う
8. 品質で落ちたら、焦点を絞った修正を依頼する
9. マージするか、次のタスクへ進む

この流れなら、順序管理と受け入れ判断の主導権を coordinator が維持できます。

出力品質に影響する制約

この skill は、前提条件を守るほど効果が出ます。

• 複雑に絡んだタスクより、独立タスクのほうが向く
• 推測された要件より、明示的な要件のほうが強い
• 「見て判断して」より、repo 範囲を狭く示すほうが良い
• 大きな複数機能のまとめ投げより、短いタスクループのほうが安定する
• 黙って推測させるより、明確なエスカレーションルールのほうが良い

コードベース全体の多くの要素を横断して subagent に調整させる必要が出てきたら、そのタスクはこのワークフローには広すぎる可能性が高いです。

よくある導入ミス

最大のミスは、subagent-driven-development skill というラベルだけ使いながら、実際には緩いプロンプトを書き続けることです。このワークフローが効くのは、文脈を丁寧にパッケージし、レビュー順序をきちんと守ったときだけです。そこを省くと、オーケストレーションの手間だけ増えて、品質改善は得られません。

subagent-driven-development skill FAQ

subagent-driven-development は初心者にも向いていますか？

はい、ただし「何を作りたいか」を自分で理解している場合に限ります。ワークフロー自体は明示的で、用意された prompt template によって手探りも減らせます。ただし、これは計画立案の代わりにはなりません。まだ明確な実装計画がない初心者には厳しいことがあります。この skill は、すでにタスク定義が存在している前提だからです。

どんなときに subagent-driven-development を使わないべきですか？

次の状況では subagent-driven-development を見送るべきです。

• まだ問題探索の段階にいる
• タスクが深く相互依存している
• 要件が安定していない
• 1人の人間または1つの agent がシステム全体を継続的に見渡して考える必要がある

これは探索パターンではなく、実行パターンです。

1つの agent に全部コーディングさせるのと何が違いますか？

単一の長いプロンプトだと、計画、実装、検証、レビューが1つのコンテキストウィンドウに混ざりやすくなります。この skill は、それらの役割を分けます。その結果、集中しやすくなり、要件のズレも見つけやすくなり、coordinator のコンテキストもコード生成ではなくオーケストレーションのために残しやすくなります。

この skill に特別なツールは必要ですか？

特別なスクリプトはこの skill folder には含まれていません。この repository が提供しているのは自動化コードではなく、markdown の prompt template です。subagent を起動でき、コードレビュー作業を回せる環境であれば、どこでもこのパターンを使えます。

subagent-driven-development は大規模プロジェクト専用ですか？

いいえ。小さな変更にも使えます。ただし、いくつかの独立タスクを含む計画があり、要件の見落としコストがレビューの手間に見合う場面で、特に価値が出ます。

インストール前に repo 内でどんな証拠を見るべきですか？

この skill では、最も重要なのは SKILL.md に書かれたワークフロー設計と、3つの prompt template です。裏で何かをしてくれる helper script や resource folder はないので、導入判断では「このプロンプト構造とレビュー規律が、自分たちのコード出荷のやり方に合うか」を見るべきです。

subagent-driven-development skill を改善するには

プロンプトを長くするより、task packet を良くする

subagent-driven-development skill の結果を改善したいなら、冗長さではなく精度を上げてください。特に効く追加情報は次のとおりです。

• 正確な受け入れ条件
• 明示的な非目標
• このタスクにだけ関係するアーキテクチャメモ
• ファイルまたはディレクトリの境界
• 期待される挙動の例
• テストに関する期待値

これにより implementer はぶれにくくなり、spec reviewer も逸脱を見つけやすくなります。

タスク境界をもっと鋭くする

多くの失敗は、タスクの切り方が甘いことから生まれます。subagent が複数の可動要素を調整し、アーキテクチャを決め、要件まで同時に推測しなければならないなら、そのタスクは分割すべきです。より良いタスクとは、「求められたものを正確に実装したか」が簡単に検証できる程度に狭いものです。

先に質問させるステップを消さない

implementer template では、作業開始前に質問し、実装中に想定外が出た場合も再度確認するよう明確に指示しています。この挙動は維持してください。確認依頼を抑え込むと、出力は速くなっても信頼性が落ち、この skill の狙いそのものが崩れます。

比較用入力を強くしてレビュー品質を上げる

spec reviewer には、次を渡します。

• 要件文の全文
• implementer の報告
• 変更ファイルまたは diff の範囲
• 明示的な除外事項

code quality reviewer には、次を渡します。

• BASE_SHA
• HEAD_SHA
• タスク要約
• 関連する計画セクション

こうした具体的な比較の足場があると、レビューが単なる感想で終わりません。

よくある失敗パターンを監視する

subagent-driven-development for Agent Orchestration でよく起きる問題は、次のとおりです。

• implementer が余計な機能を推測で足す
• task packet から重要な制約が抜けている
• reviewer が implementer の要約を信用しすぎる
• spec review より先に code quality review をしてしまう
• タスクが大きすぎてきれいに検証できない
• ファイル肥大化が放置される

どれも、task packet の質を上げ、関門管理を厳格にすれば防げます。

最初の出力後に改善を回す

1回目の結果が弱くても、すぐに最初からやり直す必要はありません。まず、どの層で失敗したのかを特定してください。

• spec failure: 要件が曖昧、不足、または作り込みすぎ
• quality failure: 分割、保守性、ファイル構造に問題がある
• coordination failure: タスク分割またはコンテキストの渡し方が悪い

そのうえで、その層だけを修正します。このほうがワークフローを効率的に保てます。

ファイル構成のガイダンスを明確にする

quality template の有用な点のひとつは、実装が予定したファイル構成に従っているか、新規作成ファイルがすでに大きくなりすぎていないかを確認することです。保守性を重視するなら、reviewer が後で拾ってくれることを期待するのではなく、最初から task packet に意図したファイル境界を入れておくべきです。

再利用できるローカルチェックリストを作る

subagent-driven-development を繰り返し使うなら、coordinator 用の短いチェックリストを持っておくと有効です。

• plan が存在する
• task は独立している
• タスク全文を貼り付けた
• 制約を含めた
• baseline SHA を記録した
• implementer にコーディング前の確認を求めた
• spec review を完了した
• quality review を完了した

この小さな習慣は、プロンプトを長くするより一貫性向上に効きます。

自分のワークフローに合わせて skill を改善する

ベースの skill は意図的に軽量です。自分の環境でより効果的にするには、prompt template を自分たちのスタックやレビュー基準に合わせて調整してください。

• テストコマンドを追加する
• repo 固有のアーキテクチャルールを追加する
• どこからを過剰設計とみなすか定義する
• 好みの報告フォーマットを指定する
• 自分たちのコードベースで起きやすい失敗パターンを含める

こうしたローカルな調整のほうが、理論を増やすより subagent-driven-development usage の改善につながることが多いです。