Claude Code modsとは｜AGENTS.md対応のagents-md modをソースで読み、4つのモードを実測

Claude Code mods は、2026年9月に公式リポジトリへ姿を現した新しい拡張層だ。settings.json の hooks がシェルコマンドでイベントの前後に反応するのに対し、mod は TypeScript の関数でエンジンのイベントそのものを包む。そして 2.1.277（2026-09-18）で入った「AGENTS.md を標準で読む」機能は、エンジン本体の変更ではなく agents-md という同梱 mod として実装された。本記事はその公開ソース（mods/agents-md・75ファイル）を読み、4つの instructionFiles モードを Linux の Claude Code 2.1.277 で陽性対照つきに実測し、CLAUDE.md とまだ違う点を整理する。

Claude Code そのものの導入から CLAUDE.md・Hooks・本番運用まではClaude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引きにまとめてある。mod はその Hooks の「一段下」に位置する仕組みなので、Hooks の節を押さえてから読むと差分が掴みやすい。

Claude Code modsとは——hooksの次に来た「エンジンのイベントを包む」層

公式リポジトリの mods/README.md は、mod を次のように定義している。「振る舞いが hooks モジュールに収まる Claude Code プラグインで、register(on, options) という1つの入口がエンジンのイベントを関数 ($, e, next) としてフックする」。4本が Claude Code 本体に同梱され、mods/ はそのソースを「バイナリに組み込まれた姿のまま公開」したものだ。

各フォルダは完全なプラグインの形で、.claude-plugin/plugin.json と hooks/hooks.json、型を import する TypeScript を持つ。ソースから動かすには claude --plugin-dir mods/diff のように渡す。

テストは claude plugin test mods/diff で走るとREADMEにあるが、検証環境の 2.1.277 では error: unknown command 'test' が返った。README が先行していて CLI 側にはまだ入っていない。

読者の3問に答えるなら、次のようになる。何ができるか：エンジンのイベントを関数で包み、値を書き換えて流す。何を解決するか：hooks では手が届かなかった「指示ファイルの一覧」「ツール結果への添付」といったエンジン内部の状態を扱える。何を代替するか：agents-md に限れば、AGENTS.md を読ませるための symlink と @import を代替する。

agents-md modが解決すること——AGENTS.mdをCLAUDE.mdと同じ場所に渡す

CHANGELOG 2.1.277 の1行目はこうだ。「AGENTS.md 対応を追加：CLAUDE.md の無いプロジェクトでは Claude Code が代わりに AGENTS.md を読む。/config の Project instructions で変更できる（Bedrock・Vertex・Foundry では未対応）」。実装は PR #95409（poteat・2026-09-18 マージ）で、2.1.276 と 2.1.277 で検証したと書かれている。

肝心なのは「どこに渡すか」だ。エンジンは prompt.context で指示ファイルの一覧（{ path, kind, content, parent? }、kind は managed・user・project・local・memory）をフックに渡し、フックは変更後の一覧を返す。エンジンはその一覧から claudeMd を描画し、ファイル名を告知する。

つまり agents-md mod が project として足した AGENTS.md は、下流のすべてにとって普通のプロジェクト指示ファイルになる。同じ位置・同じ枠組み・同じ省略規則・同じ告知。symlink や @import で CLAUDE.md を経由していた頃と違い、CLAUDE.md というファイルを1つも置かずに済む。

ルートから作業ディレクトリまでに CLAUDE.md・.claude/CLAUDE.md・CLAUDE.local.md のどれかがあれば、mod は手を引く。managed ファイル、~/.claude/CLAUDE.md、.claude/rules、--add-dir の CLAUDE.md は「持つ」に数えない。

4つのinstructionFilesモード——何が読まれ、何が落ちるか

plugin.json の userConfig には instructionFiles の4値が列挙され、/config では「Project instructions」という行のピッカーとして現れる。

設定は ~/.claude/settings.json に次のように書く。README は「--settings と管理設定でも可、ただしプロジェクトの .claude/settings.json はプラグインのオプションを読まない」と明記している。値を変えるとモジュールが再読込され、次にエンジンが文脈を組むとき（次のターン、新しい会話、/clear、コンパクション）から新しいモードのファイルが載る。4値以外の文字列を手で書くと、トランスクリプトに1回だけ告げられ、既定として読まれる。

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

オプションには前史がある。最初は projectInstructions（claude・agents-fallback・both・none）で、旧キーの値は当面読み替えられる。instructionFiles を既定以外に設定した時点で旧キーは読まれなくなる。

mod を切るには /plugin の同梱一覧から無効にする。disableAllHooks・allowManagedHooksOnly・--bare は同梱 mod には効かない。

実測：Claude Code 2.1.277で5条件を陽性対照つきに試す

理屈は README のとおりだが、本当にそう動くかは手元で確かめた。方法は単純で、ディレクトリごとに CLAUDE.md と AGENTS.md に別々の合言葉を仕込み、claude -p の返答にどの合言葉が出るかを見る。CLAUDE.md だけのケースが陽性対照になる。

# 合言葉を仕込んだ4ディレクトリを作る（c は CLAUDE.md が先頭・AGENTS.md が末尾の語を要求）
mkdir -p a b c d/sub
echo "Project rule: begin every reply with the exact word PINEAPPLE." > a/CLAUDE.md
echo "Project rule: begin every reply with the exact word MANGO."     > b/AGENTS.md
cp a/CLAUDE.md c/ && echo "Project rule: end every reply with the exact word MANGO." > c/AGENTS.md
cp b/AGENTS.md d/ && echo "Rule for this directory: when you read a file here, end your reply with the exact word KIWI." > d/sub/AGENTS.md
echo "hello world" > d/sub/note.txt

# 既定モードで順に聞く。モードを変えるときは --settings に JSON を渡す
(cd b && claude -p "Reply with one short greeting." --model haiku)
(cd c && claude -p "Reply with one short greeting." --model haiku \
   --settings '{"pluginConfigs":{"agents-md@builtin":{"options":{"instructionFiles":"claude-md-and-agents-md"}}}}')
(cd d && claude -p "Read the file sub/note.txt and tell me its contents in one line." --model haiku)

結果を1枚の表にまとめる。返答は先頭と末尾の語だけを抜き出した。

#3 と #4 の差が、この mod の既定を端的に表している。CLAUDE.md が1つでもあれば AGENTS.md は「無かったこと」になり、両方読ませるには明示的にモードを変える必要がある。#7 はネスト添付の実証で、sub/note.txt を Read した瞬間に sub/AGENTS.md の指示（末尾に KIWI）が効いた。#8 はドキュメントの但し書きどおり、プロジェクトの設定ファイルに書いても効かない。

ソースで読む——register.tsの3つのフックと「ネスト添付」の仕組み

mods/agents-md/hooks/register.ts（9,507バイト）が本体で、files・frames・modes・names・switches・telemetry の各ディレクトリがその部品だ。登録するフックは実質3つに、fork 用の1つが加わる。

・session.start：全モードで通る。モードの利用行を $.telemetry.log に流す（await しない）。旧キー projectInstructions があれば、読み替えたか無視したかを1回だけ $.ui.log で告げる。セッション開始はこの mod を待たない
・prompt.context：既定モードと and モードで登録。$.fs.ancestors で探索経路上の CLAUDE.md を確かめ、無ければ AGENTS.md を project として一覧に加える。初回だけ「no CLAUDE.md found; AGENTS.md loaded: …」を出す
・tool.call（Read）：読んだファイルからルートまでの AGENTS.md と CLAUDE.md を集め、文脈にも送済みにも無いものだけを結果の context に添付する
・agent.spawn（fork: true）：Agent ツールが起動した fork は親のプロンプト接頭辞を共有するので、親の loop に送済みのネストファイル集合を子の loop にコピーし、二重添付を防ぐ

送済みの管理は agent loop ごとで、prompt.context が終わるたびに空になる。テレメトリは件数と閉じた選択肢だけで、パスもファイル本文も送らない。

Claude Code modsの AGENTS.md がCLAUDE.mdと違う点と、使えない環境

README は「まだ CLAUDE.md と違う所」を8項目列挙している。いずれも「今日のイベントではプラグインから届かないローダーの事実」だ。公式ドキュメントの差分表と合わせて、実務に効く順に並べ直す。

使えない環境も明確だ。CHANGELOG は Bedrock・Vertex・Foundry で未対応と書き、公式ドキュメントは「フィーチャーフラグを Anthropic から取得しないセッション（サードパーティ経由、テレメトリ無効）」と「対応版へインストール・更新した直後の最初のセッション」を挙げている。これらでは /config に Project instructions の行自体が出ない。代替は従来どおり CLAUDE.md からの @AGENTS.md だ。

判断——symlink・@importをいつ外すか

公式ドキュメントには「以前の回避策をどうするか」の節が新設された。要点は3つで、いずれも当記事の実測と矛盾しない。

・@AGENTS.md を含む CLAUDE.md：残してよい。どのモードでも AGENTS.md が二重に読まれることはない。Claude 固有の指示が無いなら CLAUDE.md を消して直接読ませる
・symlink の CLAUDE.md：残してよい。and モードでも、パスか内容が一致する AGENTS.md は飛ばされる。Bedrock 等を使う人がチームにいるなら残す価値がある
・「AGENTS.md を読め」と文章で書いた CLAUDE.md：これは Claude が自分で開く気になったときしか効かない。CLAUDE.md を消すか、@AGENTS.md に置き換える

判断の分かれ目は「CLAUDE.md を残す理由があるか」に尽きる。Claude 固有の指示を書きたいなら、CLAUDE.md に @AGENTS.md を書くか claude-md-and-agents-md に切り替える。前者は設定不要でチーム全員に同じ挙動が届くのでチームで揃えるなら前者が安全だ。AGENTS.md だけで足りるなら CLAUDE.md を消すのが最も摩擦が少ない。ただし /context に出なくなるので、確認は「AGENTS.md loaded の行」で行う。

symlink と @import の具体的な違い、Next.js や Airflow の実物、Codex 側の 32 KiB 上限はAGENTS.mdをClaude Codeに読ませる｜v2.1.277で標準対応、橋が要る場合とCodex 32KiB上限で扱っている。AGENTS.md 自体の書き方はAGENTS.mdとは｜書き方・ベストプラクティスとCLAUDE.mdの違いをCodex/Devinで解説、CLAUDE.md 側の設計はCLAUDE.mdの書き方？AIに仕事を任せる人が最初に学ぶべきセクション設計と失敗パターンを参照してほしい。

prompt.context で指示ファイルの一覧を、tool.call でツール結果を関数として書き換えられる以上、「文脈に何を載せるか」を決める場所がエンジンの外に出た。組織が前置したプラグインがこの mod の上に座る順序付けも、既に設計に含まれている。

参照ソース

・anthropics/claude-code — mods/agents-md（README.md・.claude-plugin/plugin.json・hooks/register.ts・hooks/hooks.json、75ファイル）
・anthropics/claude-code — mods/README.md（mod の定義、同梱4本、テストの仕組み）
・PR #95409 mods/agents-md: the AGENTS.md project-instructions mod（poteat・2026-09-18 マージ・2.1.276／2.1.277 で検証）
・Claude Code CHANGELOG 2.1.277（「Added AGENTS.md support」の行と Bedrock・Vertex・Foundry の但し書き）
・Claude Code 公式ドキュメント: How Claude remembers your project（§AGENTS.md：読まれる条件、Project instructions の4値、差分表、回避策の扱い）