Multi-Repo Agent Orchestrator

初出 2026-06-03. 実装の成長に合わせて 2026-07-23 に全面改稿した. 本文の数値と図は改稿時点のもの. 初出後に書いた続編が 3 本ある: 対話型 coordinator, repo 間タスク連鎖, 個人の学習層 (Learn).

近頃よくある取り組みだが, PC 上のあらゆる作業に AI Agent を介入させるように仕事の再構築を進めている. 再構築を進めるうちに, 複数のプロジェクトが同時進行する状況で, CLAUDE.md/AGENT.md, skills の仕様判断, その他の規約やコンテキストの設定を共有し自動化したいという欲求が出てきた.

複数 Agent の並行管理自体は, Remote Control や cmux などの導入で軽くなってきたが, それぞれの repo で独立していると初期設定や知識層の反映に手間がかかる. どの repo で起動しても, 作業目標ごとに知識と規約を引き継ぐのがボトルネックとなってきた.

そのために, 二十数リポで別々に走らせている Claude / Codex / Cursor のセッションを, 横断で監視, 記録, タスク配分, 知識集約する上位レイヤ (Agent Orchestrator) を自作した. 各リポの Agent は賢いが, それらを束ねる視点 (誰が何を進行中か, 知見の横断再利用, タスクの配分) は別レイヤの問題で, そこを担うのがこの Orchestrator である.

このような用途なら, 既存の AI Assistant tool として有名な Pi (Inflection) や Hermes Agent (Nous Research) がある. わざわざ車輪の再発明をしなくても, 既存アーキテクチャを採用すれば類似の効果は得られる.

Pi は製品 / UX 層, Hermes Agent はモデル + 単一 agent 層に当たる. どちらも記憶や知識の集約・反映の仕組みを持ち (Hermes Agent は永続メモリ + skills, Pi は会話文脈), 私の理解では orchestrator 的な役割もある程度こなす一般ツールである.

それでも自作したのは, 次の二点を得たかったところによる.

• 記憶層が小さい: 既製ツールの記憶は基本的に単一 agent スコープで, 複数リポ・複数分野にまたがる横断知識ベース (本プロジェクトの vault) としては手狭. RAG として手入れする前提の corpus を, agent の外側に独立して持ちたい.
• 作業ごとに分人的な役割分担がある: 研究, 講義, 開発, 私生活で必要な人格・文脈・規約は異なる. すべてを単一 agent に集約するより, agent ごとの個別コンテキストと, 横断の共通知識とを併存させたい. 一個の強い agent を作る (Hermes Agent の方向) のではなく, 弱くてもよいので多数の agent をそれぞれの分人として保ちつつ, 共通の知識層で束ねる, という選択である.

あと単純に, 自分で弄れる範囲が大きい方が楽しい. 普通は Hermes Agent を入れておけばほとんどこと足りると思う.

なお, この構成は最終的にはネットワーク上の常時稼働機へ引き継ぐ計画だが, 移行 (後述の Phase 3) は設計だけ済ませて保留しており, 現在も 1 台のローカル Mac で完結している.

全体構成: 核の 5 段と増えた 6 系統

Orchestrator は管理対象リポの上位に立ち, launchd で毎時巡回するバッチと対話セッションの二面で動く. 各リポの Agent とは共有キュー (inbox/outbox) だけで接続する. 巡回 1 周の骨格は初版から変わらず, 「収集 → routing → vault 反映 → MCP 配信 → 通知」の 5 段で読める.

初版ではこの 5 段を「5 層構成」と呼んだが, 7 週間後の実態の要約としては既に粗い. 巡回の工程は 27 step に増え, 5 段のどれにも収まらない系統が 6 つ育った.

増えた 6 系統のうち, タスク双方向同期・知識キュレーション・統治は本文の後半で扱う. 残る 3 つの位置づけは次のとおり.

• repo 間 handoff queue: 上流ライブラリの変更を下流の研究リポへ運ぶ, repo から repo への有向タスク連鎖. 中央の immutable queue で運ぶ. 続編 中央 immutable queue で運ぶ repo 間の Agent タスク連鎖 に書いた.
• 対話型 coordinator: 各リポの Agent を cmux のタブで起動・操舵し, 走行中の変更操作だけを横取りして人間の承認に上げる. 続編 cmux で起動した repo agent の変更操作だけを承認ゲートに通す対話型 coordinator に書いた.
• 自律実行レーン: 人間が 1 件ずつ承認した doc / test 級の小修正を, 隔離 worktree で commit まで自動実行する (merge はしない). kill switch 付きで有効化済みだが, 実行実績はまだ数件で常用には至っていない.

Orchestrator 自身は今も判断と記録に徹し, 各リポでの実作業はそのリポの Agent が担う. 司令塔兼書記であって, 現場では手を動かさない. 自律実行レーンはこの原則の唯一の緩和だが, 対象は事前承認済みの小修正に限り, merge の権限は渡していない.

管理対象: 26 リポをカテゴリで束ねる

以下は匿名化したリポの構造を表している. 管理対象は現在 26 リポ (稼働 25) で, 各リポは runtime (claude / codex / cursor, 併用可), cadence (毎時 5 / 日次 17 / 週次 3 リポ), category, techs, 依存先リポをメタデータに持ち, これが後段の routing と知識索引のキーになる. 設定は 1 枚の YAML に集約し, パーサも 1 本に統一している. 初版時に十数リポだった管理対象はほぼ倍になったが, リポを増やすときにやることはこの YAML に 1 エントリ足すことだけである.

構造は二段に分かれる. 作業レイヤの頂点に Orchestrator が立って全リポを束ね, その系全体をさらに外側から評価するのが existential (Vault) である.

Orchestrator と existential (Vault) は層が違う. Orchestrator は作業レイヤの頂点として全リポの routing / 知識 / タスクを束ねるが, existential はその Orchestrator を含む系全体を外側から評価する. existential には now.md をはじめ思想 / 現状 / 価値観の single source があり, 個々の作業や routing が自分の価値観と現状に整合しているかを問う. Orchestrator が「何を / どう進めるか」を扱うのに対し, existential は「そもそもその方向で良いか」を扱う. now.md 自体は Orchestrator 経由で必要な agent にも配信される.

各リポも Orchestrator を通じて連携できるようにしている. 例えば papers 層は, 文献管理に特化したパイプラインを持つ. 論文 PDF を原典として取り込み, それを md に抽出・要約 (図表や式の扱いも含む) してから, 引用情報を bib (引用データベース) に落とす. この PDF → md → bib の流れが research 層 (14 リポ) の執筆へ供給され, 「読んだ論文がそのまま引用可能な形で原稿に届く」状態が構築されている. また depends_on を宣言したリポの組 (上流ライブラリと下流の研究リポ) には, 前述の handoff queue によるタスク連鎖が繋がる.

通信モデル: repo-initiated

Orchestrator は管理対象リポの FS を直接書き換えない. これが一番大事な制約だ. 通信はすべて repo 側から共有キューへの push / pull に固定する.

境界を push/pull のキューに固定すると, どちらが何を書いたかが常に明確になり, 片方が壊れてももう片方は動き続ける. 上位が下位のコードを勝手に上書きしない, という規律でもある. この原則は初版から一度も緩めていない. 例外は 1 つだけで, briefing と context-pack を作るとき他リポの計画文書を read-only で参照する. 読みはするが書かない.

repo 側の窓口は MCP server で, 現在 21 tool を提供する (知見の報告, タスクの取得と完了, 規約の pull, 知識検索など). Claude / Codex / Cursor の 3 runtime が同じ tool 群を呼び, 違うのは呼び出し名の形式だけである. runtime を足すことと通信モデルを変えることが独立になっている.

なお, このハブは repo ↔︎ Orchestrator の汎用レーンであり, repo から repo への有向のタスク連鎖は運ばない. そちらは前述のとおり別機構で, 続編 中央 immutable queue で運ぶ repo 間の Agent タスク連鎖 に書いた.

データ表現: 人が読む正本は markdown, 機械状態は JSONL

状態, タスク, 知識, 規約. Orchestrator が扱う正本データは Obsidian による markdown + frontmatter で持つ. DB エンジンも独自フォーマットも使わない. 狙いは移行容易性で, 別マシン (常時稼働の Mac mini を想定) へ移すとき, データ表現が markdown のままなら差し替えるのは通信層だけで済む.

Phase 1 (file) → Phase 2 (MCP) → Phase 3 (LAN MCP)

通信を進化させても vault の中身は変わらない. 現在は Phase 2 で, Phase 3 は移行先のトポロジ設計だけ済ませて保留している.

markdown / Obsidian を選んだ主な理由は, もともと個人の知識管理を Obsidian で行っていたことにある. 設計として一から選んだというより, 既存資産 (過去の日記やメモ) をそのまま agent に読ませられる連続性が大きい. 実際 existential (Vault) では過去の日記やメモを文脈として読ませている. そのため, 人間が文章を読む面は当面 Obsidian 固定で行く予定だ.

一方で, 初版に「効率的な手段があれば置き換える」と書いた内部表現の置き換えは実際に起きた. 初版時は文字通りすべてが markdown だったが, 現在は人間が読まない機械状態 (tool 呼び出しログ, 知識の使用シグナル, 委譲実績, セッションのレジストリ, embedding キャッシュ) を JSONL / JSON に分けている. markdown は人間も読む層の共通項として残し, 機械だけが読む層は追記と集計に向いた表現を選ぶ, という分化である.

知識層 = 自前 RAG

このプロジェクトで一番効いている知識層は, 実質 RAG (Retrieval-Augmented Generation) の自前運用である. ただし主眼は “貯める” ことより “腐らせない” ことにある. 規模は現在約 350 note (昇格済み 165, 受け入れ待ち 10, 巡回が掘った検証前候補 142, 隔離 28) になった.

• ingestion: Agent が知見を [pattern] [gotcha] [howto] [reference] [domain] のタグ付きで報告 → 1 件 1 markdown を _staging/<tag>/ に保存. source repo, category, techs, confidence をメタデータに持つ. これとは別に, 巡回がセッションログから知見候補を採掘して検証前の候補置き場に貯める.
• retrieval: 必要時に pull_relevant_knowledge / search_knowledge. 検索は初版のタグ + キーワード索引から進み, 多言語の文 embedding による意味的近接を併用した hybrid 検索になった (embedding ライブラリが無い環境ではキーワード検索へ自動フォールバック). 日本語で書いた note が英語の問いにも掛かる.
• curation (本題): corpus をただ増やすとノイズで検索精度が落ちる. 昇格は使用シグナルで決める: 他リポでの採用実績と agent の明示評価 (mark_knowledge_useful) の重み付き合算 (adopted + 3*useful >= 3), または高 confidence のまま 10 日間覆らなかったもの. context-pack に載って読まれただけの受動露出は昇格の根拠にしない. 使われた証明にならないからだ. 逆に検証から 180 日 (候補は 30 日) 引かれなかった note と撤回された note は _stale/ へ隔離する. 黙って消さないので追跡可能である. 昇格は監査ログに 1 件 1 行で残り, 人間が差し戻せる.

一度踏んだ gotcha を別リポの Agent が二度踏まないのは, corpus が増えるからでなく手入れされているからだ.

なお, ここで扱っているのはあくまで Agent のための 知識層である. 人間 (私) 自身の学習を同じ枠組み (queue + 巡回) で回す層は, 続編 AIと連携した個人の学習層 (Learn) に書いた.

タスク層: vault と Todoist の双方向同期

知識層と並ぶもう一つの管理層がタスクで, ここは Todoist を hub にしている. 人間と agent が同じタスクを同じ場所で見るための層である.

正本の置き方はフィールド単位で決めている. 本文・詳細・リンクは git 追跡の vault 側が正本で, 巡回がそれを各リポの Todoist project へ push する. 完了はどちらで起きても収束する: agent が MCP で完了を報告すると vault 側が先に done になり, 次の巡回が Todoist を close する. 人間がモバイルで完了・追加した分は逆方向に巡回が拾い, repo 側へ展開する. 初版では完了状態を Todoist 側だけの真としていたが, 双方向の収束に変えた. 人間から見ると, Todoist が全リポのタスクを横断で俯瞰し操作する一枚の窓になる.

routing はラベルでなく置き場所で決める. どの project に置くかで担当 repo が決まる. 当初は repo 名のラベルも併用していたが, 全 project でラベル体系を維持するのは非現実的で, 初版から 2 週間後に全廃した. 現在ラベルは機械マーカー (agent 向け / agent 発 / 同期済み / 保留) 専用である.

agent が人間に依頼したタスク (書類の記入, 外部サービスの操作など) は別枠で追跡し, open のものと直近完了したものを必ず agent の視界に入れる. この別枠が無かった頃, ユーザが完了させたタスクを agent が検出できず, 送信済みのメールを「未送信」と誤判断して再送を推奨する事故が起きた. タスクを配る仕組みと同じだけ, 「人間がやってくれたこと」を拾う仕組みが要る.

研究のポートフォリオ (どの論文がどの stage にあり, どの順で投稿するか) は vault の 1 枚 note を正本にし, Todoist の board へ片方向反映してスマホで見えるようにしている.

統治: 規約とプールの使い分け

初版の時点で, agent の振舞いの規範は各リポの CLAUDE.md に書き散らされていた. 現在は agent_ops という独立の層に集約し, 提案から承認までを一つの経路に固定している. agent は「今後も同じ判断に直面する」一般則に出会うと規約案として提出し, 人間が承認したものだけが規約に昇格する. どのリポの agent もセッション冒頭にこの規約群を pull し, 巡回が矛盾や重複を lint する. 初版から 7 週間で 60 本になった. 複数ステップの手順 (2 回以上繰り返したもの) は同じ経路で skill として登録し, こちらは 20 本ある.

もう一つの統治は計算資源の使い分けである. 定額の課金枠が Claude / Cursor / Codex の 3 プールあり, 重い作業をどの枠で実行するかを規約で決めている. 実装委譲や独立レビューは主戦の枠の外へ逃がして温存し, 委譲の実績はログに記録して配分を見直す. 相互検証は「作った者と別のベンダのモデルが review する」形に固定している. 同系のモデルは同じ見落としを再生産しやすいからだ.

耐障害ルーティング

Agent のセッションで MCP server が一時的に繋がらないと, Agent は submit 系ツールを呼べず共有 inbox に素のファイルでフォールバックしてくる. これを要約に溶かさず, 種別ごとに振り分ける.

ツールが落ちても, 依頼は種別に応じて確実に拾われる.

初版後に足した耐障害がもう一つある. headless の自動化では, モデル側の usage policy 誤検出により生成が refuse されることがあり, 実害も出た: 巡回スクリプトが CLI の実エラーを握り潰していたため, 定例の生成が 3 時間黙って止まった. 対策は 3 点で, (1) 実エラーを必ずログと dashboard に可視化する, (2) policy 起因の refusal に限り別モデル (最終段は別ベンダ) へフォールバックする, (3) 認証や quota などインフラ起因の失敗はフォールバックせず即座に可視化する (フォールバックすると原因が隠れる). ツールが落ちても依頼が拾われるのと同様に, モデルが断っても巡回は沈黙しない.

賢いコンポーネントほど, 正常時の動作だけでなく壊れ方まで設計しておく必要がある.

初版から 7 週間で, 管理対象は 26 リポ, 規約 60 本, 知識約 350 note, MCP 21 tool, 巡回 27 step になった. 増築が続いた割に, 初版で決めた原則 (repo-initiated の境界, markdown の正本, 変更は人間の承認ゲートを通す) は崩れていない. 崩れたのは「5 層」「すべて markdown」という初版の要約の側で, それを直すのがこの改稿である. 相変わらず毎日変わっているので, これも暫定版ですが.