| name | subagent-driven-development |
| description | 実装計画のタスクをサブエージェントに委譲し、spec準拠+品質の2段階レビューで品質を担保する。Use when: 「この実装をエージェントに任せたい」「サブエージェントで実装して」「タスクを分割して並列実行したい」「大きな実装タスクの分割実行」「並列開発」。計画作成にはai-dev-workflowを使用。 |
Subagent-Driven Development
実装計画の各タスクを専門サブエージェントに委譲し、2段階レビュー(spec準拠+品質)で高品質な実装を高速に回す。
Iron Law
NO MERGE WITHOUT TWO-STAGE REVIEW
Spec Reviewerによる仕様準拠確認とQuality Reviewerによる品質確認の両方を通過しない限り、タスクを完了としない。
Common Rationalizations
| こう思ったら | 現実 |
|---|
| 「Spec Reviewは実装者を信頼してスキップ」 | 信頼とレビューは別。2段階は必須 |
| 「小さい修正だからQuality Review不要」 | 小さい修正こそバグが潜む。スキップ禁止 |
| 「前のタスクと同じパターンだからレビュー軽め」 | 各タスクは独立評価。前回の結果は根拠にならない |
核心原則: Fresh subagent per task + two-stage review = high quality, fast iteration
プロセス概要
Plan読み込み → タスク抽出 → 各タスクについて:
1. Implementerサブエージェント派遣
2. Spec Reviewerサブエージェント派遣
3. (問題あれば) Implementer修正 → 再レビュー
4. Quality Reviewerサブエージェント派遣
5. (問題あれば) Implementer修正 → 再レビュー
6. タスク完了 → 次のタスクへ
→ 全タスク完了後、最終統合レビュー
Step 1: 計画読み込みとタスク抽出
plan.md と todo.md を読む
- 各タスクに以下の情報を付与:
- 変更対象ファイル
- 受入基準(specから該当部分を抽出)
- 依存関係(前のタスクの完了が必要か)
- 推奨モデル(複雑度に応じて選択)
モデル選択ガイド
| タスク複雑度 | 推奨 | 例 |
|---|
| 低(機械的) | haiku | 単純なCRUD、テンプレート適用 |
| 中(統合) | sonnet | API連携、コンポーネント結合 |
| 高(設計判断) | opus | アーキテクチャ決定、複雑なロジック |
Step 2: Implementerサブエージェント派遣
各タスクに対して、以下の情報を含むプロンプトでサブエージェントを起動:
タスク: {タスク名}
スコープ: {変更対象ファイル}
受入基準: {具体的な基準}
既存パターン: {プロジェクトの既存実装パターン}
制約: {アーキテクチャ構造、依存方向、命名規則}
Implementerのルール:
- 不明点があれば実装前に質問する(推測で進めない)
- 既存パターンに従う
- テストを含める
- 実装後にセルフレビューを行う
Step 3: Spec Reviewerサブエージェント派遣
Implementerの成果物に対して、spec準拠レビューを実施:
チェック項目:
□ 受入基準を全て満たしているか
□ スコープ外の変更がないか
□ 既存のAPIコントラクトを破壊していないか
□ テストが受入基準をカバーしているか
判定: PASS / FAIL(修正必須箇所を明示)
FAIL → Implementerに差し戻し → 修正 → 再レビュー
Step 4: Quality Reviewerサブエージェント派遣
Spec PASSした成果物に対して、コード品質レビューを実施:
チェック項目:
□ アーキテクチャ原則の遵守(レイヤー間依存方向)
□ 命名の一貫性
□ エラーハンドリング
□ パフォーマンス(N+1クエリ、不要なデータ取得)
□ セキュリティ(入力バリデーション、認証・認可)
□ テスト品質(境界値、異常系)
判定: PASS / WARN(改善提案)/ FAIL(修正必須)
FAIL → Implementerに差し戻し → 修正 → 再レビュー
Step 5: 最終統合レビュー
全タスク完了後:
- 全変更ファイルの統合的なレビュー
- コンフリクトの確認
- プロジェクトの検証コマンド実行(lint/test/typecheck)
todo.md の全チェック更新
重要ルール
- レビューをスキップしない: 「close enough」でspec準拠を妥協しない
- ブロッカーは即停止: 依存関係の問題、テスト失敗、不明点は即座にユーザーに報告
- worktreeで隔離: 可能な場合はgit worktreeで作業を隔離する
- mainブランチでは作業しない: ユーザー同意なしにmainで作業開始しない
ファイルベース復元(#581 要素3)
実装者・reviewer への受け渡しは会話履歴でなく dispatch/ 配下のファイル(brief / report / review-package / progress-ledger)で行う。compaction・モデル切替後は progress-ledger.md から再開し、完了済みタスクの再実行・要件の曖昧化・責務の混在を防ぐ。テンプレは docs/working/templates/dispatch/。
worktree 委託の安全ルール定型(委託プロンプト必須要素)
worktree で隔離したサブエージェントへ実装を委託する際、委託プロンプトには
以下 6 要素を必ず含める。要素を欠いた委託は git 事故(誤ブランチ・意図しない
巻き込み・push 失敗の見落とし)につながる。
- ブランチ作成元の明示:
origin/main(スタック構成で前段ブランチに
依存する場合はその前段ブランチ)から新規ブランチを作成させ、base を
コマンドとして明示する(例: git fetch && git checkout -b <new> origin/main。fetch 前置は responsibility-classes.md の base verify 節が正本)
- 変更可能パスの限定列挙: 触ってよいファイル・ディレクトリを具体パスで
列挙する(
allowed_files 相当)。曖昧な「関連ファイル」等の指定は禁止
- commit 前後の検証手順: commit 前に
git diff --cached --stat で
staged 内容を確認させ、git add は明示パスのみ(-A / . 禁止)とする。
push 前に git branch -vv で current branch を verify させる
- ツールブロック時の回避手順:
Write が EPERM で失敗する場合は
python3 で open(...) + 一時ファイル書き込み + shutil.copy2 へ回避する。
EH-3 でブロックされる場合は Bash heredoc、または
PLANGATE_SKIP_REASON を用いた明示的スキップで回避する
- lint コマンドの指定:
npx markdownlint-cli2(CI 実体と同一)を使わせる。
素の markdownlint-cli は設定ファイルの解釈が異なり CI と結果が食い違う
ため使用しない
- 返答形式の指定: commit SHA・変更ファイル一覧・検証結果に加え、
仕様から逸脱した点・実装中に迷った点を必須報告項目とする(自己申告
なしの「完了しました」報告を許容しない)
統合責任者チェックリスト
委託成果物を受け取った側(統合責任者)は、以下を独立検証する。委託
エージェントの自己申告のみを根拠に完了とみなさない:
委託の要否判断は subagent-economy の基準(複雑さ判断が先・同時委託は
最大 3 体まで)に従う。1 エージェントで完結する小タスクに委託は不要。
関連スキル
- ai-dev-workflow: 計画生成(plan/todo)に使用
- brainstorming: 要件整理に使用
- find-bugs: 最終品質チェックに使用