あなたの指示ファイルはアドレッシングであり、断片化ではありません

エージェントツールの世界には、整理整頓好きの衝動が出回っています。すべてを支配する 1 つの指示ファイル、というわけです。どのコーディングエージェントも自前の dotfile を、CLAUDE.md やそれに相当するものを育ててきました。そして複数を運用するチームは、結局のところ、不注意な編集のたびに少しずつ乖離していくニアイコールの重複ファイルの小さな山を、抱え込むことになります。それに対して、どのツールも読む単一の標準には明白な魅力があり、AGENTS.md を求める主張は Claude Code に直接ぶつけられました。Claude 固有のファイルは他ツールの共同作業者のところへうまく渡っていかないのだから、共通の標準にコンテキストを運ばせて、全員が 2 つのコピーを保つのはもうやめよう、と。この重複は本物ですし、その苛立ちはもっともです。

その要望が実際にどう解決されたかに注目してください。他を飲み込む万能ファイルによってではなく、1 つのポインタによってです。その issue を閉じた maintainer のコメントは、自分の CLAUDE.md を共通ファイルへの 1 行のインポートに、AGENTS.md の include にすることを勧めていました。そうすれば共通のコンテキストがセッション開始時に読み込まれ、ツール固有の行はそれに取って代わるのではなく、その隣に並びます。2 つの名前をつなぐシンボリックリンクも提案されていますが、そちらは退化したケースです。シンボリックリンクは 2 つの名前をまとった 1 つのファイルであり、何かが隣に並ぶ余地はどこにもありません。ですから失って困るツール固有の行が 1 つもないときにだけ、正しい選択になります。興味深いのはインポートのほうです。重複への処方箋が、統合ではなく参照だと判明したからです。共通のものは 1 か所に保ち、アドレス付けされたものはアドレス付けされたまま保つ。この形を覚えておいてください。見た目ほど多くを決着させてはいないからです。

インポートは読み込みを解決します。共通ファイルとネイティブファイルを、1 つのセッションで 1 つのエージェントの前に並べる。それこそが重複への苦情の全体だった問題です。それが手をつけないのは所有権です。どの行がそのリポジトリに属し、クローンする誰のところへも渡っていくのか、そしてどの行が私に属し、共通ファイルには決してコミットしてはならないのか。それが、何もかも統合する版の主張には見えない区別です。なぜならその主張は、これらのファイルを、散らばった 1 つのもののコピーとして読むからです。いくつかはそうです。大半はそうではありません。似て見えるのは、どれもが持つ唯一の形式が Markdown だからで、メモも住宅ローン契約書も脅迫状も、みな等しくただのテキストであるのと同じです。入れ物が同じことは中身が同じことではありません。そして本気のエージェント構成が積み上げる指示ファイルは、異なる読み手に向けて、誰が編集してよいかについての異なるルールのもとで、異なる問いに答えています。ファイル拡張子を共有しているからと 1 つにまとめれば、あなたは偶然を取り除いたのではありません。アドレッシングを取り除いたのです。

アドレスとは、1 つの行がどこに属するかを決める、たった 1 組の事実です。何に当てはまるのか、そしてどれだけ速く変わるのか。ネットワークではアドレスは、パケットが誰宛てかを告げるものであり、別々のアドレスを持つことの価値は、アドレスが保守して気持ちいいからではなく、それがなければ何もルーティングできないからです。指示ファイルも同じです。どの行もアドレス付けされていて、それらを整理する問いは、どのツールがパースするかではなく、それが何についての事実なのか、です。そうしたスコープは 3 つあり、統合の主張が正しく聞こえる理由は、そのうちの 1 つだけを正面から見据えているからです。

第 1 のスコープはオペレーター、つまり私であり、どのプロジェクトからも独立しています。エージェントが私にどう話すべきか、壁を回避する方法をひねり出す代わりにいつ立ち止まって尋ねなければならないか、シークレットをどう扱うか、同じやり方で 3 回失敗したあとに何をするか。そのどれもコードベースについての事実ではありません。それはあらゆるエージェントに、触れるすべてのリポジトリへ持ち込んでほしい心構えであり、それらすべての上位に、私自身の設定の中に置かれ、誰のプロジェクトの持ち物でもないからこそ、すべてのセッションに注入されます。それをリポジトリごとのファイルへ押し下げようとすれば、あなたの選択肢は、コピーすること、つまり同じルールが微妙に異なる版へと乖離していくこと、あるいは捨てることだけです。ここではインポートも助けにはなりません。その理由はまさに所有権の論点です。私の個人ガイドを include しようとする共通のリポジトリファイルは、同僚のチェックアウトでそれを見つけられないか、各人ごとに異なるものを引き込むかの、どちらかになります。オペレーターのレイヤーは共通の成果物の中を旅してはならないレイヤーであり、だからこそ共通の成果物こそが、それの行けない唯一の場所なのです。

第 2 のスコープはプロジェクトです。このスタック、これらの規約、知らなければ噛みついてくるこの制約、このリポジトリで、そしてほかのどこでもなく、エージェントが役立つために必要なローカルな真実。これは AGENTS.md が収まる、しかもうまく収まるレイヤーであり、インポートが実際に共有するレイヤーです。というのも build コマンドも test runner も、生成ファイルには決して触れないというルールも、どのツールが読もうと真だからです。もし議論の全体がこのスコープだけについてなら、統合派は端的に正しく、彼らの主張の誠実な版は、彼らが正しいというものです。デュアルファイルの提案はすでにこれを感じ取っています。共有のセットアップとツール固有の素材を、両方を 1 つのバケツに押し込むのではなく、切り分けているのです。誤りはただ 1 点、プロジェクトのレイヤーについての正しい主張から、あらゆるレイヤーについての主張への飛躍だけにあります。

第 3 のスコープは環境です。エージェントが動く場所に、実際に何がインストールされ動いているか。このランタイムが定義したサブエージェント、ここでプロビジョニングされ認可された MCP サーバー、このホスト固有のサービスとタイマー。この移行をスキーマのサブエージェントに渡せ のような行は、たまたま Claude のファイルに着地した可搬なコンテキストだ、というのが直感ですが、そうではありません。ただしその理由は、他のツールにはこれができない、よりも具体的です。他のエージェントにもサブエージェントはありますし、MCP はクライアント横断で使えるように作られました。定義はコピーされる普通のファイルです。可搬でないのは解決です。参照が何かを意味するのは、それが名指すものが実際に整えられている場所だけです。そのサーバーが一度もプロビジョニングされたことのないマシンで読まれる万能ファイルにそれを落とせば、それは共有のコンテキストではなく、何も指さない参照です。このスコープの中には速い軸と遅い軸、つまり永続的な束縛とライブな状態がありますが、それらは同じ問い、すなわち今この瞬間にこの環境について何が真か、に答えていて、その問いはプロジェクトのものでも私のものでもありません。(手順ファイル、つまりスコープではなく今どんなタスクをしているかでアドレス付けされる skill やスラッシュコマンドは、これらすべてを別の軸で横断します。それらは実在するカテゴリーで、別の議論であり、ここでは脇に置きます。)

ここまでは別々のファイルを保つべきという論であり、インポートに基づく単一の入り口はすでにそれを尊重しています。それでも公正な読み手は、行が 1 つの物理ファイルにあるか、縫い合わされた複数にあるかがなぜ重要なのか、と問えます。理由はこうです。同じ内容を、何に当てはまるかではなく、誰が書いてよいかで仕分けてみてください。リポジトリの共有ファイルは、プルリクエストを開ける誰もが書き込め、しかも見知らぬ他人からクローンするどのリポジトリにも、すでに書かれた状態で届きます。私のオペレーターガイドは、私だけが書き込めます。それらは異なる信頼レベルであり、今日それらを隔てているのは、別々のファイルで異なる立場で読まれるという事実のほかには、ほとんど何もありません。それらを、エージェントが単一の権限レベルで取り込む 1 つのドキュメントに統合すれば、あなたは見知らぬ他人が編集できるテキストを、立ち止まって人間に尋ねよ と告げることだけが役目のルールと、同じファイルに同居させたことになります。オペレーターのレイヤーはスタックの中でリポジトリを上回れる唯一のものであり、それこそがリポジトリの中に置いてはならない正確な理由です。これはまた、include を使えばいい が、聞こえるほどの反論ではない理由でもあります。信頼できないリポジトリファイルをオペレーターの信頼されたコンテキストへ引き込む include は、解決策ではなく脆弱性であり、参照の安全な向きは、小綺麗な版が望む向きのちょうど正反対です。

それを手にすれば、区別は名指しやすく、しかもそれは統合の主張が決してしない区別です。断片化とは、多くのファイルが同じ問いに答えていることです。4 つのツールにまたがる 4 つの AGENTS.md 風のファイルが、みな同じ build 手順を唱えている。これは絶対に 1 つの共有プロジェクトファイルへまとめるべきで、その点では標準は本物の勝利です。レイヤー化とは、いくつかのファイルがそれぞれ別の問いに、別のスコープで、別の書き込み権限のもとで答えていることです。インポートはレイヤーを組み立て、そのあいだ各レイヤーを、それを所有すべき者の所有のもとに保ちます。ネイティブファイルを読んで止まるフォールバックは、何も組み立てず、ただレイヤーを 1 つ落とすだけです。そして、実際に生きている意見の対立がいかに狭いかに注目してください。オペレーターの常設ルールやホストの稼働中サービスを共有のリポジトリファイルに置くべきだ、とほとんど誰も論じません。はっきり口に出した瞬間、それは明白に間違っています。本当に争われている境界はただ 1 つ、オペレーターの境界だけで、しかもそれは誰にも声高に争われておらず、それこそがそれが侵食されていく道筋そのものです。レイヤーは誰かが統合を布告するから崩れるのではありません。共有ファイルがいったん慣習になれば、それが人々の手が伸びるファイルになり、オペレータースコープや環境スコープの行が、便利な編集のたびに少しずつ、そこへ漏れ込んでいくから崩れるのです。

私はかなりの数のエージェントを運用していますが、システムを読み解けるものに保っているのは、何もかもが 1 つのファイルにあることではありません。それは、私がいつでも狭い問いに答えられることです。どの指示がどのエージェントに届き、誰がそれをそこに置いてよかったのか。運用上の心構えは、あらゆるプロジェクトの上位の 1 か所に置かれるので、変えるべきコピーは 1 つで、全員に対して一度に変わり、リポジトリが同梱するどんなものもそれを上書きできません。各プロジェクトは自身の真実を述べ、自身の repo とともに旅します。環境のレイヤーは、それが解決する場所にとどまります。AGENTS.md はそれが作られたレイヤーにとって良い解決策で、議論を閉じたインポートは、そのレイヤーを共有する正しいやり方です。共有ファイルのどの提案も答えておらず、インポートもまた答えていないのは、優先順位です。プロジェクトファイルが これをせよ と言い、私のオペレーターガイドが これは決してするな と言うとき、統合された単一のファイルにはちょうど 1 つの規則、ドキュメントの順序しかありません。レイヤーの積み重ねなら少なくとも、どれが勝ちなぜかを言わせてくれます。それが未解決の部分であり、それはレイヤーを名指せるまま保つべきという論であって、技術的には短いが、肝心な唯一の問いにもう答えないテキストの壁へと混ぜ合わせるべきという論ではありません。