AIエージェントを増やすほど「共通ファイル」への依存関係が複雑になる

複数体のAIエージェントを運用する構成では、各エージェントが個別の役割を持ちながら、いくつかの共通ファイルを横断的に参照します。たとえばブランドのトンマナを定めたファイル、委任の作法を定めたファイル、料金や商品構成を定めたファイルなどです。これらは「真実源」として1箇所にまとめておくのが定石で、同じ内容を各エージェントの定義に複製すると、直したときに一部だけ更新漏れが起きて矛盾を抱えることになります。真実源を1本化すること自体は正しい設計判断です。

問題はその先にあります。真実源を1本化すると、そのファイルを直す作業は「1回の変更で、読んでいる全員に影響する」作業になります。エージェントが数体のうちは、どの体がどのファイルを読んでいるかを頭の中で把握できます。しかしrelmeaのチームは2026年7月28日の時点で既にエージェント96体・コマンド45本まで増えており、この時点でもう「頭の中で把握」は成立しなくなっていました。共通ファイルを直すたびに、波及先を列挙できないまま変更する状態です。これは、サイレントに壊れたまま気づけないリスクを常に抱えていることを意味します。

依存関係を管理するために「洗い出し台帳」を作った

この課題に対して2026年7月28日に作ったのが、依存関係を一覧化した「洗い出し台帳」（114行のMarkdownファイル）です。目的は明確で、複数エージェントが読む共通ファイルを直したときに、波及先を列挙できるようにすることでした。台帳には当時運用していた3つのシリーズ（ウェビナー制作14体・ファネル制作・SaaS開発）と、全社横断で使う正典ファイルを登録しました。

この台帳には、作成時点で既に重要な一文が書き込まれていました。「台帳は人間が書くので陳腐化する。実測（grep）が上位。台帳と実測がズレていたら台帳を実測に合わせて直す」というものです。つまり台帳を作った時点で、台帳がいずれ実態とズレることを予見していました。その予見は、結果としてそのまま的中することになります。

53日間で35体増えても、波及先を書いた台帳は1回しか更新されなかった

台帳を作ってから2026年9月19日までの53日間で、エージェントチームの規模は大きく変わりました。エージェントは96体から125体へ35体増加し、コマンドは45本から66本へ増えました。追加されたのはYouTube運用7体、動画レンダリング6体、メタ広告3体、学習ライブラリ4体、コピープロセス2体などです。

この53日間で、台帳が更新されたのは1回だけでした。2026年9月2日に、SaaS開発シリーズの総数を「26体から27体」に直す1行の修正のみです。追加された35体のうち、台帳に名前が載ったものは0体でした。さらに、廃止する時点で台帳に名前が出ていたエージェントは、当時の全125体のうち14体しかありませんでした。つまり台帳は「一部の古いシリーズだけを覚えていて、それ以外の約9割のエージェントについては何も知らない」状態のまま、依存関係の唯一の記録として存在し続けていたことになります。

これは台帳の担当者が怠けていたという話ではありません。実測（grepで確かめる）が正しいと最初に明記していたにもかかわらず、この53日間、誰も実測して台帳を直す作業を行わなかった。それだけ台帳を開く動機が、日々の作業の中に存在しなかったということです。

なぜ陳腐化したのか — 台帳という設計そのものの問題

原因を辿ると、サボりではなく構造の問題に行き着きます。台帳は「共通ファイルを直すとき」に読む前提で設計されていました。しかし実際にエージェントを新設する作業では、開くファイルは新しい体の定義ファイルと、その体が読みに行く共通ファイルの2つだけです。新設という作業の動線の上に、台帳は一度も登場しません。

言い換えると、台帳を更新するかどうかは「読む側が台帳の存在を思い出せるかどうか」に依存していました。思い出さなければ何も起きず、実体とのズレはそのまま静かに広がっていきます。これは共通ファイルの本体とは別の場所に「二重の情報源」を置いてしまったこと自体が原因です。情報が正しいかどうかではなく、情報が置いてある場所が、参照する人の視界に入らない場所だったことが、53日間で更新1回・登録0体という結果につながりました。

台帳という形式は、誰かが定期的に見に行く運用が成立して初めて機能します。その運用コストを、日々増え続けるエージェント新設作業に常に上乗せし続けるのは現実的ではありませんでした。

台帳を廃止し、依存関係を「読まれる場所」へ焼き込む

2026年9月19日に、台帳（114行）を廃止しました。代わりに採用したのは、依存関係の情報を独立したファイルに集約するのではなく、実際に「読まれる場所」そのものへ両面から焼き込む方式です。

面1: 共通ファイルの冒頭に「誰が読むか」を書く

1つ目の面は、共通ファイルの冒頭です。各共通ファイルの先頭に、次の形式のヘッダーを設置しました。

  • このファイルは以下が読む: エージェント◯体（実名列挙）＋コマンド◯本（実名列挙）
  • 実測: grep -ln <ファイル名> .claude/agents/*.md .claude/commands/*.md（YYYY-MM-DD時点 N件）
  • 変更したら各体の該当節を確認

これを共通ファイル5本に設置しました。たとえばアプリ一覧を定めたファイルはエージェント20体・コマンド14本が読んでおり、grepで実測すると34件がヒットします。委任の作法を定めたファイルはサブエージェント11体とL1コマンド全部が読んでおり、実測は65件です。ファネル型のカード集を定めたファイルはエージェント6体・コマンド2本が読んでおり、実測は8件です。これらの数字はすべて、書く直前にgrepで数え直したうえで、ヘッダーの体数表記と実測件数を並べて記載しています。

面2: 各エージェント本体に「依存する共通ファイル」を書く

2つ目の面は、各エージェント本体側です。新設するエージェントの定義ファイルに「依存する共通コンテキスト」という節を設け、そのエージェントが依存する共通ファイルのパスを明示的に列挙するようにしました。これは新設される体から適用しており、既存の体を一括で改修することはしていません。既存の体には、作業開始時に確認すべき項目を並べた節が既にあり、同じ役目を代替していたためです。

新設の動線の上に置く

エージェントの新設を指揮する側の手順にも、この設計を組み込みました。共通ファイルの冒頭ヘッダーを書き終えるまで次の工程に進まない、という順番を新設フローの中に置いたのです。台帳のときの失敗は「更新作業が本流の動線の外にあったこと」だったので、今回は逆に、新設という作業そのものの中に依存関係の記録を組み込みました。

焼き込みで実現した「逆引き」と、この設計が効く条件

この設計の実際の動き方はこうです。共通ファイルを直そうとして開いた瞬間、冒頭のヘッダーに波及先の一覧が目に入ります。これが一次の逆引きです。次に、そのヘッダーが本当に正しいかどうかは、ヘッダーに書かれたgrepコマンドをそのまま実行して検証できます。全エージェント本体を対象に共通ファイル名でgrepをかければ、ヘッダーの体数表記と実際の参照数が一致しているかどうかがその場で分かります。ズレていれば、そのタイミングでヘッダーを実測値に合わせて直せばよいだけです。

台帳方式との違いは、情報の正しさではなく、情報がどこにあるかという点に尽きます。台帳方式にはこの3つがどれも欠けていました。

  • 情報が「使う瞬間に既に開いているファイルの中」にある（思い出す必要がない）
  • 一覧に実測コマンドが併記してあるので、ヘッダーが古びてもgrep一発でズレを検出でき、自己修復できる
  • 記録作業そのものが新設フローの中に組み込まれているため、別作業として独立して発生しない

成立条件: 共通ファイルが少数であること

ただし、この焼き込み方式にも成立条件があります。共通ファイルが少数、目安として数本から十数本程度の規模であることが前提です。共通ファイルが数十本規模に増えた場合、各ファイルのヘッダーを人力で書き続けるのは現実的でなくなるため、grepの実行結果からヘッダーを機械生成する方向へ寄せる必要が出てきます。手で書く量を増やさないことが、この設計を長く保つための条件です。

grepだけに頼らない理由

またこの方式は、grepだけに依存する設計とも違います。grepは「誰がこのファイルを読んでいるか」という機械的な事実は出せますが、「これは共通ファイルで、これは個別ファイルだ」という設計上の意図までは出せません。ヘッダーの1行（このファイルは共通ファイルであり、誰が読むか）が、その意図を人が読める形で残す役割を担っています。依存関係の管理は、機械的な実測と、人が書く意図の両方が揃って初めて、増え続けるエージェント数に追従できる仕組みになります。