Claude Media
AGENTS.mdとCLAUDE.mdで設定を統合する運用パターン
Claude CodeTips

AGENTS.mdとCLAUDE.mdで設定を統合する運用パターン

Cursor・Cline・Windsurf・Claude Codeを併用するとルールファイルが乱立する。AGENTS.mdを一次情報源にし、CLAUDE.mdは読み込むだけにする運用パターンを、各ツールの公式ドキュメントに基づいて示す。

読了目安 約11分

このTipsでできること

Cursor・Cline・Windsurf(Cascade)・Claude Codeを併用していると、.cursor/rules/・.clinerules/・.windsurf/rules/・CLAUDE.mdという4つの置き場所に同じような指示を書き散らかしがちになります。共通の指示は AGENTS.md という1ファイルにまとめ、各ツール側はそれを読み込むだけにする運用パターンを、各ツールの公式ドキュメントで確認できる範囲で示します。

Claude Code・Cursor・Cline・Windsurfはどのファイルを読むか

ツールによって主形式もファイル名もばらばらで、これが二重管理の元になっています。

ツール主形式置き場所
Claude Code主形式CLAUDE.md置き場所プロジェクト直下or .claude/CLAUDE.md
Cursor主形式.mdcファイル(frontmatterで発動条件を指定)置き場所.cursor/rules/
Cline主形式.md/.txtファイル(プレーンMarkdown)置き場所.clinerules/(ディレクトリ)
Windsurf(Cascade)主形式frontmatterのtriggerで発動条件を指定置き場所.devin/rules/(旧.windsurf/rules/)
GitHub Copilot主形式プレーンMarkdown置き場所.github/copilot-instructions.md
Codex(OpenAI)主形式AGENTS.mdをそのままネイティブ形式として使用置き場所プロジェクト直下

AGENTS.mdはツール専用の独自形式ではなく、「エージェント向けのREADME」として設計された共通フォーマットです。60,000を超えるオープンソースプロジェクトが採用しており、Codex・Cursor・RooCode・Windsurf・Devin・Gemini CLI・GitHub Copilotなどが対応しています。Codexはそもそも専用のルールファイル形式を持たず、AGENTS.mdをそのままネイティブ形式として読む設計になっているため、Codexも使うチームではAGENTS.mdを共通化の起点にする理由がもう1つ増えます。ツールを追加するたびにファイルが1つ増える事態を避けられます。

ツールによってファイルの分割単位や上限も違います。Claude CodeのCLAUDE.mdは1ファイルあたり200行を目安にし、長くなる分は後述するパス指定のルールに分割することが公式に推奨されています。Windsurf(Cascade)はワークスペースのルールファイルが1つあたり12,000字、グローバルルールファイルが6,000字という具体的な上限を設けています。Clineは.clinerules/ディレクトリの中に01-coding.mdのような数字接頭辞つきファイルを好きなだけ並べる方式で、上限より分割のしやすさを優先した設計になっています。AGENTS.mdに寄せる共通部分は短く保ち、ツールごとの上限や分割単位の違いを気にせずに済む量にとどめておくと、余計な調整が減ります。

AGENTS.mdを一次情報源にする

まずリポジトリのルートに AGENTS.md を1つ置き、ツールを問わず共通の指示(セットアップコマンド・コーディング規約・テストの回し方)をそこに書きます。

# AGENTS.md
 
## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
 
## Code style
- TypeScript strict mode
- Single quotes, no semicolons

AGENTS.mdはfrontmatterも特殊な構文も要らないプレーンなMarkdownで、Windsurf(Cascade)はルート直下のAGENTS.mdを常時有効なルールとして、サブディレクトリのものはglob相当のスコープ付きルールとして自動的に読み込みます。

Claude Code側でAGENTS.mdを読ませる

Claude Codeは CLAUDE.md しか読まず、AGENTS.md を単独では読み込みません。共通化のやり方は公式ドキュメントに2通り示されています。

1つ目は CLAUDE.md から @AGENTS.md の形でインポートし、Claude Code固有の指示をその下に足す方法です。

@AGENTS.md
 
## Claude Code
Use plan mode for changes under `src/billing/`.

Claude固有の追記が要らないなら、シンボリックリンクでも同じことができます。

ln -s AGENTS.md CLAUDE.md

Windowsでシンボリックリンクを張るには管理者権限か開発者モードが要るため、Windows環境では @AGENTS.md インポートの方を使います。どちらの方法でも、次のセッションで /context を実行し、Memory filesに CLAUDE.md が出ていることを確認します。

二層構成にすると、リポジトリの構成は最終的にこうなります。

your-project/
├── AGENTS.md              # 全ツール共通の指示(セットアップ・規約)
├── CLAUDE.md               # @AGENTS.md をインポート + Claude固有の指示
├── .claude/
│   └── rules/
│       └── billing.md      # Claude Code専用、pathsでsrc/billing/**に限定
└── .cursor/
    └── rules/
        └── billing.mdc     # Cursor専用、globsでsrc/billing/**に限定

同じsrc/billing/**という制約を、Claude Codeにはpaths:のYAML frontmatterで、Cursorには.mdcのglobs:フロントマターで、それぞれのネイティブ形式のまま二重に書きます。中身の指示文だけは使い回せても、発動条件の書き方までは共通化できない、という線引きがこの構成に表れています。

既存のツール別ルールをまとめて集約する

すでに .cursor/rules/ や .github/copilot-instructions.md にルールを書き溜めている場合、ゼロから書き直す必要はありません。Claude Codeの /init コマンドは、.cursor/rules/ または .cursorrules、.github/copilot-instructions.md を読み取り、内容を要約して生成する CLAUDE.md に組み込みます。環境変数 CLAUDE_CODE_NEW_INIT=1 を設定すると、この対象がさらに広がり、AGENTS.md・.devin/rules/・.windsurf/rules/または.windsurfrules・.clinerules も読み込み対象になります。

MCPサーバーやカスタムコマンド、サブエージェント、Skillsまで含めて他ツールの設定を移したい場合は /import コマンドが使えます。対応するエージェントの設定から AGENTS.md 等の指示ファイルを一度だけコピーして該当する CLAUDE.md に追記し、MCPサーバーやコマンド定義も引き継ぎます。Claude Code v2.1.213以降が必要で、claude import codex のように取り込み元を指定して実行します。

補足: ツール固有のルールは無理に共通化しない

AGENTS.mdに寄せられるのは「どのツールでも意味が通る指示」までです。ツール固有の発動条件はツール側のディレクトリに残したほうが混乱しません。それぞれのfrontmatterの書き方自体が違うため、1つのファイルで表現しきれません。

ツールスコープ指定の書き方
Claude Code(.claude/rules/)スコープ指定の書き方paths: フィールドにglobパターンを列挙
Cursor(.cursor/rules/*.mdc)スコープ指定の書き方globs: / description: / alwaysApply: の組み合わせ
Windsurf(Cascade)スコープ指定の書き方trigger: に always_on / glob / model_decision / manual

たとえば「src/api/**/*.ts にだけ効かせたい規約」のような細かいスコープ指定は、AGENTS.mdに書いても他のツールが解釈できるとは限らないので、各ツールのネイティブ形式のまま残します。二層構成にする、というのが落としどころです。

Cursorは実質4種類のルールを使い分けられる設計になっています。バージョン管理下に置く「Project Rules」(.cursor/rules/)、個人設定の「User Rules」、Team/Enterpriseプランでダッシュボードから配る「Team Rules」、そしてAGENTS.mdです。チーム全体に強制したい規約はCursor側の管理画面から配る一方、ツールをまたいで通じる規約はAGENTS.mdに書く、と役割を分けられます。

この収束は、Claude Code側からの歩み寄りだけで起きているわけではありません。Clineは自分の.clinerules/に加えて、.cursorrules・.windsurfrules・AGENTS.md(グローバル設定の~/.agents/AGENTS.mdを含む)を自動検出する仕組みをすでに持っています。ツールをまたいで同じ指示ファイルが通じる状態は、一方的な移行ではなく各ツールが互いのフォーマットを読みに行く形で進んでいます。

個人の好み(全プロジェクト共通のコーディングスタイルなど)をプロジェクトのAGENTS.mdに書きたくない場合、Claude Codeは~/.claude/CLAUDE.md、Clineは~/.agents/AGENTS.mdのほかOSごとに次のディレクトリをグローバルルールの置き場所として使います。

OSClineのグローバルルール置き場所
WindowsClineのグローバルルール置き場所Documents\Cline\Rules
macOSClineのグローバルルール置き場所~/Documents/Cline/Rules
Linux/WSLClineのグローバルルール置き場所~/Documents/Cline/Rules(無ければ~/Cline/Rules)

プロジェクト単位で共通化するAGENTS.mdと、個人の好みを乗せるグローバル設定は分けて管理した方が、リポジトリをチームに共有したときに個人設定が紛れ込まずに済みます。Claude Codeの~/.claude/CLAUDE.mdも同じ位置づけで、プロジェクトのCLAUDE.mdより先に読み込まれます。

よくあるつまずき

  • Bedrock/Vertex/Foundry経由でClaude Codeを使っていると/importが使えない: このコマンドはAnthropicから取得するfeature flagに依存しており、サードパーティ提供環境ではその取得自体が行われないため動作しません
  • .cursor/rules/の.md拡張子ファイルが無視される: Cursorのプロジェクトルールは.mdc拡張子が必須で、frontmatterの無い.mdファイルは読み込み対象から外れます
  • AGENTS.mdを外部リポジトリからインポートしたら承認ダイアログが出た: プロジェクト配下のメモリファイルが作業ディレクトリ外のパスをインポートすると、Claude Codeは初回に承認ダイアログを出します。共有リポジトリ経由のAGENTS.mdを安全に扱うための挙動で、拒否すると以後そのインポートは無効のままになります
  • 複数フォルダを開くとルールの件数が少なく表示される: Windsurf(Cascade)は同じルールファイルが複数のワークスペースで開かれているとき、相対パスが最も短いものを代表として重複排除して表示します。一覧に想定より少ない件数しか出ていなくても、ルール自体が消えたわけではありません

統合後に確認すること

AGENTS.mdへの一本化は「ファイルを1つにした」で終わりではありません。実際に指示が効いているかを/contextで確認する習慣をつけておきましょう。

  • /context を実行し、Memory filesに CLAUDE.md(またはインポート先のAGENTS.md)が出ているかを確認します。ここに出ていなければ、そもそもClaudeはその内容を読めていません
  • 複数のツール向けにコピーしていた古い指示を消し忘れると、AGENTS.mdの内容と食い違ったまま.claude/rules/や.cursor/rules/に残り続けます。ツールごとのルールを見比べて矛盾がないか確認します
  • 各ツールのルールをそのまま合算するとCLAUDE.mdが肥大化しやすくなります。/doctorはチェックイン済みのCLAUDE.mdを診断し、ディレクトリ構成や依存関係のようにコードから推測できる記述を削り、ツールのデフォルトと異なる規約やハマりどころだけを残すよう提案してくれます

まとめ

複数のAIコーディングツールを併用するなら、共通の指示はAGENTS.mdに一本化し、Claude Codeは@AGENTS.mdインポートかシンボリックリンクで読み込むだけにします。既存の.cursor/rules/や.github/copilot-instructions.mdは/initで、MCPサーバーやSkillsまで含めた移行は/importで一度に集約できます。ツール固有の発動条件(パス指定・glob・trigger)まで無理に1ファイルへ押し込む必要はなく、AGENTS.mdは共通の土台、各ツールのネイティブ形式は追加の書式、と役割を分けるとうまくいきます。

CLAUDE.mdの書き方の型はCLAUDE.mdを実用に引き上げる10のパターン、チーム導入時の規約設計はClaude Codeチーム導入ガイド、CLAUDE.mdとSkillsの役割分担はClaude Codeのoutput styleとCLAUDE.md・Skillsは何が違うかを参照。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →