エージェントチームのワークフロー

問題: エージェントチームはオンになっています。最初のチームを動かしました。スポーンも機能しています。しかしアウトプットは半統合の断片の山で、結局自分でつなぎ合わせることになります。「エージェントチームが動く」と「エージェントチームが本番コードをリリースする」の間には、プロセスが必要です。フラグではありません。

クイックウィン: エージェントチームを信頼できるものにするワークフローは 2 つのフェーズで動きます。計画フェーズで仮定を除去し、ドメイン間のコントラクトを確定させます。実行フェーズではエージェントをウェーブでスポーンし、並行作業がきれいに結合するよう各ウェーブに必要なコントラクトを渡します。完全なワークフローを以下に説明します。

このガイドはエージェントチーム概要の姉妹ガイドです。機能をまだオンにしていないか最初のチームを動かしていない場合は、そちらから始めてください。コントロールと設定については、アドバンスドコントロールをご覧ください。コピペテンプレートについては、ユースケースをご覧ください。

並行して通信する Claude セッションをスポーンできることは能力です。エージェンティックなワークフローには能力以上のものが必要です。プロセスなしの生のスポーンは、設計図なしに工事現場のカギを 5 人の業者に渡すようなものです: 全員が作業するが、何一つ合わない。

ワークフローのない状態では 2 つの失敗モードが常に現れます。

1. 仮定のずれ。 各エージェントが独自のデータ形状、名前付け、エラーフォーマット、エッジケースを選びます。バックエンドが { notif_type: "comment" } を返し、フロントエンドが { type: "COMMENT" } を読みます。両側でユニットテストは通ります。統合が爆発します。

2. 検証の欠如。 すべてのエージェントが成功を報告するため、リードがタスクを完了とマークします。誰もフルフローをテストしていません。最初にクリックして通ると、アプリが壊れて埋もれていたエラーが浮かび上がります。

1 つのパイプラインが両方を解決します。

1. 要件をブレインダンプする（非構造的、混乱していても OK）
2. Claude がコードベースを調査してあなたに確認事項を尋ねるリサーチと Q&A
3. チームメンバー、依存チェーン、受け入れ基準を含む構造化プラン
4. プランだけを持って新しいセッションを始めるフレッシュコンテキスト
5. リードがプランの依存グラフからインターフェースを導出するコントラクトチェーン分析
6. エージェントが注入されたコントラクトに対して並行してビルドするウェーブ実行
7. リードが受け入れ基準に対してエンドツーエンドのチェックを実行するバリデーションループ

各ステップは、スキップすると特定の失敗が発生するために存在します。この記事の残りでそれぞれを順に説明します。

ステップ 1: ブレインダンプ

入力を磨かないでください。平易な言葉で欲しいものを書きます。混乱していても、半分しか形になっていなくても、矛盾していても、思いついたことはすべて含めます。目標: 頭の中をページに注ぎ出すこと。

これは仕様書ではありません。原材料です。ブレインダンプの全目的は、頭の中から正式な仕様を絞り出そうとした瞬間に死んでしまう意図とコンテキストを捕まえることです。

ブレインダンプはスコープのチェックにもなります。数段落で欲しいものを描けない場合、その機能は単一のエージェントチームセッションには大きすぎます。まず分割します。

ステップ 2: リサーチと Q&A

これは多くの人がスキップするステップであり、最も重要なステップです。目標: コードが書かれる前に仮定を減らすこと。

エージェントチームの失敗のほとんどはコードの悪さから来ていません。ミスアラインメントから来ています。エージェントが誤って推測したために欲しくないものを納品します。解決策: Claude が何かを計画する前にコードベースを読ませて質問させます。構造化されたチーム計画は、場当たり的な「プランモードに入る」という習慣を置き換えます。

2〜3 の質問ではありません。最低でも 10 の質問。Claude が尋ねる追加の質問ひとつひとつが、プランに組み込まれる仮定をひとつ減らします。

Claude はこんな質問をしてくるでしょう。

• 請求ページはダッシュボードレイアウトの下に置くべきか、スタンドアローンにすべきか?
• どのトークンパッケージのティアと価格が必要か?
• ChargeB のホスト型チェックアウトを使うか、アプリ内に埋め込むか?
• ユーザーのトークンがゼロの場合、チャット UI で何が起きるべきか?
• すでに ChargeB アカウントとウェブフックエンドポイントが設定されているか?

各質問は実装の潜在的な分岐点です。「埋め込みチェックアウト」と推測してビルドを始めたエージェントは、ホスト型チェックアウトが欲しかったと伝えると、すべてを破棄することになります。10 分の Q&A が何時間の手戻りを防ぎます。

Claude Code の AskUserQuestion ツールはこれを速くします。ほとんどの回答は選択肢からの選択です。Claude の選択が正しい場所はクリックして通過します。精度が必要な場所にはカスタムの答えを入力します。

計画フェーズのより構造化されたアプローチについては、自動計画戦略をご覧ください。

ステップ 3: 構造化プランに変換する

Q&A が終わったら、すべてを構造化プランに固めます。そのプランがチームの全実行を駆動する単一のアーティファクトになります。含めなければならない要素は以下の通りです。

• タスクの説明と目標 チームが成功がどう見えるかを理解するために
• 関連ファイル エージェントが何が存在して何を作成するかを理解するために
• チームメンバー 名前付きの役割、エージェントタイプ、単一の責任を持つ
• ステップバイステップのタスク 依存チェーン（Depends On フィールド）とファイルオーナーシップの境界を含む
• 受け入れ基準 具体的で測定可能なもの
• バリデーションコマンド 作業を確認するために実行できるもの

チームオーケストレーションを機能させる構造がここにあります。

プランは 3 つの仕事を同時にこなします: ファイルオーナーシップの境界線を引く（コンフリクトなし）、依存チェーンをコードに落とす（実行が何を最初にビルドするかを知るために）、受け入れ基準を書き留める（バリデーションが具体的な目標を持つために）。

Depends On フィールドを見てください。これはドキュメントではありません。これは実行フェーズが最初にどのエージェントをスポーンし、ウェーブ間でどのインターフェースを引き出すかを選ぶために使用するコントラクトチェーンを形成します。

ステップ 4: プランだけを持って新しいセッションを始める

これは間違っているように感じますが、それでも重要です。ブレインダンプと Q&A を行ったのと同じコンテキストウィンドウで継続しないでください。プランだけをロードした新しい Claude Code セッションを開きます。

なぜか? 計画の会話はコンテキストを消費します。探索的な質問、ボツになったアイデア、今は無関係な往復のやり取りで詰め込まれています。プランは蒸留されたバージョンです。チームが必要なものはすでに含まれています。計画の雑談はビルドを圧迫する死んだ重荷です。

これはプランが再利用可能であることも意味します。途中で失敗したセッションは同じプランファイルから再開できます。計画作業が再度行われることはありません。

ステップ 5: コントラクトチェーン分析

エージェントがスポーンされる前に、リードはプランの依存グラフを辿りコントラクトチェーンを引き出します。このステップが本番ビルドでエージェントチームを信頼できるものにします。

コントラクトチェーンはタスクを依存関係によってウェーブにグループ化し、完了した各ウェーブが次のウェーブに必要な出力を名前付けます。

重要な洞察: どのエージェントも自分のコントラクトが存在するまで作業を開始しません。 データベースエージェントが最初に動きます。完了すると、リードに実際のスキーマ定義、テーブル型、リレーションシップを含むメッセージを送ります。これらの出力がコントラクトです。リードはこれらの具体的なスキーマを API とフロントエンドエージェントのスポーンプロンプトに貼り付け、両方が独自のものを発明する代わりに実際のインターフェースに対してビルドします。

これが並行エージェントが実際に統合するコードを書く理由です: 独立してデータ形状を推測していません。全員が同じコントラクトに対して書いており、そのコントラクトはすでにリリースされた作業から来ています。

コントラクトとして注入されるもの

コントラクトは抽象的な仕様ではありません。上流の作業の実際の出力です。

• データベース完了 -> スキーマコントラクト: 正確なテーブル定義、カラム型、外部キー、TypeScript 型
• API 完了 -> API コントラクト: エンドポイントルート、リクエスト/レスポンス形状、ステータスコード、認証要件
• 共有型の作成 -> 型コントラクト: 複数のエージェントが参照するインターフェース、列挙型、定数

すべての下流エージェントは対応するコントラクトをスポーンプロンプトに貼り付けられます。「データベースエージェントが何をしたか読みに行って」ではありません。生のコンテンツそのものです。これにより、あるエージェントが古いファイルを読んだり別のエージェントの出力を誤読したりするという失敗モードを排除します。サブエージェントパターンは各エージェントをそれぞれのコーナーで推測させたままにします。適切なエージェンティックワークフローはすべてのエージェントを検証済みのインターフェースに接続します。

ステップ 6: ウェーブ実行

コントラクトチェーンが整ったら、リードはエージェントをウェーブでスポーンします。

ウェーブ 1（基盤）: データベースエージェントが最初に動きます。スキーマ、共有型、設定などの基盤となる作業を処理します。リードは完了を待ってコントラクトを受け取ります。

ウェーブ 2 以降（並行）: スキーマコントラクトが届いたら、API とフロントエンドエージェントが一緒にスポーンされます。各エージェントはスキーマコントラクトをプロンプトに落とし込み、タスクの割り当てとファイルオーナーシップの境界線とともに受け取ります。

チームメンバーのスポーンプロンプトはこの構造に従います。

重要な部分: ファイルオーナーシップの境界（2 つのエージェントが同じファイルに触れない）、上流コントラクト（参照ではなく実際のコンテンツ）、下流コントラクトの義務（このエージェントが他者のために生成しなければならないもの）。

リードがコードを書く代わりにコーディネートするようにデリゲートモードをオンにします。実行中のリードの仕事はタスクリストを監視し、コントラクトの不一致を解決し、ドリフトし始めたエージェントを促すことです。

ブラウンフィールドコードベース

実際の作業のほとんどは既存のコードベースの中で行われます。ブラウンフィールドのエージェントチームは規約の一貫性が必要です。同時に同じプロジェクトを編集する 3 つのエージェントは、すでにあるパターンに従う必要があります。

解決策: CLAUDE.md にプロジェクトの規約を文書化します（命名、エラー処理、ファイルレイアウト、テストアプローチ）。エージェントチームは CLAUDE.md を共有のランタイムコンテキストとして読むため、すべてのチームメンバーが最初の行から整合した状態でスタートします。これをスキップすると、あるエージェントが camelCase の API レスポンスを返し、別のエージェントが snake_case を返します。それぞれが独自の規約をその場で選んだからです。

ステップ 7: ビルド後の検証

チームメンバーがタスクを完了しても、それで完了ではありません。並行ビルドは単独ではパスするコンポーネントを生成しますが、境界で崩壊します。バリデーションがそれらの失敗を捕捉します。

プランの受け入れ基準とバリデーションコマンドがこのステップを駆動します。リード（または専任の品質エンジニアエージェント）が各基準をひとつずつ確認します。

偽陽性問題

最も怖いビルド後のシナリオ: すべてのエージェントがタスクを完了としてマークし成功を報告するが、埋もれたエラーがそこにある。これはエージェントがタスクをクローズするよう動機付けられており、自分の作業を表面的に承認することがあるために発生します。

確認ではなく証拠を求めることで対抗します。「すべてうまくいきましたか?」と尋ねるのではなく、具体的な出力を求めます。

証拠を要求することで、リードがパターンマッチングで直感的に判断する代わりに実際に検証することを強制します。コードレビューと同じ考え方です: 差分を読む、著者に機能するか尋ねるのではなく。

修正・再テストのサイクル

バリデーションで問題が見つかった場合、ループはシンプルです。

1. リードが不一致を特定する（例: ウェブフックハンドラーが間違ったステータスコードを返す）
2. リードが担当チームメンバーにメッセージを送るか、ターゲットを絞った修正エージェントをスポーンする
3. 修正を適用する
4. リードが影響を受けるバリデーションチェックを再実行する

コントラクトが正しく設定されていれば、ほとんどの実行は 1〜2 回のイテレーションで収束します。コントラクトなしでは、すべての修正が別の仮定の不一致を掘り起こすため、修正・再テストループがスパイラルします。そのスパイラルがまさにコントラクトチェーンが存在する理由です。

依存チェーンに基づいた構造化された修正ループについては、ビルダー・バリデーターパターンがこれをタスク依存関係として形式化し、ビルダーが完了した後にバリデーターが自動的に実行されます。

ステップ 1〜3（計画）は 15〜30 分のインタラクティブな作業が必要です。ステップ 4〜7（実行）は最初のウェーブが出たらほぼ無人で動きます。

この比率が重要です: 計画とコントラクトに費やす 30% の時間が、計画不足の並行ビルドの統合失敗をクリーンアップするのに費やす 70% の手戻りを帳消しにします。

7 つのステップはすべて生のプロンプトで手動で実行できます。ただし繰り返しの部分（プランのフォーマット、コントラクトチェーンの導出、ウェーブ実行、バリデーションのシーケンス）は機械的で、再利用可能なコマンドにまとめるのに十分な規則性があります。

ここでの概念（Q&A を通じた仮定の削減、ウェーブ間のコントラクトチェーン、証拠ベースのバリデーション）は、コマンド、生のプロンプト、カスタムオーケストレーションレイヤーのいずれで実行しても適用できます。

少なくとも 2 つのレイヤーをまたがる機能を選びます（フロントエンド + バックエンド、または API + データベース）。

1. 欲しいものをブレインダンプする
2. Claude に 10 個の確認事項を尋ねさせる
3. チームメンバーと依存チェーンを含む構造化プランを作る
4. 新しいセッションを開始し、リードにコントラクトチェーンを導出させる
5. エージェントが共有コントラクトに対してウェーブでビルドするのを観察する
6. 確認ではなく証拠で統合ポイントを検証する

最初の実行は筋肉記憶を構築しているので時間がかかります。3 つ目の機能になれば、ワークフローが自然になり複利が効き始めます: プランが再利用可能なテンプレートになり、コントラクトが標準化されたインターフェースになり、バリデーション基準がプロジェクト全体の品質ベースラインに積み重なります。