subagent-driven-development

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

タスクや課題ごとに新しいサブエージェントを割り当てて計画を作成・実行し、各タスクまたはタスク群の完了後にコードと出力をレビューします。

基本原則： タスクごとに新しいサブエージェントを割り当て、タスク間またはタスク後にレビューすることで、高品質かつ迅速に反復できます。

エージェントを使った計画の実行：

• 同じセッション内で実行（コンテキストの切り替えなし）
• タスクごとに新しいサブエージェントを使用（コンテキストの汚染なし）
• 各タスクまたはタスク群の完了後にコードレビューを実施（問題を早期に発見）
• より迅速に反復（タスク間で人間が介在しない）

対応している実行方式

順次実行

互いに関連し、順番に実行する必要があるタスクや課題は、順次調査または変更するのが最適です。

タスクまたは課題ごとにエージェントを 1 つ割り当てます。順次作業させ、各タスクまたは課題の完了後に出力とコードをレビューします。

使用する場面：

• タスク同士が密接に関連している
• タスクを順番に実行する必要がある

並列実行

互いに関連のない複数のタスクや課題（異なるファイル、異なるサブシステム、異なるバグ）がある場合、順次調査または変更すると時間が無駄になります。それぞれのタスクや調査は独立しており、並列に進められます。

独立した問題領域ごとにエージェントを 1 つ割り当て、並行して作業させます。

使用する場面：

• タスクの大部分が独立している
• すべてのタスク完了後にまとめてレビューできる

順次実行の手順

1. 計画を読み込む

計画ファイルを読み、すべてのタスクを含む TodoWrite を作成します。

2. サブエージェントでタスクを実行する

各タスクについて：

新しいサブエージェントを割り当てます：

Task tool (general-purpose):
  description: "Implement Task N: [task name]"
  prompt: |
    You are implementing Task N from [plan-file].

    Read that task carefully. Your job is to:
    1. Implement exactly what the task specifies
    2. Write tests (following TDD if task says to)
    3. Verify implementation works
    4. Commit your work
    5. Report back

    Work from: [directory]

    Report: What you implemented, what you tested, test results, files changed, any issues

サブエージェントが作業の概要を報告します。

3. サブエージェントの作業をレビューする

コードレビュアーのサブエージェントを割り当てます：

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

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

コードレビュアーが返す内容： 強み、問題点（重大／重要／軽微）、評価

4. レビューのフィードバックを反映する

問題が見つかった場合：

• 重大な問題は直ちに修正します
• 重要な問題は次のタスクに進む前に修正します
• 軽微な問題は記録します

必要に応じて、後続のサブエージェントを割り当てます：

"Fix issues from code review: [list issues]"

5. タスクを完了にし、次のタスクに進む

• TodoWrite でタスクを完了としてマークします
• 次のタスクに進みます
• 手順 2～5 を繰り返します

6. 最終レビュー

すべてのタスクが完了したら、最終コードレビュアーを割り当てます：

• 実装全体をレビューします
• 計画のすべての要件が満たされていることを確認します
• アーキテクチャ全体を検証します

7. 開発を完了する

最終レビューに合格したら：

• 「作業を完了するために finishing-a-development-branch スキルを使用します」と宣言します
• 必須のサブスキル： superpowers:finishing-a-development-branch を使用します
• そのスキルに従ってテストを検証し、選択肢を提示して、選択された作業を実行します

ワークフローの例

You: I'm using Subagent-Driven Development to execute this plan.

[Load plan, create TodoWrite]

Task 1: Hook installation script

[Dispatch implementation subagent]
Subagent: Implemented install-hook with tests, 5/5 passing

[Get git SHAs, dispatch code-reviewer]
Reviewer: Strengths: Good test coverage. Issues: None. Ready.

[Mark Task 1 complete]

Task 2: Recovery modes

[Dispatch implementation subagent]
Subagent: Added verify/repair, 8/8 tests passing

[Dispatch code-reviewer]
Reviewer: Strengths: Solid. Issues (Important): Missing progress reporting

[Dispatch fix subagent]
Fix subagent: Added progress every 100 conversations

[Verify fix, mark Task 2 complete]

...

[After all tasks]
[Dispatch final code-reviewer]
Final reviewer: All requirements met, ready to merge

Done!

要注意事項

次のことは決して行わないでください：

• タスク間のコードレビューを省略する
• 未修正の重大な問題があるまま先に進む
• 複数の実装用サブエージェントを並列に割り当てる（競合が発生します）
• 計画のタスクを読まずに実装する

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

• 具体的な指示を添えて修正用サブエージェントを割り当てます
• 自分で修正しようとしないでください（コンテキストが汚染されます）

並列実行の手順

計画を読み込み、厳密にレビューし、タスクをバッチに分けて実行し、バッチごとにレビューを依頼します。

基本原則： バッチを実行し、アーキテクトのレビュー用チェックポイントを設けます。

開始時に宣言： 「この計画を実装するために executing-plans スキルを使用します。」

ステップ 1：計画を読み込み、レビューする

1. 計画ファイルを読む
2. 計画を厳密にレビューし、質問や懸念事項を特定する
3. 懸念がある場合：開始前に人間のパートナーに伝える
4. 懸念がない場合：TodoWrite を作成して進む

ステップ 2：バッチを実行する

既定：最初の 3 タスク

各タスクについて：

1. in_progress としてマークする
2. 各手順を正確に実行する（計画には細分化された手順があります）
3. 指定された検証を実行する
4. completed としてマークする

ステップ 3：報告する

バッチの完了時：

• 実装した内容を示す
• 検証結果を示す
• 「フィードバックをお待ちしています」と伝える

ステップ 4：続行する

フィードバックに基づいて：

• 必要に応じて変更を反映する
• 次のバッチを実行する
• 完了するまで繰り返す

ステップ 5：開発を完了する

すべてのタスクが完了し、検証されたら：

• 「開発ブランチを完了するスキルを使用して、この作業を完了します。」と宣言します。
• 必須サブスキル： superpowers:finishing-a-development-branch を使用します
• そのスキルに従って、テストを検証し、選択肢を提示して、選ばれた項目を実行します

停止して助けを求めるタイミング

次の場合は、直ちに実行を停止してください：

• バッチの途中でブロッカーに遭遇した（依存関係がない、テストが失敗する、指示が不明確など）
• 計画に重大な欠落があり、開始できない
• 指示を理解できない
• 検証が繰り返し失敗する

推測するのではなく、説明を求めてください。

以前のステップを再確認するタイミング

次の場合は、レビュー（ステップ 1）に戻ってください：

• パートナーがフィードバックに基づいて計画を更新した
• 根本的なアプローチを再考する必要がある

ブロッカーを無理に突破しないでください。停止して質問してください。

覚えておくこと

• まず計画を批判的にレビューする
• 計画の手順に正確に従う
• 検証を省略しない
• 計画で指示されている場合は、スキルを参照する
• バッチの間は、報告して待つだけにする
• ブロックされたら停止し、推測しない

並列調査プロセス

共有状態や依存関係のない、複数の無関係な失敗を調査できる場合の、並列実行の特殊ケースです。

1. 独立した領域を特定する

問題の内容ごとに失敗をグループ化します：

• ファイル A のテスト：ツールの承認フロー
• ファイル B のテスト：バッチ完了の動作
• ファイル C のテスト：中止機能

それぞれの領域は独立しています。ツールの承認を修正しても、中止のテストには影響しません。

2. エージェントに絞り込んだタスクを作成する

各エージェントに次の内容を割り当てます：

• 具体的な範囲： 1 つのテストファイルまたはサブシステム
• 明確な目標： 対象のテストを通過させる
• 制約： 他のコードは変更しない
• 期待する出力： 発見した内容と修正内容の概要

3. 並列に割り当てる

// In Claude Code / AI environment
Task("Fix agent-tool-abort.test.ts failures")
Task("Fix batch-completion-behavior.test.ts failures")
Task("Fix tool-approval-race-conditions.test.ts failures")
// All three run concurrently

4. レビューして統合する

エージェントから返答があったら：

• 各概要を読む
• 修正が互いに競合しないことを確認する
• テストスイート全体を実行する
• すべての変更を統合する

エージェントプロンプトの構成

適切なエージェントプロンプトは、次の条件を満たします：

1. 焦点が絞られている - 問題領域が 1 つに明確化されている
2. 自己完結している - 問題を理解するために必要なコンテキストがすべて含まれている
3. 出力が具体的である - エージェントが何を返すべきか明確になっている

Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:

1. "should abort tool with partial output capture" - expects 'interrupted at' in message
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "should properly track pendingToolCount" - expects 3 results but gets 0

These are timing/race condition issues. Your task:

1. Read the test file and understand what each test verifies
2. Identify root cause - timing issues or actual bugs?
3. Fix by:
   - Replacing arbitrary timeouts with event-based waiting
   - Fixing bugs in abort implementation if found
   - Adjusting test expectations if testing changed behavior

Do NOT just increase timeouts - find the real issue.

Return: Summary of what you found and what you fixed.

よくある間違い

❌ 範囲が広すぎる：「すべてのテストを修正して」 - エージェントは迷ってしまいます
✅ 具体的：「agent-tool-abort.test.ts を修正して」 - 範囲が絞られています

❌ コンテキストがない：「競合状態を修正して」 - エージェントには場所がわかりません
✅ コンテキストがある： エラーメッセージとテスト名を貼り付けます

❌ 制約がない： エージェントがすべてをリファクタリングする可能性があります
✅ 制約がある：「本番コードは変更しないでください」または「テストのみを修正してください」

❌ 出力が曖昧：「修正して」 - 何が変更されたかわかりません
✅ 具体的：「根本原因と変更内容の概要を返してください」

使用しない場合

関連する失敗： 1 つの修正で他も直る可能性があります。まず一緒に調査してください
全体的なコンテキストが必要： 理解するにはシステム全体を見る必要があります
探索的なデバッグ： 何が壊れているのか、まだわかっていません
共有状態： エージェント同士が干渉します（同じファイルの編集、同じリソースの使用など）

セッションの実例

シナリオ： 大規模なリファクタリング後、3 つのファイルで 6 件のテストが失敗

失敗：

• agent-tool-abort.test.ts：3 件の失敗（タイミングの問題）
• batch-completion-behavior.test.ts：2 件の失敗（ツールが実行されない）
• tool-approval-race-conditions.test.ts：1 件の失敗（実行回数 = 0）

判断： 独立した領域です。中止のロジック、バッチ完了、競合状態はそれぞれ別の問題です。

割り当て：

Agent 1 → Fix agent-tool-abort.test.ts
Agent 2 → Fix batch-completion-behavior.test.ts
Agent 3 → Fix tool-approval-race-conditions.test.ts

結果：

• エージェント 1：タイムアウトをイベントベースの待機に置き換えました
• エージェント 2：イベント構造のバグを修正しました（threadId の位置が誤っていました）
• エージェント 3：非同期のツール実行が完了するまで待機する処理を追加しました

統合： すべての修正は独立しており、競合はなく、テストスイート全体が成功しました

節約できた時間： 3 つの問題を順次ではなく並列に解決しました

#検証

エージェントの作業が完了したら：

1. 各サマリーを確認する - 何が変更されたかを把握します
2. 競合を確認する - エージェントが同じコードを編集していないか確認します
3. 全テストスイートを実行する - すべての修正が連携して動作することを検証します
4. 抜き取り確認を行う - エージェントは体系的な誤りを犯すことがあります