Zenn
🎓

Cursorで使う.mdcファイルとは

に公開
初心者
Cursor
生成 AI
tech

はじめに

Cursorで.cursorrulesを使えば、プロジェクト固有のルールや文脈を理解してもらえていると思っていたのですが、今はProject Rulesに設定することが推奨されているんですね。

https://docs.cursor.com/context/rules-for-ai


色々実例を見ている中で .mdcファイルに出会ったのですが、.mdcファイルってYAMLファイルとどう違うの？従来の.cursorrulesとどう違うの？を調べたので、メモを残します。

.mdcファイルとは？

.mdcファイルは、CursorのAIアシスタントが参照する、プロジェクト固有のルールやコンテキストを定義するための設定ファイルです。

AIがコード補完、生成、リファクタリングなどを行う際に、このファイルに記述された指示やガイドラインを参照します。これにより、以下のような情報をAIに伝達できます。

  • プロジェクト固有のコーディング規約
  • チームで定められた命名規則
  • 特定のフレームワーク利用時のベストプラクティス
  • セキュリティに関する注意点

つまり、.mdcファイルを使うことで、汎用的なAIアシスタントを 「このプロジェクト専用のアシスタントへとカスタマイズできるってことですね。

従来のカスタムルールとProject Rules (.mdc) の違い

Cursorには、以前からAIにカスタムルールを教える機能がありました。設定画面から入力する 「Rules for AI」 や、プロジェクトルートに置く 「.cursorrules」ファイルがそれにあたります。これらもプロンプトに特定のコンテキストを追加する役割を果たしていました。

では、新しく登場した Project Rules (.cursor/rules/*.mdc) は何が違うのでしょうか？

  • より具体的・個別的な指示が可能: 従来のルールはプロジェクト全体に大まかに適用される傾向がありましたが、Project Rules (.mdc) では、globs パターンを使って特定のファイルやディレクトリに対して、より詳細なルールを個別に設定できます。
  • 構造化された管理: .mdcファイルはYAMLフロントマターとMarkdown本文で構成され、ルールを目的ごとにファイル分割（例: naming.mdc, style.mdc）して、.cursor/rules/ ディレクトリ内で整理・管理しやすくなっています。
  • プロジェクトとの連携: ルールファイルがプロジェクトディレクトリ内 (.cursor/rules/) に配置されるため、Gitなどのバージョン管理システムでプロジェクトコードと一緒に管理できます。

なぜ Project Rules (.mdc) が推奨されるのか？

従来の「Rules for AI」や「.cursorrules」も引き続き利用可能で、Project Rulesと併用することも可能です。しかし、上記のような詳細な制御、管理のしやすさ、プロジェクトとの一体性といったメリットから、現在では Project Rules (.cursor/rules/*.mdc) を活用することが推奨されています。公式の案内にもある通り、将来的にcursorrulesはremoveされそうです。

.mdcファイルの主な特徴と構造

.mdcファイルには、いくつかの重要な特徴があります。

  1. 形式:

    • YAML形式のメタデータ（フロントマター）とMarkdown形式の本文を組み合わせた、ハイブリッド形式で記述されます。
    • 拡張子.mdcは、この特殊な形式を示すCursor独自のものと考えられます。

  2. 保存場所:

    • プロジェクトのルートディレクトリ直下にある .cursor/rules/ ディレクトリ内に配置します。この場所に置くことで、Cursorはこれらを「Project Rules」として認識し、プロジェクト固有のルールとして扱います。

  3. 内容:

    • YAMLフロントマター:
      • description: このルールファイルが何をするものなのか、概要を記述します。AIがルールを理解する上で重要です。
      • globs: このルールをどのファイルに適用するかをGlobパターンで指定します（例: **/*.py でPythonファイル全体、src/components/**/*.tsx で特定のディレクトリ配下のTSXファイル）。
    • Markdown本文:
      • AIに守ってほしい具体的な指示やルールを箇条書きなどで記述します。自然言語で書けるため、柔軟な指示が可能です。

YAMLについては、前回まとめたので、参考までに。
https://zenn.dev/channnnsm/articles/db70d645d878f5

.mdcファイルの具体例

簡単な.mdcファイルの例を見てみましょう。これは .cursor/rules/javascript_style.mdc として保存するイメージです。

---
description: JavaScript/TypeScriptファイル向けの基本的な命名規則とスタイルガイド
globs: "**/*.{js,ts,jsx,tsx}"
---
- 変数名とプロパティ名はキャメルケース（`camelCase`）を使用してください。
- 関数名やメソッド名は、処理内容を表す動詞から始めてください（例: `getUserData`, `calculateTotal`）。
- 定数は大文字スネークケース（`UPPER_SNAKE_CASE`）で定義してください。
- 不要な `console.log` は残さないようにしてください。

この.mdcファイルをプロジェクトの .cursor/rules/ ディレクトリに配置すると、CursorのAIは .js, .ts, .jsx, .tsx ファイルを扱う際に、このルールを考慮してコード補完や提案を行うようになります。

.mdcファイル (Project Rules) を使うメリット

.mdcファイルを活用することで、従来のカスタムルール機能と比較しても、以下のような明確なメリットが得られます。

  1. 高度な柔軟性: globs により、ルール適用範囲をファイルタイプやディレクトリ構造に応じて細かく制御できます。これは従来の全体的なルール設定よりも格段に柔軟です。
  2. 優れたモジュール性と管理性: ルールを機能や目的に応じて複数の .mdc ファイルに分割し、.cursor/rules/ ディレクトリで一元管理できます。「security.mdc」「react_patterns.mdc」のように分けることで、ルールの可読性とメンテナンス性が向上します。
  3. 開発効率のさらなる向上: AIがプロジェクト固有のルールをファイル単位で正確に把握するため、開発者が指示を繰り返したり、AI生成コードを手直ししたりする手間が大幅に削減されます。
  4. コード品質と一貫性の強化: チーム全員がバージョン管理された共通の .mdc ルールセットに基づいてAIを利用できるため、プロジェクト全体のコード品質とスタイルの一貫性を高いレベルで維持しやすくなります。
  5. プロジェクトとの同期: ルールがプロジェクトの一部としてバージョン管理されるため、ブランチ切り替えやチームメンバー間のルール共有が容易になります。

ディレクトリ構成によるルール管理の具体例

より大規模なプロジェクトでは、ルールをさらに構造化して管理することが有効です。例えば、以下のようなディレクトリ構成を採用することで、ルールの意図が明確になり、スケーラビリティも向上します。

.cursor/rules
├── dev-rules        # 機能別・実装領域ごとのルール
│   ├── auth.mdc
│   ├── database.mdc
│   ├── framework.mdc
│   ├── architecture.mdc
│   ├── tasks.mdc
│   └── design.mdc
└── globals-rules    # プロジェクト横断的なルール
    ├── shared.mdc
    ├── naming-conventions.mdc
    └── linting.mdc

この構成では、ルールを 開発領域に特化したルール (dev-rules) と プロジェクト全体に関わる共通ルール (globals-rules) に分割しています。それぞれの意図と用途の例は以下の通りです。

🔧 dev-rules/（機能別・実装領域ごとのルール）

ファイル名 意図・用途の例
auth.mdc 認証・認可の方針、トークン管理、RBAC設計、Clerk/Auth0などのベストプラクティス
database.mdc RDB/NoSQLの設計基準、マイグレーション、スキーマ設計、クエリパフォーマンス指針
framework.mdc 使用フレームワーク（例：Next.js、Remixなど）の構成や命名規則、プラグイン指針
architecture.mdc クリーンアーキテクチャ、DDD、レイヤー構造、依存関係管理のルール
tasks.mdc 技術的課題のトラッキング、TODOリスト、未解決タスクの共有メモ
design.mdc UIコンポーネント設計指針、Figma連携、アクセシビリティ、レスポンシブ対応方針など

🌐 globals-rules/（プロジェクト横断ルール）

ファイル名 意図・用途の例
shared.mdc 全体に関わる汎用的な方針（共通の型定義、レスポンスフォーマット、共通ユーティリティなど）
naming-conventions.mdc 変数・関数・ファイルの命名規則（PascalCase / snake_case / kebab-case など）
linting.mdc ESLint, Prettierのルール、フォーマット設定、コード整形のベースラインルール

このようにルールを分割・整理することで、AIが参照するコンテキストをより適切に管理でき、チームメンバーもルールの全体像を把握しやすくなります。ルールの変更や追加も影響範囲を最小限に抑えて実施できるため、継続的な改善がしやすくなる構成です。

利用上の注意点

  • descriptionとglobsは正確に: AIがルールを正しく認識し、適切なファイルに適用するためには、descriptionとglobsを適切に設定することが重要です。空欄だったり、意図しないパターンを指定したりすると、ルールが適用されない可能性があります。
  • まずは簡単なルールから: 最初から複雑なルールを大量に記述するのではなく、基本的な命名規則やスタイルガイドなど、簡単なものから試してみるのがおすすめです。
  • Cursorのバージョンによる挙動: Cursorは活発に開発が進められています。無料版と有料版、あるいはバージョンによって.mdcファイルの解釈や機能が異なる可能性があります。公式ドキュメント等で最新情報を確認することをお勧めします。

おわりに

Cursorの Project Rules を実現する .mdcファイルは、従来のカスタムルール機能よりも便利そうだなという印象を持ちました。.cursor/rules/ ディレクトリを作成して、.mdcファイルでプロジェクトルールを定義してみるのは良さそうですね。

特に、dev-rules/ で機能的責務別（垂直分割）にルールを配置、globals-rules/ で横断的関心事（水平分割）にルールを配置することで、いい感じに制御してくれそうな感覚があります。この辺りはいろいろと試してみて、結果を見て調整していきたいと思います！

Discussion