AGENTS.md をリンクで CLAUDE.md と共有する方法と、それを裏書きしない文書たち

AGENTS.md と CLAUDE.md をリンクで束ねる共有の慣行

AIに仕事を頼むとき、プロジェクトごとの約束事を書いたメモを用意するやり方が広がっている。AGENTS.md はその約束事を書くファイルの名前で、ある種類のAIツールが読む。CLAUDE.md は同じ役割のもので、別の種類のAIツールが読む。内容はほぼ同じなのに、読む道具が違うためにファイル名が二つ必要になる。

ここでよく使われるのが、シンボリックリンクという仕組みだ。シンボリックリンクとは、実体ではないが実体につながった紙のことで、見た目は一枚のファイルでありながら、開くともう一つのファイルの中身が出てくる。

このリンクを使うと、AGENTS.md と CLAUDE.md に一つの中身を同じように供給できる。手間が半分になり、直す場所も一つで済む。ところが、この方法には一つ気になる点がある。使っている人は多いのに、どこかが「この方法は正しい」と保証している文書が見当たらないのだ。今日たまたま動いているのと、明日も動くと約束されているのは別の話である。この距離は、実測で確かめる価値がある。

文書の表面三か所での確認結果

まず、保証が書いてある可能性の高い三つの文書を調べた。一つ目はClaude Codeの変更履歴である。変更履歴とは、その道具がこれまでに何を新しく読めるようにしたかを書き並べた日記のような文書だ。そこにAGENTS.mdを直接読む機能が載っていれば、リンクを使う必要はすでに薄い。

調べ方の一例は素朴だ。公式の変更履歴を丸ごと取得し、AGENTS.mdという言葉が何回出てくるか数える。同じ方法で、AGENTS.mdの公式仕様書と、もう一つのAIツールCodexの公式文書も眺めた。結果は次のとおりだった。

同じ変更履歴でCLAUDE.mdへの言及が59件、リンクへの言及が72件あったことを考えると、0件という数から、この話題が扱われなかったことがはっきりわかる。書く人がこの話題を避けたのではない。話題として扱う機会がそもそもなかったことを示す数だ。

仕様書とCodexの文書にも、リンクで共有する置き方を薦める記述は見つからなかった。AGENTS.mdの仕様には symbolicLink という言葉が一か所だけ現れたが、それがリンクを許す話なのか禁じる話なのかは、この調査では読み切れていない。いずれにしても、リンクで共有する置き方を積極的に薦める文はどこにも見つからなかった。なお、文書に載っていないことが自動的に「存在しない」を意味しない点には限界がある。

測り方：四つのセル、12回の実行

文書を読むだけでは足りないので、ファイルの置き場所を管理する仕組みの側も測った。LinuxというOSの入った薄い箱の中で、AIそのものは一度も動かさず、ファイル操作だけを4種類、各3回、計12回の実行をした。AIを呼ばなかったのは、測りたいのがAIの判断ではなく、リンクという仕組みそのものだからだ。

四つのうち三つは測定として完走した。残る一つの32KiBサイズ上限検査は、測定器具側の不具合で全試行が止まり、その項目だけは結果が出なかった。

再配置後の生存の差

測定の中心になったのは、フォルダごと引っ越したときにリンクが生き残るかどうかだ。ここには二種類の張り方がある。一つは相対パスのリンクで、「隣の家の方へ」と方向で指す紙。もう一つは絶対パスのリンクで、「本店の住所はここ」と壁に住所を書き込んだ紙である。

相対の紙なら、家ごと丸ごと引っ越しても方向はそのままで読める。住所の紙は、建物自体が変わらないうちは正しいが、場所が変わった瞬間に古い住所を指したまま台無しになる。実測はこの日常の見立てどおりに終わった。

張り方	isSymlink	解決
相対リンク CL_rel.md	true	true
絶対リンク CL_abs.md	true	false

コピーにした置き方は、リンクではない普通のファイルとして生き残った。ここで差が出る原因は道具の賢さではなく、リンクのもつ意味そのものにある。相対リンクは相手を「自分との距離」で記憶し、絶対リンクは「当時の場所の住所」を文字として記憶する。引っ越したとき、相対リンクの記憶方法は意味を保ち、絶対リンクの記憶方法は正しくなくなる。結果を作ったのは ln という命令の性質であって、AIツールのどの処理でもない。

32KiB サイズ上限検査が止まった場所

AIツールの中には、読み込むメモの大きさに上限を設けているものがある。その上限が32キロバイトで、サイズ超過時にどう処理されるかは、今回の実測では確認できていない。ここで自然な疑問が出る。リンクを張った場合、この大きさの測定は、シンボリックリンクそのものに対して行われるのか、リンク先の実ファイルに対して行われるのか。

この疑問には今回は答えられなかった。3回の試行はいずれも、対象のファイルが見付からないというエラーで止まり、大きさの比較が一度も実行されなかった。停止の原因は測り方の側にある。リンクの生成を確認した同じ手順では解決できたのに、この検査だけが決まった場所で落ちたので、準備の段階の不具合と考えるのが自然だ。つまり「リンクは上限検査にそのまま投影される」という予想は、確認も否定もされていない状態で残る。

この記事が確認できなかったこと

今回は三つの限界が残った。第一に、AI道具がリンクの中身を実際に読んでいるかどうかの実行検証をしなかった。第二に、32KiBの検査が全試行失敗で、上限との関わりが完全に未測定のままだ。第三に、仕様書に現れた symbolicLink のただ一つの文を読んでいない。この置き方の唯一の文書的根拠がそこにある可能性は、排除できない。次に見るべきは、その一文の文脈と、リンクを実際に置いた状態での道具の読み取りである。また、変更履歴は日々更新されるため、ここに書いた0件という数は調べた時点の値だ。なお、リンク共有をやめたい場合には、相対パスのリンクに置き換えるか、リンクの代わりにファイルの複製を配ればよい。チームの決まりとしてこの繋ぎ方を採用したい人は、紙を決まりの文に書くのではなく、紙を作る係と毎日折り返し確認する係を自分のチームの中に置くこと。そして、Claude Codeの変更履歴にAGENTS.mdを直接読む項目が新たに現れたら、この結論は引き上げる。どこかの文書がこのリンクの使い方を保証する文言を載せた場合も同じだ。この判断は、2026-08-30時点の文書の記録とファイルシステムの測定だけに基づく。

参考資料

1. Claude Code CHANGELOG (raw scan target) — Anthropic (raw.githubusercontent.com)
2. AGENTS.md spec page (symlink 규정 부재 확인 대상) — agents.md
3. Codex 공식 문서·README (symlink·한도 규정 부재 확인 대상) — OpenAI