# 2026年のClaude Code、Codex、Cursorのための単一の指示ファイル > 2026年にClaude Code、Codex、Cursorで使う単一の情報源：Claude CodeがAGENTS.mdを直接読み込む条件、CLAUDE.mdへの@AGENTS.mdのインポート、シンボリックリンク、/init。 Source: https://ailoot.ai/blog/ja/agents-md-claude-md-one-instruction-file/ Canonical: https://ailoot.ai/blog/ja/agents-md-claude-md-one-instruction-file/ Language: ja Publisher: Ailoot (https://ailoot.ai/) Translation: guide-004 Revision: sha256-c35fa427d5e4accc2a59317025baaa71c73cf47ecd8384a4c025e37b78eb2dc5 サービスについては、[Ailootのドキュメント](https://ailoot.ai/docs/)をご覧ください。 ## Claude Code、Codex、Cursorを一緒に使うと何が変わる？
重要なポイント 2026年、一般的なバイブコーダーの環境は1つのツールではなく、3〜5個のツールで構成されています。メインツールとしてのClaude Code、長時間の自律タスク用のCodex、IDEでの手早い編集用のCursor。それぞれに独自の指示ファイルがあります。`CLAUDE.md`、`AGENTS.md`、`.cursorrules`です。これらを手作業で同期し続けると、5か所で同じ1行を編集し、Cursorの更新を忘れ、1週間後には同じプロンプトにClaudeとCodexが異なる結果を返すことになります。
ここで説明する例では、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の問題ではなく、複数の情報源があるシステムにありがちな基本的な落とし穴です。この問題については、[マルチエージェント作業のガイド](https://ailoot.ai/blog/ja/claude-code-codex-together/)で詳しく説明しています。 2026年6月、AnthropicのClaude Codeメモリに関するドキュメントは、共有ファイルとインポートという1つの解決策を示しました。2026年9月以降、プロジェクトに`CLAUDE.md`がなければClaude Codeは`AGENTS.md`自体を読み込むようになり、Claude専用のルールがある場合はインポートが必要です。以下では、単一の`AGENTS.md`で十分な場合、インポートの設定方法、共有ルールとClaude専用ルールの分け方を説明します。 ## Claude CodeはAGENTS.mdを直接読み込む？
重要なポイント はい。2026年9月18日にリリースされたバージョン2.1.277以降が対象ですが、作業ディレクトリまたはその上位に`CLAUDE.md`、`.claude/CLAUDE.md`、`CLAUDE.local.md`のいずれも存在しない場合に限ります。`CLAUDE.md`が存在すると、Claude Codeは既定でそのファイルだけを読み込みます。`CLAUDE.md`内に`@AGENTS.md`の行を追加するか、シンボリックリンクを使って`AGENTS.md`を含めます。動作は`/config`の「Project instructions」で変わります。9月より前の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はプロジェクト指示としてAGENTS.mdを読み込めるため、他のエージェント向けにすでに設定されたリポジトリなら、CLAUDE.md、インポート、設定なしで動作します。

— Anthropic, https://code.claude.com/docs/en/memory#agents-md
Claude Codeが読み込む内容は、プロジェクト内のファイル構成によって決まります。 | プロジェクト内のファイル | Claude Codeが読み込むもの | |----|----| | `AGENTS.md`があり、作業ディレクトリまたはその上位に`CLAUDE.md`も`CLAUDE.local.md`もない | `AGENTS.md` | | 作業ディレクトリまたはその上位に`AGENTS.md`と`CLAUDE.md`（または`CLAUDE.local.md`）がある | `CLAUDE.md`のみ | | `@AGENTS.md`の行がある`CLAUDE.md` | `CLAUDE.md`と、インポートによってその中に含まれる`AGENTS.md` | この確認では、作業ディレクトリとその上位の各ディレクトリにある`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」で変わります。 | 設定 | Claude Codeが読み込むもの | |----|----| | `claude-md-or-agents-md`（既定） | `CLAUDE.md`、または`CLAUDE.md`も`CLAUDE.local.md`もない場合は`AGENTS.md` | | `claude-md-and-agents-md` | 両方のファイル。各ディレクトリで、最初に`CLAUDE.md`、次に`AGENTS.md` | | `claude-md` | `CLAUDE.md`のみ | | `managed-only` | 企業が管理する`CLAUDE.md`と自動メモリのみ | `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をインポートするには？
重要なポイント プロジェクトに`CLAUDE.md`がある場合はインポートが必要です。`CLAUDE.md`があると、Claude Codeは既定で`AGENTS.md`自体を読み込みません。設定するには、`CLAUDE.md`ファイルの先頭に`@AGENTS.md`の行を書きます。Claude Codeはセッション開始時にその行を`AGENTS.md`の内容で置き換え、1つのテキストとして読み込みます。インポートの下には、Claudeだけに適用するルールを「Claude Code」セクションとして追加できます。インポートには相対パスと絶対パスを使え、最大4階層までネストできます。
公式ドキュメントにある最小限の動作例です。 ```markdown @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`を使います。 インポートの仕組みについて、ドキュメントから引用します。

CLAUDE.mdファイルは、@path/to/import構文を使って追加ファイルをインポートできます。インポートされたファイルは展開され、参照元のCLAUDE.mdとともにセッション開始時にコンテキストへ読み込まれます。

— Anthropic, https://code.claude.com/docs/en/memory
実用上の詳細をいくつか挙げます。 - **相対パスと絶対パス。** `@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`に置いています。 ## シンボリックリンクとインポート、どちらを選ぶ？
重要なポイント Anthropicは、`@AGENTS.md`によるインポートと、`ln -s AGENTS.md CLAUDE.md`によるシンボリックリンクという2つの方法を示しています。シンボリックリンクは単なる別名で、ファイルを変更する必要がないため、より簡単です。ただし、欠点が3つあります。Windowsでは管理者権限が必要、`CLAUDE.md`にClaude専用のルールを追加できない、Gitの差分でシンボリックリンクが不自然に見えることがあります。インポートはどの環境でも使える方法です。Claude専用のルールがないなら、バージョン2.1.277以降はどちらも必要ありません。Claude Codeが`AGENTS.md`を直接読み込みます。
ドキュメントでは、シンボリックリンクの方法を次のように示しています。 ```bash ln -s AGENTS.md CLAUDE.md ``` また、Windowsについて率直な注意書きがあります。

リポジトリをクローンする人がWindowsを使っている場合は、@AGENTS.mdインポートを使ってください。Windowsでシンボリックリンクを作成するには管理者権限または開発者モードが必要です。また、core.symlinksが有効でないGitでは、コミットされたリンクが通常のテキストファイルとしてチェックアウトされます。その結果、指示の代わりに1行のCLAUDE.mdが残ります。

— Anthropic, https://code.claude.com/docs/en/memory
比較表です。 | 基準 | `@AGENTS.md`インポート | `ln -s`によるシンボリックリンク | |----|----|----| | **Windowsで管理者権限なしに動作する** | はい | いいえ（開発者モードが必要） | | **Claude専用のルールを追加できる** | はい。インポートの下に追加 | いいえ。ファイルが同一 | | **Gitで通常のMarkdownとして表示される** | はい | リンクとして表示（`core.symlinks`による） | | **複数ファイルをインポートできる** | はい。最大4階層 | いいえ。1対1 | | **Claude Codeでのキャッシュ／無効化** | CLAUDE.mdの標準動作 | 動作するが、シンボリックリンクには見落としやすい問題がある | | **既定の選択肢** | 誰にでも適する | クロスプラットフォーム利用が問題にならない場合のみ | 説明したプロジェクトではインポートを使っています。理由は次のとおりです。 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の設定のデバッグについては、[セーフモードのガイド](https://ailoot.ai/blog/ja/claude-code-safe-mode-recovery/)をご覧ください。 Claude専用のルールがなければ、バージョン2.1.277以降はシンボリックリンクも必要ありません。`CLAUDE.md`を削除すれば、Claude Codeが`AGENTS.md`を直接読み込みます。チーム内にバージョン2.1.277より古く、更新できない人がいる場合に限り、シンボリックリンクを残してください。Claude専用のルールがある場合、10件中9件ではインポートの方が便利です。 ## Codex、Cursor、Copilot、Windsurf、Gemini CLIは何を読み込む？
重要なポイント 各ツールはそれぞれ独自のファイルを読み込み、複数読むこともあります。Claude Codeは`CLAUDE.md`を読み込み、2026年9月以降、プロジェクトに`CLAUDE.md`がない場合は`AGENTS.md`も読み込みます。Codex CLIは`AGENTS.md`と`AGENTS.override.md`を読み込みます。Cursorは旧形式の`.cursorrules`か、新形式の`.cursor/rules/*.mdc`を読み込み、2026年夏以降は`AGENTS.md`も読み込みます。Copilotは`.github/copilot-instructions.md`または`.github/instructions/*.instructions.md`を読み込みます。Windsurfは旧形式の`.windsurfrules`か、新形式の`.windsurf/rules/`を読み込みます。Gemini CLIは`GEMINI.md`を読み込みます。AiderとClineはすでに`AGENTS.md`に対応しています。
7つの主要ツールの一覧です（各ツールの公式ドキュメントに基づきます）。 | ツール | 主な指示ファイル | 代替 | AGENTS.mdを読む？ | |----|----|----|----| | **Claude Code** | `CLAUDE.md` | `~/.claude/CLAUDE.md`、`./.claude/CLAUDE.md`、管理ポリシー | はい。プロジェクトに`CLAUDE.md`がなければ（2.1.277以降）、それ以外はインポート経由 | | **Codex CLI**（OpenAI） | `AGENTS.md` | `AGENTS.override.md` | はい（ネイティブ対応） | | **Cursor** | `.cursor/rules/*.mdc` | `.cursorrules`（非推奨） | はい | | **GitHub Copilot** | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | 拡張機能経由 | | **Windsurf** | `.windsurf/rules/` | `.windsurfrules`（非推奨） | はい | | **Gemini CLI** | `GEMINI.md` | \- | いいえ | | **Aider、Cline、opencode** | `AGENTS.md` | \- | はい（ネイティブ対応） | ここから何がわかるでしょうか。リポジトリに`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をどう取り込む？
重要なポイント `/init`はリポジトリの既存内容から`CLAUDE.md`を作成し、手作業を20〜30分省きます。既定ではCursorのルール（`.cursor/rules/`、`.cursorrules`）とCopilotのルール（`.github/copilot-instructions.md`）を取り込みます。`CLAUDE_CODE_NEW_INIT=1`モードでは`AGENTS.md`、`.windsurfrules`、`.clinerules`も読み込みます。このモードは対話式の複数段階のフローも開始します。質問を行い、サブエージェントでコードを調べ、書き込みの前に計画を提案します。2026年9月以降、`AGENTS.md`があるプロジェクトで`/init`を使うと欠点があります。新しい`CLAUDE.md`が`AGENTS.md`の直接読み込みを無効にし、ルールが2つのファイルに分かれてしまいます。
Anthropicは、ドキュメントで`/init`を次のように説明しています。

/initを実行すると、他のツールの指示ファイルを読み、関連する内容を生成したCLAUDE.mdに移します。対象は、.cursor/rules/または.cursorrulesにあるCursorルール、.github/copilot-instructions.mdにあるCopilotルールです。また、CLAUDE_CODE_NEW_INIT=1の場合は、AGENTS.md、.devin/rules/、.windsurf/rules/または.windsurfrules、.clinerulesも対象になります。

— Anthropic, https://code.claude.com/docs/en/memory
実際にはどういう意味でしょうか。説明したリポジトリには、Cursorを試していた頃の`.cursorrules`（約80行）と、手作業でまとめた`AGENTS.md`（120行）がありました。`claude /init`を実行すると、両方のファイルを取り込み、似たルールを重複排除し、1分で整理された`CLAUDE.md`を作成しました。あとで内容を確認し、古い項目を削除して見出しを追加するなど、軽く編集しました。最初から書き直すより速く済みました。 `/init`が`AGENTS.md`も読み込む対話モードは、環境変数で有効にします。 ```bash CLAUDE_CODE_NEW_INIT=1 claude ``` `/init`が始まると、Claudeは一連の確認質問をします。どの成果物（`CLAUDE.md`、スキル、フック）を設定するか、プロジェクトで使う技術スタックは何か、テストにどのコマンドを使うか、といった質問です。次にサブエージェントがコードベースを調べ、`package.json`、`README.md`、設定ファイルを読み、足りない部分を補います。最後に編集可能な提案が表示され、保存前に調整できます。プロジェクト開始時のClaude Codeの設定については、[別のガイド](https://ailoot.ai/blog/ja/spec-kit-claude-code-spec-driven-development/)をご覧ください。 欠点について説明します。プロジェクトにすでに有効な`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専用指示をどう分ける？
重要なポイント どのAIエージェントでも理解できるルールは`AGENTS.md`に置きます。触れてはいけないもの、ブランチの命名方法、`.env`に秘密情報が入っていること、テストに使うコマンドなどです。Claude Code固有のルールは`CLAUDE.md`（インポートの下）に置きます。plan mode、スキル、フック、スキルの参照先、バージョンごとのモデル名などです。区別は簡単です。「Claudeは〜すべき」で始まるルールは`CLAUDE.md`に、「ツールは〜すべき」で始まるルールは`AGENTS.md`に置きます。
私は次の原則で分けています。`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のガイド](https://ailoot.ai/blog/ja/claude-memory-claude-md-auto-memory/)をご覧ください。 - **フック。** `.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には何を入れる？
重要なポイント 大きなプロジェクトでは`AGENTS.md`が1つだけでは不十分です。ファイルが大きくなりすぎ、各エージェントのコンテキストに不要な情報が入るためです。解決策は、トピックごとにファイルを分けた`.claude/rules/`ディレクトリと、パスごとに適用するYAMLフロントマターの`paths:`です。たとえばAPIのルールは、Claudeが`src/api/`で作業するときだけ適用できます。これにより、コンテキストウィンドウを大幅に節約できます。Cursorでは`.cursor/rules/`、Windsurfでは`.windsurf/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/`内の各ファイルには、次のようなフロントマターを付けられます。 ```markdown --- 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を置ける場所を広い順に並べます。 | レベル | 場所 | 目的 | |----|----|----| | **管理ポリシー** | `/Library/Application Support/ClaudeCode/CLAUDE.md`（Mac）、`/etc/claude-code/CLAUDE.md`（Linux） | 企業のルール、IT／DevOps | | **ユーザー** | `~/.claude/CLAUDE.md` | すべてのプロジェクトに適用する個人設定 | | **プロジェクト** | `./CLAUDE.md`または`./.claude/CLAUDE.md` | プロジェクトチームのルール | | **ローカル** | `./CLAUDE.local.md`（`.gitignore`に追加） | 特定のプロジェクトに対する個人設定 | たとえば`~/.claude/CLAUDE.md`には、「ユーザーの希望する言語で返答する」「Ailootのスペルを正確に保つ」という2つのルールを書けます。これらはすべてのプロジェクトに適用されるため、各リポジトリで重複させる必要はありません。 この4つのレベルのうち、`AGENTS.md`の直接読み込みを無効にするのは、プロジェクトレベルの`CLAUDE.md`と`CLAUDE.local.md`だけです。個人用の`~/.claude/CLAUDE.md`と管理ポリシーは妨げになりません。Claude Codeはこれらを`AGENTS.md`と一緒に読み込みます。 ## プロジェクトのAGENTS.mdがすでに古くなっていたら？
重要なポイント `AGENTS.md`が2025年にCodexまたはAider向けにまとめられ、それ以降編集されていない場合は、プロジェクトをClaude Codeで開き、ファイルの編集をClaudeに依頼してください。AGENTS.mdは継続的に更新する文書です。Linux Foundationの仕様も更新されています。最新状態を保つための主なルールは、各ルールが「Claude／Codexに何度も言い直すのに疲れたこと」に答えているか確認することです。そうでなければ、アーカイブしてください。
説明したプロジェクトには、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`を実行する」はルールです。「変更をテストする」はルールではありません。 ## この設定で確実にうまくいかないことは？
重要なポイント `@AGENTS.md`をインポートしても、異なるツールが同じように動作するわけではありません。それぞれに固有の違いがあります。Codex CLIは`.claude/rules/`やフックを認識しません。Cursorには独自の自動補完エンジンがあり、テキストの補完中にCLAUDE.mdを読み込みません。Copilotは`.github/copilot-instructions.md`に従い、AGENTS.mdのルールだけでは不十分です。これは「1つのファイルですべての挙動を統一する」ということではありません。「基準となるルールの情報源を1つにし、その後に各ツール固有の追加ルールを置く」ということです。
この設定を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](https://github.com/marketplace?type=apps&category=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`に対しては実行されません。
### 出典 - [Claude Codeメモリのドキュメント - AGENTS.mdのセクション](https://code.claude.com/docs/en/memory#agents-md) - Claude CodeがAGENTS.mdを直接読み込む条件、「Project instructions」の設定、インポート、シンボリックリンク、`/init`の動作。 - [Claude Codeメモリのドキュメント - 追加ファイルのインポート](https://code.claude.com/docs/en/memory#import-additional-files) - `@path/to/file`構文、4階層の深さ、相対パスと絶対パス。 - [agents.md - Linux Foundation標準](https://agents.md/) - 公式のAGENTS.md標準と対応ツールの一覧。 - [Cursor Rulesのドキュメント](https://docs.cursor.com/context/rules-for-ai) - Cursorが読み込むもの（`.cursor/rules/*.mdc`、AGENTS.md）。 - [GitHub Copilotのカスタム指示](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) - `.github/copilot-instructions.md`の形式。 - [Linux FoundationのAGENTS.md仕様](https://aaif.io/projects/agents-md/) - 継続的に更新される仕様。
夜に取り組むバイブコーディング環境の全体像：**AIクローン + セカンドブレイン + コンテキストエンジニアリング**。 [Ailoot](https://ailoot.ai/)について知る。 ## 2026年のClaude Code、Codex、Cursorのための単一の指示ファイル：よくある質問 ### シンボリックリンクよりインポートを選ぶのはいつですか？ Claude固有の追記が必要な場合や、メンバーがWindowsを使う場合は、`CLAUDE.md`に`@AGENTS.md`を書きます。シンボリックリンクは両方の名前が同じ内容を参照するため、Claude専用の独立した節は持てません。 ### 共通の指示が読み込まれたか、どう確認しますか？ `/memory`で指示ファイルの一覧を確認します。設定上、`CLAUDE.md`や`CLAUDE.local.md`がAGENTS.mdの直接読み込みを抑えているなら、インポートを加えるか両方を読む設定にし、新しいセッションを開いてください。 ## Ailoot · 企業とそのプロジェクト群 Ailootは、蓄積した運営経験、幅広い顧客基盤、安定したサービス、継続的なKPI管理を基盤としています。 企業とそのプロジェクト群：数百万の顧客、毎月数十億規模の売上。 Ailootはこの運営経験を、お客様の製品、エージェント、アプリケーション、自動化でAI機能を利用するためのAPIアクセスに活かしています。