Claude CodeとAGENTS.md：2026年のAIエージェント向け指示ファイルの仕組み

AGENTS.mdとは何か、なぜ存在するのか

しばらくの間、各コーディングツールが独自の指示ファイルを作っていました。Cursorには.cursorrules、Claude CodeにはCLAUDE.md、Aiderには.aider.conf.yml、GeminiにはGEMINI.md、といった具合です。1つのエージェント向けにリポジトリを整えても、次のエージェントのためにもう一度やり直す必要がありました。

AGENTS.mdはその解決策です。コーディングエージェントを導くための1つのオープンな形式で、多くのエージェントが読み込む、リポジトリルートのプレーンなMarkdownファイル1つです。プロジェクトはこれを"README for agents"と呼んでおり、私が見た中で最も的確な一言です。README.mdは人間向け（クイックスタートやコントリビュートガイド）で、AGENTS.mdにはエージェントが必要とする追加のコンテキスト（ビルド手順、テスト、規約）を入れます。これらはREADMEに入れると散らかってしまう内容です。

必須フィールドはありません。ただのMarkdownなので、好きな見出しを使えば、エージェントがテキストを解釈します。この標準は、OpenAI Codex、Amp、GoogleのJules、Cursor、Factoryなどによるエコシステム横断の協力から生まれ、最初のコミットは2025年8月19日でした。その後、中立的な場所に移り、現在はLinux Foundation傘下のAgentic AI Foundationが管理しています。リポジトリはagentsmd/agents.mdにあり、MITライセンスです。

これはニッチな実験ではありません。リポジトリには2.45万のスターが付き、GitHubのコード検索では6万以上のサンプルファイルが見つかり、OpenAI自身のリポジトリにも88個あります。これまで単なる流行だと無視してきたなら、そろそろやめどきだと思います。

実際に読み込むエージェント

トップページには24の対応ツールが並んでおり、この分野の主要どころがほぼ揃っています。Zed、OpenAI Codex、Gemini CLI、Cursor、Jules、Devin、Warp、Windsurf、VS Code、GitHub Copilotのコーディングエージェント、Aider、goose、Ampなどです。そして今月からはClaude Codeも加わりました。競合する多くのベンダーが静かに同じプレーンなファイルに落ち着いたのですから、この形式は事実上勝負がついたと言えます。

Claude CodeはAGENTS.mdを読み込む？はい、いまはネイティブで

多くの人が最初に抱く疑問なので、端的に答えます。Claude CodeはAGENTS.mdをネイティブで読み込みます。必要なのはv2.1.277以降です（Anthropicがクロスツール仕様を採用した2026年9月18日にリリース）。他のエージェントがすでに理解できるリポジトリは、CLAUDE.mdもインポート行も設定も追加せずに、Claude Codeで動きます。

注意したいのは、両方のファイルがある場合です。デフォルトの挙動は次のとおりです。

つまり、古くなったCLAUDE.mdが、丁寧に保守しているAGENTS.mdに黙って勝ってしまうのが落とし穴です。両方を読み込ませたい場合は、Project instructions設定（/config）にclaude-md-or-agents-md（デフォルト）、claude-md-and-agents-md（両方、CLAUDE優先）、claude-md（CLAUDEのみ）、managed-onlyという値があります。知っておきたい点として、CLAUDE.local.mdもCLAUDEファミリーのファイルとして扱われるため、1つ置くと、この設定を切り替えるまでClaudeはAGENTS.mdを読まなくなります。~/.claude/CLAUDE.md、管理ポリシーファイル、.claude/rules/は「CLAUDE.mdがある」の判定には含まれないため、AGENTS.mdと並んで引き続き読み込まれます。

もう1つ覚えておきたい癖があります。直接読み込まれたAGENTS.mdは/memoryや/contextに表示されず、InstructionsLoadedフックも発火しません。読み込まれたかどうかは、セッション開始時のAGENTS.md loadedという行で確認できます。このツールが初めてなら、入門ガイドとCLIリファレンスで基本を押さえられます。

CLAUDE.md vs AGENTS.md：正直な違い

これを対立のように語る人がいますが、実際はそうではありません。AGENTS.mdはクロスツールの標準で、CLAUDE.mdはClaude Code独自のより豊富な指示システムです。どちらもプレーンなMarkdownで、Claudeはいまやどちらも読み込みます。

実際的には、チームが複数のコーディングエージェントを併用しているなら、信頼できる唯一の情報源はAGENTS.mdに置きましょう。Claude Codeだけを使っていて、インポートやパスごとのルールが欲しいなら、CLAUDE.mdのほうが仕組みが充実しています。両方を持つことも可能ですが、偶然ではなく意図して連携させてください。

はっきり言っておくと、CLAUDE.mdはなくなりませんし、「劣っている」わけでもありません。AGENTS.mdがあえて省いている機能（仕様は意図的に最小限に保たれています）を持っています。どちらを選ぶかは、いくつのツールを使うかの問題であって、どちらの出来が良いかではありません。

Claude Codeが指示ファイルを読み込む仕組み

CLAUDE.mdファイルは最も広いスコープから最も具体的なスコープへと読み込まれ、見つかったものはすべて上書きではなく連結されます。そのため、起動した場所に近い指示ほど最後に読まれます。スコープは4つあります。

1. 管理ポリシー（組織全体、最初に読み込まれ、除外できません）。macOSでは/Library/Application Support/ClaudeCode/CLAUDE.mdのようにOSごとのパスに置かれます。
2. ユーザー（~/.claude/CLAUDE.md）。すべてのプロジェクトに共通するあなた個人の設定です。
3. プロジェクト（./CLAUDE.mdまたは./.claude/CLAUDE.md）。ソース管理を通じてチームで共有します。
4. ローカル（./CLAUDE.local.md）。プロジェクトごとの個人的なメモで、.gitignoreに追加します。

探索は再帰的です。Claudeは作業ディレクトリとその上のすべてのディレクトリからCLAUDE.mdファイルを読み込みます。自分より下のサブディレクトリにあるファイルは起動時には読み込まれず、Claudeがそれらのフォルダ内のファイルを読むときに必要に応じて取り込まれます。このサブツリーの挙動のおかげでモノレポも扱いやすく、AGENTS.mdの動きとも一致します。最も近いファイルが優先され、チャットでの明示的な指示はすべてに優先します。規模の目安として、OpenAIのメインリポジトリには、パッケージごとに1つずつ、88個の独立したAGENTS.mdファイルがあります。

このパッケージごとの分割は見た目以上に重要です。大きなコードベースでは、ルートの1ファイルだけでは限界に達するからです。これは、こうしたツールを大規模に運用している人から最もよく聞く不満です。

"AGENTS dot md files don't scale beyond modest codebases. Lots of discussions on this lately. If you're building serious software with Claude Code or any agentic tool, a single AGENTS dot md will eventually fail you."

elvis (@omarsar0), X

解決策はファイルを大きくすることではなく、増やすことです。短いルートファイルと各パッケージ内のネストしたファイルを組み合わせ、エージェントが常に、触っている対象に絞った指示を読めるようにします。

インポートと4階層の上限

CLAUDE.mdは@path/to/import構文で他のファイルを取り込めます。相対パスも絶対パスも使え、インポートされたファイルがさらに別のファイルをインポートすることもできますが、最大の深さは4階層です。パスをバッククォートで囲むとインポートされません（ファイルに言及したいだけのときに便利です）。コンテキストを減らそうとする人がつまずく点があります。インポートに分割してもトークン使用量は減りません。インポートされたファイルも起動時に読み込まれるからです。整理には役立ちますが、サイズの削減にはなりません。

良いAGENTS.md（またはCLAUDE.md）に書くこと

必須のセクションはありませんが、よく使われるのは、プロジェクト概要、ビルドとテストのコマンド、コードスタイル、テストの指示、セキュリティ上の注意、PRやコミットのルールです。仕様にある標準的な例は次のようなものです。

# AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package.
- Run `pnpm install --filter <project_name>` to add a package to your workspace.

## Testing instructions
- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check.
- Fix any test or type errors until the whole suite is green.
- Add or update tests for the code you change, even if nobody asked.

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.

ドキュメント以上の意味を持たせる点は、記載したテストコマンドが自動的に実行されることです。エージェントは関連するチェックを実行し、終わる前に失敗を修正しようとします。つまり、正確なpnpm testの1行は単なるメモではなく、エージェントが実行に移す指示なのです。

書き方については、AnthropicのCLAUDE.mdのガイダンスがAGENTS.mdにもそのまま当てはまります。どちらもコンテキストウィンドウに読み込まれ、強制される設定ではなくコンテキストとして扱われるからです。

• 短くする。 200行未満を目標にしましょう。長いファイルはコンテキストを消費し、ドキュメントによれば、エージェントが従う精度を実際に下げます。
• 具体的にする。 書き方のガイダンスによれば、"Use 2-space indentation"は"Format code properly"より優れ、"Run npm test before committing"は"Test your changes."より優れています。検証できるほど具体的にルールを書きましょう。
• 構造化する。 Markdownの見出しと箇条書きで、関連する指示をグループ化します。
• 一貫性を保つ。 2つのルールが矛盾していると、Claudeはどちらかを任意に選ぶことがあるため、ネストしたファイルを定期的に見直しましょう。

うまく書けば、多くの人が思う以上に効果があります。これらのファイルの保守を扱ったAsk HNのスレッドで、ある開発者はこう述べています。

"AGENTS.md is extremely important - it's probably the highest leverage thing you can give your agent. It's injected into every turn, and the agents are trained to follow instructions. If anything, I think people are under-investing into AGENTS.md and going purely based on vibes."

bisonbear, Hacker News

最初の下書きを最速で作る方法は/initです。コードベースを分析してビルドコマンド、テスト、規約を見つけ、初期ファイルを書き出します（CursorやCopilotのファイルを移行することもできます）。その後は/memoryで編集し、/contextで実際に何が読み込まれたかを確認します。また、CLAUDE.mdはシステムプロンプトの後にユーザーメッセージとして渡されるため、厳密な遵守は保証されません。何があってもルールを強制したいなら、ドキュメントは指示ファイルではなくPreToolUseフックを勧めています。

1つのファイルをすべてのエージェントで共有する方法

Claude CodeをCodex、Cursor、Geminiと併用しているなら、目標は信頼できる唯一の情報源を持つことです。ネイティブ対応により、いまはそれがデフォルトです。すべてをAGENTS.mdに入れ、CLAUDE.mdは追加しません。

古いバージョンを使っている場合や、ネイティブ読み込みが使えない環境（Amazon Bedrock、その他のサードパーティプロバイダ、テレメトリ無効）では、CLAUDE.mdからインポートするのが代替策です。

# CLAUDE.md
@AGENTS.md

昔ながらのシンボリックリンクもありますが、ドキュメントでは現在、最後の手段として扱われています。

ln -s AGENTS.md CLAUDE.md

シンボリックリンクの方法には実際の注意点があります。ClaudeのEditツールとWriteツールはシンボリックリンクを通した書き込みを拒否し（編集は対象のAGENTS.mdにリダイレクトされます）、Windowsではcore.symlinksを有効にしていない限り、コミットしたシンボリックリンクがプレーンテキストとしてチェックアウトされます。そのため、いまはインポートのほうが無難です。古いファイルを統合するための公式の移行ワンライナーは次のとおりです。

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

避けたいよくある間違い

私がよく目にする落とし穴をいくつか挙げます。その多くは優先順位のルールに直接由来します。

• 忘れていたCLAUDE.mdがAGENTS.mdを黙って上書きする。 両方あればClaudeはCLAUDE.mdを読みます。古いほうを削除するか、もう一方をインポートしましょう。
• インポートをダイエットだと考える。 巨大なファイルを@インポートに分割してもコンテキストは減りません。すべて読み込まれます。代わりに内容を削りましょう。
• 曖昧なルール。 "Write clean code"では何も変わりません。正確なコマンド、正確なインデント、正確なPRタイトルの形式を書きましょう。
• 600行のファイル。 約200行を超えると、遵守率が下がります。複数ステップの手順はスキルやサブエージェントに、コードベースの一部だけに関わるルールはパス単位の.claude/rules/ファイルに移しましょう。
• 強制されると思い込む。 指示ファイルはコンテキストであり、厳格な関門ではありません。確実にブロックしたいならフックを使いましょう。

指示ファイルの周辺環境については、settings.jsonガイドと権限に目を通しておくと役立ちます。どちらも、ルールが実際にどう適用されるかに影響するからです。

eeselを試す：同じ発想を、サポートを担うエージェントに

ここで話がつながります。AGENTS.mdとCLAUDE.mdは、コーディングエージェントに常時有効な指示をファイルで渡す方法です。そのコーディングエージェントは、あなたが設定するインフラです。eeselは絵のもう半分にあたります。指示を与えるツールではなく、決まった仕事のために採用する、すぐ働けるAIチームメイトです。現在は、サポートキューを担当するAIヘルプデスクエージェントとAIブログライターがあります。

そして、同じ「指示は1か所にある」という考え方で動いています。eeselエージェントの常時ルールは、設定画面に散らばっているのではなく、編集可能な1つの指示セットと、実際のナレッジ（過去のチケット、ヘルプセンター、ドキュメント）で構成されています。AGENTS.mdの考え方を、サポートのチームメイトに当てはめたものです。

すでにターミナルが日常の場なら、馴染み深く感じるはずです。eeselには本格的なCLI（@eesel/cli）があり、そのドキュメントは意図をはっきり述べています。ダッシュボードでできることはすべてターミナルからでき、AIコーディングエージェントにセットアップを任せることもできます。インストール不要で実行でき（npx @eesel/cli init）、エージェントとチャットし（eesel chat）、常時ルールを編集し（eesel instructions）、エージェントが何をしたかを確認できます（eesel activity）。すべてのコマンドはJSONを出力し、--dry-runに対応しています。だからこそ、人がクリックして回るのではなく、スクリプトやエージェントから操作できるのです。

さらに、すべてのeeselワークスペースはMCPサーバーでもあります。eesel mcp tokenを実行すると、そのまま貼り付けられるclaude mcp addの行が出力され、Claude Code（あるいはCursorやCodex）が、エディタを離れずにサポートエージェントの指示を管理し、アクティビティを確認し、保留中のアクションを承認できます。同じエージェントを、ターミナル、スクリプト、MCP経由のコーディングエージェントという3つの面から扱えます。

料金は固定の月額で、500クレジット（チケットまたはチャット1件につき1クレジット）が月額$299からです。ダッシュボード上の質問はほぼ無料で、カード不要・100クレジットの無料プランもあります。すでにAGENTS.mdを書いているなら、すぐに馴染めるでしょう。eeselを試すか、Claude Codeを向けて配線を任せてみてください。