Anthropicのコーディングツール「Claude Code」がバージョン2.1.277からAGENTS.mdに対応した。ルールはシンプルで、あるフォルダーにCLAUDE.mdが存在しない場合、Claude Codeは同じフォルダー内のAGENTS.mdを探し、プロジェクトの指示としてコンテキストに読み込む。CLAUDE.mdが置かれているフォルダーでは、従来通りCLAUDE.mdのみを参照する。
このバージョンは9月18日にGitHubで公開された。Claude CodeチームのメンバーであるThariq氏がSNSでこの変更を発表している。
Starting today in version 2.1.277, if there is no CLAUDE.md in a folder, Claude will check for and use AGENTS.md.
本日リリースの2.1.277から、フォルダーにCLAUDE.mdが存在しない場合、ClaudeはAGENTS.mdを探して使用するようになる、という内容だ。
4段階の切り替え
AGENTS.md対応は組み込みプラグインとして実装されており、コードはClaude CodeのGitHubリポジトリで公開されている。ユーザーは/configの「Project instructions」から切り替えられ、モードは4段階ある。
| モード | 挙動 |
|---|---|
| claude-md | CLAUDE.mdのみを読み込む。実質的にこの機能をオフにするのと同じ |
| claude-md-or-agents-md（デフォルト） | 同じフォルダーにCLAUDE.mdがあればそこのAGENTS.mdは無視し、なければAGENTS.mdを読み込む |
| claude-md-and-agents-md | ディレクトリツリー全体で両方のファイルを読み込む |
| managed-only | リポジトリにコミットされた指示ファイルと個人用の指示ファイルを破棄し、組織が一括配布したファイルとメモリのみを残す |
デフォルトモードは「フォールバック」であり「マージ」ではない。すでにClaude Code用にCLAUDE.mdを用意しているリポジトリは、アップグレード後も挙動が変わらない。CLAUDE.mdを一度も書いたことがなく、他のツール向けにAGENTS.mdだけを用意していたリポジトリだけが、今回初めてこのファイルを読み込まれることになる。パスや内容が重複と判定された同一ファイルは、二重に読み込まれることはない。
CLAUDE.mdとの違いがいくつか残る
プラグインのドキュメントには、CLAUDE.mdとの違いがいくつか挙げられている。サブディレクトリ内のAGENTS.mdは、Agentがそのディレクトリ内のテキストファイルをReadツールで読んだときにのみ付随して読み込まれる。IDEの選択範囲、Notebook、画像、PDFではトリガーされない。付随して読み込まれたファイルは「既読」として記録されないため、コンテキスト圧縮後に自動で復元されることもない。/memoryコマンドや#によるクイックメモリもAGENTS.mdには触れない。--add-dirで追加したディレクトリもAGENTS.mdを提供しない。シンボリックリンクのパスは解決されず、文字列としてそのまま比較される。
対応チャネルについては、AWS Bedrock、Google Vertex、Microsoft Foundryは今のところ未対応だ。同じバージョンでは指示ファイル関連でもう一つ変更があり、SDKとヘッドレスモードでの起動時、最初のターンでCLAUDE.mdの検索完了を待たなくなった。
1つのリポジトリに複数のAgent
AGENTS.mdは、コーディングAgent向けに書かれたREADMEのようなものだ。ビルド方法、テストの実行方法、コードスタイルの規約、触れてはいけないディレクトリなどを記す。このフォーマットはもともと2025年にOpenAI Codexなど複数のツールが共同で推進し、その後Linux Foundation傘下のAgentic AI Foundationに管理が移り、CursorやGitHub Copilotなど各ツールが認識できるようになっている。Claude Codeはこれまで自社のCLAUDE.mdしか認識しておらず、複数ツールを併用するチームは、ほぼ同じ内容の2つのファイルを維持せざるを得なかった。シンボリックリンクで両者を同じファイルに向けるのが、よく使われる回避策だった。
国内(中国)チームのツール構成はさらに雑多になりがちで、Claude Code以外にKimi Code、Qwen Code、Cursor、Codexなどがよく併用される。これらの多くはデフォルトでAGENTS.mdを読むか、指示ファイル名を変更できる。デフォルトモードなら、既存リポジトリは何も変更しなくていい。AGENTS.mdだけを維持したいチームはCLAUDE.mdを削除して指示を1本化できるが、その前に上記の制限、特に長時間セッションが圧縮された後にサブディレクトリの指示が自動で戻らない点は確認しておくべきだ。
managed-onlyモードは企業の管理者向けだ。リポジトリにコミットされた指示ファイルはAgentによって指示として実行されるため、それ自体が汚染されうる入口になる。管理者はこのモードを使うことで、組織が一括配布したルールのみを許可できる。大規模チームでの運用実績を示す公開データは、現時点ではまだない。
参考資料: Claude Code GitHubリリースノート、CocoLoop、Anthropicエンジニア Thariq氏の公開投稿。agents-mdプラグインのドキュメントで4つのモード、読み込み順序、制限事項を確認済み。