AGENTS.md を CLAUDE.md につなぐ三つの方法と、例示の一行が文書の読み込みを止める問題
三つの接続方法を実測したら結果は同じで、選ぶ基準は速さではなく環境の制約だった。本当の落とし穴は、例示の一行が文書の読み込みを静かに止めることにある。
規則文書が二つになる問題
AI に作業を頼むとき、ルールや約束ごとを書いた文書を用意しておくと仕事の質が安定する。この文書には名前が二つある。Claude Code という道具は CLAUDE.md という名前だけを読む。別の道具たちは AGENTS.md という名前の方を読む。Claude Code は AGENTS.md という名前の文書を読まない。公式の説明にそう書いてある。
名前が違うだけで中身は同じ用途の文書が二つ並ぶと、同じ内容を二度書くことになる。同じ内容を二か所に書くことになり、片方だけ直して片方を直し忘れる事故が起きる。問題になるのは、書いたルールが本当に AI に届くかどうかだ。AGENTS.md を一つだけ手書きにしたい。それを CLAUDE.md が読めるようにしたい。文書そのものは書かずに、参照だけで済ませる方法があればよい。その方法はあるのか。実測で確かめた。
三つの接続方法
公式に用意されている引き方は三つある。一つめは「インポート」という機能で、CLAUDE.md の中に @AGENTS.md と一行だけ書く方法だ。インポートとは、その場に書いたこととして別のファイルの中身を取り込む仕組みだ。手紙の本文に「同封の説明書を参照」と書くのではなく、説明書の中身をそのまま手紙に写し込んでくれるイメージだ。
二つめはシンボリックリンクという仕組みを使う方法だ。シンボリックリンクとは、あるファイルの「写し」ではなく「同じファイルを指す道標」をもう一つ作るやり方だ。これを作ると、AGENTS.md と CLAUDE.md の二つの名前のどちらから読んでも同じ一つのファイルにたどり着く。三つめは単純に複製する方法で、AGENTS.md の中身を CLAUDE.md という名前のファイルにそのまま作っておく。
どの方法が一番いいのかは、やってみないと分からなかった。接続の仕方によって、読み込まれる内容や読み込みに必要な分量が変わる可能性があるからだ。そこで三つの方法を同じ条件で回して比べた。
測定方法
比較のために六つの状態を作った。AGENTS.md を置きっぱなしにした状態、CLAUDE.md は置かない。@AGENTS.md の一行を入れた状態。シンボリックリンクを作った状態。複製した状態。さらに落とし穴を探すため、@AGENTS.md の一行をコードブロックで囲んで書いた状態。コードブロックとは、見本を見せるために書き方を特別な枠で囲んだ領域のことだ。
それぞれに決め手となる確認用の手がかりを入れた文書を用意した。標識は、文書が本当に読み込まれたときだけ出力に現れる合図の文で、合図の出方で届いたかを判定できる。前段落の「確認用の手がかり」と呼んだものと同じである。各状態で三回ずつ実行し、合図が何回現れたかと、読み込みの量をトークンという単位で数えた。トークンとは、AI の側で文章を数えるときの単位で、おおまかに言えば単語や文字のくぎりのことだ。基準線として、ルール文書をどこにも置かない状態も回した。
- ステップ 1. カナリアという標識フレーズを入れたAGENTS.mdを六つの状態でそれぞれ用意した。
- ステップ 2. 各状態でClaude Codeを三回ずつ回して、標識が出力に現れるかを見た。
- ステップ 3. 何の接続もない状態では標識が出ないことを確認して基準線を作った。
- ステップ 4. 接続方法ごとに標識の的中回数を数えて互いに比較した。
- ステップ 5. コードブロック内に入れたimport文も別に試して、どこで解けるのかを見た。
接続なしで置かれた文書の結果
まず予想を確認した。AGENTS.md を置きっぱなしにして、何の接続もしなかったら、文書は読み込まれない。結果は三回とも標識ゼロだった。読み込まれたなら出るはずの標識文が、まったく現れなかった。読み込みにかかる量も、文書をどこにも置かない基準線とほとんど同じだった。文書は一枚も届いていないということだ。
これは当然の結果に思える。だが落とし穴を探す段階で、予想と逆のことが起きた。
三つの接続方法の実測結果
三つの接続方法は、どれも三回の中で三回標識が現れた。届くかどうかという判断なら、三つが同じ結果だった。届いたときにかかる量を比べると、違いはあった。もっとも軽いシンボリックリンクともっとも重いインポートの差は 122 トークンで、インポートは複製より 116 トークン多かった。
ここで文書の分量を確認する。ルール文書一式が占める量は約 2,920 トークンだった。三つの方法の 122 トークンの違いは、その約 4 パーセントだ。六つの状態を比べた結論は、読み込まれる内容に差はなく、トークン数に小さな差があるだけだというものだった。つまりこの結果から読み取れるのは、方法の優劣はスピードや読み込み量の問題ではなく、作業のしやすさや手間の問題に変わるということだ。
@importとシンボリックリンクとコピーは三つの方法すべてが同じ文書内容をモデルに入れてくれ、接続がなければ文書はまったく入らなかった。
数字には一つ注意がある。各条件は三回ずつしか回しておらず、同じ実験の中で理由の分からない 109 トークンの揺れが観測された。だから「三つは完全に同じ」と断定するのは行き過ぎで、「どれも届くし、金額の差は小さい」という言い方が正確だ。三つの方法の 122 トークンの違いが文書全体の約 4 パーセントであるということ自体は、この揺れがあっても安定していた。
例示のコードとして囲まれた一行の落とし穴
ルール文書や設定の書き方を誰かに説明するとき、「こう書けば読み込まれる」という例を文書の中に載せたくなる。その例として @AGENTS.md と一行書いて、見本なのでコードブロックで囲んでおいた。予想では、囲まれた行は文書として読み込まれなくなるが、ほかはいつもどおりだろうということだった。
結果は逆だった。囲んだ状態では、三回とも標識が一切現れなかった。読み込みにかかる量も、囲まなかった場合よりずっと少なかった。しかも読み込みの量も、文書をどこにも置かなかった状態とほとんど同じだった。つまり文書全体が一枚も届いていなかった。囲んだのが一行なのに、読み込まれなくなったのはその一行ではない。文書の全部だった。トークン数で見ると、失われたのは約 2,920 トークンで、この揺れの 27 倍にあたる規模だ。
なぜこうなるのか。Claude Code は文書を読み込むとき、その中にインポートの指示があるかを見る。このときコードブロックの中は「見本として書かれた文字」であって、指示ではない、という解釈が定められている。公式の説明には、インポートの読み取りはコードブロックと囲み文字を飛ばすと明記されている。つまり囲まれた @AGENTS.md は指示として解釈されない。その結果、文書に書かれていたはずの読み込みは行われず、文書全体がなかったものとして扱われた。
厄介なのは、この失敗にエラーも注意も一切出ないことだ。エラーも注意も何も出ない。作業中の人が気づくのは、読み込まれるはずだったルールが効いていないという事実からだけで、原因が例示の一行だとは思いつきにくい。設定を書き込むとき、見本として見せるつもりで書いた一行が、文書ごと消す引き金になりうる。
接続方法を選ぶ基準
三つの方法は結果が同じだった。だから選ぶ基準は、どれが一番読み込みが軽いかではなく、自分の環境でどの方法が一番壊れにくいかだ。使える方法は環境ごとに変わる。Windows ではシンボリックリンクを作るのに管理者権限が必要になる。公式の説明は、Windows では @AGENTS.md の引き方を使うように案内している。一方で複製は毎回手作業が発生して、直すとき忘れやすい。手作業の手間と直し忘れのリスクも判断の材料に入る。
以上を踏まえると、Claude 専用の追記なしに AGENTS.md を参照できて権限の制限がない環境では、シンボリックリンクが標準の選択になっていた。反対に Windows 環境などで権限の制限があるなら、@AGENTS.md の一行を入れる形が現実的だった。差は 122 トークン、つまり文書全体の約 4 パーセントで、選択の判断材料にはならなかった。このことから導ける判断は、接続の方法は速さではなく、手元の制約から選ぶべきだということだ。
この記事が確認できなかったこと
この測定は各条件三回ずつで、まれに起きる揺れは捉えられなかった。理由の分からない 109 トークンのがたつきも説明できていない。Windows でのシンボリックリンク挙動も確認しておらず、別の道具では同じ結果が出るかも分からないから、次はこれらを確認する必要がある。最後に、この記事全体の判断には条件が付く。同じ測定をもう一度回したとき、どれかの方法が三回とも標識を出さなければ、この判断は間違いになる。トークン量の差が 122 から大きく外れた場合も同様だ。