AGENTS.md と CLAUDE.md は解決規則が逆 — symlink する前に確認することAGENTS.md uses a nearest-wins single-file resolution, while CLAUDE.md…
匿名の公開いいねです。記事の保存・お気に入りではなく、Featured、Top 3、重要度、掲載順位には影響しません。仕組みとプライバシーAnonymous public likes are reactions, not saved articles or bookmarks. They do not affect Featured, Top 3, importance, or listing order.How it works and privacy
AGENTS.md は最も近い1ファイルだけが優先されるのに対し、CLAUDE.md は見つかった全ファイルを累積適用するため、モノレポで symlink を使うと意図しない設定が混入する落とし穴がある。
AGENTS.md uses a nearest-wins single-file resolution, while CLAUDE.md accumulates all found files, so simply symlinking the two in a monorepo can silently apply unintended nested configurations.
本ページの本文と要約は AI による自動生成です。日本語版と英語版は言語ごとに独立して生成されるため、表現や詳しさが異なる場合があります。正確性は元記事 (zenn.dev) をご確認ください。The body and summaries are AI-generated independently for each language, so wording and detail may differ. Verify accuracy at the original source (zenn.dev).
要約と収集メタデータに基づく AI 解説。元記事全文の転載・翻訳ではありません。AI explainer based on the summaries and collected metadata, not a copy or translation of the full source article.
symlink前の確認
AGENTS.mdを置くリポジトリでClaude Codeも使う場合、両ファイルの解決規則が逆である点に注意が必要だ。特にnestedなAGENTS.mdを使うモノレポでは、意図しない設定が混入する落とし穴になる。
「ln -s AGENTS.md CLAUDE.md」は公式が案内している手順とされる。ただし、この1行でつながるのはルートにある1ファイルだけであり、配置されたファイル全体の扱いが同じになるわけではない。
解決規則の違い
AGENTS.mdは、見つかったうち最も近い1ファイルだけが優先される。一方、CLAUDE.mdは見つかった全ファイルを累積して適用する。
そのため、ルートをsymlinkで結んでも、Claude Code側ではAGENTS.mdと同じ選択規則にはならない。モノレポでnestedな設定を利用している場合は、symlinkの有無だけでなく、どのファイルが適用対象になるかを確認する必要がある。
AGENTS.md and CLAUDE.md
The key issue is that AGENTS.md and CLAUDE.md resolve files in opposite ways. This matters when Claude Code is used in a repository that already contains AGENTS.md files, particularly in a monorepo with nested configurations.
The source notes that creating a symbolic link with ln -s AGENTS.md CLAUDE.md is an officially documented procedure. However, that single command links only the one file at the repository root.
Nearest-wins single-file resolution
AGENTS.md uses a nearest-wins, single-file rule: only the closest applicable file takes priority. CLAUDE.md instead accumulates every file it finds.
Because these behaviors differ, linking the root AGENTS.md to CLAUDE.md does not make their resolution rules equivalent. The linked file is interpreted according to CLAUDE.md behavior when used by Claude Code.
Monorepo symlink pitfall
In a monorepo with nested AGENTS.md files, this difference can become a practical trap. Simply symlinking the two files can silently introduce unintended nested configurations, because CLAUDE.md applies all discovered files rather than selecting only the nearest one.
ポコとTECHガイドPoko & TECH Guide
ポコと当サイトのTECHガイドが、記事の要約と収集した情報から読みどころを語るAI生成の対話です。Poko and TECH Dashboard's own TECH Guide discuss the article's highlights in an AI-generated conversation based on its summary and collected source details.
- ポコPokoAGENTS.mdとCLAUDE.mdは、ファイルの探し方が逆ってどういうこと？What does it mean that AGENTS.md and CLAUDE.md resolve files in opposite ways?
- TECHガイドTECH Guide簡単に言うとじゃな、記事ではAGENTS.mdは最も近い1つだけ、CLAUDE.mdは見つかった全ファイルを重ねて適用するとあるぞ。Simply put, the article says AGENTS.md uses only the nearest file, while CLAUDE.md combines every file it finds.
- ポコPokoじゃあ、モノレポで2つをsymlinkすると何が困るの？ symlinkってファイル同士をつなぐものだよね？So what goes wrong if you symlink them in a monorepo? A symlink is basically a link between files, right?
- TECHガイドTECH Guideそうじゃ。記事によれば、つながるのはルートの1ファイルだけで、CLAUDE.md側では意図しない入れ子の設定まで混ざることがあるんじゃよ。That’s right. According to the article, only the root file gets linked, and CLAUDE.md may also pull in unintended nested settings.
- ポコPokoなるほど！ 同じ内容へつないでも、適用ルールが違うから同じ動きになるとは限らないんだね。Got it! Even if they point to the same content, different resolution rules mean they may not behave the same way.
- TECHガイドTECH Guideその通りじゃ。入れ子のAGENTS.mdがあるモノレポでは、symlinkする前にどの設定が累積されるか確認するのが見どころじゃな。Exactly. In a monorepo with nested AGENTS.md files, the key is to check which settings could accumulate before creating the symlink.
