CLAUDE.md vs .cursorrules vs .windsurfrules vs AGENTS.md：AIコーディングルールファイル構文リファレンス（2026年版）

import ExternalLinkCard from ”../../components/ExternalLinkCard.astro”;

主要なAIコーディングツールはそれぞれ独自のルール形式を持っている。CLAUDE.mdはClaude Codeに属し、.cursorrulesとそのモダンな後継.mdcはCursorに、.windsurfrulesはWindsurfのCascadeエージェントを制御し、AGENTS.mdはOpenAI Codex・GitHub Copilot・Gemini CLIをはじめ多数のツールが採用する新興クロスツール標準だ。

複数のツールを使っているか、すでにルールが書かれたリポジトリに参加する場合、これらの形式が同じように動作しないことに気づく。Cursorのglobスコープ付き.mdcルールはCLAUDE.mdのセクションに1:1で変換できない。AGENTS.mdのネスト構造は.windsurfrulesに相当する仕組みがない。シェルフックはClaude Codeにしか存在しない。

このページはリファレンスだ——「どのツールが勝ちか」というガイドではない。正確な構文の確認、各形式がサポートする機能の把握、そして必要なときに形式間でルールを変換するために使う。

クイック比較表

各形式の基本特性を下表にまとめた。詳細は後続のセクションで解説する。

各形式の詳細

CLAUDE.md（Claude Code）

ファイルロードの階層 — Claude Codeは作業ディレクトリからディレクトリツリーを上方向にたどり、見つかったすべてのCLAUDE.mdとCLAUDE.local.mdを収集する。発見されたファイルはファイルシステムのルートから作業ディレクトリに向かって順に連結され、最も近いファイルが実質的に高い優先度を持つ：

/Library/Application Support/ClaudeCode/CLAUDE.md   # 管理/組織ポリシー
~/.claude/CLAUDE.md                                  # ユーザー全体の設定
./CLAUDE.md  または  ./.claude/CLAUDE.md             # プロジェクト（コミット済み）
./CLAUDE.local.md                                    # 個人設定（gitignore推奨）
./src/api/CLAUDE.md                                  # サブディレクトリ（遅延ロード）

サブディレクトリ内のCLAUDE.mdは起動時には読み込まれない。Claudeがそのディレクトリのファイルを読んだタイミングでオンデマンドにロードされる。これにより大規模モノレポでもコンテキストが肥大化しない——バックエンドで作業しているときにフロントエンドのルールが混入しない。

paths:フロントマター付きの.claude/rules/ — パスベースのスコープには、.claude/rules/に.mdファイルを置く。フロントマターなしのファイルは毎セッションロードされる。paths:フロントマターを持つファイルは、Claudeが対応するファイルを読んだときだけロードされる：

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

# APIルール

- すべてのエンドポイントはZodで入力を検証する
- エラーは `{ code, message, details }` オブジェクトで返す
- OpenAPI JSDocコメントでドキュメント化する

サポートされるglobパターン：

フック — CLAUDE.mdだけが持つ最も強力な機能だ。フックはライフサイクルイベントで発火し、Claudeが何をするかとは独立してシェルコマンドを実行する。これはルールを「Claudeへの指示」としてではなく「機械的な強制」として機能させられる唯一の形式だ：

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --fix $CLAUDE_TOOL_INPUT_PATH"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/local/bin/check-dangerous-command.sh"
          }
        ]
      }
    ]
  }
}

2026年時点のフックタイプ：command（シェルスクリプト）、prompt（LLM評価）、mcp_tool（接続済みMCPサーバーへの直接呼び出し、2026年4月追加）。

@pathインポート — CLAUDE.mdは他のファイルをインラインで取り込める。インポートされたファイルはセッション開始時にフルロードされる：

プロジェクト概要は @README.md を参照。

# Dev Setup
@docs/setup.md

# Git Conventions
@docs/git-guide.md

注意点：

• 200行推奨はガイドラインであり上限ではない。200行を超えると遵守率が低下する傾向がある。
• CLAUDE.mdは/compact後も残る。ネストされたサブディレクトリのCLAUDE.mdはコンパクション後に自動再注入されない。
• ~/.claude/rules/（ユーザーレベル）のpaths:フロントマターは無視されるバグがある。パススコープにはプロジェクトレベルのルールを使うこと。
• CLAUDE.md本体にYAMLフロントマターは使えない。フロントマターが有効なのは.claude/rules/*.md内だけだ。

.cursorrules と .mdc（Cursor）

Cursorのルール形式には2世代ある。どちらを使っているかによって動作が大きく異なる。

第1世代：.cursorrules — プロジェクトルートに置く単一のプレーンMarkdownファイル。CursorのChat・Composerセッションで自動的に読み込まれる：

# .cursorrules

あなたはNext.js 14アプリで作業する熟練TypeScript開発者です。

## コードスタイル
- 関数コンポーネントのみ使用
- default exportより名前付きexportを優先
- propsは必ず明示的に型付けする。`any`禁止

## テスト
- すべてのユーティリティ関数にVitestのユニットテストを書く
- コンポーネントテストはReact Testing Libraryを使う

このレガシー形式の制約：

• Agentモードでは読み込まれない。 ユーザーがCursorのAgentに切り替えると.cursorrulesは見えなくなる。
• スコープ制御なし。関連性に関わらず、すべての会話ですべてのルールがロードされる。
• ファイルタイプのターゲティングなし。フロントエンドとバックエンドのルールが同じコンテキストに入る。

第2世代：.cursor/rules/*.mdc — YAMLフロントマター付きの.mdcファイルを使うモダン形式。.mdc拡張子が必須——.cursor/rules/内の.mdファイルは無視される：

---
description: "TypeScript APIルート規約"
globs: ["src/app/api/**/*.ts"]
alwaysApply: false
---

# APIルートのルール

- Next.js 14のRoute Handler（`route.ts`）を使う。Pages Router APIルートは使わない
- Zodでリクエストボディを検証してから処理する
- 一貫した `{ data, error }` レスポンス形式を返す
- try/catchでエラーを処理し、適切なHTTPステータスコードを返す

フロントマターで決まる4つのルール適用タイプ：

注意点：

• .mdc拡張子は必須。.cursor/rules/内のreact.mdという名前のファイルは何もしない。
• .cursorrulesはルートに置いたままでも読み込まれるが、Agentモードでは無効だ。
• 1ファイルあたり500行推奨。大きなルールセットは複数ファイルに分割する。
• alwaysApply: trueとglobs:を同時設定すると、常時ロードかつ対応ファイルで自動アタッチされる。冗長だが問題はない。
• ファイル間インポートの仕組みはない。各.mdcは独立して存在する。

.windsurfrules（Windsurf）

Windsurfはプロジェクトルートに置く.windsurfrulesという単一のプレーンテキストファイルを使う。WindsurfのAIエージェントCascadeは毎セッション開始時にこれを読む。

.windsurfrules  （プロジェクトルート）

形式 — 自由形式のプレーンテキストまたはMarkdown。必須スキーマ、YAMLフロントマター、特殊な構文は一切ない：

あなたはPythonバックエンドの熟練開発者です。このプロジェクトはFastAPI + SQLAlchemy + PostgreSQLを使用しています。

以下の規約に従うこと：

1. すべてのデータベース操作にはasync/awaitを使う
2. すべてのリクエスト/レスポンススキーマをPydantic v2モデルで定義する
3. すべてのpublic関数にGoogleスタイルのdocstringを書く
4. データベースマイグレーションはAlembicを使う——テーブルを直接変更しない
5. テストはtests/に置き、pytest with pytest-asyncioを使う
6. 環境変数はpython-dotenvで読み込む。認証情報をハードコードしない

2層構造：

• グローバルルール: Windsurf設定のCascade → Custom Instructionsで設定。マシン上のすべてのプロジェクトに適用される。
• プロジェクトルール（.windsurfrules）: 現在のプロジェクトにのみ適用。チームの一貫性のためにバージョン管理にコミットする。競合時はプロジェクトルールがグローバルを上書きする。

注意点：

• シングルルートの制限 — プロジェクトに.windsurfrulesは1つだけ。サブディレクトリスコープも、ディレクトリ単位のファイルも使えない。モノレポではすべてのルールを1ファイルに集約する必要があり、肥大化しやすい。
• フロントマター、globパターン、条件付きロードはない。すべての行が常にコンテキストに入る。
• インポート機構もない。すべてを1ファイルにインライン記述する必要がある。
• WindsurfはAGENTS.mdも読む——チームがAGENTS.mdをコミットしていれば、.windsurfrulesを別途管理しなくてもWindsurfサポートが得られる。

AGENTS.md（OpenAI Codex + 20以上のツール）

AGENTS.mdは最もポータブルな形式だ。2026年半ば時点で、OpenAI Codex・GitHub Copilotのコーディングエージェント・Gemini CLI・Windsurf・Aider・Zed・Factory・Jules・Devin・Amp・Kilo・RooCode・Augment・Warp・JetBrains Junieなどでネイティブサポートされている。

形式 — 純粋なMarkdown。必須のフロントマターも必須のセクションもない。プロジェクトに合った見出し構造を自由に使える：

# プロジェクトルール

## コードスタイル
- すべてのファイルでTypeScript strictモードを必須とする
- `any`型は使わない。`unknown`を使い明示的にナローイングする
- インポートの順序: 外部 → 内部 → 相対パス

## テスト
- コミット前に`pnpm test`を実行する
- エクスポートされたすべてのユーティリティ関数にユニットテストが必要
- インテグレーションテストは`tests/integration/`に置く

## Git
- コミットメッセージはConventional Commits（feat/fix/chore/docs）に従う
- ブランチ名: `feat/`・`fix/`・`chore/`プレフィックス必須
- `main`へのforce-push禁止

ネストと階層 — AGENTS.mdの最強の機能だ。任意のディレクトリにAGENTS.mdを置ける。Codexは編集中のファイルからディレクトリツリーを上方向にたどり、見つかったすべてのAGENTS.mdをルートから現在のディレクトリの順に連結する。最も近いファイルが競合時に優先される。

project/
├── AGENTS.md                    # プロジェクト全体のルール（常時ロード）
├── src/
│   ├── AGENTS.md                # フロントエンド固有のルール
│   └── api/
│       └── AGENTS.md            # API固有のルール（このディレクトリで最高優先度）
└── packages/
    └── auth/
        └── AGENTS.md            # authパッケージのルール

OpenAI自身のCodexモノレポには88個のネストされたAGENTS.mdファイルが存在する——サービスやパッケージごとに1つずつだ。

AGENTS.override.md — AGENTS.mdが親ファイルと連結されるのに対し、AGENTS.override.mdはそのレベルのファイルを完全に置き換える。サブディレクトリが親のルールの拡張ではなく、完全に異なるルールを必要とする場合に使う：

project/
├── AGENTS.md                    # 会社標準（連結される）
├── legacy-service/
│   └── AGENTS.override.md      # 親を完全に置き換え。レガシーサービス独自のルール

グローバルスコープ — ~/.codex/AGENTS.mdはユーザー全体のすべてのプロジェクトに適用される。Codexはこれをプロジェクトレベルのファイルとマージする。

注意点：

• サイズ上限: 連結後32 KiB（project_doc_max_bytes）。空のファイルはスキップされる。
• フロントマターがないため、パスベースのロードはない。AGENTS.md内のルールは、そのディレクトリ以下に対して常にスコープ内にある——粒度はパターンではなくファイルの配置で制御する。
• AGENTS.override.mdは置き換えであり拡張ではない。誤って使うと親ルールが消える。
• ツールによってサポートの程度が異なる。ほとんどのツールはAGENTS.mdを読むが、完全な仕様を同一の方法で実装しているわけではない。Codexがネストを最も忠実に実装している。

ルールのポータビリティガイド

形式間のルール変換は常に1:1ではない。最も一般的な4カテゴリの変換例を具体的に示す。

コードスタイルルール

Cursor .mdc → CLAUDE.md

変換前（.cursor/rules/typescript.mdc）:

---
description: "TypeScriptコーディング規約"
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---

- strictモードのTypeScriptを使う。`any`型禁止
- `let`より`const`を優先する
- 名前付きexportのみ。default exportは使わない

変換後（./CLAUDE.mdまたは.claude/rules/typescript.md）:

---
paths:
  - "**/*.ts"
  - "**/*.tsx"
---

# TypeScript規約

- strictモードのTypeScriptを使う。`any`型禁止
- `let`より`const`を優先する
- 名前付きexportのみ。default exportは使わない

変換はほぼ1:1だ。フロントマターのキーがglobs:からpaths:に変わり、ファイルの配置先が.cursor/rules/（.mdc拡張子）から.claude/rules/（.md拡張子）になる。

Gitとコミットのルール

AGENTS.md → .windsurfrules

変換前（AGENTS.mdのセクション）:

## Gitワークフロー
- Conventional Commitsを使う: `feat:`・`fix:`・`chore:`・`docs:`
- ブランチ名は`feat/`・`fix/`・`chore/`で始める必要がある
- PRはCI通過後にマージ可能
- `.env`ファイルをコミットしない

変換後（.windsurfrulesのセクション）:

Gitワークフロー:
- Conventional Commitsを使う: feat:、fix:、chore:、docs:
- ブランチ名はfeat/、fix/、chore/で始める必要がある
- PRはCI通過後にマージ可能
- .envファイルをコミットしない

.windsurfrulesは自由形式なので、変換は主に見た目の調整だ。Markdown見出し構文は使えるが必須ではない。

テストルール

CLAUDE.mdの.claude/rules/ → AGENTS.md

変換前（.claude/rules/testing.md）:

---
paths:
  - "**/*.test.ts"
  - "**/*.spec.ts"
  - "tests/**/*"
---

# テストルール

- コミット前に`npm test`を実行する
- 外部HTTPコールはモックする。テスト中に実際のAPIを叩かない
- テストファイル名はテスト対象モジュールに合わせる: `users.ts` → `users.test.ts`

変換後（AGENTS.mdまたはtests/AGENTS.md）:

## テスト

- コミット前に`npm test`を実行する
- 外部HTTPコールはモックする。テスト中に実際のAPIを叩かない
- テストファイル名はテスト対象モジュールに合わせる: `users.ts` → `users.test.ts`

パスベースのスコープは失われる。AGENTS.mdにはフロントマターベースのパスフィルタリングがない。tests/ディレクトリ内にAGENTS.mdを置くことで代替できる——そのディレクトリ以下のファイルを操作するときだけロードされる。

アーキテクチャルール

.cursorrules（レガシー）→ CLAUDE.md

変換前（.cursorrules）:

これはNext.js 14のモノレポです。以下のアーキテクチャルールに従ってください:

- APIルートはsrc/app/api/に置く
- 共有型はpackages/types/に置く
- apps/からpackages/へのインポート禁止
- データベースアクセスはsrc/server/のみ——Reactコンポーネントでは禁止
- ミューテーションにはServer Actionsを使う。クライアントコンポーネントからAPIを直接呼ばない

変換後（CLAUDE.md）:

# アーキテクチャルール

これはNext.js 14のモノレポです。

- APIルートは`src/app/api/`に置く
- 共有型は`packages/types/`に置く
- `apps/`から`packages/`へのインポート禁止
- データベースアクセスは`src/server/`のみ——Reactコンポーネントでは禁止
- ミューテーションにはServer Actionsを使う。クライアントコンポーネントからAPIを直接呼ばない

アーキテクチャルールを「ガイダンス」ではなく「強制」として機能させたいなら、ファイル保存時にインポートパターンをチェックするClaude Codeフックの追加を検討する：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "npx madge --circular src/" }]
      }
    ]
  }
}

ユースケース別の最適解

Claude Code を使うソロ開発者

推奨: CLAUDE.md

サブディレクトリスコープ、シェルフック、@pathインポート、そして最も充実したツールセットが手に入る。200行の規律でコンテキストを軽量に保てる。プロジェクトが大きくなったら.claude/rules/でファイルタイプ別にルールを分割する。

たまに他のツールに切り替える場合でなければ、.cursorrulesや.windsurfrulesを管理する必要はない。

ツールが混在するチーム（Cursor使いもいれば Claude Code使いもいる）

推奨: AGENTS.mdをコア、ツール固有のアダプターを拡張に

コーディング規約・git規則・アーキテクチャを網羅する共有AGENTS.mdをルートにコミットする。そのツールだけがサポートする機能のために、ツール固有のファイルを追加する：

project/
├── AGENTS.md           # 共有コア——すべてのツールが読む
├── CLAUDE.md           # AGENTS.mdをインポート + Claude固有のフック設定
├── .cursor/rules/
│   └── react.mdc       # *.tsxに自動アタッチ——Cursor専用
└── .windsurfrules      # WindsurfはAGENTS.mdをネイティブに読むため省略可能

混在ツールのリポジトリにおけるCLAUDE.mdの例：

@AGENTS.md

## Claude Code拡張

- `src/billing/`以下を編集する前にプランモードを使う
- PR提出前に`/review`を実行する

WindsurfはAGENTS.mdをネイティブに読むため、.windsurfrulesは省略可能なことが多い。

複数パッケージのモノレポ

推奨: AGENTS.mdのネスト + CLAUDE.mdのサブディレクトリファイル

AGENTS.mdのネスト構造はモノレポのパッケージ構造と自然にマッピングされる。各パッケージがパッケージ固有のルールを持つAGENTS.mdを持つ。Codex・Copilot・Gemini CLIはこの階層を尊重する。

Claude CodeにはパッケージレベルのCLAUDE.mdファイルを追加する。Claudeがそのディレクトリで作業するときに遅延ロードされる：

packages/
├── auth/
│   ├── AGENTS.md       # authルール（マルチツール）
│   └── CLAUDE.md       # Claude固有のauthルール
├── payments/
│   ├── AGENTS.md
│   └── CLAUDE.md

モノレポでの.windsurfrulesは避けるべきだ——単一のルートファイルではパッケージレベルの違いを表現できず、メンテナンスが困難な巨大ファイルになりやすい。

ユニバーサル互換性を求めるOSSプロジェクト

推奨: AGENTS.mdのみ

あらゆるAIツールを使うコントリビューターに一貫した動作をさせたいなら、AGENTS.mdが自明な選択だ。ツールごとのメンテナンスなしに20以上のツールで動作する。よくある間違いを防ぐルールに絞って簡潔に保つ。

ツール固有のファイルは、そのツールにしかない機能（フック、パススコープルール）が本当に必要な場合のために予約し、コントリビューターが見つけられるようにドキュメントに記載しておく。

2026年 マルチツール戦略：重複なしで同期を維持する

4つのルールファイルを別々に管理するのはメンテナンスの悪夢だ。機能する方法は共有コア + 薄いアダプター層という構造だ。

アーキテクチャ

project/
├── AGENTS.md                    # 共有ルールの唯一の正規ソース
├── CLAUDE.md                    # AGENTS.mdをインポート + Claude固有の追加
├── .cursor/rules/
│   ├── auto-attached.mdc        # Cursorがファイルタイプ別に適用できるパススコープルール
│   └── always.mdc               # alwaysApply: trueが必要なルール
└── .windsurfrules               # 省略可能。Windsurfは元々AGENTS.mdを読む

どこに何を書くか

AGENTS.md（共有コア）:

• コーディングスタイル規約
• 命名規約
• GitとPRワークフロー
• アーキテクチャの制約（「XからYをインポートしない」など）
• テスト要件

CLAUDE.mdへの追加:

• フック設定（ファイル保存時のシェルコマンド、プリコミットチェック）
• 大きなリファレンスドキュメントをオンデマンドで取り込む@pathインポート
• Claude固有の行動ガイダンス（「決済変更にはプランモードを使う」など）
• サブディレクトリスコープが必要な指示

.cursor/rules/*.mdcへの追加:

• Cursorのglobs:自動アタッチのためのパススコープルール
• Cursorのエージェント関連性チェックのための充実したdescription:を持つAgent Requestedルール
• CursorのalwaysApply: trueがAgentモードで必要なルール

.windsurfrules（省略可能）: チームがWindsurfを使い、かつそのセットアップでAGENTS.mdが読まれない場合は、Cascadeのエージェントワークフローに最も関連するルールだけをカバーする最小限の.windsurfrulesを管理する。スコープ機構がないため関連性のないルールがコンテキストに混入しやすく、短く保つことが重要だ。

実践的な同期ワークフロー

共有ルールを更新するとき：

1. AGENTS.mdを編集する（正規ソース）。
2. CLAUDE.mdで@AGENTS.mdとしてインポート済みなら、Claude Codeへの対応はこれで完了。
3. そのルールがCursorの.mdcに相当するものが必要か確認する（パスのスコープ、Agentモード用のalwaysApply）。
4. チームがWindsurfをAGENTS.mdサポートなしで積極的に使う場合のみ.windsurfrulesを更新する。

GitフックやCIを使うチームの場合、重要なルールが4つのファイルすべてに存在するかチェックするシンプルなリンターを用意すると、同期のズレを本番で踏む前に検出できる。

機能比較マトリックス

まとめ

各形式はそれぞれのツールのメンタルモデルに合わせて設計されている：

• CLAUDE.md は精度と強制力に最適化されている。階層的なロード、シェルフック、ファイルインポートによって、Claudeへの指示だけでなく機械的な強制が実現できる。
• .cursorrules はクイックスタート用のレガシー形式だ。動くがCursorのAgentモードでは無効になる——エージェントを使うなら.mdcに移行すべきだ。
• .mdc はCursorの成熟した形式だ。4つのルールタイプ（always/auto/agent/manual）によって、ルールがコンテキストに入るタイミングを細かく制御できる。
• .windsurfrules は意図的にシンプルに設計されている。1ファイル、スキーマなし、とにかく動く。シングルルートの制限は大規模リポジトリで痛手になるが、WindsurfがAGENTS.mdをネイティブサポートしているため、別途管理しなくて済むことが多い。
• AGENTS.md はツール固有の強みをユニバーサルなリーチとトレードしている。ディレクトリベースのネストはモノレポにとって決定的な機能だ。事実上のオープン標準として、マルチツールチームの明確なアンカーとなっている。

最もシンプルな2026年の構成：AGENTS.mdを正規ソースとし、CLAUDE.mdでそれをインポートしてClaude固有のフックを追加し、.cursor/rules/*.mdcはCursorのパススコープやAgent Requestedアクティベーションが本当に必要なルールにだけ使う。

FAQ

CLAUDE.mdとAGENTS.mdの違いは？

CLAUDE.mdはClaude Code専用のネイティブ形式だ。シェルフック、@pathファイルインポート、ディレクトリ単位の遅延ロードをサポートする——他の形式にはない機能だ。AGENTS.mdはOpenAI Codex・GitHub Copilot・Gemini CLI・Windsurfを含む20以上のツールでネイティブサポートされるクロスツール標準。Claude固有のワークフローにはCLAUDE.md、複数ツールのチームでは共有コアとしてAGENTS.mdを使う。

CLAUDE.mdはプロジェクトのどこに置くべきか？

Claude Codeは複数の場所からCLAUDE.mdを読み込む。~/.claude/CLAUDE.md（ユーザー全体）、プロジェクトルートまたは.claude/CLAUDE.md（プロジェクト）、CLAUDE.local.md（個人設定・gitignore推奨）の順だ。サブディレクトリ内のCLAUDE.mdは、Claudeがそのディレクトリのファイルを読んだタイミングで遅延ロードされる。すべてのファイルは連結され、より近いファイルが競合時に優先される。

.cursorrulesと.mdcの違いは？

.cursorrulesはCursorのレガシー形式で、プロジェクトルートの単一MarkdownファイルだがCursorのAgentモードでは読み込まれない。.mdcは.cursor/rules/以下に置くモダン形式で、YAMLフロントマターにより「Always / Auto Attached / Agent Requested / Manual」の4タイプを定義できる。Agentモードを使うなら.cursorrulesから.mdcへの移行が必要だ。

Claude Codeで特定のファイル種別にのみルールを適用するには？

.claude/rules/以下に.mdファイルを置き、YAMLフロントマターのpaths:キーにglobパターンを指定する。たとえばpaths: ["src/api/**/*.ts"]と書くと、Claudeが対応するTypeScriptファイルを読んだときだけルールがロードされる。フロントマターなしのファイルは毎セッション読み込まれる。なお~/.claude/rules/（ユーザーレベル）ではpaths:フロントマターが無視されるバグがあるため、パススコープにはプロジェクトレベルの.claude/rules/を使うこと。

複数ツールのチームにはどの形式が適しているか？

AGENTS.mdを共有コアとして使うのがベストだ。20以上のツールでサポートされており、共通のコーディング規約・git規則・アーキテクチャルールをツールごとにコピーする必要がない。ツール固有の機能にだけ薄いアダプター層を追加する——シェルフックと@pathインポートはCLAUDE.md、パスベースのスコープ制御はCursorの.cursor/rules/*.mdcという分担だ。

AGENTS.override.mdとは何か？

AGENTS.override.mdはそのディレクトリレベルのAGENTS.mdを完全に置き換え、親ディレクトリのAGENTS.mdは適用されなくなる。通常のAGENTS.mdはルートから現在のディレクトリまで連結され、最も近いファイルが競合時に優先される。レガシーサービスのように、親のルールを継承せず完全に異なるルールが必要なサブディレクトリで使う。

関連記事

• AGENTS.md vs CLAUDE.md どっちを使う？5つの違いと正解（2026年版）
• ユースケース別 AGENTS.md・CLAUDE.md・.cursorrules テンプレート集
• CursorでAGENTS.mdを使う：完全セットアップガイド（2026年版）
• AiderのAGENTS.md vs CONVENTIONS.md：どちらを使うべきか

ルールファイルにシークレットを書かない——そのための仕組み

このリファレンスのすべての例が同じことを言っている——認証情報をハードコードしない、.envファイルをコミットしない、シークレットはリポジトリの外から読み込む。ルールファイルはその境界を定義するが、ランタイムで強制するわけではない。1Password CLIのop runは実行中だけ環境変数にシークレットをインジェクトするため、APIキーやデータベースパスワードがプロジェクトディレクトリ内のディスクに残ることがない——ルールファイルが定義しようとしている分離を、ランタイムレベルで実現できる。