9.10.4 プロジェクト：マルチ Agent 開発チーム【選択】

この節の位置づけ

マルチ Agent 開発チームのプロジェクトは、すぐに“見せるだけ”になりがちです。

• 役割が多い
• 会話が多い
• でも結果が安定しない

だから本当に価値があるのは、役割の数ではなく、次の点です。

タスクが安定して分解されているか、引き継ぎが明確か、失敗後に巻き戻せるか。

この章では、作品レベルの「最小ループ」を作ります。

学習目標

• マルチ Agent 開発チームの最小役割セットを定義できるようになる
• 役割間で最も重要な引き継ぎ用アーティファクトが何かを理解する
• そのまま見せられる、検証可能なマルチ Agent プロジェクトの骨組みを作る
• なぜ「何回も会話すること」より、プロトコルと状態のほうが大事なのかを理解する

---

なぜ最小役割セットだけで十分なことが多いのか？

とても安定した最小ループには、普通は次の4つだけあれば十分です。

• プランナー
• 実装担当（コーダー）
• レビュー担当
• テスト担当

この4種類の役割があれば、次の流れを十分に示せます。

• タスク分解
• 実装
• レビュー
• 検証

最初から役割を増やしすぎると、
システムは忙しそうに見えても、実際には空回りしやすくなります。

---

まずは役割間のアーティファクト引き継ぎ例を動かしてみよう

この例では実際にはコードを変更しません。
ただし、最も重要な「引き継ぎアーティファクト」の形を表します。

from dataclasses import dataclass


@dataclass
class TaskPlan:
    goal: str
    files_to_change: list
    acceptance_test: str


@dataclass
class Patch:
    summary: str
    changed_files: list


@dataclass
class ReviewNote:
    approved: bool
    issues: list


@dataclass
class TestReport:
    passed: bool
    cases: list


plan = TaskPlan(
    goal="返金ページのステータス表示の不一致を修正する",
    files_to_change=["status.py", "test_status.py"],
    acceptance_test="'  OPEN ' を入力したら、正規化結果は 'open' になること",
)

patch = Patch(
    summary="ステータス正規化ロジックを修正し、テストを追加する",
    changed_files=["status.py", "test_status.py"],
)

review = ReviewNote(
    approved=False,
    issues=["変数名がわかりにくい", "境界条件のテストが不十分"],
)

test_report = TestReport(
    passed=False,
    cases=["test_status_normalize_basic", "test_status_normalize_empty"],
)

print(plan)
print(patch)
print(review)
print(test_report)

実行結果の例：

TaskPlan(goal='返金ページのステータス表示の不一致を修正する', files_to_change=['status.py', 'test_status.py'], acceptance_test="'  OPEN ' を入力したら、正規化結果は 'open' になること")
Patch(summary='ステータス正規化ロジックを修正し、テストを追加する', changed_files=['status.py', 'test_status.py'])
ReviewNote(approved=False, issues=['変数名がわかりにくい', '境界条件のテストが不十分'])
TestReport(passed=False, cases=['test_status_normalize_basic', 'test_status_normalize_empty'])

この例でいちばん大事な点は何か？

この例が示しているのは、マルチ Agent プロジェクトで本当に見せるべきものは、
単なる会話ログではなく、次のようなものだということです。

• 引き継ぎアーティファクト
• タスク状態
• 結果の検証

なぜアーティファクトのほうが会話より重要なのか？

アーティファクトこそが、その後の役割が実際に依存する入力だからです。
会話だけを見ても、システムが安定して協調できるかどうかは判断しにくいです。

---

最小ワークフローのループ

同じファイルまたは同じ Python セッションで続けて実行してください。このブロックは前の例の dataclass を再利用します。

次に、4つの役割を1本の最小フローにつなげます。

def planner(goal):
    return TaskPlan(
        goal=goal,
        files_to_change=["status.py", "test_status.py"],
        acceptance_test="'  OPEN ' を入力したら、正規化結果は 'open' になること",
    )


def coder(plan):
    return Patch(
        summary=f"タスク目標に基づいて実装: {plan.goal}",
        changed_files=plan.files_to_change,
    )


def reviewer(patch):
    if "test_status.py" not in patch.changed_files:
        return ReviewNote(approved=False, issues=["テストファイルの変更がありません"])
    return ReviewNote(approved=True, issues=[])


def tester(review_note):
    if not review_note.approved:
        return TestReport(passed=False, cases=["review_failed"])
    return TestReport(passed=True, cases=["test_status_normalize_basic", "test_status_normalize_empty"])


goal = "返金ページのステータス表示の不一致を修正する"
plan = planner(goal)
patch = coder(plan)
review = reviewer(patch)
test_report = tester(review)

print(plan)
print(patch)
print(review)
print(test_report)

実行結果の例：

TaskPlan(goal='返金ページのステータス表示の不一致を修正する', files_to_change=['status.py', 'test_status.py'], acceptance_test="'  OPEN ' を入力したら、正規化結果は 'open' になること")
Patch(summary='タスク目標に基づいて実装: 返金ページのステータス表示の不一致を修正する', changed_files=['status.py', 'test_status.py'])
ReviewNote(approved=True, issues=[])
TestReport(passed=True, cases=['test_status_normalize_basic', 'test_status_normalize_empty'])

結果の読み方

出力を artifact chain として読みます。TaskPlan が目標と受け入れ条件を定義し、Patch が実装とテストファイルを変え、ReviewNote がゲートになり、TestReport が最後の証拠になります。

なぜこのループだけでもかなり実際のプロジェクトに近いのか？

マルチ Agent プロジェクトで本当に大事な3つの点が入っているからです。

1. 役割分担
2. 明確なアーティファクトの引き継ぎ
3. レビューとテストにもとづくフィードバックループ

レビュー担当が承認しないのにテスト担当が続けないほうがいいのはなぜ？

これは、マルチ Agent システムが「みんなが並行で好きにやる」ものではなく、
次のことをきちんと守る必要があるからです。

• 段階依存
• 引き継ぎ品質

図の見方

この図が強調しているのは、「役割の数が重要なのではなく、アーティファクトの引き継ぎが重要」ということです。プランナーは計画を出し、コーダーはパッチを出し、レビュー担当は指摘を出し、テスト担当はテストレポートを出します。失敗したら、それぞれの役割に戻って修正します。

---

作品レベルのプロジェクトで本当に見せるべきものは？

1本の完全なタスクトレース

たとえば次のような流れです。

• タスク目標
• 計画（plan）
• パッチ（patch）
• レビュー指摘
• テストレポート

1回の失敗からの巻き戻し

これは非常に説得力があります。
たとえば：

• レビュー担当が差し戻す
• コーダー が再修正する
• テスト担当が再度検証する

はっきりした役割の境界

作品集では、次の点に答えられる必要があります。

• なぜこの4つの役割が必要なのか
• 各役割の入力と出力は何か

---

いちばんハマりやすい落とし穴

役割は多いのに境界が不明確

これだと、システムは複雑に見えますが、
実際には同じ作業を繰り返しているだけです。

共有状態や統一されたアーティファクト形式がない

この場合、役割間の引き継ぎが安定しません。

成功パスしか見せない

良いマルチ Agent プロジェクトでは、むしろ次のことを見せるべきです。

• 失敗後にどう巻き戻すか
• どの段階で問題が起きやすいか

---

期待される結果：各 role の入力と出力、共有 artifact、失敗時の巻き戻しを trace に残し、マルチ Agent が単なる会話ではなく工程として動くことを示せる状態です。

残す証拠

このページを終えたら、この証拠カードを残します。

プロジェクト目標

エージェントが達成すべきことと、してはいけないこと

ベースライン

高度な機能を追加する前の単一エージェントループ

追跡パック

目標、計画、ツール呼び出し、観察、メモリ、評価

失敗ログ

少なくとも1回の失敗または危険な実行と根本原因

成果物

README、実行コマンド、trace スクリーンショット/ログ、次の一手

まとめ

この節でいちばん大事なのは、作品レベルの判断基準を持つことです。

マルチ Agent 開発チームプロジェクトの本当の価値は、役割が多くて派手なことではなく、タスク分解、アーティファクトの引き継ぎ、失敗からの巻き戻しを安定したループとして組み立てられるかどうかにあります。

このループさえしっかり作れれば、このプロジェクトはマルチ Agent システムへの理解をしっかり示すのにとても向いています。

---

バージョン別の進め方

バージョン	目的	重点的に作るもの
基礎版	最小ループを通す	入力できる、処理できる、出力できる、そして1組の例を残す
標準版	見せられるプロジェクトにする	設定、ログ、エラー処理、README、スクリーンショットを追加する
チャレンジ版	作品集レベルに近づける	評価、比較実験、失敗サンプル分析、次のステップの道筋を追加する

まずは基礎版を完成させましょう。最初から何でも盛り込もうとしないことが大切です。バージョンを1つ上げるたびに、「何が新しくできるようになったか、どう検証したか、まだ何が課題か」を README に書きましょう。

練習

1. ワークフローに ops_agent を追加して、どの段階に接続すべきか考えてみましょう。
2. 考えてみましょう：なぜマルチ Agent プロジェクトでは「統一されたアーティファクト形式」が「役割が会話できること」より大事なのか？
3. レビュー担当が patch をよく差し戻す場合、どの層を優先して改善すべきでしょうか？
4. このプロジェクトをデモページにするなら、いちばん見せたい完全な トレース はどれですか？

プロジェクト参考とレビュー観点

1. ops_agent は implementation の後、final release review の前に入れます。run commands、environment variables、logging、rollback notes、deployment risks を確認します。
2. unified artifact format が重要なのは、Agent coordination には安定した input/output が必要だからです。chat だけでは test、replay、diff、別 Agent への handoff が難しくなります。
3. reviewer が patch を頻繁に reject するなら、まず task specification と acceptance criteria を改善します。その後 coder context、test feedback、review comments が actionable かを見ます。
4. 良いデモの追跡記録は、要件 -> 計画 -> パッチ -> テスト結果 -> レビューの却下または承認 -> 修正 -> 最終成果物 を示します。これにより協働の構造が見えます。