CLAUDE.md・AGENTS.md・.cursorrules：設定を一本化する戦略

私が支援しているエンタープライズの開発チームの多くは、今や複数のAIコーディングエージェントを併用しています。プラットフォームチームはClaude Codeに標準化し、フロントエンドチームはCursorを契約し、全員が組織のGitHub Enterprise契約を通じてGitHub Copilotを使い、誰かがCodexでバックグラウンドタスクを流し、データチームのノートPCの半分にはGemini CLIが入っている、という状況です。各ツールはそれぞれ独自の指示ファイルを読み込み、そのファイルはそのツールを最初に導入した人が書いたものです。半年後にはCLAUDE.mdのビルドコマンドが間違っていて、.cursorrulesはチームが今や依存しているライブラリをまだ禁止したままで、どのファイルが正なのか誰も答えられません。本ガイドでは、この状況に対する単一の設定戦略を示します。AGENTS.mdをベンダー中立の信頼できる唯一の情報源とし、その周囲に薄いツール固有のアダプターを置き、ツール固有に留めるべきものを明確に線引きし、ファイルを正直な状態に保つガバナンスを整える、という戦略です。各ツールが何を読み込むかについての記述はすべて、そのベンダーの最新ドキュメントで確認し、本文中にリンクしています。

問題：5つのツール、5つのファイル、そしてドリフト

指示ファイルは、新しく入ったエンジニアに渡すオンボーディング資料のようなものです。違いは、そのエンジニアが毎回のセッション開始時に必ず読み、しかも内容が間違っていても決して反論しないことです。そのため、ドリフト（内容のずれ）のコストは、ドキュメントのドリフトとは比べものにならないほど高くなります。古くなったREADME.mdは、新入社員の午後を一度無駄にするだけです。古くなった指示ファイルは、リポジトリ内のすべてのエージェントセッションを同じ誤った道へ送り込みます。さらに各ツールが別々のファイルを持つため、ドリフトは不均一に起こります。Claude Codeは新しいテストランナーを知っているのに、Copilotはまだ古いものを実行している、といったことが起きるのです。

最もよく使われる2つのファイルについては、エンタープライズチーム向けCLAUDE.mdガイドとエンタープライズAIコーディング向けAGENTS.mdガイドでそれぞれ個別に解説しました。それらの記事は、各ファイルの中身に何を書くかを説明しています。本記事はその上位に位置し、検索クエリやディスカバリーコールで繰り返し寄せられる質問に答えます。チームが複数のエージェントを使うとき、どのファイルが優先されるのか、そして同じルールのコピーを5つ維持し続けるのをどう止めればよいのか、という質問です。

端的に答えるなら、5つのコピーは維持しません。維持するのは1つだけで、各ツールがそれをどのように消費するかを正確に理解しておく、ということです。

各ツールが読み込むもの

以下の表は、私がこの問題を整理し始めたときに欲しかったリファレンスです。各ベンダーの最新ドキュメントに基づいて作成しており、続くツール別のセクションで詳細とリンクを示します。

Claude Code：CLAUDE.mdとそのレイヤー

Claude Codeのメモリに関するドキュメントは、読み込み順に4つのスコープを挙げています。ITが配布する管理ポリシーファイル（macOSでは/Library/Application Support/ClaudeCode/CLAUDE.md、LinuxおよびWSLでは/etc/claude-code/CLAUDE.md、WindowsではC:\Program Files\ClaudeCode\CLAUDE.md）、~/.claude/CLAUDE.mdのユーザーファイル、./CLAUDE.mdまたは./.claude/CLAUDE.mdのプロジェクトファイル、そして個人メモ用でgitignore対象の./CLAUDE.local.mdです。Claudeは起動時に作業ディレクトリとその上位すべてのディレクトリからCLAUDE.mdを読み込み、ファイルシステムのルートから下に向かって連結するため、最も近いファイルが最後に読まれます。サブディレクトリのファイルは、そのサブディレクトリ内のファイルを読み取り、書き込み、または編集したときにのみ読み込まれます。

共有戦略の観点で重要な点が3つあります。第一に、@path/to/fileのインポート構文は別のファイルをコンテキストに取り込み、インポートを含むファイルからの相対パスで解決され、最大4ホップまでネストできます。コードスパンやフェンスで囲まれたコードブロック内のインポートは無視されます。第二に、AnthropicのガイダンスではCLAUDE.mdは1ファイルあたり200行未満が目標とされており、インポートされたファイルはインポート元のファイルと一緒に読み込まれるため、インポートを使ってもこのコストは減りません。第三に、.claude/rules/*.mdのファイルはプロジェクトのCLAUDE.mdと一緒に読み込まれ、フロントマターのpaths:フィールドでルールを一致するファイルにスコープすると、Claudeがそれらのファイルを扱うときだけ読み込まれます。スキルやフックも含めたClaude Codeリポジトリのレイヤーごとの全体像を知りたい方は、Claude Codeプロジェクトの解剖学をお読みください。

OpenAI Codex：オーバーライドファイル付きのAGENTS.md

Codexはこのフォーマットがもともと作られたツールであり、そのAGENTS.mdドキュメントは、私が見つけた中でネストに関する最も正確な説明です。Codexはまずホームディレクトリ（~/.codex、またはCODEX_HOME）を調べ、そこでは空でない最初のファイルだけを使い、AGENTS.mdよりAGENTS.override.mdを優先します。次にプロジェクトルート（通常はGitルート）から始めて現在のディレクトリまで下りながら、各ディレクトリでAGENTS.override.md、AGENTS.md、そしてproject_doc_fallback_filenamesに列挙された名前の順に最大1ファイルを採用します。ファイルはルートから下に向かって空行区切りで結合されるため、作業ディレクトリに近い指示ほどプロンプトの後方に現れ、優先されます。

多くのチームが見落とす制限があります。project_doc_max_bytesは結合後のサイズを既定で32 KiBに制限し、チェーンがその上限に達するとCodexはファイルの追加を止めます。肥大化したルートファイルは、パッケージレベルのファイルを静かにコンテキストから押し出してしまうのです。

GitHub Copilot：3種類の指示ファイル

GitHubのリポジトリカスタム指示のドキュメントは、リポジトリ全体に適用される.github/copilot-instructions.md、フロントマターにapplyToグロブ（および任意でcode-reviewまたはcloud-agentを指定するexcludeAgent）を持つ.github/instructions/配下のパス固有のNAME.instructions.mdファイル、そしてエージェント指示ファイルを説明しています。エージェント指示ファイルとは、リポジトリ内の任意の場所に置けるAGENTS.md（最も近いファイルが優先）、またはルートに置く単一のCLAUDE.mdかGEMINI.mdです。パス固有ファイルが一致し、かつリポジトリ全体のファイルも存在する場合は両方が使われます。ソース間では個人の指示がリポジトリの指示より上位、リポジトリの指示が組織の指示より上位ですが、関連するすべてのセットがモデルに渡されるため、GitHubの助言は順位に頼るのではなく矛盾を避けることです。

落とし穴はサポートマトリクスにあります。Copilotクラウドエージェント、GitHub.com上のCopilotコードレビュー、VS CodeのCopilot Chat、Copilot CLIはAGENTS.mdを読みます。GitHub.com上、Visual Studio内、JetBrains IDE内のCopilot Chatは.github/copilot-instructions.mdを読みますが、AGENTS.mdは読みません。また、Copilotコードレビューはベースブランチではなくプルリクエストのヘッドブランチから指示を読み込むため、同じPR内でファイルを変更する場合に影響します。

Cursor：.cursor/rulesとAGENTS.md

Cursorのルールのドキュメントは、プロジェクトルールを.cursor/rules/配下の.mdcファイルとして説明しています（フロントマターがないため、そこに置いた素の.mdは無視されます）。フロントマターのフィールドは3つで、alwaysApply: trueはルールをすべてのチャットに含め、globsは一致するファイルがコンテキストにあるときにルールを添付し、descriptionだけを指定するとエージェントが取り込むかどうかを判断します。ルールはTeam Rules、Project Rules、User Rulesの順にマージされ、競合時は先のソースが優先されます。Team RulesはTeamおよびEnterpriseプランでCursorダッシュボードから管理でき、ユーザーが無効化できないよう強制することも可能です。Cursorはまた、ルールを500行未満に保つよう求めており、ルールから参照されたファイルはインライン展開されず、エージェントが必要と判断したときにのみツールで読み込むと注意しています。

AGENTS.mdは、単純なケース向けの.cursor/rulesに代わる素のMarkdownの選択肢としてドキュメント化されており、プロジェクトルートとサブディレクトリの両方でサポートされ、ネストされた指示は親と結合され、より具体的なファイルが優先されます。古いガイドが説明している単一の.cursorrulesファイルは、現在のルールページにはまったく登場しません。レガシーとみなして移行してください。

Gemini CLI：名前を変更できるGEMINI.md

Gemini CLIのコンテキストファイルのドキュメントは、グローバルの~/.gemini/GEMINI.md、設定済みのワークスペースディレクトリとその親で見つかるGEMINI.mdファイル、そしてツールが触れた任意のディレクトリから信頼されたルートまでのファイルをジャストインタイムで読み込む仕組みを説明しています。見つかったものはすべて連結され、各プロンプトとともに送信されます。@file.mdインポートは相対パスと絶対パスの両方に対応します。ここで重要な機能はsettings.jsonのcontext.fileNameで、単一の名前またはリストを受け付け、ドキュメント自身の例は["AGENTS.md", "CONTEXT.md", "GEMINI.md"]です。/memory showは結合されたコンテキストを表示し、/memory reloadはファイルを再スキャンします。

Windsurf：文字数制限付きのルール

Windsurfのルールのドキュメントは現在Devin Desktopの配下にあり、.devin/rules/*.mdが推奨で、.windsurf/rules/*.mdはフォールバックとして維持されています。レガシーの単一ファイル.windsurfrulesも引き続き読み込まれます。各ルールファイルはalways_on、glob、model_decision、manualのいずれかのtriggerを持ちます。グローバルルールファイルは6,000文字、ワークスペースの各ルールファイルは12,000文字に制限されており、これは本記事で扱うツールの中で最も厳しいドキュメント化された制限です。AGENTS.mdは任意のディレクトリでサポートされ、ルートのファイルは常時オン、サブディレクトリのファイルはそのディレクトリに自動的にグロブスコープされます。Gitリポジトリでは検索がGitルートまで遡り、企業のIT部門は読み取り専用のシステムルールを配布できます。

単一ソース戦略：AGENTS.mdと薄いアダプター

AGENTS.mdを信頼できる唯一の情報源にする理由

AGENTS.md仕様は必須フィールドのない素のMarkdownで、Linux Foundation傘下のAgentic AI Foundationが管理しています。サポート一覧にはCodex、Cursor、Gemini CLI、Windsurf、GitHub Copilotのコーディングエージェント、VS Code、Zed、JetBrains Junie、Devin、Aider、Factoryなどが並び、6万を超えるオープンソースプロジェクトが採用しています。比較表の中で、すべてのツールがネイティブに読むか、読むように設定できる唯一のファイルです。他に並ぶものはありません。CLAUDE.mdはClaude Codeと、ルートに限って一部のCopilotサーフェスが読み、GEMINI.mdはGemini CLIと同じCopilotサーフェスが読み、.cursor/rulesはCursorだけが読みます。

したがって共有の規約はAGENTS.mdに置き、他のすべてのファイルはアダプターになります。ツール固有の指示を持ちつつ共有ファイルを取り込む薄いスタブか、CIが同期を保つ生成コピーのどちらかです。

Claude Code：複製ではなくインポート

ここでの罠は既定の動作です。Anthropicのドキュメントには、作業ディレクトリまたはその上位のどのディレクトリにもCLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.mdがない場合に限ってClaudeがAGENTS.mdを読む、と明記されています。誰かがClaude固有のメモ用にCLAUDE.mdを追加したために両方のファイルを持つリポジトリでは、Claude CodeでのAGENTS.mdの読み込みが静かに止まります。ドキュメント化された解決策は、CLAUDE.mdの1行目を@AGENTS.mdにすることです。Claudeはインポートされたファイルを最初に読み、その下のClaude固有の内容を続けて読みます。このインポートが二重読み込みを引き起こすことはない、とドキュメントが保証しています。

シンボリックリンク（ln -s AGENTS.md CLAUDE.md）も機能しますが、Windowsでクローンする人がいる場合はAnthropicが注意を促しています。Windowsではシンボリックリンクの作成に管理者権限または開発者モードが必要で、core.symlinksが有効でなければGitはコミットされたシンボリックリンクを1行のテキストファイルとしてチェックアウトします。私のクライアントの多くには少なくとも1人のWindows開発者がいるため、私はインポートを使います。claude-md-and-agents-mdという値を持つProject instructions設定もありますが、ユーザー設定、--settings、または管理対象設定からのみ有効で、プロジェクト設定とローカル設定では無視されるため、リポジトリにコミットすることはできません。インポートが移植性のある答えです。

GitHub Copilot：参照ではなく生成

AGENTS.mdを読むCopilotサーフェスについては、これで完了です。GitHub.com上、Visual Studio、JetBrainsのCopilot Chatでは、読み込まれるリポジトリファイルは.github/copilot-instructions.mdだけです。そのファイルに「AGENTS.mdを読め」と書いても、モデルがそれを開くと判断するかどうかに依存します。これは、Claudeに言葉でAGENTS.mdを読むよう指示するCLAUDE.mdについてAnthropicが指摘している弱点と同じです。信頼できるパターンは、CIでAGENTS.mdから.github/copilot-instructions.mdを生成し、生成物であることを示すヘッダーを付け、2つが乖離したらパイプラインを失敗させるチェックを入れることです。**/*.sqlにだけ適用されるルールのようなパス固有のCopilotの振る舞いは.github/instructions/*.instructions.mdに置きます。これには共有ファイル側の対応物がありません。

Cursor、Gemini CLI、Codex、Windsurf

CursorはルートとネストされたAGENTS.mdをネイティブに読むため、.cursor/rulesはCursor固有のグロブスコープの振る舞いと、管理者がTeam Rulesで強制するものだけに縮小されます。Gemini CLIにはコミットする設定が1行必要で、.gemini/settings.jsonでcontext.fileNameを["AGENTS.md", "GEMINI.md"]に設定すれば、以後GEMINI.mdにはGemini固有の指示だけを置けばよくなります。CodexとWindsurfは設定なしで共有ファイルを読みます。Codexではチェーンを32 KiB未満に保ち、AGENTS.override.mdは一時的なローカルオーバーライドにのみ使い、CodexをGitHubのコードレビューに使う場合は、対象コードに最も近いAGENTS.mdに## Code Review Rulesセクションを追加します。これがOpenAIのドキュメントにある仕組みです。

共有できないもの

指示ファイルはモデルに向けた散文です。モデルへの提案ではなくツールによって強制されるものは、すべてそのツール自身の設定に留まり、ツールごとに異なります。

Anthropicのメモリのページは率直にこう述べています。ClaudeはCLAUDE.mdを強制される設定ではなくコンテキストとして扱うため、モデルの判断にかかわらずアクションをブロックするにはPreToolUseフックまたはpermissions.denyルールを使う、と。これは本ガイドのすべてのファイルに当てはまります。すべてのエージェントが知るようにAGENTS.mdにルールを書き、重要なものはツールの設定とCIで強制してください。

モノレポの優先順位：ルートとパッケージ単位のファイル

表のすべてのツールがルートファイルとネストされたファイルの組み合わせをサポートしていますが、そのマージの仕方は少しずつ異なります。共有AGENTS.md戦略が持ちこたえるか崩れるかは、ここで決まります。

この表から2つのルールが導かれます。第一に、ネストされたAGENTS.mdはすべて、ルートがコンテキストにあってもなくても正しいように書くことです。Copilotのドキュメントはマージを約束しておらず、Codexは切り詰める可能性があり、Claude Codeはエージェントが実際にそのディレクトリに触れたときにしかネストされたファイルを読み込みません。見逃すと致命的になる1つか2つの境界は繰り返して書き、ルートと矛盾させないでください。指示が競合するとモデルが「任意にどちらかを選ぶ可能性がある」というAnthropicの助言は、すべてのエージェントに当てはまります。第二に、ルートは短く保つことです。Anthropicの200行目標とCodexの32 KiB上限が設計を縛る2つの数字であり、ルートファイルをおよそ10 KB未満に収めれば、Codexが切り捨てを始める前にパッケージファイル2つか3つ分の余地が残ります。

数十のパッケージを持つチームには、Claude Codeの大規模コードベースのガイダンスが、ルートに加えてパッケージごとに1ファイルという2階層の分割を推奨しています。各ファイルはそのパッケージの所有者が維持し、関わらないパッケージにはclaudeMdExcludesを使います。この所有権モデルは、他のすべてのツールのネストされたAGENTS.mdにそのまま対応します。

共有ファイルに置くものとツール固有ファイルに置くもの

私がすべての行に適用するテストはこうです。開発者が明日ツールを切り替えたとしても、この指示はまだ正しいか。正しいならAGENTS.mdに属します。1つの製品の中でしか意味を持たないなら、その製品のファイルに属します。

ガバナンス：所有権、レビュー、バージョン管理、シークレット、テスト

所有権：AGENTS.md、アダプターファイル、同期スクリプトをCODEOWNERSに追加し、ルートの所有者をプラットフォームチームまたは開発者体験チーム、ネストされた各ファイルの所有者を各パッケージチームにします。Anthropicのモノレポガイダンスも、ディレクトリ単位のCLAUDE.mdについて同じ推奨をしています。各ディレクトリの所有者がそのファイルを維持する、というものです。

レビュー：指示ファイルへのすべての変更は、コードと同様にプルリクエストを通します。Claude Codeにはここで役立つ機能があります。/doctor prompt-audit（v2.1.283以降）は、CLAUDE.md、CLAUDE.local.md、AGENTS.mdに加えてルールやスキルを検査し、存在しないファイルやコマンドへの参照、古いモデル向けに書かれた指示、互いに矛盾するファイルを見つけ、承認するまで何も変更せずに修正案を提示します。共有ファイルの変更をマージする前に、変更のきっかけがClaude Codeでなくても実行してください。

バージョン管理：ファイルはGitにあるので、バージョン管理されています。チームが忘れがちなのは、生成されたコピーを意図的にバージョン管理することです。誰も差分を見ないビルド時に黙って再生成するのではなく、.github/copilot-instructions.mdをコミットし、古くなったらCIを失敗させてください。

シークレット：絶対に入れません。これらのファイルは、すべての開発者のマシン上のすべてのツールによってモデルのコンテキストに注入され、そのツールが呼び出すベンダーに送信され、生成スクリプトによってコピーされます。AGENTS.md内の接続文字列は、5つのベンダーのリクエストログに残る接続文字列になります。個人用ファイルであるCLAUDE.local.mdと~/.codex/AGENTS.override.mdはgitignore対象ですが、やはりコンテキストに入るため、シークレットの置き場所にはなりません。エージェントには環境変数またはシークレットマネージャーを参照させ、ルールを強制で裏付けてください。Read(./.env)のようなClaude Codeのpermissions.denyルールは、モデルの意図にかかわらず読み取りをブロックします。

指示のテスト：共有ファイルの変更をビルドスクリプトの変更と同じように扱い、各ツールでスモークテストを行います。まず読み込みを確認します。Claude Codeの/contextはMemory filesの下にファイルを一覧表示し、Gemini CLIの/memory showは結合されたコンテキストを表示し、GitHub.com上のCopilot Chatはファイルを使った場合にReferencesに.github/copilot-instructions.mdを表示し、OpenAIは監査可能なログを書き出すためにcodex -c log_dir=./.codex-logを提案しています。次に、固定のプロンプトセット（「テストを実行するコマンドは？」「データベースクエリはどこに置く？」）を実行し、ツール間で回答を比較します。食い違いがあれば、それは開発者より先にあなたが捕まえたドリフトです。

テンプレート

コピーして使える、短く現実的なセットです。リポジトリは架空の決済プラットフォームなので、具体的な内容は置き換えてください。

AGENTS.md（信頼できる唯一の情報源）

# AGENTS.md: Payments Platform

## Project
Node 22 / TypeScript 5.6 monorepo using pnpm workspaces.
Services live under `services/`, shared libraries under `packages/`.

## Commands
- Install: `pnpm install --frozen-lockfile`
- Build: `pnpm -r build`
- Test: `pnpm -r test` (run before every commit)
- Lint and format check: `pnpm lint && pnpm format:check`

## Conventions
- TypeScript strict mode. No `any` without a comment explaining why.
- Database access goes through `packages/db`. No raw SQL in route handlers.
- Commit subjects: `<package>: <imperative summary>`, for example `api: add idempotency keys`.

## Boundaries
- Never edit files under `**/generated/`. Run `pnpm codegen` instead.
- Never modify a migration that has merged. Add a new one.
- Never commit secrets or `.env*` files. Configuration comes from the environment.
- Changes under `services/payments/` require a human reviewer from the payments team.

## Pull requests
- Title format: `[<package>] <summary>`. Run lint and tests before opening the PR.

## Code Review Rules
- Flag any new dependency without a justification in the PR description.
- Flag raw SQL strings outside `packages/db`.

CLAUDE.md（薄いアダプター）

@AGENTS.md

## Claude Code

- Use plan mode for any change under `services/payments/`.
- Permissions, hooks and MCP servers are configured in `.claude/settings.json`. Do not duplicate them here.

.cursor/rules/testing.mdc（Cursor固有、グロブスコープ）

---
description: Testing conventions for the payments monorepo
globs: "**/*.test.ts"
alwaysApply: false
---

- Use Vitest. Never add Jest.
- Wrap database tests in a transaction that rolls back.
- Shared project rules live in AGENTS.md; this file holds Cursor-specific behaviour only.

.gemini/settings.json（Gemini CLIに共有ファイルを指定）

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

scripts/sync-agent-instructions.sh（Copilot用コピーの生成）

#!/usr/bin/env bash
set -euo pipefail
{
  echo "<!-- GENERATED from AGENTS.md. Edit AGENTS.md and run scripts/sync-agent-instructions.sh. -->"
  cat AGENTS.md
} > .github/copilot-instructions.md
# In CI, fail when the committed copy is out of date:
git diff --exit-code -- .github/copilot-instructions.md

チームへの展開計画

1. 第1週：棚卸し。すべてのリポジトリのすべての指示ファイルを一覧化します。たとえばgit ls-files | grep -Ei 'claude\.md|agents\.md|cursorrules|cursor/rules|copilot-instructions|instructions\.md|gemini\.md|windsurf'を使います。誰が書き、最後に変更されたのはいつかを記録します。活発に開発されているリポジトリを1つパイロットとして選びます。
2. 第2週：統合。「どのツールでも正しいか」のテストを使って、パイロットのファイルを1つのAGENTS.mdに統合します。Claude Codeの/initは既存のCursorとCopilotのファイルを読み、CLAUDE_CODE_NEW_INIT=1を設定すればAGENTS.md、Windsurf、Clineのファイルも読んで統合ドラフトを提案しますが、これは出発点であって結果ではありません。薄いCLAUDE.md、Geminiの設定、Copilot同期スクリプトを書きます。.cursorrulesと重複した散文を削除します。
3. 第3週：パイロット。チームが使うすべてのツールを合わせてカバーする3人から5人の開発者で実施します。各人が読み込みチェックと固定プロンプトセットを実行し、その後1週間通常どおり作業して、エージェントが無視した、または誤った指示をすべて記録します。直すのはファイルであって、開発者ではありません。
4. 第4週：制度化。CODEOWNERSのエントリ、CIの同期チェック、リポジトリテンプレートを追加します。何を組織レイヤーに移すかを決めます。Claude Codeの管理対象CLAUDE.mdと管理対象設定、CursorのTeam Rules、Copilotの組織指示、Windsurfのシステムルールが、すべてのリポジトリに適用しなければならないルールの置き場所です。その後、次のリポジトリへパターンを展開します。1リポジトリにつき1プルリクエストです。

対応すべきこと

1. すべてのリポジトリの指示ファイルを棚卸しし、それぞれに所有者を決めます。
2. コマンド、レイアウト、規約、境界、セキュリティルール、PR規約を含むルートのAGENTS.mdを作成し、200行未満に保ちます。
3. CLAUDE.mdが存在する場合は1行目を@AGENTS.mdにし、Claude固有でないものをすべてそこから移動します。
4. Gemini CLIを使う人がいる場合は、コミットする.gemini/settings.jsonでcontext.fileNameにAGENTS.mdを含めます。
5. AGENTS.mdから.github/copilot-instructions.mdを生成し、古くなったら失敗するCIチェックを追加します。
6. .cursorrulesを削除し、.cursor/rules/*.mdcはグロブスコープのCursor専用の振る舞いにのみ使います。
7. パッケージごとにネストされたAGENTS.mdを追加します。自己完結させ、ルートと矛盾させず、重要な境界を繰り返します。
8. 権限、フック、MCP登録を各ツールの設定に移し、重要なルールはdenyルールとCIで強制します。
9. すべての指示ファイルからシークレットを検索して削除し、.envの読み取りに対するdenyルールを追加します。
10. ファイルをCODEOWNERSに追加し、変更をマージする前に/doctor prompt-auditを実行し、変更のたびに各ツールでスモークテストを行います。

よくある質問

AGENTS.mdとCLAUDE.mdの違いは何ですか？ AGENTS.mdは、Linux Foundation傘下のAgentic AI Foundationが管理するベンダー中立のファイルで、Codex、Cursor、Copilotのエージェント、Gemini CLI、Windsurfが読み込みます。CLAUDE.mdはClaude Code独自のファイルで、共有フォーマットにはない@pathインポート、管理ポリシーレイヤー、CLAUDE.local.md、パススコープのルールを備えています。共有の規約はAGENTS.mdに置き、短いCLAUDE.mdがそれをインポートしてClaude固有の指示を追加します。

Claude CodeはAGENTS.mdを読みますか？ はい。v2.1.277以降で読みますが、作業ディレクトリまたはその上位にCLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.mdがない場合に限られます。両方のファイルがある場合、Project instructionsをclaude-md-and-agents-mdに設定しない限りCLAUDE.mdだけを読みます。移植性のある解決策は、CLAUDE.mdの1行目に@AGENTS.mdインポートを置くことです。

.cursorrulesと.cursor/rulesのどちらを使うべきですか？ .cursor/rules/*.mdcまたは素のAGENTS.mdを使ってください。Cursorの現在のドキュメントは.mdcプロジェクトルール、Team Rules、ルートとサブディレクトリのAGENTS.mdを扱っており、.cursorrulesはもう記載されていません。

GitHub CopilotはAGENTS.mdを読みますか？ Copilotクラウドエージェント、GitHub.com上のコードレビュー、VS CodeのCopilot Chat、Copilot CLIは読みます。GitHub.com上、Visual Studio内、JetBrains IDE内のCopilot Chatは読まず、.github/copilot-instructions.mdに依存するため、そのファイルをAGENTS.mdから生成してください。

モノレポでネストされたAGENTS.mdはどのように動作しますか？ 仕様では、最も近いファイルが優先され、明示的なプロンプトがすべてに優先するとされています。Codexはルートから下へ連結して近いファイルほど強く作用し、既定で32 KiBで停止します。Cursorはネストされたファイルを親と結合し、Windsurfはグロブで自動スコープし、Copilotは最も近いファイルを適用します。ネストされたファイルはルートと矛盾しないように書いてください。

指示だけでなく再利用可能なエージェントの振る舞いもパッケージ化しているチームには、gh skillによるGitHub CLIエージェントスキル管理ガイドが、Copilot、Claude Code、Cursor、Codex、Gemini CLIにわたってスキルをインストールし固定する方法を解説しています。同じ単一ソースの規律がそこにも当てはまります。

もう一組の手が必要ですか。Big Hat Groupは、米国とカナダの組織向けにアプリケーション開発コンサルティングを提供しています。2週間のAIコーディングエージェント設定レビューから、リポジトリ全体にわたるマルチエージェントの本格展開まで対応します。お客様の環境についてご相談いただくには、ディスカバリーコールを予約してください。

出典

• How Claude remembers your project (CLAUDE.md, imports, rules, AGENTS.md)、Claude Codeドキュメント
• Settings files and precedence、Claude Codeドキュメント
• Set up Claude Code in a monorepo or large codebase、Claude Codeドキュメント
• AGENTS.md specification、Agentic AI Foundation
• Custom instructions with AGENTS.md、OpenAI Codexドキュメント
• Adding repository custom instructions for GitHub Copilot、GitHub Docs
• Support for custom instructions in GitHub Copilot、GitHub Docs
• Rules、Cursorドキュメント
• Provide context with GEMINI.md files、Gemini CLIドキュメント
• Rules and memories、Devin Desktop（Windsurf）ドキュメント