subagent-driven-development

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

概要

各タスクごとに新しいサブエージェントを起動し、体系的な2段階レビューを実施して実装計画を実行します。

基本原則： タスクごとに新しいサブエージェントを割り当て、2段階レビュー（仕様確認、その後に品質確認）を行うことで、高品質かつ迅速に反復できます。

使用するタイミング

次のような場合にこのスキルを使用します。

• 実装計画がある（plan スキルまたはユーザーの要件から作成）
• タスクの大部分が独立している
• 品質と仕様への準拠が重要
• タスク間で自動レビューを行いたい

手動で実行する場合との違い：

• タスクごとに新しいコンテキストを使用します（蓄積した状態による混乱を防ぎます）
• 自動レビューのプロセスで問題を早期に発見します
• すべてのタスクで一貫した品質チェックを実施します
• サブエージェントは作業開始前に質問できます

プロセス

1. 計画を読み、解析する

計画ファイルを読み込みます。すべてのタスクを全文とコンテキストを含めて事前に抽出します。ToDo リストを作成します。

# Read the plan
read_file("docs/plans/feature-plan.md")

# Create todo list with all tasks
todo([
    {"id": "task-1", "content": "Create User model with email field", "status": "pending"},
    {"id": "task-2", "content": "Add password hashing utility", "status": "pending"},
    {"id": "task-3", "content": "Create login endpoint", "status": "pending"},
])

重要： 計画は一度だけ読みます。必要な情報をすべて抽出します。サブエージェントには計画ファイルを読ませず、タスクの全文を直接コンテキストに含めて渡します。

2. タスクごとのワークフロー

計画内の各タスクについて、次の手順を実行します。

ステップ 1：実装サブエージェントを起動する

完全なコンテキストを指定して delegate_task を使用します。

delegate_task(
    goal="Implement Task 1: Create User model with email and password_hash fields",
    context="""
    TASK FROM PLAN:
    - Create: src/models/user.py
    - Add User class with email (str) and password_hash (str) fields
    - Use bcrypt for password hashing
    - Include __repr__ for debugging

    FOLLOW TDD:
    1. Write failing test in tests/models/test_user.py
    2. Run: pytest tests/models/test_user.py -v (verify FAIL)
    3. Write minimal implementation
    4. Run: pytest tests/models/test_user.py -v (verify PASS)
    5. Run: pytest tests/ -q (verify no regressions)
    6. Commit: git add -A && git commit -m "feat: add User model with password hashing"

    PROJECT CONTEXT:
    - Python 3.11, Flask app in src/app.py
    - Existing models in src/models/
    - Tests use pytest, run from project root
    - bcrypt already in requirements.txt
    """,
    toolsets=['terminal', 'file']
)

ステップ 2：仕様準拠レビュアーを起動する

実装サブエージェントの作業完了後、元の仕様に照らして確認します。

delegate_task(
    goal="Review if implementation matches the spec from the plan",
    context="""
    ORIGINAL TASK SPEC:
    - Create src/models/user.py with User class
    - Fields: email (str), password_hash (str)
    - Use bcrypt for password hashing
    - Include __repr__

    CHECK:
    - [ ] All requirements from spec implemented?
    - [ ] File paths match spec?
    - [ ] Function signatures match spec?
    - [ ] Behavior matches expected?
    - [ ] Nothing extra added (no scope creep)?

    OUTPUT: PASS or list of specific spec gaps to fix.
    """,
    toolsets=['file']
)

仕様上の問題が見つかった場合： 不足箇所を修正してから、仕様レビューを再実行します。仕様に準拠するまで次に進みません。

ステップ 3：コード品質レビュアーを起動する

仕様準拠の確認に合格した後に実施します。

delegate_task(
    goal="Review code quality for Task 1 implementation",
    context="""
    FILES TO REVIEW:
    - src/models/user.py
    - tests/models/test_user.py

    CHECK:
    - [ ] Follows project conventions and style?
    - [ ] Proper error handling?
    - [ ] Clear variable/function names?
    - [ ] Adequate test coverage?
    - [ ] No obvious bugs or missed edge cases?
    - [ ] No security issues?

    OUTPUT FORMAT:
    - Critical Issues: [must fix before proceeding]
    - Important Issues: [should fix]
    - Minor Issues: [optional]
    - Verdict: APPROVED or REQUEST_CHANGES
    """,
    toolsets=['file']
)

品質上の問題が見つかった場合： 問題を修正し、再レビューします。承認されるまで次に進みません。

ステップ 4：完了としてマークする

todo([{"id": "task-1", "content": "Create User model with email field", "status": "completed"}], merge=True)

3. 最終レビュー

すべてのタスクが完了した後、最終統合レビュアーを起動します。

delegate_task(
    goal="Review the entire implementation for consistency and integration issues",
    context="""
    All tasks from the plan are complete. Review the full implementation:
    - Do all components work together?
    - Any inconsistencies between tasks?
    - All tests passing?
    - Ready for merge?
    """,
    toolsets=['terminal', 'file']
)

4. 検証してコミットする

# Run full test suite
pytest tests/ -q

# Review all changes
git diff --stat

# Final commit if needed
git add -A && git commit -m "feat: complete [feature name] implementation"

タスクの粒度

各タスクは、2～5分で集中して取り組める規模にします。

大きすぎる例：

• 「ユーザー認証システムを実装する」

適切な規模の例：

• 「メールアドレスとパスワードのフィールドを持つ User モデルを作成する」
• 「パスワードのハッシュ化関数を追加する」
• 「ログインエンドポイントを作成する」
• 「JWT トークンの生成機能を追加する」
• 「登録エンドポイントを作成する」

注意事項 — 次のことは絶対にしないでください

• 計画なしで実装を始める
• レビュー（仕様準拠またはコード品質）を省略する
• 重大または重要な問題を修正せずに進める
• 同じファイルを変更するタスクに、複数の実装サブエージェントを起動する
• サブエージェントに計画ファイルを読ませる（代わりに全文をコンテキストに含めて渡す）
• 前提となるコンテキストの説明を省略する（サブエージェントはタスクの位置づけを理解する必要があります）
• サブエージェントの質問を無視する（作業を進める前に回答する）
• 仕様準拠について「だいたい合っている」で済ませる
• レビューの反復を省略する（レビュアーが問題を発見 → 実装担当が修正 → 再レビュー）
• 実装担当の自己レビューを実際のレビューの代わりにする（どちらも必要です）
• 仕様準拠が PASS になる前にコード品質レビューを始める（順序が間違っています）
• どちらかのレビューで未解決の問題があるまま次のタスクに進む

問題への対応

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

• 明確かつ漏れなく回答します
• 必要に応じて追加のコンテキストを提供します
• 実装を急がせないでください

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

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

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

• 問題点を具体的に伝えて、新しい修正サブエージェントを起動します
• コントローラーのセッションで手動修正しないでください（コンテキストが汚染されます）

効率に関する補足

タスクごとに新しいサブエージェントを使用する理由：

• 蓄積した状態によるコンテキストの汚染を防ぎます
• 各サブエージェントがクリーンで焦点の絞られたコンテキストを得られます
• 先行タスクのコードや推論による混乱がありません

2段階レビューを行う理由：

• 仕様レビューで、作り込み不足や過剰な実装を早期に発見できます
• 品質レビューで、実装が適切に構築されていることを確認できます
• 問題が複数のタスクに波及する前に発見できます

コストとのトレードオフ：

• サブエージェントの起動回数が増えます（タスクごとに実装担当1回、レビュアー2回）
• ただし、問題を早期に発見できるため、問題が積み重なった後にデバッグするよりコストを抑えられます

他のスキルとの連携

プランと併用する場合

このスキルは plan スキルが作成したプランを実行します：

1. ユーザー要件 → プラン → 実装プラン
2. 実装プラン → サブエージェント駆動開発 → 動作するコード

テスト駆動開発と併用する場合

実装担当のサブエージェントは TDD に従う必要があります：

1. まず失敗するテストを書く
2. 最小限のコードを実装する
3. テストが成功することを確認する
4. コミットする

すべての実装担当のコンテキストに TDD の指示を含めてください。

コードレビューの依頼と併用する場合

2段階のレビュープロセスがコードレビューそのものです。最終的な統合レビューでは、コードレビュー依頼スキルのレビュー観点を使用してください。

システムデバッグと併用する場合

実装中にサブエージェントがバグに遭遇した場合：

1. システムデバッグのプロセスに従う
2. 修正する前に根本原因を特定する
3. 回帰テストを書く
4. 実装を再開する

ワークフローの例

[Read plan: docs/plans/auth-feature.md]
[Create todo list with 5 tasks]

--- Task 1: Create User model ---
[Dispatch implementer subagent]
  Implementer: "Should email be unique?"
  You: "Yes, email must be unique"
  Implementer: Implemented, 3/3 tests passing, committed.

[Dispatch spec reviewer]
  Spec reviewer: ✅ PASS — all requirements met

[Dispatch quality reviewer]
  Quality reviewer: ✅ APPROVED — clean code, good tests

[Mark Task 1 complete]

--- Task 2: Password hashing ---
[Dispatch implementer subagent]
  Implementer: No questions, implemented, 5/5 tests passing.

[Dispatch spec reviewer]
  Spec reviewer: ❌ Missing: password strength validation (spec says "min 8 chars")

[Implementer fixes]
  Implementer: Added validation, 7/7 tests passing.

[Dispatch spec reviewer again]
  Spec reviewer: ✅ PASS

[Dispatch quality reviewer]
  Quality reviewer: Important: Magic number 8, extract to constant
  Implementer: Extracted MIN_PASSWORD_LENGTH constant
  Quality reviewer: ✅ APPROVED

[Mark Task 2 complete]

... (continue for all tasks)

[After all tasks: dispatch final integration reviewer]
[Run full test suite: all passing]
[Done!]

覚えておくこと

Fresh subagent per task
Two-stage review every time
Spec compliance FIRST
Code quality SECOND
Never skip reviews
Catch issues early

品質は偶然ではありません。それは体系的なプロセスの結果です。

参考資料（必要に応じて読み込む）

オーケストレーションで大量のコンテキストを使用する場合、長いレビューループ、または複雑な検証チェックポイントが含まれる場合は、それぞれの規律について以下のリファレンスを読み込んでください：

• references/context-budget-discipline.md — 4段階のコンテキスト劣化モデル（PEAK / GOOD / DEGRADING / POOR）、コンテキストウィンドウのサイズに応じて拡張される読み込み深度のルール、およびサイレント劣化の初期警告サイン。実行時に明らかに大量のコンテキストを消費する場合（多段階プラン、多数のサブエージェント、大きな成果物など）に読み込んでください。
• references/gates-taxonomy.md — 4つの標準的なゲートタイプ（Pre-flight、Revision、Escalation、Abort）とその動作、リカバリ、および例。検証チェックポイントを持つワークフローを設計またはレビューする際に読み込んでください。語彙を明示的に使用し、各ゲートに定義された entry、failure behavior、resumption rules を持たせてください。

両リファレンスは gsd-build/get-shit-done（MIT © 2025 Lex Christopherson）から改変したものです。