2026年のClaude Code、Codex、Cursorのための単一の指示ファイル

サービスについては、Ailootのドキュメントをご覧ください。

Claude Code、Codex、Cursorを一緒に使うと何が変わる？#

ここで説明する例では、Claude Codeをメインツールとして使い、CodexとCursorは特定のタスクに使います。私のCLAUDE.mdには、何をどの順番で読むか、何に触れてはいけないか、デプロイにどのコマンドを使うか、コミットの書式ルールなど、約250行の指示があります。このプロジェクトで初めてCodex CLIを試したとき、Codexはどのルールも知りませんでした。git push --forceを実行し、.envをのぞき、ファイル名を不注意に変更しました。

最初はCLAUDE.mdを手作業でAGENTS.mdにコピーしました。2週間後、プロジェクトには同じ指示の版がすでに4つあると気づきました。CLAUDE.md、AGENTS.md、.cursorrules、.windsurf/rules/です。それぞれ少しずつ違っていました。これはClaudeやCursorの問題ではなく、複数の情報源があるシステムにありがちな基本的な落とし穴です。この問題については、マルチエージェント作業のガイドで詳しく説明しています。

2026年6月、AnthropicのClaude Codeメモリに関するドキュメントは、共有ファイルとインポートという1つの解決策を示しました。2026年9月以降、プロジェクトにCLAUDE.mdがなければClaude CodeはAGENTS.md自体を読み込むようになり、Claude専用のルールがある場合はインポートが必要です。以下では、単一のAGENTS.mdで十分な場合、インポートの設定方法、共有ルールとClaude専用ルールの分け方を説明します。

Claude CodeはAGENTS.mdを直接読み込む？#

2026年9月より前の答えは「いいえ」でした。AGENTS.mdのサポートを求めたIssue #6235は、2025年8月からオープンしており、2026年8月17日にクローズされました。その間、メモリのドキュメントは1つの解決策を案内していました。CLAUDE.mdを作成し、インポートとしてAGENTS.mdを含める方法です。バージョン2.1.277以降、ドキュメントの説明は変わっています。

Claude Codeが読み込む内容は、プロジェクト内のファイル構成によって決まります。

この確認では、作業ディレクトリとその上位の各ディレクトリにあるCLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.mdが対象になります。個人用の~/.claude/CLAUDE.md、企業が管理するファイル、.claude/rules/のルールは対象外です。これらはAGENTS.mdと一緒に読み込まれます。

CLAUDE.mdがない場合、Claude Codeは起動時に作業ディレクトリとその上位にあるすべてのAGENTS.mdおよび.claude/AGENTS.mdを読み込み、サブディレクトリ内のファイルを開くと、そのディレクトリのAGENTS.mdも読み込みます。AGENTS.md内の@pathインポートも機能します。Claude CodeはAGENTS.local.md、AGENTS.override.md、.agents/ディレクトリの内容は読み込みません。

落とし穴は、個人用のCLAUDE.local.mdも対象になることです。コミットしていないルールを保管するためにこれを作成すると、Claude CodeはAGENTS.mdを黙って読み込まなくなります。以下の設定で解決できます。

動作は/configの「Project instructions」で変わります。

AGENTS.mdを失わずにCLAUDE.local.mdを使いたい場合は、claude-md-and-agents-mdを設定してください。AGENTS.mdがすでに@AGENTS.mdの行またはシンボリックリンクで含まれている場合、設定にかかわらず二重に読み込まれることはありません。

/memoryコマンドを使うと、ファイルが読み込まれたか確認できます。バージョン2.1.280以降では、一覧にAGENTS.mdのパスが表示されます。バージョン2.1.277より前、または組み込みのagents-mdプラグインが無効なセッションでは、Claude CodeはCLAUDE.mdのみを読み込み、/configに「Project instructions」の項目はありません。バージョン2.1.281より前は、Amazon Bedrock経由のセッションとテレメトリが無効なセッションも同様に動作しました。古いバージョンから更新した直後の最初のセッションでは、AGENTS.mdが読み込まれない場合もあります。次のセッションから機能します。

単一ファイルで運用する場合はどうすればよいでしょうか。Claude専用のルールがなければ、CLAUDE.mdは省略できます。AGENTS.mdだけで十分で、Claude Code、Codex、Cursorがこれを読み込みます。専用ルール（リスクの高いディレクトリでのplan mode、スキル、フックなど）がある場合はCLAUDE.mdが必要です。その場合、Claude CodeはAGENTS.mdを自動では読み込まなくなるため、CLAUDE.md内に@AGENTS.mdの行を置いてインポートします。この方法は9月より前と同じように機能し、古いバージョンのClaude Codeにも役立ちます。詳しくは以下で説明します。

CLAUDE.md内に@AGENTS.mdをインポートするには？#

公式ドキュメントにある最小限の動作例です。

@AGENTS.md

## Claude Code

`src/billing/`以下を変更するときはplan modeを使ってください。

実際の動作は次のとおりです。最初の行の@AGENTS.mdはインポート指示です。Claude Codeはセッション開始時にCLAUDE.mdを解析し、このインポートを見つけると、その場所にAGENTS.mdの内容全体を挿入します。続く## Claude Code見出しは、単なるMarkdownですが、「Claude専用の追加ルール」セクションとして機能します。その下には、Claude Codeだけに適用するルールがあります。billingディレクトリの変更にはplan modeを使う、というルールです。Codex CLIやCursorはこのファイルを開かず、通常のAGENTS.mdを使います。

インポートの仕組みについて、ドキュメントから引用します。

実用上の詳細をいくつか挙げます。

• 相対パスと絶対パス。 @AGENTS.mdは、インポートを記述したファイルからの相対パスです。@/Users/me/shared/rules.mdや@~/.claude/personal.mdは絶対パスです。私は、リポジトリに入れたくない個人設定に@~/.claude/personal.mdを使っています。
• 4段階の深さ。 AGENTS.mdから@docs/coding-style.mdをインポートし、さらにcoding-style.mdから別のファイルをインポートできます。深さは最大4階層です。実用上、これでどのような構成にも対応できます。
• バッククォートで囲むとインポートされない。 `@README`のように書かれていれば、名前への言及にすぎず、インポートされません。インポートを実行せずに仕組みを説明する場合に便利です。
• プロジェクト外のファイルには承認が必要。 @~/.claude/personal.mdのようにインポート先が作業ディレクトリの外部にある場合、Claude Codeは初回にそのファイルの一覧を示すダイアログを表示します。拒否すると、外部インポートは無効になり、ダイアログは再表示されません。プロジェクトルートの@AGENTS.mdではダイアログは表示されません。これにより、無関係なファイルを誤ってコンテキストに読み込むのを防げます。

説明したプロジェクトでこの設定に切り替えた後、CLAUDE.mdは250行から60行になりました。@AGENTS.mdに加え、Claude Codeだけに適用する5〜7個のルール（リスクの高いディレクトリでのplan mode、管理画面で触れてはいけないもの、コミットの表現方法など）です。共有ルールはすべて、CodexとCursorが読むAGENTS.mdに置いています。

シンボリックリンクとインポート、どちらを選ぶ？#

ドキュメントでは、シンボリックリンクの方法を次のように示しています。

ln -s AGENTS.md CLAUDE.md

また、Windowsについて率直な注意書きがあります。

比較表です。

説明したプロジェクトではインポートを使っています。理由は次のとおりです。

1. チームのOSが混在している。 私はMacを使っています。例のチームはWindowsとMacがおよそ半々です。リポジトリにシンボリックリンクがあると、開発者モードを使っていないWindowsユーザーには、AGENTS.mdという1行だけを含む通常のテキストファイルとしてチェックアウトされます。ルールが効く場合と効かない場合があり、原因がわからない奇妙なバグになります。
2. Claude専用のルールを使いたい。 @AGENTS.mdの下にある私のCLAUDE.mdには「Claude Code」セクションがあり、アーキテクチャ作業には--effort highを使う、git push前にnpm run buildを実行する、/api/v1/deployを手動で呼び出さない、といったルールを書いています。Codexはこれらのコマンドを理解しません。
3. デバッグが簡単。 問題が起きたとき、CLAUDE.mdを開けばインポートと上書きルールを確認できます。シンボリックリンクには「ここで追加した」という情報がありません。Claude Codeの設定のデバッグについては、セーフモードのガイドをご覧ください。

Claude専用のルールがなければ、バージョン2.1.277以降はシンボリックリンクも必要ありません。CLAUDE.mdを削除すれば、Claude CodeがAGENTS.mdを直接読み込みます。チーム内にバージョン2.1.277より古く、更新できない人がいる場合に限り、シンボリックリンクを残してください。Claude専用のルールがある場合、10件中9件ではインポートの方が便利です。

Codex、Cursor、Copilot、Windsurf、Gemini CLIは何を読み込む？#

7つの主要ツールの一覧です（各ツールの公式ドキュメントに基づきます）。

ここから何がわかるでしょうか。リポジトリにAGENTS.mdを置き、Claude専用のルールが必要なときはインポート付きのCLAUDE.mdを加えると、7つのツールのうち5つは自動で最新の指示を得られます。ネイティブファイルを持つCursorとWindsurfは、現状のままにできます（どちらもAGENTS.mdを読み込みます）。または@AGENTS.mdのインポートを追加できますが、構文が異なり、常にサポートされるとは限りません。

新しいプロジェクトで最も簡単な方針は次のとおりです。

1. すべての共有ルールをAGENTS.mdに置く。 ルールの95%はここに入ります。
2. Claude専用のルールが必要ならCLAUDE.mdを作成する。 先頭行に@AGENTS.mdを置き、その下にClaude専用のルールを追加します。専用ルールがなければCLAUDE.mdは不要です。Claude Codeはバージョン2.1.277以降、AGENTS.mdを直接読み込みます。
3. Cursor固有の機能が必要な場合に備えて、Cursor用に.cursor/rules/を残す。 たとえば@Codebaseや@Docsコマンドが必要な場合です。
4. Windsurfも同様にする。 古い.windsurfrulesは使わず、Windsurfの構文で書いたパターンが必要な場合だけ新しい.windsurf/rules/を使います。

この方法なら、作業の20%でメリットの80%を得られます。私の経験では、「アンチグラビティ」で混在チームの環境を整理したとき、情報源が2つ（共有ルールとClaude専用ルール）を超えると維持が大変になります。誰かが.cursorrulesにルールを追加してAGENTS.mdの更新を忘れると、1週間後にはCursorとCodexが互いに食い違うようになります。

Claude Codeの/initは既存のAGENTS.mdをどう取り込む？#

Anthropicは、ドキュメントで/initを次のように説明しています。

実際にはどういう意味でしょうか。説明したリポジトリには、Cursorを試していた頃の.cursorrules（約80行）と、手作業でまとめたAGENTS.md（120行）がありました。claude /initを実行すると、両方のファイルを取り込み、似たルールを重複排除し、1分で整理されたCLAUDE.mdを作成しました。あとで内容を確認し、古い項目を削除して見出しを追加するなど、軽く編集しました。最初から書き直すより速く済みました。

/initがAGENTS.mdも読み込む対話モードは、環境変数で有効にします。

CLAUDE_CODE_NEW_INIT=1 claude

/initが始まると、Claudeは一連の確認質問をします。どの成果物（CLAUDE.md、スキル、フック）を設定するか、プロジェクトで使う技術スタックは何か、テストにどのコマンドを使うか、といった質問です。次にサブエージェントがコードベースを調べ、package.json、README.md、設定ファイルを読み、足りない部分を補います。最後に編集可能な提案が表示され、保存前に調整できます。プロジェクト開始時のClaude Codeの設定については、別のガイドをご覧ください。

欠点について説明します。プロジェクトにすでに有効なAGENTS.mdがあると、/initはそのルールをコピーしたCLAUDE.mdを隣に作成します。その時点から、Claude Codeは既定でCLAUDE.mdだけを読み込むため、また2つの情報源ができてしまいます。あなたはAGENTS.mdを更新し、Claudeは古いコピーを使い続けます。/importコマンドも同様に、AGENTS.mdのコピーを一度だけCLAUDE.mdに追加します。情報源を1つに保つには、/initの後にCLAUDE.mdの先頭行へ@AGENTS.mdを置き、AGENTS.mdと重複する内容をCLAUDE.mdから削除してください。

/initは、新しいプロジェクトやCursorまたはCopilotから移行するプロジェクトで、作業を始めるのに適しています。「最適なCLAUDE.mdテンプレート」をネットで探す必要はありません。Anthropicはすでにリポジトリの内容を考慮してくれます。プロジェクトに有効なAGENTS.mdがあり、Claude専用のルールがない場合は、/initは不要です。Claude CodeがAGENTS.mdを直接読み込みます。

共有指示とClaude専用指示をどう分ける？#

私は次の原則で分けています。AGENTS.mdに入れる共有ルールは次のとおりです。

• コード内で触れてはいけないもの。 .env、node_modules、prisma/migrationsフォルダ（prisma migrate経由のみ）、.next/、.git/。
• 名前の付け方。 ブランチはfeat/、fix/、chore/。コミットにはfeat:、fix:、docs:の接頭辞と短い説明を使います。コンポーネントのファイル名にはkebab-caseを使います。
• テスト／lintコマンド。 npm run build、npm run lint、npm test。git pushの前に実行するコマンドも記します。
• アーキテクチャの原則。 src/lib/とsrc/components/に入れるもの、ビジネスロジックを置く場所、UIを置く場所を定めます。
• セキュリティ。 秘密情報は絶対にコミットしない。prod-psql経由でのみ本番データベースにアクセスする。本番環境へのSSH接続にはroot@IPではなくprodエイリアスを使う。

CLAUDE.mdの@AGENTS.mdの下に置くClaude専用ルールは次のとおりです。

• Plan mode。 リスクの高いディレクトリ（例：src/billing/）の変更にはplan modeを使います。
• 労力レベル。 アーキテクチャのタスクには--effort high、日常的な作業にはmediumを使います。
• スキル。 どの状況で、どのAIエージェントやスキルを実行するかを指定します。例：「ガイドの作業では、build-masterskaya-guideスキルを実行する。」
• Claudeのメモリ。 自動メモリとCLAUDE.local.mdに何を保存するかを定めます。Claudeのメモリについては、MemoryとCLAUDE.mdのガイドをご覧ください。
• フック。 .claude/settings.jsonにフックが設定されている場合は、その動作をCLAUDE.mdに記述します（CodexとCursorはフックを知らず、知る必要もありません）。
• スキルとコマンド。 よく使うスラッシュコマンド（/init、/cd、/memory、/plan）の一覧です。

境界が明確でない場合もあります。たとえば「mainへのgit push --forceを絶対に実行しない」は明らかに共有ルールなので、AGENTS.mdに置きます。一方、「ホットブランチにgit pushする前にplan modeを使う」はClaude Code固有のため、CLAUDE.mdに置きます。判断基準は、「明日Claude Codeを削除してCodexだけを使うとしたら、このルールはまだ適用されるか」です。適用されるならAGENTS.mdに、そうでなければCLAUDE.mdに置きます。

AGENTS.mdには何を入れ、CLAUDE.mdまたは.claude/rulesには何を入れる？#

ルールが200行を超えたら、分割する時期です。Anthropicのドキュメントは、ファイルごとに200行を目指すことを推奨しています。CLAUDE.mdが長いと、Claudeの指示への従い方が徐々に弱くなります。読み込んでいるように見えても、実際には従う頻度が下がります。

大規模なプロジェクトで私が使っている構成は次のとおりです。

my-project/
├── AGENTS.md                    # 100-150行、共有
├── CLAUDE.md                    # 30-50行: @AGENTS.md + Claude専用
└── .claude/
    ├── CLAUDE.md                # ルートファイルの代わりに使用、同じファイル
    └── rules/
        ├── api.md               # paths: ['src/api/**']を設定
        ├── components.md        # paths: ['src/components/**']を設定
        ├── testing.md           # pathsなし、常に有効
        └── security.md          # pathsなし、常に有効

.claude/rules/内の各ファイルには、次のようなフロントマターを付けられます。

---
paths:
  - "src/api/**/*.ts"
---

# APIルール
- すべてのエンドポイントでzodを使って入力を検証する
- エラーは標準の`{error, code}`形式を使う
- OpenAPIのコメントを必須にする

Claudeは、このパターンに一致するファイルを扱う場合にだけ、これらのルールを読み込みます。src/components/Button.tsxを変更しても、APIルールはコンテキストに追加されません。これにより、関連する情報だけにコンテキストウィンドウを使えます。.claude/rules/ディレクトリはCLAUDE.mdがなくても機能します。プロジェクトにAGENTS.mdしかない場合も、ルールはAGENTS.mdと一緒に読み込まれ、AGENTS.mdの直接読み込みは無効になりません。

CursorとWindsurfも、それぞれ.cursor/rules/と.windsurf/rules/ディレクトリで同じ方法をサポートしています。AGENTS.md標準ではこれらのディレクトリを参照できますが、ツール間で構文が完全に安定しているわけではありません。共有ルールはAGENTS.mdに置き、パスごとのルールを.claude/rules/と.cursor/rules/に重複して置く方が安全です。こうした専用ケースは少数で、ルールの大半を占めるものではありません。

CLAUDE.mdを置ける場所を広い順に並べます。

たとえば~/.claude/CLAUDE.mdには、「ユーザーの希望する言語で返答する」「Ailootのスペルを正確に保つ」という2つのルールを書けます。これらはすべてのプロジェクトに適用されるため、各リポジトリで重複させる必要はありません。

この4つのレベルのうち、AGENTS.mdの直接読み込みを無効にするのは、プロジェクトレベルのCLAUDE.mdとCLAUDE.local.mdだけです。個人用の~/.claude/CLAUDE.mdと管理ポリシーは妨げになりません。Claude CodeはこれらをAGENTS.mdと一緒に読み込みます。

プロジェクトのAGENTS.mdがすでに古くなっていたら？#

説明したプロジェクトには、2025年5月に作成した180行のAGENTS.mdがありました。その多くは古くなっていました。変更されたAnthropic APIエンドポイント、存在しなくなったclaude --tools構文の例、古い構造の~/.claude/projects/に関するルールなどが含まれていました。

更新には、次の手順を使いました。

1. claudeをplan modeで使って確認する。 リポジトリを開き、claude --safe-modeを実行して、次のように依頼します。「AGENTS.mdを読み直し、古くなった項目や重複している項目をリストアップしてください。編集はせず、項目だけを挙げてください。」2分で確認対象となる23項目の一覧ができました。
2. 明らかに古い項目を削除する。 23項目のうち9項目は、コマンド構文、エンドポイント、フラグ名など、明らかに古くなっていました。その行を削除しました。
3. 重複をまとめる。 別の6項目は、異なる言い回しで同じ内容を繰り返していました（「force-pushしない」「--forceは絶対に使わない」「git push -fを避ける」）。これらを1行にまとめました。
4. 新しい項目を追加する。 「エラーのパターンごとに1行」というルールに従い、過去1か月にClaude／Codexが繰り返し間違えていたことを追加しました。その結果、8項目が加わりました。
5. 最終確認のためサブエージェントを実行する。 「矛盾、曖昧さ、重複を見つけてください」と指示してClaudeにレビューを依頼しました。表現を明確にできる箇所が3つ見つかり、修正しました。

1時間後、AGENTS.mdは110行になり、最新の状態で、各行の内容を自分で把握できていました。そこから30行のCLAUDE.mdを作るのも簡単でした。その後、Codexはテストにも明らかに慎重になりました。Codexの「奇妙な」判断の一部は、古いルールを忠実に守っていたためではないかと思います。

継続的に更新するAGENTS.mdの主な原則は次のとおりです。

• すべてのルールは繰り返し起きるミスに答える。 この1か月に一度も思い出さなかったルールなら、残す意味はありません。
• 理論ではなく指示として書く。 「スペースを2つ使う」はルールです。「コードスタイルを整える」はルールではありません。
• 一般論より具体例を優先する。 「git pushの前にnpm run buildを実行する」はルールです。「変更をテストする」はルールではありません。

この設定で確実にうまくいかないことは？#

この設定を6か月使う中で、苦労して学んだことをいくつか挙げます。

1. Cursorの自動補完はAGENTS.mdを使わない。 エディターでCursorが行の補完を提案するとき、リアルタイムにAGENTS.mdを読み込むことはありません。別の高速エンジンが動いています。AGENTS.mdのルールが効くのは、Cursor内のチャットで依頼したときだけです。つまり、AGENTS.mdに「varを使わずconstを使う」と書いても自動補完には影響しません。ESLintまたはTypeScriptの設定を使って指定する必要があります。

2. AGENTS.mdに書いたClaude CodeのフックはCodexでは機能しない。 .claude/settings.jsonに特定の操作をブロックするPreToolUseフックを設定しても、その情報はClaudeにしか役立ちません。Codexはフックを知らず、「ツールが自分で判断する」状態です。AGENTS.mdには「Xをしない」と書き、インポートの下にあるCLAUDE.mdには「Xを物理的にブロックするフックがある」と書くのが適切です。

3. Copilotと.github/copilot-instructions.md。 GitHub Copilotは独自ファイルを読み込み、AGENTS.mdを今も十分には読み込みません。チームでCopilotを積極的に使うなら、ルールを短くした.github/copilot-instructions.mdを別に追加するか、AGENTS.mdに対応したCopilot Extensionsを使ってください。この状況は急速に変化しているため、3〜6か月後には異なる状況になっているかもしれません。

4. GitはシンボリックリンクをCLAUDE.mdの変更として追跡しない。 ln -s AGENTS.md CLAUDE.mdを実行し、1週間後にAGENTS.mdを更新しても、Gitに表示される差分はAGENTS.mdだけです。これは正常ですが、PRをレビューする同僚は、シンボリックリンクを通じてCLAUDE.mdも更新されていることに気づかないかもしれません。解決策は、PRの説明に「AGENTS.mdを更新。Claude Codeはシンボリックリンク経由で同じファイルを参照」と明記することです。

5. 深くネストしたインポートはデバッグしにくい。 AGENTS.mdから@docs/coding-style.mdをインポートし、さらにcoding-style.mdから@docs/typescript.mdをインポートすると、ルール同士が矛盾したときに原因の特定が難しくなります。私はインポートを1階層（CLAUDE.md → AGENTS.md）にとどめ、それ以上ネストしません。AnthropicのInstructionsLoadedフックは、読み込まれたファイルを記録するため、複数層の設定のデバッグに役立ちます。注記：このフックは、インポートまたはシンボリックリンク経由で含まれたAGENTS.mdに対しては実行されますが、Claude Codeが直接読み込んだAGENTS.mdに対しては実行されません。

夜に取り組むバイブコーディング環境の全体像：AIクローン + セカンドブレイン + コンテキストエンジニアリング。

Ailootについて知る。