いえらぶGROUP Advent Calendar 2025

rules原文掲載：「rulesのメンテナンスrules」で、Cursor/Claudeドキュメントがめっちゃ整理できた話

Last updated at 2025-12-18Posted at 2025-12-18

気づいたらrulesがまあまあ大変なことに

いえらぶGROUPの和田です。執行役員をやらせていただいております。
Cursor を使った開発が日常になってくると、「.cursor/rules/ の中身が気づいたらけっこうカオス化した」問題に身に覚えはないでしょうか。

俺はあるよ。

最初は数個のルールファイルで済んでいたのに、気づけば命名規則もバラバラ、どのルールがいつ適用されるのか分からない、alwaysApply: true が乱用されてパフォーマンスが悪化…といった状況に陥りがちです。

本記事では、こうした課題を解決するために策定した「.cursor/rules ディレクトリ管理規約」を紹介します。Cursor の公式ドキュメントに準拠しながら、実際の開発現場で使える実践的な規約として設計しました。

CM「Qiitaアドベントカレンダーセルフマラソン中です」

解決したかった課題

この規約を作る前、私のプロジェクトでは以下のような問題を抱えていました：

alwaysApply の乱用: 全てのルールに alwaysApply: true を設定し、不要なコンテキストまで毎回読み込まれる
命名規則の不統一: react-rules.mdc、coding_standard.mdc、best-practices.md など、拡張子や形式がバラバラ
frontmatter 形式の不整合: 二重 frontmatter、必須項目の欠落、記述スタイルの不統一
参照ドキュメントとルールファイルの混在: .cursor/rules/ 配下に実装ルールと技術参照資料が混ざっている
体系性の欠如: ルールファイル全体に規則性がなく、どこに何があるか分からない

結果として、「どのルールがいつ適用されるか分からない」「AI が関係ないルールまで参照して混乱する」といった状況が発生していました。

規約の全体像

この規約は、以下の3つの柱で構成されています：

ディレクトリ構成の分離 - ルール（.mdc）と参照資料（.md）を明確に分ける
体系的な命名規則 - カテゴリ番号 + トピック名でファイルを整理
適切な frontmatter 設計 - ルールタイプに応じた alwaysApply と globs の使い分け

ディレクトリ構成

.cursor/
├── rules/                    # ルールファイル（.mdc）のみ配置
│   ├── 00-core.mdc
│   ├── 10-coding-*.mdc
│   ├── 20-workflow-*.mdc
│   ├── 30-domain-*.mdc
│   └── 90-meta-*.mdc
├── reference/                # 参照用ドキュメント（.md）
│   └── *.md
└── templates/                # テンプレートファイル
    └── *.md

ポイント:

.cursor/rules/ には実行可能なルール（.mdc）のみを配置
技術参照資料や設計ドキュメントは .cursor/reference/ へ分離
テンプレートは .cursor/templates/ で管理

この構造により、「Cursor が参照するルール」と「人間が読む参考資料」が明確に分離され、AI の処理効率も向上します。

命名規則 - 2桁カテゴリ番号体系

ファイル名は以下の形式に統一します：

NN-category-topic.mdc

NN: 2桁のカテゴリ番号（重要度・適用範囲の順序を示す）
category: カテゴリ名（小文字）
topic: トピック名（小文字、ハイフン区切り）

カテゴリ番号の体系

番号範囲	カテゴリ	用途	例
00-09	core	プロジェクト全体の基本ルール	`00-core.mdc`
10-19	coding	言語別コーディング規約	`10-coding-typescript.mdc`
20-29	workflow	開発ワークフロー	`20-workflow-git.mdc`
30-39	domain	ドメイン固有ルール	`30-domain-crm.mdc`
90-99	meta	管理系・メタルール	`90-meta-rules-management.mdc`

実践例:

.cursor/rules/
├── 00-core.mdc                        # 常時適用される基本ルール
├── 10-coding-typescript.mdc           # TypeScript コーディング規約
├── 10-coding-react.mdc                # React コンポーネント設計規約
├── 20-workflow-git.mdc                # Git ワークフロー
├── 20-workflow-testing.mdc            # テスト戦略
├── 30-domain-crm.mdc                  # CRM ドメインルール
└── 90-meta-rules-management.mdc       # ルール管理のメタルール

この番号体系により、ファイル一覧を見るだけで「どのルールが重要で、どの順序で適用されるか」が直感的に理解できます。

frontmatter 形式 - ルールタイプによる使い分け

Cursor のルールファイルには必ず以下の frontmatter を含めます：

---
description: ルールの説明（トリガー + キーワード形式）
globs:
  - "対象ファイルパターン"
alwaysApply: false
---

description の記載形式

「[トリガー条件]時に参照する[内容キーワード]」形式で記述します。

良い例:

description: "TypeScriptファイル編集時に参照するコーディング規約（型安全性、ESLint、命名規則）"

悪い例:

description: "TypeScript のルール"  # トリガーとキーワードが不明瞭

ルールタイプの分類と設定

タイプ	alwaysApply	globs	用途	例
Always	`true`	空	全コンテキストで常時適用	プロジェクト基本方針
Auto Attached	`false`	指定あり	ファイルパターンで自動適用	言語別規約
Agent Requested	`false`	空	AI が必要に応じて参照	トラブルシューティング
Manual	`false`	空	ユーザーが明示的に参照	設計ガイド

重要な設計原則: alwaysApply: true は 00-core.mdc のみに限定する

理由は以下の通りです：

パフォーマンス: 毎回全ルールを読み込むとレスポンスが悪化
コンテキスト汚染: 無関係なルールが AI の判断を混乱させる
保守性: 「常に適用されるルール」が増えすぎると管理不能になる

実践例: TypeScript コーディング規約

---
description: "TypeScriptファイル編集時に参照するコーディング規約（型安全性、ESLint、命名規則）"
globs:
  - "**/*.ts"
  - "**/*.tsx"
alwaysApply: false
---

# TypeScript コーディング規約

## 型安全性の原則
- `any` 型の使用を避け、具体的な型定義を行う
- 型推論に頼りすぎず、公開API には明示的な型注釈を付ける
...

この設定により、TypeScript ファイルを編集する時だけ自動的にこのルールが適用されます。

実践例: トラブルシューティングガイド（Agent Requested）

---
description: "エラー発生時やデバッグ時にAIが参照するトラブルシューティングガイド"
globs: []
alwaysApply: false
---

# トラブルシューティングガイド

## よくあるエラーと解決方法

### TypeScript型エラー
...

この設定により、AI がエラーを検出した時に必要に応じてこのルールを参照します。

チェックリスト - 実装とレビュー時の確認項目

新規ルールファイル作成時、または既存ファイルのレビュー時には以下をチェックします：

新規作成時

ファイル名が NN-category-topic.mdc 形式に従っている
カテゴリ番号が適切な範囲（00-09, 10-19, 20-29, 30-39, 90-99）に分類されている
frontmatter に description、globs、alwaysApply が含まれている
description が「[トリガー条件]時に参照する[内容キーワード]」形式
alwaysApply: true を使用していない（00-core.mdc 以外）
globs パターンが対象ファイルを正しく指定している
参照用ドキュメントは .cursor/reference/ に分離されている
ファイルサイズが 500 行以内（超える場合は分割を検討）

レビュー時

既存のルールファイルと重複していない
同じカテゴリ内での一貫性が保たれている
ルールの内容が実際に適用可能である
AI が理解しやすい構造化された記述になっている

rules原文

以下のrulesを格納しておくことで、
Cursor の AI に対しても、ルールファイルの作成・管理を適切に行うよう指示できます。

以下は .cursor/rules/90-meta-rules-management.mdc に記載するメタルールの例です：

---
description: .cursor/rules配下のファイル追加・修正時に参照するディレクトリ管理規約
globs:
  - ".cursor/rules/**/*"
alwaysApply: false
---

# .cursor/rules ディレクトリ管理規約

## 1. 概要

このドキュメントは `.cursor/rules/` ディレクトリの構成・命名・記述形式に関する規約を定める。
Cursorの公式ドキュメントに準拠し、ルールファイルの一貫性と保守性を確保することを目的とする。

## 2. 背景と課題

本規約は以下の課題を解決するために策定された：

- alwaysApply の乱用による不要なルール適用
- 命名規則の不統一
- frontmatter形式の不整合（二重frontmatter、欠落）
- 参照ドキュメントとルールファイルの混在
- Cursorの公式ドキュメントとの乖離
- rulesファイル全体に規則性がなく、体系的に構成されていなかった

## 3. ディレクトリ構成

.cursor/
├── rules/                    # ルールファイル（.mdc）のみ配置
│   ├── 00-core.mdc
│   ├── 10-coding-*.mdc
│   ├── 20-workflow-*.mdc
│   ├── 30-domain-*.mdc
│   └── 90-meta-*.mdc
├── reference/                # 参照用ドキュメント（.md）
│   └── *.md
└── templates/                # テンプレートファイル
    └── *.md

### 配置ルール

| ファイル種別 | 配置先 | 拡張子 |
|-------------|--------|--------|
| Cursorルール | `.cursor/rules/` | `.mdc` |
| 参照ドキュメント | `.cursor/reference/` | `.md` |
| テンプレート | `.cursor/templates/` | `.md` |

## 4. 命名規則

### 4.1 ファイル名形式

NN-category-topic.mdc

- `NN`: 2桁のカテゴリ番号
- `category`: カテゴリ名（小文字）
- `topic`: トピック名（小文字、ハイフン区切り）

### 4.2 カテゴリ番号体系

| 番号範囲 | カテゴリ | 用途 |
|---------|---------|------|
| 00-09 | core | プロジェクト全体の基本ルール |
| 10-19 | coding | 言語別コーディング規約 |
| 20-29 | workflow | 開発ワークフロー |
| 30-39 | domain | ドメイン固有ルール |
| 90-99 | meta | 管理系・メタルール |

### 4.3 命名例

00-core.mdc              # プロジェクトコアルール
10-coding-php.mdc        # PHPコーディング規約
11-coding-html.mdc       # HTMLコーディング規約
20-workflow-review.mdc   # コードレビューワークフロー
30-domain-batch.mdc      # バッチ処理ドメインルール
90-meta-cursor-rules.mdc # 本ドキュメント

## 5. frontmatter形式

### 5.1 必須項目

すべての `.mdc` ファイルは以下のfrontmatterを含むこと：

---
description: ルールの説明（トリガー + キーワード形式）
globs:
  - "対象ファイルパターン"
alwaysApply: false
---

### 5.2 各項目の説明

| 項目 | 必須 | 説明 |
|------|------|------|
| description | ✅ | 「〜時に参照する〜規約/チェックリスト」形式で記載 |
| globs | ✅ | 対象ファイルパターン（YAML配列形式） |
| alwaysApply | ✅ | 常時適用フラグ（原則 `false`） |

### 5.3 description記載形式

Agent Requested ルールの description は以下の形式で記載：

[トリガー条件]時に参照する[内容キーワード]

例：
- `コードレビュー時に参照するアーキテクチャ・データ設計・品質チェックリスト`
- `PHPユニットテスト作成時に参照するPHPUnit規約・モック戦略`
- `セキュリティレビュー時に参照する入力検証・認可・SQLi・XSS対策チェックリスト`

## 6. ルールタイプ分類

### 6.1 タイプ一覧

| タイプ | alwaysApply | globs | 用途 |
|--------|-------------|-------|------|
| Always | `true` | 空 | 全コンテキストで常時適用 |
| Auto Attached | `false` | 指定あり | ファイルパターンで自動適用 |
| Agent Requested | `false` | 空 | AIが必要に応じて参照 |
| Manual | `false` | 空 | ユーザーが明示的に参照 |

### 6.2 alwaysApply: true の制限

**`alwaysApply: true` は `00-core.mdc` のみに限定する。**

理由：
- 全コンテキストへの適用はトークン消費が大きい
- 不要なルール適用による混乱を防止
- Cursorの公式ベストプラクティスに準拠

## 7. チェックリスト

### 7.1 新規ファイル作成時

- [ ] ファイル名が `NN-category-topic.mdc` 形式か
- [ ] カテゴリ番号が適切か
- [ ] frontmatter 3項目（description, globs, alwaysApply）が含まれているか
- [ ] description が「トリガー + キーワード」形式か
- [ ] alwaysApply が `false` か（00-core.mdc 以外）
- [ ] globs が YAML配列形式か

### 7.2 レビュー時

- [ ] alwaysApply: true が `00-core.mdc` 以外に設定されていないか
- [ ] frontmatter が正しいYAML形式か（二重frontmatter、欠落がないか）
- [ ] 命名規則に従っているか
- [ ] 参照用 .md ファイルが `.cursor/rules/` に混在していないか
- [ ] 500行を超えていないか（超える場合は分割を検討）

## 8. 例外・暫定対応

以下のケースは例外として許可する：

1. **大きなファイル（500行超）**
   - 分割を「推奨」とするが、即時対応は必須としない
   - 次回更新時に分割を検討

2. **既存の参照用 .md ファイル**
   - `.mdc` に変換せず `.cursor/reference/` に移動
   - ルールファイルからは `@.cursor/reference/xxx.md` で参照

## 9. AIエージェント向けガイドライン

`.cursor/rules/` に関する相談やファイル追加依頼を受けた場合：

1. **命名規則を遵守**
   - `NN-category-topic.mdc` 形式を提案
   - 適切なカテゴリ番号を選定

2. **frontmatterを必ず含める**
   - description, globs, alwaysApply の3項目

3. **alwaysApply: true を避ける**
   - globs による Auto Attached を優先提案
   - 00-core.mdc 以外での alwaysApply: true は原則禁止

4. **参照ドキュメントは分離**
   - ルールではない参照用ドキュメントは `.cursor/reference/` を提案

5. **500行超の場合は分割提案**
   - カテゴリごとに分割を検討

## 10. 参照記法

### ルールファイル間の参照

@ruleId

例：`@00-core`、`@13-coding-sql`

### 参照ファイルへの参照

@.cursor/reference/xxx.md

例：`@.cursor/reference/batch-operations.md`

---

**作成日**: 2025-12-18
**対象範囲**: `.cursor/rules/` 配下

このメタルールを配置することで、AI 自身がルールファイルを作成・管理する際も規約に従った運用が可能になります。

運用上のベストプラクティス

1. 定期的なルール棚卸し

月に一度、以下を確認します（しようと思っています）：

使われていないルールファイルの削除
重複しているルールの統合
肥大化したファイルの分割
frontmatter の一貫性チェック

2. チーム共有時の注意点

チーム開発で .cursor/rules/ を共有する際は：

00-core.mdc にプロジェクト共通の基本方針を明記
個人の好みに関するルール（フォーマット設定など）は別ファイル化
.cursorignore を活用して、個人用ルールを除外

3. ルールの優先順位設計

カテゴリ番号の小さいものほど優先度が高いことを意識して設計します：

00-core.mdc           # 最優先（プロジェクト基本方針）
  ↓
10-coding-*.mdc       # 言語別規約
  ↓
20-workflow-*.mdc     # 開発フロー
  ↓
30-domain-*.mdc       # ドメイン固有
  ↓
90-meta-*.mdc         # 管理系（必要時のみ参照）

ご注意

これはあくまでも私の見解に基づく整理整頓なので、これまであっためてきたあなたのプロジェクトの独自整理整頓方法が壊れる可能性があるので、利用する場合は自己責任でお願いします。

まとめ

Cursor の .cursor/rules/ ディレクトリを体系的に管理することで、以下のメリットが得られます：

AI の判断精度向上: 必要なルールだけが適切なタイミングで適用される
パフォーマンス改善: 不要なコンテキスト読み込みが減少
保守性の向上: ルールの追加・修正が容易になる
チーム開発の効率化: ルールの共有と一貫性が保たれる

本記事で紹介した規約は、あくまで一つの設計パターンです。プロジェクトの規模や特性に応じて、カテゴリ番号の体系や frontmatter の項目をカスタマイズしてください。

重要なのは、「ルールファイル自体にも設計思想が必要」という認識を持つことです。AI とのペアプログラミングが当たり前になる時代、ルールファイルの品質が開発効率を大きく左右します。

ぜひ、この規約を参考に、あなたのプロジェクトに最適なルール管理体制を構築してみてください。
この記事が参考になったら、ぜひストックやコメントをお願いします！

参考リンク

Cursor 公式ドキュメント - Rules for AI

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up