subagent-driven-development

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

概要

このスキルは、品質ゲートを組み込んだ専用サブエージェントを通じて実装を調整します。各タスクは実装サブエージェントによって実装された後、受け入れ前に、仕様準拠とコード品質を専門とする2つのレビュアーエージェントによってレビューされます。レビューに失敗した場合は、最大3回の再試行を伴う反復的な修正サイクルが実行され、その後エスカレーションされます。これにより、並列処理のスループットを最大化しながら、大規模な開発でも一貫した品質を確保できます。

開始時の宣言：「サブエージェント駆動開発スキルを使用し、2段階のレビューゲートを設けて実装タスクを割り当てます。」

トリガー条件

• 独立して実装できるタスクが計画に3つ以上ある
• 委任に適した、明確に定義された受け入れ基準がタスクにある
• 実行速度が優先される
• タスク間の依存関係が少ない
• 委任する作業に品質ゲートが必要である

---

フェーズ1：タスクの準備

目標： サブエージェントに割り当てる前に、すべてのタスクの仕様を完全に定義します。

タスク仕様の要件（7項目）

サブエージェントに割り当てるすべてのタスクには、以下の項目をすべて含める必要があります。

項目	内容	例
1. タスクの説明	明確で曖昧さのない記述	「RS256署名を使用したJWTトークン生成を実装する」
2. 作成・変更するファイル	明示的な一覧	src/auth/jwt.ts、tests/auth/jwt.test.ts
3. 受け入れ基準	具体的でテスト可能な条件	「トークンは1時間後に期限切れになる」、「無効なキーではAuthErrorがスローされる」
4. TDDの要件	作成するテスト、対象となる動作	「テスト：有効なトークンの生成、期限切れトークンの拒否、無効なキーの処理」
5. 品質基準	コードスタイル、パターン、規約	「src/services/の既存サービスパターンに従い、エラーにはResult型を使用する」
6. コンテキスト	関連するコード、インターフェース、依存関係	「Logger API：logger.info(msg, meta)。../utils/loggerからインポートする」
7. 制約	してはいけないこと	「既存の認証ミドルウェアは変更しないでください。新しい依存関係を追加しないでください。」

割り当て前のチェックリスト

• タスク仕様の7項目すべてが記入されている
• タスクが独立している（進行中のタスクに未解決の依存関係がない）
• 受け入れ基準が具体的でテスト可能である
• 変更するファイルが特定され、アクセス可能である
• 関連するコンテキストが収集され、仕様に含まれている

タスクの独立性に関する判断表

依存関係の種類	割り当て可能か？	対応
依存関係なし	はい	すぐに割り当てる
完了済みタスクに依存	はい	完了済みタスクの成果物をコンテキストとして含める
進行中のタスクに依存	いいえ	依存するタスクの完了を待つ
別のタスクと同じファイルを共有	いいえ	順番に実行する。そのファイルは一度に1つのタスクだけが扱う
インターフェースのみ共有	はい	インターフェース定義をコンテキストとして含める

停止 — 次の条件を満たすまで割り当てないでください。

• 仕様の7項目すべてが完成している
• 独立性が確認されている
• 受け入れ基準がテスト可能である

---

フェーズ2：実装の割り当て

目標： 完全なコンテキストとともに、タスクを実装サブエージェントに渡します。

1. implementer-prompt.mdテンプレートを使用して実装担当者向けプロンプトを準備する
2. タスク仕様全体（7項目すべて）を含める
3. 関連するコードのコンテキスト（既存ファイル、インターフェース、型）を含める
4. 実装サブエージェントに割り当てる
5. 実装の出力を受け取る

割り当て方法： subagent_type="general-purpose"を指定したAgentツールを使用し、implementer-prompt.mdに記載された実装担当者向けプロンプトをpromptパラメーターに含めます。descriptionには短いタスクラベルを設定します。

実装担当者への期待事項

実装サブエージェントは、以下を必ず行う必要があります。

• TDDサイクル（RED-GREEN-REFACTOR）に従う
• 本番コードより先にテストを書く
• タスク仕様に記載されたファイルのみを変更する
• 指定された品質基準に従う
• 発生した質問やブロッカーを報告する
• 行ったすべての仮定を文書化する

質問対応プロトコル

質問の種類	実装中	対応
ブロッキングではない	妥当な仮定のもとで進められる	仮定を記録し、続行して、出力で明示する
ブロッキング	回答がないと進められない	直ちに停止し、オーケストレーターにエスカレーションする
スコープに関する質問	割り当てられたタスクの範囲外の作業について尋ねている	報告し、修正は行わない

以下を満たすまで、レビューに進まないでください。

• 実装担当者から完全な出力が返されている
• 一覧に記載されたすべてのファイルが作成または変更されている
• すべての受け入れ基準に対するテストが存在する
• 仮定があれば文書化されている

---

フェーズ 3：仕様レビューゲート

目標： 実装が元のタスク仕様に合致していることを確認します。

1. spec-reviewer-prompt.md テンプレートを使用して、仕様レビュアーへのプロンプトを準備します
2. 元のタスク仕様と実装担当者の出力を提示します
3. 仕様レビュアーのサブエージェントに作業を依頼します
4. レビュー結果を収集します

依頼方法： spec-reviewer-prompt.md の仕様レビュアープロンプトを prompt パラメーターに指定して、Agent ツールを使用します。

仕様レビューの基準

基準	評価	確認内容
すべての受け入れ基準を満たしている	基準ごとに PASS / FAIL	各基準を個別に検証する
テストが指定された動作を網羅している	PASS / FAIL	テストファイルに、すべての動作を対象とするテストが含まれている
変更されたファイルが仕様と一致している	PASS / FAIL	許可されていないファイル変更がない
スコープ外の変更がない	PASS / FAIL	一覧に記載されたファイルのみが変更されている
実装が意図に合致している	PASS / FAIL	構文的に有効なだけでなく、動作が正しい
すべての制約が守られている	PASS / FAIL	「してはいけない」項目に違反していない

ゲートの判定

結果	対応
すべて PASS	フェーズ 4（品質レビュー）に進む
FAIL がある	失敗の詳細を伝えて実装担当者に差し戻す

仕様基準に FAIL がある場合は、品質レビューに進まないでください。

---

フェーズ 4：品質レビューゲート

目標： 仕様への準拠とは独立して、コードが品質基準を満たしていることを確認します。

1. code-quality-reviewer-prompt.md テンプレートを使用して、品質レビュアーへのプロンプトを準備します
2. 実装コード、テストコード、プロジェクトの品質基準を提示します
3. 品質レビュアーのサブエージェントに作業を依頼します
4. レビュー結果を収集します

依頼方法： code-quality-reviewer-prompt.md の品質レビュアープロンプトを prompt パラメーターに指定して、Agent ツールを使用します。

品質レビュー項目

項目	確認内容
コード品質	可読性、命名、構造、複雑さ
パターンへの準拠	プロジェクトのパターンと規約に従っている
セキュリティ	インジェクション脆弱性がない、適切な検証が行われている、安全なデフォルト設定である
パフォーマンス	不要なアロケーションがない、アルゴリズムが効率的である、N+1 クエリがない
エラー処理	すべてのエラーパスが処理され、意味のあるエラーメッセージがある
テストの品質	テストに意味があり、実装の詳細をテストしていない

問題の重大度分類

重大度	定義	必要な対応
重大	セキュリティ脆弱性、データ損失のリスク、誤った動作	受け入れ前に必ず修正する
重要	パフォーマンス上の問題、保守性に関する懸念、エラー処理の不足	修正を推奨する（判断を仰ぐため、ユーザーにエスカレーションする）
提案	スタイルの改善、代替案、ドキュメント	開発者の裁量で修正してもよい

ゲートの判定

結果	対応
重大または重要な問題がない	PASS — 受け入れに進む
重大な問題がある	FAIL — 修正して再レビューする
重要な問題のみ	条件付き — 判断を仰ぐため、ユーザーにエスカレーションする

---

フェーズ 5：修正と再レビューのサイクル

目標： 上限回数を設けて、レビューでの不合格を反復的に修正します。

修正サイクルのプロセス

1. Collect all failure details from the failing review gate
2. Send failures back to implementer subagent with specific instructions
3. Implementer fixes the specific issues (not a full rewrite)
4. Re-run ONLY the failing review gate
5. If still failing: repeat (max 3 cycles)
6. After 3 failed cycles: escalate to user

再試行の判断表

試行	仕様レビュー	品質レビュー	対応
1	FAIL	—	失敗の詳細を添えて実装担当者に差し戻す
2	FAIL	—	追加のコンテキストや例を添えて差し戻す
3	FAIL	—	ユーザーにエスカレーションする
1	PASS	FAIL	品質上の問題を添えて実装担当者に差し戻す
2	PASS	FAIL	参考資料としてプロジェクトのパターンを添えて差し戻す
3	PASS	FAIL	ユーザーにエスカレーションする

エスカレーション報告の形式

ESCALATION: REPEATED REVIEW FAILURE
====================================
Task: [task description]
Review Gate: [spec / quality]
Attempts: 3

Failure Pattern:
  Attempt 1: [what failed and why]
  Attempt 2: [what failed and why]
  Attempt 3: [what failed and why]

Root Cause Assessment: [why the implementer cannot resolve this]

Options:
  A. Simplify the task specification
  B. Provide additional context/examples
  C. Break into smaller sub-tasks
  D. Implement manually (skip subagent)

Awaiting direction.

---

フェーズ 6：受け入れと統合

目標： 両方のゲートに合格したら、作業を統合し、リグレッションがないことを確認します。

1. プロジェクト全体のテストスイートを実行します（新しいテストだけではありません）
2. すべての検証コマンド（lint、型チェック、ビルド）を実行します
3. リグレッションが発生していないことを確認します
4. タスクを完了としてマークします
5. 次のタスクに進むか、完了を報告します

複数タスクのオーケストレーション

1. Identify independent tasks (no dependencies on each other)
2. For each independent task: run Phases 2-6
3. After all independent tasks complete:
   a. Run full test suite
   b. Run all verification commands
   c. Checkpoint review
4. Identify next set of tasks (now that dependencies are met)
5. Repeat until all tasks complete

---

アンチパターン／よくある間違い

アンチパターン	失敗する理由	正しいアプローチ
タスク仕様が不完全なまま割り当てる	実装担当者が誤った前提を置く	まず仕様の 7 つのセクションをすべて埋める
仕様レビューを省略する（「コードは正しそう」）	仕様からの逸脱が積み重なる	常に両方のレビューゲートを実施する
Critical な問題があるのに受け入れる	セキュリティや正確性が損なわれる	Critical な問題は必ず修正する
実装担当者に自分のコードをレビューさせる	バイアスや見落としが生じる	実装とレビューには別々のエージェントを使う
依存関係のあるタスクを並行して割り当てる	競合状態や統合の失敗が発生する	独立したタスクのみ並列化する
実装担当者からの質問を無視する	誤った前提がコードに組み込まれる	進む前にすべての質問に対応する
エスカレーションせずに 3 回を超えて修正を繰り返す	効果が薄れ、同じ間違いを繰り返す	指示を仰ぐためユーザーにエスカレーションする
受け入れ後の検証を省略する	リグレッションを見逃す	常に完全な検証を実行する
受け入れ基準が曖昧	レビュアーが客観的に評価できない	具体的でテスト可能な基準のみを使う
制約を含めない	実装担当者が触れてはいけないファイルを変更する	すべての仕様に明示的な「してはいけない」リストを含める

---

不合理な正当化を防ぐガード

どちらのレビューゲートも省略してはいけません。Critical な問題がある実装を受け入れてはいけません。完全な仕様なしにタスクを割り当ててはいけません。タスクを完了としてマークする前に、両方のレビューゲートに合格する必要があります。

次のように考えていることに気づいたら：

• 「実装は十分よさそうだ……」— 両方のレビューゲートを必ず実行してください。
• 「仕様レビューは形式的なものにすぎない……」— 仕様からの逸脱は統合の失敗につながります。レビューを実施してください。
• 「3 回の再試行は多すぎる。もう受け入れよう……」— 3 回失敗したらエスカレーションしてください。基準を下げてはいけません。

---

統合ポイント

スキル	関係	タイミング
planning	上流 — タスクを含む承認済み計画を提供	タスクの起点
executing-plans	上流 — このスキルに委任する場合がある	計画内の独立したタスク
test-driven-development	タスクごと — 実装担当者が TDD に従う	フェーズ 2 の実装
verification-before-completion	受け入れ後 — 最終検証	フェーズ 6 の統合
code-review	補完的 — 品質レビューゲート	フェーズ 4 の品質レビュー
dispatching-parallel-agents	補完的 — 並列化の戦略	独立したタスクを割り当てるとき
resilient-execution	失敗時 — 再試行の戦略	修正サイクルを使い切ったとき
task-management	追跡 — タスクのステータス管理	進捗の追跡
Agent ツール	すべてのサブエージェントのフェーズにおける割り当ての仕組み

---

具体例

例：サブエージェント向けタスク仕様

TASK SPECIFICATION
==================
1. Description: Implement user registration endpoint with email validation

2. Files:
   - Create: src/routes/auth/register.ts
   - Create: tests/routes/auth/register.test.ts
   - Modify: src/routes/index.ts (add route import)

3. Acceptance Criteria:
   - POST /api/auth/register accepts { email, password, name }
   - Returns 201 with user object (no password) on success
   - Returns 400 if email format is invalid
   - Returns 409 if email already exists
   - Password is hashed before storage

4. TDD Requirements:
   - Test: valid registration returns 201
   - Test: invalid email returns 400
   - Test: duplicate email returns 409
   - Test: password is not in response body
   - Test: password is hashed in database

5. Quality Standards:
   - Follow route pattern in src/routes/auth/login.ts
   - Use Zod for input validation (existing pattern)
   - Use Result<T, E> type for service errors

6. Context:
   - Auth service: src/services/auth.ts (has hashPassword method)
   - Route pattern: see src/routes/auth/login.ts
   - Zod schemas: see src/schemas/auth.ts

7. Constraints:
   - Do NOT modify auth service
   - Do NOT add new dependencies
   - Do NOT create migration files

---

プロンプトテンプレート

このスキルでは、3つのプロンプトテンプレートを使用します。

テンプレート	目的	ファイル
実装者プロンプト	実装作業を割り当てます	implementer-prompt.md
仕様レビュアープロンプト	タスク仕様に照らしてレビューします	spec-reviewer-prompt.md
品質レビュアープロンプト	コード品質をレビューします	code-quality-reviewer-prompt.md

各テンプレートでは、サブエージェントとのやり取りに構造化された形式を使用します。詳細については、各ファイルを参照してください。

---

スキルの種類

厳格 — このプロセスに厳密に従ってください。仕様の7つのセクションはすべて必須です。2つのレビューステップも必須です。再試行は最大3回で、これも必須です。近道は認められません。