🍣

CursorのProject Rulesの調査メモ

2025/03/25に公開

Cursorルールファイル（.mdcファイル）は、Cursor AIがプロジェクトの特定の要件やベストプラクティスを理解し、適切なコード生成や提案を行うための重要な設定ファイル

 概要Cursorルールファイルは、プロジェクトのルールやガイドラインを定義するために使用される

.mdc形式で記述され、.cursor/rules/ディレクトリに配置されます。
※Cursor v0.45より前は.cursorrulesファイル1つを使用していたが、以降は複数ファイルの対応に変わった

 主な定義内容
プロジェクト構造の定義:
特定のディレクトリ構造やファイル命名規則を強制します。


コーディング規約の適用:
命名規則やコードスタイルを一貫性を持たせます。


ベストプラクティスの推奨:
パフォーマンス最適化やセキュリティ対策に関するガイドラインを提供します。


AIによるコード生成のサポート:
Cursor AIがルールに基づいてコードを生成し、プロジェクトの品質を向上させます。


 mdcファイルの命名規則Cursorルールファイルの命名規則は以下の通りです:
ファイル拡張子は.mdcを使用します[1][5]。
ファイル名にはkebab-caseを使用します[1][3]。
ファイル名は説明的で、ルールの目的を反映させるべきです[1][3]。
数字のプレフィックスを使用して優先順位や順序を示すことができます。※大きい方が優先

例えば:
001-099: コア/ワークスペースルール
100-199: 統合ルール
200-299: パターンルール[2]

一般的なパターンは「technology-focus-cursorrules-prompt-file」のようになります[3]。
ルールファイルは.cursor/rulesディレクトリに直接配置します[3][5]。
これらの命名規則に従うことで、ルールファイルの整理と管理が容易になり、プロジェクト内での一貫性が保たれます。

 mdcファイル内の構成要素
フロントマター（YAML形式）:

description: ルールの簡潔な説明

globs: ルールを適用するファイルパターン

alwaysApply: ルールを常に適用するかどうか


Markdownコンテンツ:
ルールの詳細な説明やコードサンプルを含む。

@contextや@rulesなどのアノテーションを使用して、追加情報を提供します。


メタデータアノテーション:

@context: コンテキスト情報を提供

@rules: ルールや要件のリストを定義

@examples: 実装例を示す

@format: フォーマット仕様を定義する

@options: 利用可能なオプションを記述する

@implementations: 完全な実装の詳細を記述する

@related: 関連するドキュメントやコードを参照する

@best_practices: ベストプラクティスを定義する

@implementation_rules: 実装に関するガイドラインを提供する

@patterns: 一般的なパターンを定義

@mistakes: 一般的な間違いとその修正方法を記述する

@validation: 検証ルールを定義する

(フロントマター)
---
description: Reactコンポーネント作成ガイドライン
globs: src/components/**/*.tsx
alwaysApply: false
---
(**Markdownコンテンツ**)
# Reactコンポーネント開発ルール

(**メタデータアノテーション**)
@context
このルールはReactコンポーネントの開発に適用されます。

## 命名規則
- コンポーネント名はPascalCaseを使用すること
- ファイル名はコンポーネント名と一致させること

## 構造
- 関数コンポーネントを使用すること
- propsの型定義を明示的に行うこと

@rules
- コンポーネントは単一責任の原則に従うこと
- 副作用はuseEffectフック内で管理すること

## コードサンプル
import React, { useEffect, useState } from 'react';
interface UserProfileProps {

userId: string;

}
const UserProfile: React.FC<UserProfileProps> = ({ userId }) => {

const [userData, setUserData] = useState(null);
useEffect(() => {

// ユーザーデータの取得ロジック

}, [userId]);
return (

<div>

{/* コンポーネントの表示ロジック */}

</div>

);

};
export default UserProfile;

 Cursorルールの階層化の例※数字はpriorityで、わかりやすいようにファイルの先頭につけることを想定
※数値は大きい方が優先される

 001-099: コア/ワークスペースルール
説明: これらのルールは、Cursorの基本的な動作やワークスペース全体に適用される設定を定義します。

例えば、プロジェクトの構成、基本的なコードスタイル、エディタの設定などが含まれます。

例:
001: プロジェクトのルートディレクトリを指定するルール
010: デフォルトのコードフォーマット設定を定義するルール


 100-199: 統合ルール
説明: これらのルールは、外部ツールやサービスとの統合を管理します。

例えば、バージョン管理システム（Gitなど）、CI/CDパイプライン、外部ライブラリのインポートなどが含まれます。

例:
100: Gitリポジトリとの連携を設定するルール
150: Jenkins CI/CDパイプラインとの統合を定義するルール


 200-299: パターンルール
説明: これらのルールは、特定のコードパターンや構造に対する処理を定義します。

例えば、特定の関数やクラスの生成、コードのリファクタリングルールなどが含まれます。

例:
200: 特定のクラス構造を自動生成するルール
250: 関数名の命名規則を強制するルール


 フロントマター**（YAML形式）**の詳細
 主要フィールド
 1. description
役割: ルールの目的を人間可読な形式で説明[1][5][9]
例: description: Reactコンポーネントのベストプラクティス

ベストプラクティス:
50文字以内で簡潔に記述
キーワードを先頭に配置（例: "Goコーディング規約"）
日本語/英語の統一


 2. globs
役割: ルール適用対象のファイルパターン指定[2][4][9]
例: globs: src/components/**/*.tsx

設計指針:
階層構造を考慮（例: src/features/**/*.tsx）
拡張子の明示（例: .test.js）
除外パターンの併用（例: !**/legacy/**）


 3. alwaysApply
役割: グローバル適用フラグ[1][7]
例: alwaysApply: false

動作特性:

true: ファイルパス無視で全適用

false: globsパターンに基づく適用


 ルールタイプ別メタデータ設定

タイプ
description
globs
alwaysApply
ユースケース例


Always
任意
*
true
全プロジェクト共通ルール

Auto Attached
空
特定パターン
false
言語固有ルール

Agent Requested
詳細記述
空
false
設計原則

Manual
空
空
false
非推奨パターン


 フロントマターの例---
description: Reactコンポーネント作成ガイドライン
globs: src/components/**/*.tsx
alwaysApply: false
Related_docs: <https://reactjs.org/docs/components-and-props.html>
priority: 80
---

 メタデータ間の相互作用
 1. globsとalwaysApplyの関係
alwaysApply=trueの場合、globs値は無視され全ファイルに適用[1][7]

alwaysApply=falseではglobsパターンが厳密に評価[4][9]

 2. descriptionの影響範囲Agent Requested型ルールでAIの判断材料として活用[1][9]
検索インデックス作成時のキーワード抽出源[5][7]

 3. 複数ルールの競合解決詳細なglobsパターンが優先（例: */controller/*.js > .js）
alwaysApplyが最優先
ファイルパス近接性を考慮[4][9]

 ケース別の応用使用例
 マイクロサービスアーキテクチャ向け設定---
description: 注文サービスAPI規約
globs: services/order/**/*.ts
alwaysApply: false
---
# API設計原則
- RESTful規約厳守
- Swaggerドキュメント必須
- エンドポイントバージョニング（v1/）


 セキュリティポリシー---
description: 認証処理ガイドライン
globs: middleware/auth*.js,utils/security.js
---
# セキュリティ要件
- JWTトークンのHS256アルゴリズム使用
- パスワードハッシュ化（bcrypt）
- レートリミット実装必須

 トラブルシューティング
 ルール未適用時の対応フローメタデータ検証（description/globs入力確認）[5]
ファイルパス再チェック（相対パス/絶対パス）
インデックス再構築（⌘+Shift+P → "Rebuild Index"）
Cursor再起動
ルール優先度の調整[9]

 デバッグ手法---
description: デバッグ用ルール
globs: *
---
# 動作確認
- 適用確認メッセージ表示
- 現在日時: {{CURRENT_DATETIME}}
上記ルールで適用範囲を確認しつつ、コンソールログを監視[5][9]。

 最新動向（Cursor 0.47.5以降）動的変数サポート: {{FILE_PATH}}や{{PROJECT_NAME}}の使用可能[1][7]
パターン継承: @extends: base-rule.mdcによるルール継承[9]
条件付き適用:
When: FILE_SIZE > 100kb
Apply: 最適化警告を発動

 メタデータアノテーションの詳細メタデータアノテーションは、Cursorのルールファイル（.mdc）内で使用され、特定のセクションに追加情報を提供するための機能。
アノテーションは、有効なJSONフォーマットで記述し、関連するセクションの前に配置する。
適切に使用することで、AIがプロジェクト固有の要件やガイドラインを理解し、より正確なコード生成や提案を行うことができる1。

 よく利用するプロパティ@context: プロジェクトやドキュメントのコンテキスト情報を提供する
例:
@context {
  "type": "documentation",
  "purpose": "cursor_rules",
  "format_version": "1.0.0"
}
@rules: ルールやリクワイアメントのリストを定義する
例:
@rules [
  {
    "id": "rule_one",
    "severity": "error",
    "description": "description of rule one"
  }
]
@format: フォーマット仕様を定義する
@options: 利用可能なオプションを記述する
@examples: 実装例を提供する
@implementations: 完全な実装の詳細を記述する
@related: 関連するドキュメントやコードを参照する
@best_practices: ベストプラクティスを定義する
@implementation_rules: 実装に関するガイドラインを提供する
@patterns: 一般的なパターンを定義
@mistakes: 一般的な間違いとその修正方法を記述する
@validation: 検証ルールを定義する

 生成や周辺ツールなど既存のコードやドキュメントからルールを生成するためのツール（例: airul）を使用する
他に、収集しているサイトも有り実例が見える
Generate Cursor Project Rule (.mdc) | Cursor Directory

CursorのProject Rulesの調査メモ

概要

主な定義内容

mdcファイルの命名規則

mdcファイル内の構成要素

Cursorルールの階層化の例

001-099: コア/ワークスペースルール

100-199: 統合ルール

200-299: パターンルール

フロントマター（YAML形式）の詳細

主要フィールド

1. description

2. globs

3. alwaysApply

ルールタイプ別メタデータ設定

フロントマターの例

メタデータ間の相互作用

1. globsとalwaysApplyの関係

2. descriptionの影響範囲

3. 複数ルールの競合解決

ケース別の応用使用例

マイクロサービスアーキテクチャ向け設定

セキュリティポリシー

トラブルシューティング

ルール未適用時の対応フロー

デバッグ手法

最新動向（Cursor 0.47.5以降）

メタデータアノテーションの詳細

よく利用するプロパティ

生成や周辺ツールなど

Discussion

タイプ	description	globs	alwaysApply	ユースケース例
Always	任意	`*`	true	全プロジェクト共通ルール
Auto Attached	空	特定パターン	false	言語固有ルール
Agent Requested	詳細記述	空	false	設計原則
Manual	空	空	false	非推奨パターン