複数AIエージェント並行開発のアーキテクチャ設計：ファイル競合と手戻りを防ぐ協調プロトコル

対象読者: Claude Code、Cursor、OpenCodeなどのAIエージェントを日常的に並行稼働させているソフトウェアエンジニア、テクニカルリード
難易度: 中級〜上級
テーマ: 異種AIエージェント協調ハーネス（Agentic Coordination Harness）の設計

:::message この記事の要点 (TL;DR)

課題: 複数AIエージェントを同一リポジトリで同時に動かすと、同一ファイルの無言上書き（サイレント・コンフリクト）や、先行AIの成果を後続AIが壊す「手戻り」が構造的に発生する。
原因: 各AIプロセスが孤立しており、「誰がどのモジュールを編集中か」「直近で何が決定・変更されたか」を互いに把握できないことにある。
解決策: Model Context Protocol（MCP）を介した4つの自律動作プロトコル（入室・排他宣言・伝達・退室）と、トークン消費を抑え込むローカルFTS5検索により、安全なマルチエージェント並行開発が可能になる。 :::

1. はじめに：AIエージェント「並行運用」の限界

2026年現在、AIコーディング支援は「1つのチャット画面でコードを書かせる」段階から、**「複数の独立したAIエージェントに並行して別々のサブタスクを担当させる」**段階へ移行しました。

しかし、ターミナルを複数立ち上げてエージェントを並行稼働させた途端、開発現場では次の3大破綻が発生します。

サイレント・コンフリクト（無言の上書き衝突）: 依存関係ファイル（pyproject.toml や package.json）や共通データアクセス層など、複数の機能から参照されるハブモジュールを異なるAIが同時に編集し、差分が先祖返り・破壊される。
設計手戻り（先行AIの成果の破壊）: 先行エージェントが「型定義の共通化」を完了した直後に、後続エージェントがその意図を共有されないまま古い前提でコードを再生成し、先行作業を台無しにする。
コンテキスト破綻（トークン爆発）: 衝突を防ごうとして過去の全エージェントの会話履歴や作業ログをプロンプトに流し込むと、一瞬でコンテキスト長が上限に達し、コストが高騰するだけでなくAIの指示追従精度が著しく低下する。

単一ベンダーのエコシステム内であれば閉じた解決策も存在しますが、**「Claude Code と Cursor と OpenCode を組み合わせて使いたい」**という現場の要求には応えられません。中立かつ軽量なプロトコルによる調停基盤が必要です。

2. 協調プロトコルの基本構造：4つの自律動作

この問題を解決するため、私たちは Model Context Protocol（MCP）を用いた自律エージェント協調ハーネスを設計しました。エージェントに求める動作は、人間がチーム開発で行う「声かけ」と同じ、以下の4つのみです。

sequenceDiagram
    autonumber
    participant AgentA as Agent A (例: Claude Code)
    participant Hub as Coordination Hub (MCP Server)
    participant AgentB as Agent B (例: OpenCode / Cursor)

    AgentA->>Hub: 1. checkin (入室・在席確認)
    Hub-->>AgentA: 在席一覧・進行中の宣言・自分宛メッセージ
    AgentA->>Hub: 2. claim (編集対象パスの宣言)
    Hub-->>AgentA: 重複検知・直近の手戻り警告 (Rework Warning)
    Note over AgentA: タスク実行 (実装・テスト)
    AgentA->>Hub: 3. post_board_message (決定事項・引き継ぎ)
    Hub-->>AgentB: 宣言範囲が重なる相手へ新着として自動配送
    AgentA->>Hub: 4. checkout (退室・宣言解放)

① checkin（入室と心拍）

エージェントは作業開始時に checkin を呼び出します。これにより、現在同一プロジェクトで動いている他のエージェント、現在ロックされているモジュール一覧、および自分宛に届いている引き継ぎ情報を受け取ります。定期的な呼び出しは「生存確認（Heartbeat）」として機能します。

② claim（排他宣言）

ファイルを編集する前に、相対パスまたは機能名で claim(targets=['src/api', 'pyproject.toml']) を宣言します。もし他のエージェントがすでに同一範囲を宣言している場合、エラーで強制終了させるのではなく、「相手のセッション情報と作業目的」を返すことで、AI自身が待機または別タスクへの切り替えを自律判断します。

③ post_board_message（決定事項の伝達）

作業中に重要なアーキテクチャ判断（例: 「ライブラリAを採用しBを却下」）を行った場合や、後続へのタスクを渡す場合、伝言板へ投稿します。この投稿は、編集範囲が重複している他のエージェントへ、次回のツール呼び出し時の応答末尾に「新着通知」として相乗り（Piggybacking）配送されます。

④ checkout（引き継ぎと解放）

作業が完了、または一時中断する際、checkout を呼び出します。これにより宣言していた排他ロックがすべて解放され、完了サマリーと次のステップが自動的に引き継ぎ（Handoff）として記録されます。

3. コンテキスト保護の減算設計：履歴をどう削るか

協調システムの設計において最も警戒すべきは、**「共有情報そのものがエージェントのコンテキストを圧迫すること」**です。

数百件の作業ログやコミット履歴をそのままコンテキストに注入すれば、十万トークン規模の浪費となり、推論コストと精度の両面で破綻します。私たちは以下の減算アプローチでこれを解決しています。

1. 文字数予算（Character Budget）による物理遮断

ツール呼び出しが返却する履歴には、件数制限だけでなく厳格な文字数上限（例: 60,000文字）を課します。これを超える古い情報は強制的に省略され、エージェントには要約と期間情報のみを返します。

2. SQLite FTS5 によるオンデマンド全文検索

重厚な外部ベクトルデータベースや分散検索エンジンを排し、ローカルの単一SQLiteファイルに内蔵された FTS5（全文検索） を採用しています。エージェントが現在行っている作業の「意図（Intent）」や「宣言パス」をキーワードとして検索し、関連する過去の決定事項（Decision）上位数件だけをピンポイントでコンテキストへ注入します。

3. イベント相乗り（Piggybacking）

MCPにはサーバーからクライアントへ能動的にプッシュ通知を送る標準機構が存在しません。そのため、エージェントが任意のツールを呼び出した「戻り値の末尾」に、未読の通知やメンションを最大数件だけ付与する設計をとっています。これにより、ポーリングによる無駄なAPI呼び出しを完全に排除しています。

4. 複数エージェント運用の実践構成例

この協調ハーネスは、標準的な MCP（Model Context Protocol）設定ファイルに追加するだけで導入可能です。

設定例（Claude Code / Kiro 等の共通設定）

{
  "mcpServers": {
    "agent-hub": {
      "url": "http://127.0.0.1:8765/mcp",
      "disabled": false,
      "autoApprove": [
        "checkin",
        "claim",
        "checkout",
        "post_board_message",
        "read_board"
      ]
    }
  }
}

各エージェントのシステムプロンプトまたは指示ファイル（CLAUDE.md やエージェントポリシー）に、以下のルールを1行追加するだけで自律協調が始まります。

作業開始前に必ず checkin し、編集するディレクトリを claim してから作業すること。完了時は checkout で成果を引き継ぐこと。

5. まとめ

AIエージェントによる開発が高度化するほど、個々のLLMの賢さ以上に**「エージェント同士の交通整理（ハーネス）の頑健さ」**が開発効率を決定づけます。

ファイルの無言上書きを防ぐ「排他宣言」
依存関係の破壊を防ぐ「引き継ぎ配送」
トークン爆発を防ぐ「予算管理とFTS5抽出」

単一プラットフォームの壁を越え、手元のマシンで自律的なエージェントチームを安全に統制するアーキテクチャを、Ayato Studioでは今後もオープンに探究していきます。