Cursor Rules: 実際に機能する .cursor/rules ファイルの書き方

Cursor Rules: 実際に機能する .cursor/rules ファイルの書き方

どの Cursor ユーザーも同じ壁にぶつかります。AI が生成するコードは技術的には動作しても、プロジェクトの規約を無視したり、間違ったインポートパスを使用したり、古びたパターンを使ったり、コードベースの他の部分とは全く異なる構造のコンポーネントを作成したりします。Cursor Rules は、AI に あなたの プロジェクトがどのように機能するかという永続的なコンテキストを与えることで、これを解決します。

Cursor Rules とは何か、なぜ重要なのか？

Cursor Rules は、すべての AI インタラクション（チャット、オートコンプリート、コード生成など）の前に注入される永久システムプロンプトとして機能する Markdown ファイルです。これらを AI 向けのオンボーディング資料と考えてください。セッションごとに同じミスを修正する代わりに、指示を一度記述すれば、それが定着します。

従来のアプローチは、プロジェクトルートに単一の .cursorrules ファイルを配置することでした。これは依然として動作しますが、非推奨となっています。現在のシステムは、個々の .mdc（Markdown Cursor）ファイルを持つ .cursor/rules/ ディレクトリを使用し、それぞれが特定の状況にスコープされています。すべての指示を1つの巨大なファイルに詰め込むのではなく、関心事項ごとにルールを分割し、Cursor が現在実行している操作に関連するもののみを読み込むため、これははるかに優れた設定です。

AI ツールのためのコンテキストエンジニアリング を扱ったことがあれば、この概念は馴染み深いでしょう。より良い入力コンテキストは、劇的により良い出力を生み出します。ルールは、開発ワークフロー全体のためのコンテキストエンジニアリングなのです。

最初のルールファイルの設定

プロジェクトルートに .cursor/rules/ ディレクトリを作成します。

mkdir -p .cursor/rules

各ルールは、YAML フロントマターの後に Markdown コンテンツが続く .mdc ファイルです。以下はその骨格です。

---
description: "When this rule should apply"
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

Your instructions go here in plain markdown.

3つのフロントマター項目がすべてを制御します。

Cursor 自体を通じてルールを作成することもできます。チャットで /create-rule と入力し、必要なものを説明してください。ただし、手動で記述することで、より多くの制御が可能になります。

4種類のルールタイプ详解

ルールがどのようにアクティブになるかは、そのフロントマター設定に依存します。4つのモードがあり、コンテキストウィンドウの予算 にとって正しいものを選ぶことが重要です。

Always Apply（常に適用）

---
alwaysApply: true
---

すべての単一の AI リクエストに読み込まれます。テクノロジースタックの宣言や、あらゆる場所に適用される重要な規約など、プロジェクト全体の基本事項のために sparingly（慎重に）使用してください。常時オンのルールは、関連性があるかどうかに関わらず、すべてのインタラクションからトークンを消費します。

Auto-Attached（Glob ベースの自動添付）

---
globs: ["src/api/**/*.ts", "src/routes/**/*.ts"]
alwaysApply: false
---

glob パターンに一致するファイルを編集しているときのみアクティブになります。これが主力となるルールタイプです。コンポーネントファイルにいるときは React コンポーネントの規約が読み込まれ、ルートハンドラーにいるときは API パターンが読み込まれ、テストを書いているときはテストルールが読み込まれます。

Agent-Requested（インテリジェント・エージェント要求）

---
description: "Database migration patterns using Drizzle ORM"
alwaysApply: false
---

globs も always-apply もなく、description だけです。Cursor のエージェントは description を読み取り、そのルールが現在のタスクに関連するかどうかを決定します。マイグレーションの作成を依頼すると、このルールを引き出します。ボタンのスタイリングを行っている場合は、それをスキップします。これは、ファイルパスに neatly（綺麗に）マップされないルールにおいて、驚くほどよく機能します。

Manual（手動）

---
---

フロントマター項目が設定されていない（または空のフロントマター）。これらのルールは、チャットで @rule-name と明示的に言及したときにのみアクティブになります。デプロイチェックリストや、たまにしか必要にならないリファクタリングガイドなど、めったに使わないが重要な指示に適しています。

実際に機能する Glob パターン

Globs は、どのファイルが自動添付ルールをトリガーするかを決定します。これを間違えると、ルールがまったく発火しないか、どこでも発火してしまいます。以下は有効なパターンです。

# All TypeScript files in src
globs: ["src/**/*.ts", "src/**/*.tsx"]

# Only component files
globs: ["**/components/**/*.tsx"]

# Python files, excluding tests
globs: ["**/*.py", "!**/test_*.py"]

# Multiple specific directories
globs: ["src/api/**", "src/services/**"]

実際の使用から得られたいくつかの注意点：

• src/* は1ディレクトリレベルのみ一致します。再帰的な一致には、ほぼ常に src/**/* が必要です。
• *.js は .jsx や .ts ファイルに一致しません。拡張子を明示的に指定してください。
• Globs は YAML リストである必要があります。{src,lib}/**/*.ts のような brace 構文はサイレントに失敗することがあるため、別々のリストエントリを使用してください。
• ! プレフィックスはパターンを除外し、生成されたファイルやレガシーコードを無視するのに役立ちます。

実践的なルール例

理論が現実と出会う場所です。これらはプロジェクトに投入してすぐに AI の出力改善を実感できるルールです。

プロジェクト全体のベースルール（Always Apply）

---
alwaysApply: true
---

# Project: Acme Dashboard

## Tech Stack
- Next.js 15 (App Router only — no Pages Router)
- TypeScript strict mode
- Tailwind CSS v4
- Drizzle ORM with PostgreSQL
- pnpm for package management

## Critical Conventions
- All components are React Server Components by default
- Use "use client" only when the component needs interactivity
- Import paths use @/ alias mapped to src/
- Error handling: wrap async operations in try/catch, never use .catch()
- No default exports except for pages and layouts

これを30行以内に収めてください。すべてのリクエストと共に読み込まれるため、すべての単語がトークンコストとなります。

React コンポーネントルール（Auto-Attached）

---
description: "React component patterns and conventions"
globs: ["src/components/**/*.tsx", "src/app/**/*.tsx"]
alwaysApply: false
---

# React Component Rules

## Structure
Every component file follows this order:
1. Imports
2. Type definitions (Props interface)
3. Component function (named export)
4. Sub-components (if any)

## Patterns

Use named exports, not default:
- YES: `export function Button({ label }: ButtonProps)`
- NO: `export default function Button()`

For data fetching in Server Components:
```tsx
// useEffect なしでコンポーネント内で直接フェッチ
export async function UserProfile({ id }: { id: string }) {
  const user = await db.query.users.findFirst({
    where: eq(users.id, id)
  });
  return <div>{user.name}</div>;
}

Anti-Patterns (NEVER do these)

• No useEffect for data fetching in Server Components
• No CSS modules — use Tailwind exclusively
• No barrel exports (index.ts re-exports)
• No prop drilling beyond 2 levels — use context or composition

### Python API ルール（Auto-Attached）

```yaml
---
description: "FastAPI endpoint conventions and patterns"
globs: ["src/api/**/*.py", "src/routes/**/*.py"]
alwaysApply: false
---

# FastAPI Conventions

## Endpoint Structure
- Use APIRouter for route grouping
- Type all request/response models with Pydantic v2
- Dependency injection for database sessions

## Pattern
```python
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession

router = APIRouter(prefix="/users", tags=["users"])

@router.get("/{user_id}", response_model=UserResponse)
async def get_user(
    user_id: int,
    db: AsyncSession = Depends(get_db)
) -> UserResponse:
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return UserResponse.model_validate(user)

Error Handling

• Always use HTTPException, not raw Response objects
• Log errors with structlog before raising
• Return consistent error shapes: {"detail": "message"}

### Go サービスルール（Auto-Attached）

```yaml
---
description: "Go service patterns and error handling"
globs: ["**/*.go", "!**/*_test.go"]
alwaysApply: false
---

# Go Conventions

## Error Handling
- Always handle errors immediately — no _ for error returns
- Wrap errors with fmt.Errorf("context: %w", err)
- Use sentinel errors for expected failure cases

## Project Layout
- cmd/ for entrypoints
- internal/ for private packages
- pkg/ for public libraries

## Pattern
```go
func (s *UserService) GetByID(ctx context.Context, id string) (*User, error) {
    user, err := s.repo.Find(ctx, id)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
        }
        return nil, fmt.Errorf("fetching user %s: %w", id, err)
    }
    return user, nil
}

## トークンコストの管理

ほとんどの Cursor ガイドが省略している点があります。書くすべてのルールがトークンを消費するということです。20の常時オンルールを持つプロジェクトでは、AI がコードを見る前に、指示だけで **リクエストあたり 2,000+ トークン** を燃焼させる可能性があります。

これは重要です。なぜなら、標準モードでの Cursor のチャットコンテキストは約 20,000 トークンだからです。もしルールがその25%を食いつぶせば、実際の質問に対する AI の「思考スペース」の4分の1を失ったことになります。ルールが増えるにつれて、特に長い会話において、出力品質の低下に気づくでしょう。

トークン予算を健全に保つための3つの原則：

**1. 自動添付とエージェント要求ルールを積極的に使用する。** プロジェクトスタックの宣言のみを常時オンにするべきです。その他すべては条件付きで読み込むべきです。その React コンポーネントルールは、SQL マイグレーションを書いているときにはコンテキスト中に存在する必要はありません。

**2. 冗長ではなく、密度高く書く。** 「開発者は公開 API 契約を定義する際、型エイリアスよりも TypeScript インターフェースを使用することを強く推奨します」を「公開 API には `type` より `interface` を優先する」に置き換えます。AI は説得を必要としません、指示を必要としています。

**3. Rule of Three（3回の法則）を適用する。** AI が3回間違えた後にのみ、パターンをルールとして明文化してください。もし Cursor がルールなしで命名規約を正しく処理できているなら、そのルールはスキップしてください。不要なルールはすべて無駄なコンテキストです。

Cursor のチャットパネル下部にあるステータスバーでトークン使用量を監視できます。100% に近づいているのに注意してください。それが刈り込みの信号です。

## 実プロジェクト向けルールの整理

本番環境のプロジェクト通常需要 5〜8 のルールファイルです。うまく機能する構造は以下の通りです。

```text
.cursor/rules/
  base.mdc            # Tech stack, always-apply (< 30 lines)
  components.mdc      # React/Vue patterns, glob to component dirs
  api.mdc             # Backend conventions, glob to API dirs
  database.mdc        # ORM patterns, glob to models/migrations
  testing.mdc         # Test conventions, glob to test files
  deployment.mdc      # CI/CD patterns, manual trigger
  personal.mdc        # Your preferences (gitignored)

personal.mdc を除くすべてをバージョン管理にコミットしてください。そうすることで、チーム全員が同じ AI 動作を得られます。これこそが目的です。ある Cursor フォーラムユーザーが言うように、良いルールとは「出力が最初の試行であなたの規約に一致するため、より多くの提案をそのまま受け入れることができる」ことを意味します。

Cursor と並行して他の AI コーディングツールを使用している場合、概念は直接転送可能です。Claude Code は CLAUDE.md を使用し、GitHub Copilot には指示ファイルがあり、Windsurf には独自の形式がありますが、根底にある原則は同一です。

ルールの優先順位はどう機能するか

複数のルールが同じファイルに適用される場合、Cursor は明確な階層に従います。

チームルールは Team および Enterprise プランで利用可能です。これらは管理者によって Cursor ダッシュボードで設定され、組織全体で強制されます。個々の開発者はこれらをオフにすることはできません。

プロジェクトルール内では、2つのルールが同じファイルに適用され競合する場合、動作は厳密に定義されていません。実際には、後から読み込まれたルールが優先される傾向があります。ファイルに番号を付ける（001-base.mdc、002-components.mdc）ことで、予測可能な順序付けが可能になります。

よくある間違いとその修正方法

多数のコミュニティスレッドを読み、プロジェクト間でルールをテストした後、人々が最もつまづく間違いは以下の通りです。

ルールが曖昧すぎる。 「クリーンなコードを書く」では AI に何も伝わりません。「デフォルトエクスポートではなく名前付きエクスポートを使用する。コンポーネントを次のように構造化する：インポート、型、関数、サブコンポーネント」とすれば、実行可能な指示を与えられます。

すべてを always-apply にする。 最初の直感では、すべてのルールで alwaysApply: true を設定したくなります。それを抑えてください。ルールを四半期ごとに監査し、常時オンルールが2〜3以上ある場合、おそらくトークンを浪費しています。

ルールのテストを忘れる。 ルールを書いた後、関連するファイルを開き、ルールに従うべき何かを Cursor に生成させてください。従わない場合、glob パターンが間違っているか、指示が十分に明確ではありません。

アンチパターンの文書化を怠る。 AI に何をすべきかを伝えるのは仕事的一半です。何を すべきでないか を伝えるのがもう半分です。各ルールに「これらは決して行わないこと」セクションを含め、間違ったアプローチの明確な例を示してください。

UI でのルール保存を無視する。 既知のバグ により、ルールの編集が消えることがあります。変更が消えた場合は、Cursor を完全に閉じ、未保存の変更ポップアップで「Override（上書き）」を選択し、再開してください。

Cursor Rules vs CLAUDE.md vs AGENTS.md

指示ファイルを使用するのは Cursor だけではありません。複数の AI コーディングアシスタント を扱う人のために、フォーマットの比較を以下に示します。

Cursor の利点は粒度の細かさです。CLAUDE.md と AGENTS.md はシンプルで、すべてを常に読み込みます。Cursor は適切なタイミングで適切なルールを読み込むことができ、指示セットが数百行を超えるとこれが重要になります。

これらのツール間でコンテキストが AI 出力をどのように形成するかについて詳しく知りたい場合は、コンテキストエンジニアリングガイド で、使用するエディタに関係なく適用される原則を解説しています。

FAQ

.cursorrules は非推奨ですか？

はい。プロジェクトルートにある単一の .cursorrules ファイルはまだ動作しますが、Cursor は .cursor/rules/*.mdc ファイルへの移行を推奨しています。新しいフォーマットは glob パターン、条件付き読み込み、より良い整理をサポートしています。モノリシックなファイルを焦点を絞ったルールに分割して移行してください。

ファイル拡張子は .mdc と .md のどちらを使うべきですか？

YAML フロントマター（description, globs, alwaysApply）を含むファイルには .mdc を使用してください。プレーンな .md ファイルも rules ディレクトリで動作しますが、条件付き読み込みを可能にするフロントマターメタデータをサポートしません。

プロジェクトにはいくつのルールが必要ですか？

5〜8 がほとんどのプロジェクトにとってのスイートスポットです。1つの常時オンベースルール、ファイルタイプ別にスコープされた3〜4の自動添付ルール、そして特殊タスク用の1〜2の手動ルールです。10以上のルールがある場合、通常は一部を統合または削除できます。

Cursor ルールはオートコンプリートやタブ補完に影響しますか？

ルールはチャットおよびエージェントインタラクションに適用されます。ユーザールールはインライン編集（Cmd/Ctrl+K）には適用され ません 、またルールは一般的に Cursor Tab オートコンプリートの提案に影響しません。これらはチャットおよび Composer セッションで最も効果的です。

複数のプロジェクト間でルールを共有できますか？

はい、Cursor の Remote Rules 機能を通じて可能です。Cursor Settings > Rules, Commands に移動し、「Remote Rule (GitHub)」を選択して、リポジトリ URL を貼り付けます。ソースリポジトリが更新されるとルールは自動同期されます。あるいは、共有ルールリポジトリを維持し、各プロジェクトにシンボリックリンクを張ります。

推奨される最大ルール長は何ですか？

Cursor のドキュメントでは、個別のルールを 500行 以内に保つことを推奨しています。実際には、ルールあたり100行以内を目指してください。短いルールは維持が容易で、トークンコストも低くなります。ルールが150行を超える場合は、2つの焦点を絞ったルールに分割してください。

ルールは Cursor 内のすべての AI モデルで動作しますか？

ルールは Cursor がサポートするすべてのモデル（Claude、GPT-4o、Gemini など）で動作します。ルールは、選択したモデルに関係なく、システムレベルのコンテキストとして注入されます。モデルの動作は異なる場合がありますが、ルール自体はモデルに依存しません。

機能していないルールをデバッグするにはどうすればよいですか？

まず、glob パターンがファイルに一致していることを確認します。ファイルを開き、ルールがコンテキストパネルに表示されるか確認してください。次に、ルールをトリガーすべき直接的な質問でテストしてください。第三に、一時的に alwaysApply: true を設定して、ルールコンテンツ自体が機能することを確認してください。機能する場合、問題は glob パターンにあります。

.cursor/rules を git にコミットすべきですか？

絶対にそうです。プロジェクトルールの要点はチーム全体の整合性です。個人の好みファイルを除く .cursor/rules/ 内のすべてをコミットしてください。全員に適用すべきではない個別設定用に personal.mdc を .gitignore に追加してください。

Cursor ルールを MCP サーバーと併用できますか？

はい、そしてそれらは互いに良く補完し合います。ルールは AI が どのように コードを書くべきかを定義し、一方 MCP サーバー は AI に外部ツールやデータへのアクセスを提供します。ルールは「常に内部 API クライアントを使用する」と指示し、MCP サーバーは開発中に AI が実際にその API をクエリできるようにします。

AI 機能がロードマップにある場合、それは私たちの専門分野です。Techsy の AI 統合チーム は、LLM システムをプロトタイプから本番環境へと導きます。スタックについての第二の意見が必要ですか？無料相談をご利用ください。

ソース

• Cursor Rules Documentation
• Trigger.dev, How to Write Great Cursor Rules
• Cursor Forum, MDC Rules Best Practices and Troubleshooting
• Peakvance, Guide to Cursor Rules: Token Tax
• awesome-cursor-rules-mdc on GitHub