AIコードエディタCursorにおいて、長らくプロジェクトごとの指示を与える標準手法として使われてきたのが、リポジトリ直下の .cursorrules ファイルでした。
しかし、プロジェクトが成長するにつれて「ルールが肥大化してプロンプトのトークン上限を圧迫する」「TypeScriptの規約をPythonファイルの編集中にも毎回読み込んでしまう」といった問題が深刻化しました。これを受け、Cursorの最新仕様では単一の .cursorrules がレガシー（非推奨）扱いとなり、ディレクトリ分割形式の .cursor/rules/*.mdc（Project Rules）への移行が推奨されています。
さらに、近年の開発現場ではCursorだけでなく、Claude CodeやCodex CLIなど複数のAIエージェントを併用するケースが増えています。ツールごとに別々の設定ファイルを書く二重管理を避けるため、プレーンなMarkdownで共通管理できる AGENTS.md や CLAUDE.md との連携設計も不可欠です。
この記事では、旧 .cursorrules から新方式 .mdc へ移すときの確認ポイント、ルール作成支援、および AGENTS.md と共存させるチーム向けの設計例を解説します。
この記事で行うこと
.cursorrulesが非推奨になった理由と新方式.mdcのメリットを理解する- AIコーディングルールファイルの特徴と適用範囲を把握する
- Cursorのルール作成機能を使って自然言語からルールファイルを作成する
- 手動作成時の
.cursor/rules/*.mdcのYAML frontmatter（globs、alwaysApply、description）の書き方を習得する - 共通ルールを
AGENTS.mdに集約し、Cursor固有の分岐のみを.mdcで委譲する共存設計を導入する - 移行時によくある設定競合やファイル認識エラー（アンチパターン）を防止する
前提条件・対応バージョン
この記事で紹介する機能や構文は、以下の環境に基づいて検証しています。
| 項目 | 内容 |
|---|---|
| 検証ツール | Cursor |
| 対応バージョン | Project Rulesと.mdcに対応した現行版 |
| バージョン確認方法 | ヘルプメニューの「About Cursor」または「Cursorについて」 |
| 検証OS | macOS / Windows / Linux |
| 併用対象ツール | Claude Code CLI、Codex CLI、GitHub Copilot |
| 最終確認日 | 2026年10月 |
> 補足：古いバージョンのCursorを使用している場合、.cursor/rules/ ディレクトリ内の .mdc ファイルが読み込まれない場合があります。最新版へアップデートしてから設定を行ってください。
1. AIコーディングルールファイルの特徴と適用範囲
Cursorおよび周辺のAIコーディング環境では、ルールの適用範囲や共有方法に応じて複数の設定ファイルが存在します。それぞれの役割と優先順位を整理したのが以下の早見表です。
| ルール種別 | 配置場所・ファイル形式 | 共有範囲 | 特徴とツール横断での最適な使い分け |
|---|---|---|---|
| Project Rules（推奨） | .cursor/rules/*.mdc | Git共有 | globs や alwaysApply 等の適用条件でファイル種別ごとに制御できます |
| AGENTS.md | プロジェクト直下の AGENTS.md | Git共有 | Cursorでは単純なMarkdown形式の代替手段です。対応範囲は利用する各ツールの仕様を確認します |
| CLAUDE.md | プロジェクト直下の CLAUDE.md | Git共有 | Claude Codeも併用するリポジトリで、Claude向けの指示を管理できます |
| User Rules | Cursor設定画面（Customize → Rules） | 個人（アカウント同期） | 全プロジェクトに毎回注入される個人設定（好みの応答言語や個人のエディタ操作スタイル等） |
| Team Rules | Cursorダッシュボード（Team / Enterprise） | 組織全体 | 組織単位で強制・共有するセキュリティポリシーやガバナンスルール |
| .cursorrules（非推奨） | プロジェクト直下の単一ファイル | Git共有 | レガシー形式です。Cursorは引き続きサポートしていますが、新規作成ではProject Rulesを推奨します |
複数のルールを併用する場合、競合時の優先順位に依存しない設計が大切です。同じ内容を .cursorrules、Project Rules、User Rulesへ重複して書かず、用途ごとに正本を一つに決めてください。
2. なぜ.cursorrulesは非推奨になったのか？新方式のメリット
単一ファイル管理の限界
従来の .cursorrules は、プロジェクトルートに置かれた単一のテキストファイルにすべての指示を書き込む仕様でした。この方式には実務上、以下の3つの大きな欠点がありました。
- トークン消費の肥大化：すべてのチャットやコード生成において、ファイル全体の内容が毎回システムプロンプトに注入されるため、コンテキストウィンドウを無駄に圧迫し、モデルの応答速度低下やコスト増加を招く
- ファイル種別ごとの出し分け不可：フロントエンドのReact規約、バックエンドのGo規約、インフラのTerraform規約など、本来関係のない文脈のルールまで同時に読み込まれてしまい、AIが指示を混同しやすくなる
- チーム開発でのコンフリクト：複数人で異なるモジュールのルールを同一ファイルに追記するため、Gitのコミット時にコンフリクトが頻発する
新方式「.cursor/rules/*.mdc」の3大メリット
これらの課題を解決するために導入されたのが、ディレクトリ分割型の .mdc ファイルです。
- 条件付き読み込みによるトークン節約：編集中のファイルパス（
globs）やユーザーの質問内容（description）に応じて、必要なルールファイルだけが動的に読み込まれます - 関心の分離と保守性の向上：「Git運用ルール」「API設計規約」「UIデザインルール」のように役割ごとに独立したファイルとして分割管理できるため、コードベースが大規模化しても見通しを保てます
- 自然言語による自動生成：後述する
/create-ruleコマンドにより、手動で設定構文を調べなくてもAIと対話しながらルールファイルを作成できます
3. 新規ルールを作成する
チャット欄からの自動作成手順
CursorのAgentモードやChat機能を利用して、簡単に新しいルールファイルを作成できます。
- Cursorのチャットパネルを開きます（ショートカット:
Ctrl + LまたはCmd + L） - ルール作成が表示される場合は、それを選択します
- 作成したいルールの内容を自然言語で指示します
入力例：
Next.js App Routerのコンポーネント作成規約を作ってください。
- ファイルは src/components/**/*.tsx を対象とする
- コンポーネントはアロー関数で記述し、Propsは型エイリアス（type）で定義する
- 'use client' はインタラクティブな状態を持つ場合のみ付与する
作成された内容は、そのまま採用せず、対象パス、常時適用の有無、指示の重複を確認してから保存します。Cursorの画面やコマンド名は更新されることがあるため、利用中のバージョンで表示される案内を優先してください。
コマンドパレットからの作成
コマンドパレットからGUI感覚で作成することも可能です。
Ctrl + Shift + P（macOSはCmd + Shift + P）を押してコマンドパレットを開きますruleで検索し、表示されるルール作成コマンドを選択します- ルール名、説明、対象ファイルパターンを入力し、生成後に内容を確認します
4. 手動作成時の「.mdc」YAML frontmatter記述ルール
ルールを手動で細かくチューニングしたい場合は、.cursor/rules/ ディレクトリ内に直接 .mdc ファイルを作成します。
ファイルの先頭には、必ず3連ハイフンで囲んだYAML形式のメタデータ（frontmatter）を記述します。
---
description: ルールの概要とAIが自動適用を判断するための説明文
globs: 適用対象のファイルパターン（グロブ構文）
alwaysApply: trueまたはfalse
---
# ルール本文（Markdown）
ここに具体的なコーディング規約や設計方針を記述します。
4つの適用タイプ（スコープ）の使い分け
frontmatterに指定するキーの組み合わせによって、ルールがいつ読み込まれるか（適用スコープ）が変化します。
1. 常時適用（Always Apply）
プロジェクト全体の命名原則やコミットメッセージ規約など、どのようなファイル編集であっても常に意識させたい基本原則に適用します。
---
description: プロジェクト全体の基本コーディング方針
globs:
alwaysApply: true
---
# 全体原則
- 回答およびコミットメッセージはすべて日本語で記述してください。
- 破壊的なファイル削除や依存関係の更新を行う前には必ず確認を求めてください。
常時適用ルールに長文を書くと毎回のトークンを消費するため、文字数は200文字前後の要点に絞るのが鉄則です。
2. ファイル指定適用（Apply to Specific Files）
特定の拡張子やディレクトリ配下のファイルを編集・参照している時だけ読み込ませる設定です。実務で最も多用されます。
---
description: ReactコンポーネントおよびUI関連の実装ルール
globs: src/components/**/*.tsx, src/app/**/*.tsx
alwaysApply: false
---
# React / UIコンポーネント規約
- スタイリングにはTailwind CSSを使用し、インラインスタイルは避けてください。
- すべてのUIパーツには適切なアクセシビリティ属性（aria-label等）を付与してください。
カンマ区切りで複数のグロブパターンを指定できます。
3. インテリジェント適用（Apply Intelligently）
ファイルパターンに関係なく、ユーザーの質問やタスクの文脈に応じてAI自身に関連性を判断させたい場合に設定します。
---
description: 単体テスト（Jest / Vitest）の作成やテストケース拡充を依頼された際に参照するルール
globs:
alwaysApply: false
---
# テストコード作成規約
- Arrange-Act-Assert（準備・実行・検証）パターンに従ってテストケースを記述してください。
- 外部API呼び出しやDB接続は必ずモックを作成し、単体で完結させてください。
description の記述が重要であり、「どのような依頼のときにこのルールを使うべきか」を具体的に記載しておくと、AIの判断精度が高まります。
4. 手動適用（Apply Manually）
普段は読み込まず、必要なときだけユーザーが明示的にメンションして呼び出すルールです。
---
description: リファクタリングおよびパフォーマンス最適化の指針
globs:
alwaysApply: false
---
# リファクタリング規約
- 計算量の大きい処理はメモ化（useMemo等）を検討してください。
- 関数の責務を単一にし、ネストが3段階以上深くならないように早期リターンを活用してください。
チャット欄で @refactoring のようにファイル名をメンションした際のみコンテキストに追加されます。
5. チームで必須！「AGENTS.md」「CLAUDE.md」との共存設計
ルールファイルの乱立問題
Cursor用の .cursor/rules/*.mdc、Claude Code用の CLAUDE.md、Codexや各種汎用エージェント用の AGENTS.md など、利用するツールごとに同じコーディング規約をコピー＆ペーストして管理すると、必ず更新漏れによるルールの不整合が生じます。
これを防ぐための現代のベストプラクティスは、「共通ルールの一元化」と「エディタ固有機能の分離」です。
共通規約をAGENTS.mdに集約するハイブリッド設計
- プロジェクトルートの
AGENTS.mdに、すべてのAIツールで共通して守るべきアーキテクチャ方針、コーディング作法、禁止事項をプレーンなMarkdownで集約します - Cursor固有の
.cursor/rules/には、拡張子ごとのグロブ制御（globs）など、Cursorで必要な差分だけを記述します
リポジトリ構成例：
my-project/
├── AGENTS.md # チーム共通のSingle Source of Truth（真実の単一情報源）
├── CLAUDE.md # Claude Code用（必要に応じてAGENTS.mdへの参照やコマンドを定義）
└── .cursor/
└── rules/
├── general.mdc # Always Apply：短い共通方針
├── frontend.mdc # globs: src/components/**/*.tsx
└── backend.mdc # globs: src/api/**/*.ts
general.mdcの記述例
---
description: プロジェクト全体の共通基本規約
globs:
alwaysApply: true
---
# プロジェクト共通ルール
このリポジトリでは、破壊的な操作の前に影響範囲を確認してください。
詳細な規約は必要なルールファイルだけを参照してください。
各ツールが読むファイルと適用範囲は異なります。共通規約を AGENTS.md に置く場合も、利用するツールごとに実際に読み込まれることを確認し、Cursor向けの条件付きルールは .cursor/rules/ で管理してください。
6. よくある失敗とアンチパターン（❌間違い例 vs ⭕正しい手順）
❌ 間違い例1：拡張子を「.md」で保存してCursorに無視される
.cursor/rules/
└── react-rules.md
ルールファイルを通常のMarkdown拡張子（.md）で作成してしまうミスです。
.cursor/rules/ ディレクトリ配下に置かれたファイルは、拡張子が .mdc（Markdown with Cursor）でない場合、CursorのルールエンジンにProject Rulesとして認識されず、設定が完全に無視されます。
⭕ 正しい手順：必ず拡張子を「.mdc」にする
.cursor/rules/
└── react-rules.mdc
ファイル名は任意ですが、拡張子は必ず小文字の .mdc に統一してください。
❌ 間違い例2：旧.cursorrulesを残したまま.mdcを運用して上書きされる
リポジトリルートに以前の .cursorrules を残したまま、新しい .cursor/rules/*.mdc を追加して二重管理してしまうケースです。
Cursorの仕様上、旧 .cursorrules と新 .mdc の両方が存在する場合、基本的には両方が読み込まれますが、設定や指示が競合した場合、.mdc 側の指示で上書きされたり、予期せぬ挙動を引き起こしたりします。また、旧ファイル側だけを修正して新ファイル側を修正し忘れるといったヒューマンエラーの原因にもなります。
⭕ 正しい手順：移行を確認してから旧ファイルを削除する
旧 .cursorrules の内容を役割ごとに .mdc へ移し、Cursor上で期待どおりに適用されることを確認してから削除します。削除前に重複指示が残っていないかも確認してください。
git rm .cursorrules
git add .cursor/rules/
git commit -m "chore: .cursorrulesから.cursor/rules/*.mdcへ移行"
❌ 間違い例3：すべてのルールをAlways Applyにして長文を書く
すべての .mdc ファイルで alwaysApply: true を指定し、何千行ものAPIドキュメントや規約全文を書き込んでしまうパターンです。
コンテキストウィンドウがルールだけで埋め尽くされ、実際のソースコードを読み込む枠が削られてしまうため、AIの回答品質が著しく低下します。
⭕ 正しい手順：役割ごとに適切なスコープを割り当てる
alwaysApply: true：200文字前後の最重要方針（コミット原則、言語設定など）globs：拡張子やディレクトリに依存する言語固有規約（500文字程度）description：単体テスト作成やリファクタリングなど特定タスク用の詳細規約
❌ 間違い例4：禁止事項や「〜しないでください」ばかりを羅列する
- any型を使わないでください。
- Reduxを使わないでください。
- console.logを残さないでください。
否定形の禁止事項ばかりを羅列すると、AIは「ではどう書けばよいのか」の選択肢を見失い、かえって不自然なコードを生成することがあります。
⭕ 正しい手順：推奨コード例（⭕）と非推奨コード例（❌）を対比で示す
# 型定義の原則
❌ 避けるべき記述：
const handleData = (data: any) => { … }
⭕ 推奨する記述：
interface UserData { id: string; name: string; } const handleData = (data: UserData) => { … }
このように具体例を添えることで、AIモデルの出力精度が飛躍的に向上します。
7. 検索クエリ型FAQ（よくある質問）
Q1：既存の .cursorrules はいつまで使えますか？突然動かなくなりますか？
A：後方互換性のため、現行バージョンでも .cursorrules は引き続きフォールバックとして読み込まれます。ただし、Cursorの公式ドキュメントおよびフォーラムにおいて「レガシー（非推奨）」と明記されており、今後のメジャーアップデートでサポートが終了する可能性があります。また、ファイル単位の適用制御（globs）などの新機能の恩恵を受けられないため、早めの移行をおすすめします。
Q2：サブディレクトリごとに異なる .mdc ルールを配置できますか？
A：.cursor/rules/ ディレクトリはプロジェクトルートに配置するのが基本です。サブディレクトリごとにルールを切り替えたい場合は、ディレクトリを分散させるのではなく、ルートの .cursor/rules/ 配下にある各 .mdc ファイルの globs 設定を活用します。たとえばバックエンド専用ルールであれば globs: backend/**/*.go、フロントエンド専用ルールであれば globs: frontend/**/*.tsx と指定することで、ファイルパスに応じた自動切り替えが可能です。
Q3：.mdc ファイルの中で別のルールやファイルを @ で参照できますか？
A：参照の可否や記法はCursorのバージョン・画面によって変わる可能性があります。公式のRulesドキュメントと利用中の画面で確認してください。参照機能に依存しなくても運用できるよう、重要なCursor固有ルールは対象の .mdc に明記しておくと安全です。
Q4：Gitでチーム共有したくない個人用のルールはどう設定すればいいですか？
A：個人専用の好み（「解説は関西弁で」「コメントは英語で」「エディタ操作はVimキーバインド前提で」など）は、リポジトリ内の .mdc に書くのではなく、Cursorの設定画面（Settings → General → Rules for AI / User Rules）に記述します。User Rulesはあなたのアカウントに紐づき、すべてのプロジェクトに個人設定として適用されます。
Q5：VS Codeなど他のエディタで .mdc ファイルを開くとハイライトが崩れます
A：.mdc は実質的にMarkdown形式のファイルですが、エディタによっては拡張子 .mdc に言語モードが割り当てられていない場合があります。VS Codeなどの設定（settings.json）で以下のようにファイル関連付けを追加すると、通常のMarkdownと同様にシンタックスハイライトが効くようになります。
{
"files.associations": {
"*.mdc": "markdown"
}
}
まとめ
長らく使われてきた .cursorrules から .cursor/rules/*.mdc への移行は、単なるファイル形式の変更ではなく、トークン消費の最適化とAIの回答精度向上を実現するための重要な改善です。
- 単一ファイルの肥大化を防ぐため、
.cursor/rules/*.mdcに役割ごとに分割する - ルール作成支援を使う場合も、生成された適用条件と本文を確認してから採用する
globs、alwaysApply、descriptionを適切に使い分け、必要な時だけルールをコンテキストに読み込ませる- チーム内の他AIツール（Claude Code等）との共存には、共通規約を
AGENTS.mdに集約するハイブリッド設計を採用する - 旧
.cursorrulesは移行後の適用を確認してから削除し、設定の競合や上書き事故を防ぐ
プロジェクトに適したProject Rulesを整備し、日々のAIコーディングの生産性を最大限に引き出しましょう。
次に読むおすすめ記事
生成AIやAIエージェントを開発で活用する全体像は、以下のハブ記事で解説しています。
参考情報
- Cursor公式ドキュメント：Rules for AI
- Cursor Community Forum：Project Rules & .mdc Migration Guide
- Anthropic公式ドキュメント：Claude Code Memory and Rules (CLAUDE.md)
