multi-agent-architecture

マルチエージェントアーキテクチャ

コンテキストのあふれを防ぎながら、多数のサブエージェントをオーケストレーションするための設計原則です。

基本理念

エージェントの設計は人材採用と同じように考えます。まず職務記述書を作成し、それをアーキテクチャに落とし込みます。この考え方が、あらゆる判断を形作ります。

職務記述書の作成方法

エージェントのコードを書く前に、次の手順を踏みます。

1. 人間向けの職務記述書を作成する — この人に何をしてほしいですか？ どのような資質が必要ですか？ 成功を示すものは何ですか？
2. 引き継ぎポイントを特定する — 人間なら、どこで状況を確認したり、エスカレーションしたりする必要がありますか？
3. オンボーディングを定義する — 新入社員にどのようなハンドブックを渡しますか？
4. エージェントに落とし込む — 職務記述書の各セクションがアーキテクチャの要素になります。

職務記述書のセクション	アーキテクチャの要素
責任	エージェントのワークフロー
必須スキル	ツールの権限
成功指標	出力スキーマ
エスカレーション基準	エラー処理
オンボーディング資料	スキル／ハンドブック

共有フォルダパターン

問題： 10 体以上のサブエージェントが詳細なレポートを同時に返すと、オーケストレーターのコンテキストが圧迫されます。

解決策： サブエージェントが一時フォルダに書き込み、後続のエージェントが直接読み取ります。

.claude/workspace/
├── phase-1/
│   ├── gmail-analysis.md
│   ├── calendar-analysis.md
│   └── drive-inventory.md
├── phase-2/
│   ├── client-summary.md
│   └── action-items.md
└── manifest.yml

ワークフロー：

1. Orchestrator spawns sub-agents
2. Each sub-agent:
   - Does work
   - Writes report to .claude/workspace/{phase}/{name}.md
   - Returns only: { status: "complete", path: "..." }
3. Downstream agents read prior phase outputs directly
4. Orchestrator reads manifest, not full reports

メリット：

• オーケストレーターのコンテキストを最小限に保てます
• サブエージェントは上流のコンテキスト全体を取得できます
• 要約を介した中継による情報の損失がありません

ハンドブックパターン

問題： 細分化されたスキルが多数あると、脆弱になり、メンテナンスの負担が増します。

解決策： 章立てのハンドブックを 1 つ用意し、基本事項と関連するセクションを読みます。

skills/project-manager/
├── SKILL.md              # Entry point, routes to chapters
└── references/
    ├── 01-foundation.md  # Who we are, tools, escalation, standards
    ├── 02-daily-ops.md   # Data gathering procedures
    ├── 03-dashboards.md  # Structure, quality checks
    └── 04-onboarding.md  # New client setup

章の構成：

章	内容
基礎	チーム、ツール、データソース、エスカレーションルール、品質基準
領域別の章	各担当領域の具体的な手順

読み方：

Sub-agent reads:
1. Foundation chapter (always)
2. Relevant domain chapter(s) (based on task)

コンテキスト予算の戦略

戦略	使用する場面
共有フォルダ	サブエージェントが 5 体以上いる場合、エージェント間に依存関係がある場合
コンテキストプロキシ	調査エージェントが冗長な結果を返す場合
マニフェストファイル	オーケストレーターに詳細ではなくステータスが必要な場合
チャンク分割実行	並列実行でコンテキストが圧迫される場合の逐次フェーズ

アーキテクチャの判断ツリー

How many sub-agents?
├── 1-3 → Direct orchestration (return reports to main)
├── 4-10 → Shared folder pattern
└── 10+ → Phased execution with manifest

Do teammates need direct communication?
├── No → Sub-agents (Task tool) — report results back only
└── Yes → Agent Teams — shared task list, inter-agent messaging
    ├── See agent-teams skill for full guide
    └── Best for: parallel review, competing hypotheses, multi-module features

Do sub-agents need each other's output?
├── No → Parallel execution, merge results
└── Yes → Shared folder, dependency ordering

Is orchestrator context a concern?
├── No → Return full reports
└── Yes → Status-only returns + file paths

共有状態の変更を安全に行う

複数のエージェントが同じ作業項目（issue、task、label）を状態間で遷移させられる場合、気づかれない競合状態により、作業の重複や遷移のスキップが発生します。

3 ステップのガード（状態を書き込む前に毎回適用）：

1. READ   — Re-fetch current state immediately before mutation (never use cached state)
2. VERIFY — Confirm state matches expected pre-condition
3. WRITE  — Apply transition in a single atomic operation

実装パターン：

CURRENT_STATE = fetch_state(item_id)           # live read, not cached
If CURRENT_STATE != EXPECTED_PRE_STATE:
  ABORT — log stale-race, do not mutate
Else:
  apply_transition(item_id, NEW_STATE)         # single atomic call

特に GitHub のラベルを扱う場合：

CURRENT_LABELS = gh issue view {id} --json labels
If EXPECTED_LABEL not in CURRENT_LABELS:
  ABORT — another agent already transitioned this item
Else:
  gh issue edit {id} --remove-label {old} --add-label {new}  # one call

判断表：

シナリオ	対応
状態が想定どおり	遷移をアトミックに適用する
状態がすでに目標値	何もせずスキップする（べき等）
状態が想定外の値	中止し、競合を記録して、再試行しない
項目が見つからない	中止し、項目がないことを記録する

アトミックな呼び出しを 1 回にすることが重要な理由： --remove-label と --add-label を別々に呼び出すと、その間に別のエージェントが中間状態の項目を読み取る可能性があります。1 回の gh issue edit 呼び出しにまとめてください。

アンチパターン

パターン	問題	改善策
スラッシュコマンドによるオーケストレーション	作業開始前にコンテキストを使い切る	サブエージェントに移行する
オーケストレーターがすべてのコンテキストを中継する	ボトルネック、情報の損失	共有フォルダ
マイクロタスクごとにスキルを 1 つ作る	脆弱で、メンテナンスが困難	ハンドブックの章
サブエージェントが完全なレポートを返す	10 体以上でコンテキストがあふれる	パスのみを返す

発展の段階

多くのマルチエージェントシステムは、次の段階を経て進化します。

1. スラッシュコマンド — 手早く始められますが、コンテキストの上限が問題になります
2. オーケストレーター＋サブエージェント — コンテキストの問題を解決しますが、中継がボトルネックになります
3. 共有フォルダ — 中継の問題を解決しますが、スキルの断片化が明らかになります
4. ハンドブックの統合 — 知識を統一し、メンテナンスしやすくします

新しいシステムを構築する場合は、初期の段階を飛ばしてください。

エージェントチーム

ワーカー同士がオーケストレーターに報告するだけでなく、直接やり取りする必要がある場合は、サブエージェントではなくエージェントチームを使用してください。エージェントチームでは、共有タスクリスト、エージェント間のメッセージング、独立したコンテキストウィンドウを利用できます。

上記のサブエージェントのパターンとの主な違い：

• チームメイト同士が直接メッセージを送れます（呼び出し元への返信だけではありません）
• 自分でタスクを引き受けられ、依存関係が自動的に解除される共有タスクリスト
• 各チームメイトは、独自のコンテキストを持つ完全な Claude Code セッションです

サブエージェントからエージェントチームに切り替えるタイミング：

• サブエージェントがタスクの途中で調査結果を共有する必要がある場合
• 対立的な議論や、競合する仮説の検討が必要な場合
• 3人以上のワーカーが自主的に連携する必要がある場合

セットアップ、運用リファレンス、オーケストレーションのパターンについて詳しくは、agent-teams スキルを適用してください。