結論：AGENTS.mdは「置けば全環境で同じ」ではない
Claude Code v2.1.277では、プロジェクトにCLAUDE.mdがない場合、AGENTS.mdを読む対応が追加されました。公式release notesは、/configのProject instructionsから変更できること、Bedrock・Vertex・Foundryではまだ対応していないことを明記しています。したがって、AGENTS.mdは便利なファイル名の追加であって、提供条件・優先順位・検証を省略できる仕組みではありません。
読者の課題は、複数のagent toolが使うAGENTS.mdを置いた結果、Claude Codeが読んだと思った指示を別providerや別surfaceが読まないことです。最初に「正本」「互換コピー」「機密情報を置かない範囲」を決め、clone後のreadbackまでを導入手順に含めます。
根拠はClaude Code v2.1.277公式リリースとCLAUDE.md・AGENTS.md公式文書です。設定の優先順位はSettings files and precedence、長い手順の分離はSkills公式文書を正本にします。既存のsubagent指示ファイルは起動時promptの分離、managed settings承認は組織設定の変更管理が中心で、本稿はrepository内のProject instructionsへ限定します。
CLAUDE.mdとAGENTS.mdを比較する
| 選択 | 向いている状態 | 注意点 |
|---|---|---|
| CLAUDE.md | Claude Code固有のproject ruleを正本化 | 既存repoの運用と重複しないか確認 |
| AGENTS.md | 複数agent toolで共有するproject instruction | Claude Codeのprovider・version対応を検証 |
| 両方 | 共通規約とClaude専用補足を分ける | 矛盾、重複、読み込み順を定期review |
| Skills・rules | 特定作業やpathだけに適用 | 毎sessionへ全文を積まない設計にする |
公式文書はCLAUDE.mdをproject、user、managedなどのscopeで説明し、AGENTS.mdを既存のproject instructionとして扱います。ここで大切なのはファイル名よりも、内容が「Claudeに毎回知ってほしい短い事実・規則」かどうかです。API key、個人情報、環境固有のURL、秘密の運用手順をrepositoryへ入れないでください。拒否したい操作を文書だけで強制することもできないため、必要ならpermission、hook、CI gateを別に設計します。
導入前に行う8手順
- 対象surfaceを列挙する。Claude CodeのCLI、IDE、Desktop、SDK、Bedrock、Vertex、Foundryを使う場所ごとに記録します。
- 正本を一つ決める。既存のCLAUDE.mdを残すのか、AGENTS.mdへ移すのか、両方の役割を一文で定義します。
- 指示を三分類する。全員が守る規約、projectの構成知識、特定作業だけの手順へ分けます。
- 機密を除く。credential、customer data、内部host、個人の好みを、version管理される指示ファイルから外します。
- 短く書き直す。build command、test command、directory、禁止事項、review条件を具体的な検証可能な文にします。
- scopeを図にする。managed、command line、project local、shared project、userの同名設定がどう競合するか確認します。
- /configでreadbackする。Project instructionsにどのファイルが表示・変更対象になるか、CLIとproviderごとに確認します。
- 小さな変更で回帰する。新しいclone、subdirectory、worktree、Bedrock等の非対応環境で、期待した指示が読まれない時の表示を確認します。
移行では、ファイルをrenameして終わりにしないでください。まず旧CLAUDE.mdの内容を棚卸しし、必須のproject factと作業手順を分離します。AGENTS.mdを追加する場合は、同じ規則を二か所へコピーして片方だけ更新される状態を避けます。両方を置く場合は、共通の禁止事項を重複させず、Claude Code専用の補足だけをCLAUDE.mdへ残すなど、差分が意図的であることをREADMEへ明記します。
worktreeやmonorepoでは、rootのAGENTS.mdとsubdirectoryのAGENTS.mdが同時に候補になります。repositoryのどの階層で何が適用されるかを、代表的なdirectoryで実際にreadbackします。共通規約をrootへ、サービス固有のbuildとtestを該当subdirectoryへ置き、親子で逆のルールを書かないことが安全です。利用者が別branchで古い指示を読む可能性もあるため、重要な変更はcommit、review、適用日を残します。
企業利用でのreviewと強制を分ける
AGENTS.mdはinstruction contextであり、設定やpolicyの代替ではありません。例えば「productionへ書き込まない」と書いても、tool権限、network、credential、CIの保護がなければ強制できません。文書は判断材料と期待する手順、permissionやhookは実行の境界、CIは成果物の品質、と役割を分けます。
変更reviewでは、命令の追加だけでなく、既存ルールとの矛盾、context消費、適用範囲を確認します。毎sessionで読むファイルが長すぎると、重要な規則が埋もれます。path-scoped rulesやSkillsへ移せる手順は分離し、レビュー担当者が一回のdiffで意味を判断できる量に保ってください。Skillsの出所管理と同じように、誰が追加・削除・承認するかを台帳化すると、個人のローカル変更が標準へ混ざりにくくなります。
対応外providerでAGENTS.mdが読まれない場合は、同じ名称を配るだけで解決しません。CLAUDE.md、managed settings、provider側のproject instructionなど、公式に確認できる経路へ内容を移し、sourceとversionを記録します。対応状況が変わる将来に備え、テスト用の短い規則と期待するreadbackをrepositoryへ残し、更新時に自動検証できるようにします。
チェックリスト
- Claude Code v2.1.277以降を確認した
- AGENTS.mdを正本にする理由を書いた
- CLAUDE.mdとの重複・矛盾を確認した
- Bedrock・Vertex・Foundryの対応外条件を記録した
- 機密情報を指示ファイルから除いた
- root・subdirectory・worktreeの適用範囲をreadbackした
- 文書とpermission・hook・CIの責任を分けた
- 変更owner、review、rollbackを決めた
よくある質問
CLAUDE.mdを削除すればAGENTS.mdへ自動移行できますか？
自動移行を前提にしないでください。内容の棚卸し、providerごとの対応、/configでのreadback、別cloneでの回帰確認を行ってから削除または役割変更を決めます。
AGENTS.mdに秘密の開発手順を書いてよいですか？
repositoryへ共有するファイルなので、credentialや個人情報を置かない設計が原則です。秘密はsecret storeやmanagedな仕組みへ分離します。
AGENTS.mdに禁止事項を書けば実行を止められますか？
文書は判断を導くcontextです。強制が必要な操作はpermission、hook、network、CIなど別の制御で止め、両者を同じルールへ結び付けます。
公式情報
次の一歩
指示ファイル、権限、review、CIが別々で、変更理由を説明できない場合は、ファイル名を増やしても運用は安定しません。Miraigentの無料診断で、project instructionの正本と実行制御の境界を60秒から棚卸しできます。