CursorにおけるMDCルールのベストプラクティスとトラブルシューティング

Cursor MDC Rules

MDC（Markdown Configuration）ルールは、Cursorがコーディング標準、プロジェクト規約、AIの行動指針を強制する強力な方法です。正しく設定すると、コードの品質と一貫性を劇的に向上させます。このガイドでは、MDCルールの作成、整理、トラブルシューティングのベストプラクティスを解説します。

MDCルールとは何ですか？

MDCルールは、YAMLフロントマターを持つMarkdownファイルで、特定のファイルや特定のコンテキストで作業する際にCursorにどのように振る舞うべきかを指示します。以下が可能です：

コーディング標準の強制
プロジェクトアーキテクチャパターンの定義
ドキュメント要件の指定
特定のファイルタイプに対するAIの行動制御

ファイル形式要件

MDCルールは必ず以下の正確な形式に従う必要があります：

---
description: 'ここにルールの説明を記述'
globs: ['src/**/*.ts', 'tests/**/*.ts']
alwaysApply: false
---

# ルールタイトル

ここにルールの内容を記述...

## 具体的なガイドライン

- ガイドライン 1
- ガイドライン 2

重要な要件

要件	詳細
拡張子	`.mdc` でなければなりません（`.md` ではありません）
フロントマター	`---` 区切り文字の間にYAML形式を使用する必要があります
場所	`.cursor/rules/` ディレクトリ内に配置する必要があります
globs	このルールが適用されるファイルパターンの配列
alwaysApply	ブール値 - ファイルマッチングなしで適用するかどうか

命名規則

番号付きプレフィックスシステムを使用して整理します：

.cursor/rules/
  001-core-coding-standards.mdc
  002-typescript-conventions.mdc
  003-react-patterns.mdc
  100-api-design.mdc
  101-database-models.mdc
  200-testing-requirements.mdc
  201-documentation-rules.mdc

番号システム

範囲	カテゴリ	例
`001-099`	コアルール（すべてのファイルに適用）	コーディング標準、フォーマット
`100-199`	統合ルール（特定のドメイン）	API、データベース、認証
`200-299`	パターン/役割ルール	テスト、ドキュメント
`300-399`	技術固有のルール	React、Vue、Angular

効果的なルールの作成

具体的で実行可能にする

悪い例：

良いコードを書いてください。

良い例：

## エラーハンドリング

すべての非同期関数はtry/catchブロックを使用する必要があります：

```typescript
async function fetchUser(id: string): Promise<User> {
  try {
    const response = await api.get(`/users/${id}`);
    return response.data;
  } catch (error) {
    logger.error(`Failed to fetch user ${id}`, error);
    throw new UserNotFoundError(id);
  }
}

### 例を含める

常に正しい例と間違った例の両方を示してください：

```markdown
## 状態管理

✅ すべき：React Queryをサーバー状態に使用する
```typescript
const { data, isLoading } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId)
});

❌ すべきでない：useEffectをデータ取得に使用する

// このパターンは避ける
useEffect(() => {
  fetchUser(userId).then(setUser);
}, [userId]);

### Globパターンを効果的に使用する

```yaml
# すべてのTypeScriptファイルに適用
globs: ['**/*.ts', '**/*.tsx']

# バックエンドコードのみに適用
globs: ['src/server/**/*.ts', 'src/api/**/*.ts']

# 特定のテストファイルに適用
globs: ['**/*.test.ts', '**/*.spec.ts']

# 特定のファイルを除外
globs: ['src/**/*.ts', '!src/generated/**']

一般的なルールカテゴリ

1. コードスタイルルール

---
description: '一貫したコードスタイルを強制する'
globs: ['src/**/*.ts', 'src/**/*.tsx']
alwaysApply: true
---

# コードスタイル標準

## インポート
- インポートをグループ化：React、外部ライブラリ、内部モジュール、型
- src/ モジュールには絶対インポートを使用する
- 各グループ内でアルファベット順に並べる

## 命名
- コンポーネント：PascalCase（UserProfile）
- フック：camelCase、'use'で始まる（useAuth）
- 定数：UPPER_SNAKE_CASE
- ファイル：kebab-case（user-profile.tsx）

2. アーキテクチャルール

---
description: 'クリーンアーキテクチャパターンを強制する'
globs: ['src/**/*.ts']
alwaysApply: false
---

# アーキテクチャガイドライン

## レイヤー依存関係
- ドメインレイヤー：外部依存なし
- アプリケーションレイヤー：ドメインのみに依存
- インフラストラクチャレイヤー：アプリケーションに依存

## ファイル構成

src/ domain/ # ビジネスロジック、エンティティ application/ # ユースケース、DTO infrastructure/ # DB、API、外部サービス presentation/ # UIコンポーネント

3. テストルール

---
description: 'テスト要件とパターン'
globs: ['**/*.test.ts', '**/*.test.tsx']
alwaysApply: true
---

# テスト標準

## 必須テスト
- すべてのユーティリティ関数のユニットテスト
- すべてのReactコンポーネントのコンポーネントテスト
- APIエンドポイントの統合テスト
- 重要なユーザーフローのE2Eテスト

## テスト構造
AAAパターンに従う：
1. Arrange：テストデータとモックを設定
2. Act：テスト対象の関数を実行
3. Assert：結果を検証

一般的な問題のトラブルシューティング

問題 1：変更が保存されない

症状： .mdcファイルを編集して保存しても、Cursorが変更を適用しません。

解決策：

Cursorを完全に終了する（ウィンドウを閉じるだけでなく、アプリケーションを終了する）
Cursorを再度開く
変更が適用されるはずです

理由： MDCルールはCursor起動時にキャッシュされます。ホットリロードは行われません。

問題 2：ルールが適用されない

症状： ファイル編集時にCursorがルールを無視します。

チェックリスト：

ファイル拡張子が .mdc である（.md ではない）
ファイルが .cursor/rules/ ディレクトリ内にある
フロントマターに有効なYAML構文がある
globs パターンが対象ファイルと一致する
Markdownコンテンツに構文エラーがない

デバッグコマンド：

# Cursorがルールを認識しているか確認
ls -la .cursor/rules/
# ファイル拡張子を確認
file .cursor/rules/*

問題 3：ルールの競合

症状： 複数のルールが矛盾した指示を出します。

解決順序：

より具体的なglobパターンを持つルールが優先される
alwaysApply: true のルールが最初に評価される
アルファベット順で、後のルールが前のルールを上書きする

ベストプラクティス： priority フィールドを使用する（サポートされている場合）：

---
description: '高優先度ルール'
globs: ['src/**/*.ts']
priority: 100
---

問題 4：ルールが長すぎる

症状： Cursorが長いルールのすべての指示に従いません。

解決策： 複数の焦点を絞ったルールに分割する：

.cursor/rules/
  001-general-style.mdc       # 短く一般的なガイドライン
  002-error-handling.mdc      # エラーハンドリング専用
  003-performance.mdc         # パフォーマンス最適化

高度なテクニック

条件付きルール

globsを使用して、コードベースの異なる部分に異なるルールを適用します：

# フロントエンドルール
globs: ['src/components/**/*.tsx', 'src/pages/**/*.tsx']
---
React hooksパターンを使用する。関数コンポーネントを優先する。

# バックエンドルール
globs: ['src/server/**/*.ts', 'src/api/**/*.ts']
---
依存性注入を使用する。SOLID原則に従う。

ルールの継承

ベースルールを作成して拡張する：

---
description: '基本TypeScript標準'
globs: ['**/*.ts', '**/*.tsx']
alwaysApply: true
---

# 基本TypeScriptルール

- 厳格なTypeScript設定を使用する
- 正当な理由なしに `any` 型を使用しない
- オブジェクトの形状には `type` より `interface` を優先する

---
description: 'React固有の拡張'
globs: ['src/**/*.tsx']
alwaysApply: false
---

# Reactルール

基本TypeScriptルールに加えて：
- hooksを使用した関数コンポーネントを使用する
- Propsインターフェースはエクスポートする必要がある
- React.FCは控えめに使用する（明示的なprops型付けを優先）

変数を使用した動的ルール

一部の高度な設定ではテンプレート変数がサポートされています：

---
description: 'プロジェクト固有の規約'
globs: ['**/*.ts']
---

# プロジェクト規約

## APIベースURL
使用：{{API_BASE_URL}}

## 認証
トークンヘッダー：{{AUTH_HEADER_NAME}}

クイックリファレンス：MDCルールテンプレート

---
description: ''
globs: ['']
alwaysApply: false
---

# タイトル

## セクション 1
- ガイドライン 1
- ガイドライン 2

## セクション 2
```typescript
// サンプルコード

参考資料

ドキュメントリンク

## 関連リソース

- [Cursorルールの効果的な使用](using-cursor-rules-effectively.mdx)
- [Cursorルールのベストプラクティス](best-practices-for-cursor-rules.mdx)
- [CursorRulesセットアップガイド](cursorrules-setup-guide.mdx)

MDCルールとは何ですか？​

ファイル形式要件​

重要な要件​

命名規則​

番号システム​

効果的なルールの作成​

具体的で実行可能にする​

一般的なルールカテゴリ​

1. コードスタイルルール​

2. アーキテクチャルール​

3. テストルール​

一般的な問題のトラブルシューティング​

問題 1：変更が保存されない​

問題 2：ルールが適用されない​

問題 3：ルールの競合​

問題 4：ルールが長すぎる​

高度なテクニック​

条件付きルール​

ルールの継承​

変数を使用した動的ルール​

クイックリファレンス：MDCルールテンプレート​

参考資料​