⚡
★ 86.6k

実行とSubagent

各タスクは新鮮なコンテキストで実行されます。汚染なし。仮定なし。引き継がれた混乱なし。

なぜ新鮮なSubagentが必要なのか

AIエージェントが長いタスクに取り組むとき、コンテキストが蓄積されます—以前の決定、以前のエラー、1時間前のステップからの半ば形成された仮定。タスク15に到達するころには、タスク1から14で起きたすべてのことによって微妙に（または明らかに）影響を受けている可能性があります。

これはコンテキスト汚染と呼ばれ、AI支援開発における連鎖的な失敗の主な原因の一つです。タスク3での誤解が静かに広がります。タスク7で行われた誤った仮定が、タスク8、9、10で書かれたコードに影響します。何かが間違っていることに誰かが気づくころには、それを解きほぐすのは高コストです。

Superpowersはこれをsubagentで解決します：以前のタスクの記憶を持たない新鮮なAIインスタンスです。各タスクはクリーンなコンテキストにディスパッチされます。以前に何が起きたかは存在しません。subagentはタスクを読み、関連するコードを読み、タスクが言うことを正確に実行します—それ以上でも以下でもありません。

コンテキスト分離の3つのメリット

  1. エラー伝播なし — タスク3のミスはタスク4に影響しません。各タスクは独自に成功または失敗します。

  2. 偏りのないレビュー — 完了したタスクをレビューするエージェントは、レビューするコードへの執着がありません。それを書いていません。問題を合理化する理由がありません。

  3. 並列実行の安全性 — 互いに依存しないタスクは同時にディスパッチできます。新鮮なコンテキストは競合しません。

コントローラープロセス

コントローラーは主要なオーケストレーションエージェントです—計画実行ループを管理します。仕組みは次の通りです：

┌──────────────────────────────────────────────────────────────┐
│                     CONTROLLER LOOP                          │
│                                                              │
│  1. 計画を読み込む → 次のPENDINGタスクを特定する             │
│  2. subagentをディスパッチ：タスク説明 + 関連コード          │
│  3. subagentがタスクを完了 → 結果 + ステータスを返す         │
│  4. コントローラーが2段階レビューを実行する                  │
│  5. ステータスを処理する：                                   │
│     DONE           → タスクを完了としてマーク、続行          │
│     DONE_WITH_CONCERNS → ログに記録し、注記付きで続行        │
│     NEEDS_CONTEXT  → コンテキストを収集し、再ディスパッチ    │
│     BLOCKED        → 停止し、ユーザーにエスカレーション      │
└──────────────────────────────────────────────────────────────┘

計画の読み込み

コントローラーは完全な計画ドキュメントを読み、Status: PENDINGの最初のタスクを特定します。先にスキップせず、順序を変えず、効率のためにタスクを「結合」しようとしません。計画は契約です—コントローラーは契約を実行します。

subagentのディスパッチ

コントローラーはsubagentが必要とする情報を正確に渡してsubagentを作成します：

  • タスクの説明
  • 書くべき正確なコード（計画から）
  • 修正する正確なファイル
  • 実行する正確なコマンド

余分なものは何もありません。以前のタスクの履歴はありません（タスクがコンテキストとして明示的に必要としない限り）。subagentの仕事は一つのタスクをクリーンに実行することです。

2段階レビュー

subagentがタスクを完了した後、コントローラーはすぐに結果を受け入れません。2段階レビューを実行します：

ステージ1：仕様準拠

「subagentはタスクが指定したものを構築したか？」

コントローラーはsubagentの出力をタスクの説明と比較します：

  • 正しいファイルが修正されたか？
  • 正しいシグネチャで正しい関数が作成されたか？
  • 必要なテストが書かれたか？
  • スコープ外の変更が行われたか？

出力が仕様に一致しない場合、タスクは完了ではありません。コントローラーは逸脱を記録し、明確化して再ディスパッチするか、ユーザーにエスカレーションします。

ステージ2：コード品質

「コードは正確で、読みやすく、保守可能か？」

これは仕様準拠とは独立して評価されます。subagentは仕様を完全に一致させながらも、貧弱なコードを生成する可能性があります：

  • 明らかなケースのエラーハンドリングの欠如
  • 指定されたテストを通過するが誤ったロジック
  • コードベースに一致しない命名規則
  • セキュリティの問題

コード品質の懸念は準拠の問題とは別にログに記録されます。タスクはDONE_WITH_CONCERNSになる可能性があります—技術的には完了しているが、レビュアーが対処すべき注記があります。

ステータスプロトコル

完了したすべてのタスクは4つのステータスのいずれかを返します：

DONE

タスクは完了です。コードは仕様に一致します。品質は許容可能です。懸念なし。次のタスクに続きます。

DONE_WITH_CONCERNS

タスクは技術的に完了でテストは通過していますが、レビューエージェントが人間の注意に値するものをフラグしました。例：

  • 実装は動作するが非推奨のAPIを使用している
  • テストカバレッジは技術的に通過しているが弱い
  • 軽微な命名の不一致が導入された

作業は続きますが、懸念は計画の終了時または次のレビューチェックポイントで人間がレビューするためにログに記録されます。

NEEDS_CONTEXT

提供された情報ではsubagentが解決できないものに遭遇したため、タスクを完了できませんでした。これは失敗ではありません—より多くの情報が必要であるという正直な報告です。例：

  • 指定されたファイルが存在せず、タスクは作成するよう指示していない
  • インポートされたモジュールがコードベースにない
  • タスクが参照する関数シグネチャが存在するものと一致しない

コントローラーは不足しているコンテキストを収集し、再ディスパッチします。

BLOCKED

進行を妨げる根本的な問題があります。例：

  • 依存タスクがDONEとマークされたが、作成されるはずだったコードが存在しない
  • 現在のタスクでは説明できない方法でテストが失敗している
  • 計画の設計上の仮定が誤っていることが判明した

タスクがBLOCKEDを返した場合、コントローラーは実行を停止してユーザーにエスカレーションします。これはAIが計画レベルの問題について一方的な決定を行うのを防ぐ強制関数です。

複雑さによるモデル選択

すべてのタスクが同じレベルのAI能力を必要とするわけではありません。Superpowersはタスクの複雑さをモデルの層に合わせることを推奨します：

タスクタイプ例推奨モデル層
機械的importの追加、変数名の変更、config値の更新小型/高速モデル
統合2つの既存システムの接続、新しいAPI endpointの追加中間層モデル
アーキテクチャ新しい抽象化の設計、コアデータモデルのリファクタリング最も能力の高いモデル

機械的なタスクに小型モデルを使用するとコストとレイテンシが削減されます。アーキテクチャに最も能力の高いモデルを使用すると、重要な決定が最高の推論を得られます。タスクの複雑さは通常、計画に記述されているか、タスクの説明から推測できます。

並列エージェントのディスパッチ

計画の中には独立したタスクもあります—タスク4の完了はタスク5が完了していることに依存しません。これらの場合、コントローラーは複数のsubagentを同時にディスパッチできます。

並列ディスパッチのルール

  1. 共有状態なし — 並列で実行されるタスクは同じファイルに書き込んだり、同じデータベースレコードを変更したりしてはならない
  2. 順序依存なし — タスクBは並列で実行される場合、タスクAの出力を必要としてはならない
  3. 明示的な宣言 — 並列タスクは計画に記載されるべき（[PARALLEL_GROUP: A]）。コントローラーが一緒に実行しても安全であることを知るために
  4. レビューは引き続き適用 — 各並列タスクは完了時に独立して2段階レビューを経る
### タスク6：auth middlewareテストを書く [PARALLEL_GROUP: 1]
### タスク7：order validatorテストを書く [PARALLEL_GROUP: 1]
### タスク8：cart serviceテストを書く [PARALLEL_GROUP: 1]

// タスク6、7、8は同時にディスパッチできます。
// タスク9は3つすべての完了を待たなければなりません。

並列化してはいけない場合

  • タスクが同じファイルを修正する場合（merge conflictは高コスト）
  • あるタスクの出力が別のタスクの環境を変える場合
  • 確信が持てない場合（不確かな場合はデフォルトで順次実行）

フォールバック：subagentなしで計画を実行する

一部の環境はsubagentのディスパッチをサポートしていません—AIツールが独立したプロセスを生成する能力なしに、単一コンテキストモードで実行されます。

これらの場合、executing-plansスキル（subagentディスパッチフローではない）を使用してください。executing-plansスキルは単一コンテキスト内でsubagentの規律をシミュレートします：

  • 各タスクを明示的なコンテキストリセットで清潔な単位として扱う
  • 各タスクの後に同じ2段階レビューを適用する
  • 同じステータスプロトコルを使用する
  • 現在のタスクを実行しながら将来のタスクを先読みしない

結果は真のsubagentほど分離されていませんが、プロセスの規律が同じメリットのほとんどを提供します。

/executing-plans [計画ドキュメントへのパス]

一般的な実行の失敗とその防止方法

失敗原因防止策
タスクが完了するがテストが通過しないsubagentがファイルの存在を確認し、テストの通過を確認しなかったレビューゲートはファイルの存在確認だけでなくテストを実行しなければならない
DONE_WITH_CONCERNSが蓄積するコントローラーが懸念にもかかわらず実行し続けるしきい値を設定する—N個の懸念が蓄積したら一時停止してレビュー
BLOCKEDタスクがスキップされるコントローラーがブロックされたタスクを回避しようとするBLOCKEDは常に実行を停止する—回避策なし
並列タスクが競合する2つのタスクが同じファイルに書き込む並列グループを明示的にマークする；ディスパッチ前に共有状態を確認する
実行中に計画が逸脱するsubagentが計画を「改善」するsubagentは計画に正確に従わなければならない、解釈または改善しない

subagentモデルは優れたエンジニアリングマネジメントから借用されています： 各エンジニアに明確で自己完結したタスクを与え、mergeする前に作業をレビューし、一人のエンジニアの混乱がチーム全体の問題にならないようにする。