MENU

.cursorrules

Cursor AIガバナンスとコンテキスト工学：プロジェクトルールアーキテクチャ

画像クリックでインフォグラフィックサイトに遷移します。

1. 序論：AI支援開発におけるコンテキスト制御のパラダイムシフト

ソフトウェアエンジニアリングの歴史において、統合開発環境（IDE）の進化は、開発者の認知負荷を低減する一連の試みでした。シンタックスハイライト、コード補完（IntelliSense）、リファクタリングツールといった機能は、開発者が「コードを書く」という行為から「ロジックを設計する」という行為へ注力するための支援を提供してきました。しかし、Cursorに代表されるAIネイティブエディタの登場は、この支援の質を根本的に変えようとしています。これは単なる入力補助ではなく、開発者の意図（Intent）を理解し、自律的にコードを生成・修正する「エージェント」としての役割を担うものです。

このパラダイムシフトにおいて、最も重要な資源となるのが「コンテキスト」です。大規模言語モデル（LLM）は、学習済みデータという膨大な知識を持っていますが、特定のプロジェクトにおける固有の規約、アーキテクチャの決定事項、あるいはチームの暗黙知については何も知りません。これらの情報をいかに効率的かつ正確にAIへ伝達（インジェクション）するかが、AI支援開発の成否を分ける決定的な要因となります。

本レポートでは、Cursorにおけるコンテキスト制御の中核メカニズムである.cursorrulesおよび、その発展形であるプロジェクトルール（.mdcアーキテクチャ）について、技術的な詳細、運用戦略、そしてその背後にあるプロンプトエンジニアリングの理論を徹底的に解説します。15,000語に及ぶこの分析を通じて、単なる設定ファイルの記述方法を超え、AIとの協働におけるガバナンスモデルを確立するための指針を提供します。

1.1 コンテキストウィンドウの経済学

LLMを動かす基盤となるトランスフォーマーアーキテクチャには、一度に処理できる情報量（トークン数）に物理的な上限があります。これを「コンテキストウィンドウ」と呼びます。GPT-4やClaude 3.5 Sonnetなどの最新モデルでは、このウィンドウサイズは拡大傾向にありますが、それでも無限ではありません。また、入力トークン数が増加すればするほど、推論にかかるコスト（金銭的および時間的レイテンシ）は増大し、さらに「Needle in a Haystack（干し草の中の針）」問題、つまり重要な指示が大量の情報のノイズに埋もれて無視されるリスクが高まります1。

したがって、.cursorrulesの本質的な役割は、この有限なコンテキストウィンドウという資源を最適化することにあります。無関係なファイルを読み込ませるのではなく、現在のタスクに真に必要なルールと制約のみを選択的に注入する「動的コンテキスト管理」が求められます。これが、レガシーな単一ファイル形式から、メタデータ駆動型のモダンなルールシステムへと移行している背景にある技術的な動機です3。

1.2 指示型プログラミングから宣言的コンテキストへ

従来、開発者はチャット欄で「Reactのコンポーネントを作って。あ、TypeScriptで書いてね。スタイルはTailwindで」と毎回指示する必要がありました。これは命令的（Imperative）なアプローチです。対して、ルールシステムを用いることで、開発者は「このプロジェクトはNext.js App RouterとTailwind CSSを採用している」という状態を宣言的（Declarative）に定義します。一度定義されれば、AIはその制約をシステムレベルのインストラクションとして受動的に受け入れ、開発者が意識せずとも自動的に従うようになります4。

このシフトは、開発者のメンタルモデルにも変化を要求します。プロンプトを毎回工夫する「プロンプトエンジニアリング」から、プロジェクト全体のルールセットを設計・維持する「コンテキストエンジニアリング」へのスキル転換が必要とされているのです。

2. Cursorルールシステムのアーキテクチャと優先順位

CursorがAIモデルにリクエストを送信する際、そのプロンプトは単一のテキストではなく、複数の情報源から合成された複雑な構造体となります。開発者が意図した通りにAIを制御するためには、これらの情報源がどのような順序で評価され、競合が発生した場合にどのルールが優先されるかという「解決ロジック」を正確に理解する必要があります。

2.1 ルールの階層構造と適用スコープ

Cursorにおける指示の優先順位は、影響範囲の広さと具体性のバランスによって決定されます。一般的に、より具体的かつ局所的なスコープを持つルールが、広範で一般的なルールよりも優先される傾向があります。以下に、その階層構造を詳細に分析します6。

2.1.1 ハードコードされたシステムプロンプト (System Prompt)

最下層（あるいは最上流）には、Cursorの開発チームが定義した不可視のシステムプロンプトが存在します。これには、AIとしての基本的な振る舞い、安全性に関するガードレール、ユーザーに危害を加えるコードの生成禁止、そしてMarkdown形式での出力強制などが含まれています。ユーザーはこの層を直接編集することはできませんが、上位のルールによってその振る舞いをある程度「上書き」あるいは「誘導」することは可能です。

2.1.2 ユーザールール (User Rules / Global Rules)

Cursorの設定画面（Settings > General > Rules for AI）で定義されるグローバルなルールです。これは特定のプロジェクトに依存せず、そのユーザーが使用するすべてのワークスペースに適用されます。

  • 役割: 個人のコーディングスタイルの好み（例：「中括弧は改行せずに記述する」「常に日本語で回答する」）や、エディタとの対話におけるトーン＆マナーを定義します。
  • 適用メカニズム: すべてのチャットセッションやComposerの起動時に、システムプロンプトの直後に連結されて送信されます6。

2.1.3 プロジェクトルール (Project Rules / Repository Rules)

リポジトリ単位で設定されるルールであり、本レポートの主題です。これには、レガシーな.cursorrulesファイルと、モダンな.cursor/rules/*.mdcファイル群が含まれます。

  • 役割: プロジェクト固有の技術スタック、アーキテクチャパターン、ディレクトリ構造、命名規則などを定義します。チーム開発においては、この層が「唯一の正解（Single Source of Truth）」として機能し、メンバー間でのコード品質のバラつきを抑制します10。
  • 優先順位: 一般に、ユーザールールよりもプロジェクトルールが優先されます。これは「個人の好みよりもプロジェクトの規約が優先される」というソフトウェア開発の一般的な原則に合致します。

2.1.4 セッションコンテキスト (Session Context)

ユーザーがチャット欄やComposerに直接入力したプロンプトです。

  • 役割: その瞬間の具体的なタスク指示。
  • 優先順位: 最も高い優先度を持ちます。例えば、プロジェクトルールで「常にTypeScriptを使用せよ」と定義されていても、ユーザーが「このファイルだけはJavaScriptで書いて」と指示すれば、AIはその指示に従う（従うべき）設計になっています。

2.2 コンテキスト競合の解決アルゴリズム

複数のルール層で矛盾する指示が存在する場合、LLMはどのように振る舞うのでしょうか。これは厳密なアルゴリズムというよりも、LLMの注意機構（Attention Mechanism）の特性に依存します。

通常、プロンプトの「後方」にある情報ほど、AIの出力に強い影響を与える「リーセンシー効果（Recency Bias）」が働きます。Cursorはプロンプトを構築する際、システムプロンプト → ユーザールール → プロジェクトルール → 直近の会話履歴、という順序で情報を連結していると推測されます。したがって、プロジェクトルールはユーザールールを効果的に上書きできます。

しかし、ルール記述があまりに曖昧であったり、相反する指示が同じレベル（例：複数の.mdcファイル間）で存在したりする場合、AIは混乱し、どちらか一方をランダムに選択するか、あるいは両方を無視して一般的な学習データに基づいた回答をする可能性があります。これを防ぐためには、ルール記述において「曖昧さを排除する」ことが何よりも重要です。

表1: ルール階層と優先順位の要約

階層定義場所スコープ優先度主な用途
Sessionチャット入力欄その場限り最高特定タスクの指示、例外的な上書き
Project.cursor/rules/, .cursorrulesリポジトリ高アーキテクチャ、技術スタック、命名規則
UserCursor Settings全環境中個人の好み、言語設定、回答スタイル
System内部 (不可視)アプリ全体低 (基盤)安全性、基本機能の定義

3. レガシー形式：.cursorrules ファイルの構造と限界

Cursorの初期バージョンからサポートされている.cursorrulesは、シンプルながらも強力なコンテキスト注入手段として広く普及しました。現在、より高度な.mdc形式への移行が推奨されていますが、後方互換性のために依然として多くのプロジェクトで利用されており、小規模なプロジェクトではその簡便さがメリットとなる場合もあります。

3.1 基本仕様と動作原理

.cursorrulesは、プロジェクトのルートディレクトリ（通常は.gitフォルダと同じ階層、あるいはpackage.jsonが存在する階層）に配置される単一のファイルです。特別な拡張子は持たず、内容はプレーンテキストまたはMarkdown形式で記述されます4。

Cursorのエージェント（ChatやComposer）は、新しいセッションを開始するたびにこのファイルの内容を読み込み、プロンプトの「システム指示」セクションに全文を挿入します。これにより、AIはあたかも最初からそのプロジェクトの専門家であるかのように振る舞うことが可能になります。

3.2 記述内容のベストプラクティス

.cursorrulesの効果を最大化するためには、以下の要素を含めることが推奨されています12。

  1. プロジェクトの概要 (High-Level Context):
  • 「このプロジェクトは、Next.jsを使用したEコマースプラットフォームであり、パフォーマンスとSEOを最優先する」といった全体像。
  1. 技術スタックの明示 (Tech Stack):
  • 使用しているフレームワーク、ライブラリ、データベース、およびそれらのバージョン。
  • 例：「React 18, TypeScript 5.0, Tailwind CSS 3.0を使用。状態管理にはZustandを採用」
  1. コーディングスタイル (Style Guidelines):
  • 「関数型コンポーネントを使用」「クラスコンポーネントは禁止」「変数はキャメルケース」といった具体的な制約。
  1. ディレクトリ構造 (Directory Structure):
  • 主要なディレクトリの役割説明。「src/components/uiは汎用UIパーツ、src/featuresはドメインロジックを含む」など。

3.3 単一ファイル運用の限界と「認知的過負荷」

プロジェクト規模が拡大するにつれ、単一の.cursorrulesファイルには以下のような深刻な問題が生じます。

3.3.1 コンテキストウィンドウの浪費

.cursorrulesの内容は、関連性の有無にかかわらず「常に（Always）」読み込まれます。例えば、CSSの微修正を行いたいだけの場面で、バックエンドのデータベーススキーマ定義やAPIの認証ロジックに関する長大なルールをAIに読ませることは、貴重なコンテキストウィンドウの無駄遣いです1。これは、本当に必要な直近の会話履歴がコンテキストから押し出される（切り捨てられる）原因となります。

3.3.2 ノイズによる精度の低下

情報量が多すぎることは、AIにとってノイズとなります。無関係なルールが大量に含まれていると、AIの注意力が散漫になり、重要な指示を見落とす確率（幻覚の発生率）が上昇します。これを「コンテキスト汚染」と呼ぶこともあります。

3.3.3 メンテナンスの破綻

数千行に及ぶ巨大なMarkdownファイルは、人間にとってもメンテナンスが困難です。どのルールが現在も有効なのか、矛盾する記述がないかを確認するコストが増大し、結果としてルールが形骸化するリスクがあります。

これらの課題を解決するために導入されたのが、次章で解説する「プロジェクトルール（.mdc）」という新しいアーキテクチャです。

4. モダンアーキテクチャ：.cursor/rules と .mdc プロトコル

Cursorバージョン0.45以降で導入されたプロジェクトルール機能は、従来のモノリシックなファイルを分割し、メタデータを用いて制御する高度なシステムです。これは、ファイルシステムベースのルーティングに似た概念をAIのコンテキスト管理に持ち込んだものと言えます6。

4.1 ディレクトリ構造とファイル形式

新しいルールシステムでは、プロジェクトルートに.cursor/rules/というディレクトリを作成し、その中に複数の.mdcファイルを配置します。.mdcという拡張子は、一見すると独自のバイナリ形式のように見えますが、実態はFrontmatter（YAML形式のメタデータブロック）を含むMarkdownファイルです15。

description: このルールの説明（AIが適用判断に使用） globs: [“src//*.ts”, “/*.test.ts”] alwaysApply: false

ルールのタイトル

ここに具体的な指示や規約をMarkdownで記述します。

この構造により、各ルールファイルは「自分自身がいつ適用されるべきか」という自己記述的な情報を持つことになります。

4.2 Frontmatterによる動的コンテキスト制御

.mdcファイルの核心は、ファイルの先頭に記述されるFrontmatterブロックにあります。ここで定義される3つのキー（description, globs, alwaysApply）の組み合わせによって、Cursorのルールエンジンはそのルールをコンテキストに含めるかどうかを動的に判断します3。

4.2.1 常時適用 (Always Apply)

  • 設定: alwaysApply: true
  • 挙動: globsやdescriptionの内容に関わらず、すべてのチャットおよびComposerセッションにおいて常に読み込まれます。
  • 用途: プロジェクトの絶対的な原則（「TypeScriptを使用する」「セキュリティ第一」）や、全体に共通するアーキテクチャの定義に使用します。ただし、トークン消費を抑えるため、このタイプのルールは必要最小限（Core Rules）に留めるべきです。

4.2.2 自動添付 (Auto-Attached via Globs)

  • 設定: alwaysApply: false, globs: [“pattern”]
  • 挙動: ユーザーが現在編集しているファイル、またはチャットのコンテキストに追加されたファイルが、指定されたGlobパターンに一致する場合にのみ自動的に読み込まれます。
  • 用途: 特定の言語やモジュールに関するルール。
  • 例：globs: [“**/*.test.ts”] → テストファイルを触っている時だけ、テストライブラリ（Jest/Vitest）の規約を読み込む。
  • 例：globs: [“src/components/**/*.tsx”] → UIコンポーネントを編集する時だけ、Tailwind CSSやShadcn UIのルールを読み込む。
  • 技術的利点: これにより、バックエンドの作業中にフロントエンドのルールが混入することを防ぎ、コンテキストの純度を保つことができます。

4.2.3 エージェント判断 (Agent-Requested)

  • 設定: alwaysApply: false, globs:, description: “詳細な説明”
  • 挙動: これが最も先進的な機能です。Cursorのエージェントは、ユーザーのプロンプト（質問）を受け取った際、まず利用可能なすべてのルールのdescription（説明文）のみをスキャンします。そして、「この質問に回答するためには、このルールが必要だ」と判断した場合にのみ、そのルールの本文を読み込みます19。
  • 用途: 特定の複雑なタスクや、稀にしか発生しないワークフロー。
  • 例：description: “データベースのマイグレーションを行う際の手順と命名規則” → ユーザーが「マイグレーションファイルを作って」と言った時だけ読み込まれる。
  • RAG的な挙動: この仕組みは、実質的にエディタ内でのRetrieval-Augmented Generation（検索拡張生成）を実現しており、数千ものルールが存在してもトークンを消費せずに運用することを可能にします。

4.2.4 手動適用 (Manual)

  • 設定: alwaysApply: false, globs:, description: “”
  • 挙動: 自動的には一切読み込まれません。ユーザーがチャット内で@ルール名とタイプして明示的に指定した場合にのみ適用されます。
  • 用途: 極めて特殊的、あるいは破壊的な変更を伴う操作（例：大規模リファクタリングの手順書）など、意図しない適用を防ぎたい場合に使用します。

4.3 Globパターンの構文と仕様詳細

globsキーにおけるパターンマッチングは、標準的な.gitignoreやシェルのグロブ構文に準拠していますが、いくつかの注意点があります3。

  • サポートされる記法:
  • *: パス区切り文字を含まない任意の文字列（単一階層）。
  • **: パス区切り文字を含む任意の文字列（再帰的ディレクトリ）。
  • {a,b}: 集合（aまたはb）。例：src/**/*.{ts,tsx}
  • データ構造:
  • 配列形式: globs: [“src/**/*.ts”, “test/**/*.ts”] （推奨：パースエラーが起きにくい）
  • カンマ区切り文字列: globs: src/**/*.ts, test/**/*.ts （許容されているが、スペースの扱いやエスケープで問題が起きやすい）

コミュニティの検証によると、否定パターン（!で始まる除外設定）の動作は不安定であるという報告があります。したがって、基本的には「適用したいファイル」をポジティブに指定するアプローチが安全です。

4.4 MDCエディタのバグと運用上の回避策

Cursorには、.mdcファイルを編集するための専用GUI（MDC Editor）が搭載されていますが、現時点ではこのエディタに重大なバグ（保存されない、メタデータが消える、チャットからの編集が反映されない等）が報告されています22。

推奨される回避策:

  1. .mdcファイルを編集する際は、Cursor上でファイルを右クリックし、「Open With…」から通常のテキストエディタを選択する。あるいはVS Code設定で”workbench.editorAssociations”: { “*.mdc”: “default” }を追加し、常にテキストとして開くようにする23。
  2. 外部エディタ（Vimや別のVS Codeインスタンス）で編集する。

表2: レガシー形式とモダン形式の比較

特徴レガシー形式 (.cursorrules)モダン形式 (.cursor/rules/*.mdc)
ファイル構成単一ファイル（モノリシック）複数ファイル（モジュラー）
コンテキスト制御静的（常にすべて読み込み）動的（状況に応じて選択的読み込み）
トークン効率低い（無駄が多い）高い（最適化されている）
競合管理困難（一つのファイル内で整理が必要）容易（ファイル単位で分離可能）
スケーラビリティ小規模プロジェクト向き大規模・チーム開発向き

5. プロンプトエンジニアリングによる静的解析と制御

ルールファイルという「器」を用意しただけでは不十分です。その中に記述される「中身（指示）」が、AIモデルの特性を理解した上で最適化されていなければ、期待通りのコードは生成されません。ここでは、AIを効果的に制御するためのプロンプトエンジニアリング技法を、ルール記述に応用する方法を解説します。

5.1 「Anti-Lazy」プロンプト：AIのサボり癖との戦い

GPT-4やClaude 3.5といった高度なモデルは、推論コストを削減し、応答速度を上げるために、意図的に出力を省略する傾向があります。「既存のコードはそのまま…（//… existing code）」といったプレースホルダーでお茶を濁す現象です。これを防ぐために、コミュニティでは「Anti-Lazy」と呼ばれる強力なプロンプトパターンが開発されました24。

効果的な記述例:

Output Constraints

You are an expert engineer.

  • You DO NOT use placeholders.
  • You DO NOT use “//… existing code” or similar comments.
  • You output the FULL content of every file, every time.
  • You do not be lazy.
  • If a file is too long, say so and ask to proceed explicitly.
  • NEVER truncate or abbreviate code sections.

このプロンプトが機能する理由は、LLMに対して「省略する」という選択肢が禁止事項（Negative Constraint）であることを強く認識させ、出力生成時の確率分布において「省略トークン」の選択確率を極限まで下げる効果があるためです。特にComposer機能を使用する場合、ファイル全体を書き換えることが前提となるため、この指示は必須と言えます。

5.2 Chain of Thought (思考の連鎖) の強制

複雑なリファクタリングや機能追加を依頼した際、AIがいきなりコードを書き始めて失敗することがあります。これを防ぐために、コード生成の前に「思考プロセス」を出力させるようルールで強制します12。

記述例:

Before writing any code, you must:

  1. Analyze the existing file structure and dependencies.
  2. List the necessary changes step-by-step in natural language.
  3. Identify potential side effects or breaking changes.
  4. Only after this analysis, proceed to generate the code.

このプロセスを経ることで、AIは自身の論理的整合性を確認する機会を得ます（Self-Correction）。ルールシステムを通じてこれを自動化することで、すべての変更に対して「設計レビュー」のフェーズを強制的に挟むことが可能になります。

5.3 Role-Playing（役割付与）による専門性の向上

AIに対して、単なる「アシスタント」ではなく、特定の技術領域の「エキスパート」としてのペルソナを与えることで、回答の質が向上することが知られています28。

記述例:

“You are an expert in TypeScript, Node.js, Next.js App Router, React, Shadcn UI, Radix UI, and Tailwind. You prioritize functional programming patterns and avoid classes.”

このように技術スタックを具体的に列挙し、役割を定義することで、AIはその領域に関連する学習データ（ベストプラクティス、一般的なアンチパターン）へのアクセス重みを高め、より適切で専門的なコードを生成するようになります。

5.4 XMLタグを用いた構造化データ

.mdcファイル内でXMLタグを使用することは必須ではありませんが、AIにとって情報の境界を明確にする上で非常に有効です30。

XML

<coding_style>
  <rule>Always use const for variables unless reassignment is needed.</rule>
  <rule>Prefer arrow functions over function expressions.</rule>
</coding_style>

<examples>
  <example type=”correct”>
    const handleClick = () => {… }
  </example>
  <example type=”incorrect”>
    function handleClick() {… }
  </example>
</examples>

このように構造化することで、AIは「どこからどこまでが例示なのか」「何がルールなのか」を正確にパースでき、ルールの適用ミスを減らすことができます。

6. 実践的ケーススタディ：フレームワーク別ルールアーキテクチャ

ここでは、主要な技術スタックごとに、どのようなルールを設定すべきか、その具体的な構成と理由を深掘りします。これらは実際のプロジェクト（”awesome-cursorrules”リポジトリ等）で採用されているベストプラクティスに基づいています。

6.1 Next.js (App Router) プロジェクトのルール戦略

Next.jsのApp Routerは、Server ComponentsとClient Componentsの厳格な分離を求めます。AIはこの新しいパラダイムを完全には理解していない場合が多く、古いPages Routerの知識と混同しがちです。

推奨されるルール構成:

  1. RSC (React Server Components) の強制:
  • 「デフォルトではすべてのコンポーネントをServer Componentとして扱うこと」
  • 「’use client’ディレクティブは、useStateやuseEffectが必要なリーフコンポーネントにのみ記述すること」
  • このルールにより、パフォーマンス低下の原因となる不要なクライアントバンドル化を防ぎます29。
  1. データフェッチの規約:
  • 「データ取得はServer Component内での直接的なasync/awaitで行うこと」
  • 「クライアント側でのuseEffectによるフェッチを禁止する」
  1. スタイリングとUI:
  • 「Shadcn UIコンポーネントを使用し、スタイリングにはTailwind CSSのみを使用すること（CSS Modulesやstyleタグの禁止）」
  • 「クラス名はclsxまたはcnユーティリティで結合すること」

6.2 Python (FastAPI) プロジェクトのルール戦略

動的型付け言語であるPythonにおいて、AIに堅牢なコードを書かせるためには、型ヒントとPydanticモデルの強制が不可欠です。

推奨されるルール構成:

  1. 厳格な型定義:
  • 「すべての関数引数と戻り値に型ヒント（Type Hints）を付与すること」
  • 「データバリデーションにはPydantic v2モデルを使用し、生の辞書（Dict）の受け渡しを禁止する（ROROパターン）」33。
  1. 非同期処理の徹底:
  • 「DBアクセスや外部API呼び出しを含む関数は必ずasync defで定義すること」
  • 「ブロッキングIO操作を避けること」
  1. ディレクトリ構造の遵守:
  • 「ルーター（routers）、スキーマ（schemas）、CRUD操作（crud）を別々のディレクトリに分離する構成を維持すること」
  • この指示がないと、AIは一つのファイル（main.py）にすべてのロジックを詰め込もうとする傾向があります。

6.3 Flutter (Mobile) プロジェクトのルール戦略

Flutterはネストが深くなりやすく、コードの可読性が低下しやすいフレームワークです。

推奨されるルール構成:

  1. ウィジェットの分割:
  • 「buildメソッドが長くなりすぎる場合、サブウィジェットを別のファイルまたはプライベートウィジェットとして切り出すこと」
  • 「ヘルパーメソッドではなく、ウィジェットクラスとして切り出すこと（パフォーマンス最適化のため）」35。
  1. 状態管理の統一:
  • 「状態管理にはRiverpodを使用すること（GetXやProviderの混在を禁止）」
  • 「ビジネスロジックはUIから分離し、Notifierクラスに記述すること」
  1. 定数の利用:
  • 「不変なウィジェットには必ずconstコンストラクタを使用すること」

7. エコシステムとコミュニティ主導の標準化

Cursorのルール機能は、個々の開発者の設定にとどまらず、一つのエコシステムを形成しつつあります。cursor.directoryやGitHub上のawesome-cursorrulesリポジトリには、数千ものルールファイルが共有されています37。

7.1 共有ルールの活用とリスク

コミュニティで共有されているルールは、各フレームワークのベストプラクティスが凝縮されており、ゼロからルールを書く手間を省くことができます。しかし、これらを無批判に導入することにはリスクも伴います。

  • コンテキストの不一致: 他人のプロジェクト構造を前提としたGlobパターンが、自分のプロジェクトに適合しない可能性があります。
  • プロンプトインジェクションのリスク: 悪意のある第三者が作成したルールファイルに、AIのガードレールを無効化したり、秘密情報を外部へ送信させようとする指示（プロンプトインジェクション）が含まれている可能性もゼロではありません（現状では理論的なリスクですが、注意が必要です）。

7.2 セキュリティと秘密情報の管理

ルールファイル内でAPIキーやパスワードなどの秘密情報をハードコードすることは厳禁です。.cursorrulesはGitリポジトリに含まれるため、これらは即座に漏洩します。また、AIに対して「.envファイルの中身を読み取ってコードに埋め込むこと」を禁止するルールを明記することも重要です40。

セキュリティルールの例:

SECURITY CRITICAL:

  • NEVER output secrets, API keys, or passwords in plain text.
  • Always use environment variables (process.env, etc.).
  • Do not read or display the contents of.env files.

8. トラブルシューティング：AIがルールを無視する理由

「ルールを設定したのに、Cursorがそれを無視する」という不満は、フォーラムで最も頻繁に見られるトピックの一つです。この現象には明確な技術的理由があります2。

8.1 コンテキストウィンドウのオーバーフロー

最も一般的な原因は、読み込ませている情報の総量が多すぎることです。チャット履歴が長くなったり、大量のファイルを開いたりしている状態で、さらに巨大なルールファイルを読み込ませると、LLMは古い情報（ルールの指示）を切り捨ててしまいます。これを防ぐために、.mdcファイルによるルールの分割と、不要なルールの読み込み回避（alwaysApply: falseの活用）が必須となります。

8.2 ComposerとChatのコンテキスト乖離

CursorのComposer機能（Cmd+I / Ctrl+I）は、通常のチャット（Cmd+L / Ctrl+L）とは異なるコンテキスト管理を行っている可能性があります。Composerは複数のファイルを同時に書き換えることに特化しているため、独自のシステムプロンプトが強く作用し、ユーザー定義ルールの優先度が相対的に下がることが観察されています43。

対策: Composerで作業を開始する際、明示的に「ルールに従って（Refer to project rules）」と一言添えるか、重要なルールファイルをComposerのコンテキストに手動で追加することで改善する場合があります。

8.3 モデルの特性（Steerability）

使用するモデルによっても、ルールへの従順度は異なります。一般に、OpenAIのo1やgpt-4o、Anthropicのclaude-3-5-sonnetは指示に従う能力が高いですが、軽量モデル（gpt-4o-miniなど）は複雑なルールを無視する傾向があります。重要なタスクには必ず高性能なモデルを使用すべきです。

9. 結論と将来展望：自律的エージェントへの道

Cursorのルールシステムは、単なるコードスニペットの共有機能ではありません。これは、AIエージェントに対してプロジェクトの「憲法」や「法律」を制定するガバナンスの仕組みです。

9.1 エージェントスキルと外部ツール連携

最新のCursorでは、AGENTS.mdやAgent Skillsといった機能を通じて、ルールシステムがさらに拡張されようとしています6。これにより、AIは単にコードを書くだけでなく、外部ツールのドキュメントを参照したり、リポジトリ内のスクリプトを実行して検証を行ったりする能力を獲得しつつあります。ルールファイルは、これらの能力をいつ、どのように行使すべきかを定義する「トリガー」としての役割も担うことになるでしょう。

9.2 チーム開発の標準装備へ

.cursor/rulesをGitで管理し、CI/CDパイプラインのように「AIの振る舞い」をバージョン管理することは、今後のチーム開発における標準的なプラクティスとなるはずです。新しくチームに入ったメンバーは、ドキュメントを読むよりも先に、Cursorを開くだけで、AIを通じてチームの規約に沿ったコーディングを強制的に（しかし自然に）サポートされるようになります。

私たちは今、コードを書くこと以上に、AIにどのようにコードを書かせるかを設計する「メタエンジニアリング」の時代に足を踏み入れています。本レポートで解説した技術的詳細とアーキテクチャの理解は、その時代を生き抜くための強力な武器となるでしょう。

表3: トラブルシューティングガイド

現象推定原因推奨される対策
ルールが全く反映されないファイル名/場所の間違い.cursor/rules/ 内に .mdc 拡張子で配置されているか確認。.cursorrulesはルートにあるか確認。
一部のルールだけ無視されるプロンプトの競合・曖昧さルール内の指示が矛盾していないか確認。「DO NOT」等の強い言葉で書き直す。
チャットでは効くがComposerで無視されるコンテキスト管理の仕様差Composer開始時に明示的にルールを参照するよう指示するか、重要なルールをalwaysApply: trueにする。
コードが省略される（…existing code）モデルのLazy特性「Anti-Lazy」プロンプト（全文出力の強制）をルールの冒頭に追加する。
MDCエディタで保存できないエディタのUIバグVS Code設定で.mdcをテキストエディタとして開くよう変更し、直接編集する。

免責事項: 本レポートの情報は、2025年現在利用可能な公開情報およびコミュニティの検証結果に基づいています。Cursorの仕様は頻繁に更新されるため、最新の公式ドキュメントを常に参照することを推奨します。

引用文献

  1. Anyone else finding the the new *.mdc .cursor/rules files SUPER effective? : r/cursor – Reddit https://www.reddit.com/r/cursor/comments/1idg434/anyone_else_finding_the_the_new_mdc_cursorrules/
  2. Why does Cursor ignore rules? – Bug Reports https://forum.cursor.com/t/why-does-cursor-ignore-rules/137219
  3. Complete Guide: How to Set AI Coding Rules for Cursor – DEV Community https://dev.to/yigit-konur/complete-guide-how-to-set-ai-coding-rules-for-cursor-ff2
  4. 12月 22, 2025にアクセス、 https://trigger.dev/blog/cursor-rules#:~:text=A%20Cursor%20Rules%20file%20is,your%20specific%20project%20or%20framework.
  5. The Power of Cursor Rules: Enforce Naming, Style & Best Practices https://www.youtube.com/shorts/IHlmqCNkiBs
  6. Rules | Cursor Docs https://cursor.com/docs/context/rules
  7. Rules Hierarchy in Cursor – Discussions https://forum.cursor.com/t/rules-hierarchy-in-cursor/108589
  8. Best practices when using Cursor the AI editor. – GitHub https://github.com/digitalchild/cursor-best-practices
  9. Mastering Cursor Rules: A Developer’s Guide to Smart AI Integration – DEV Community https://dev.to/dpaluy/mastering-cursor-rules-a-developers-guide-to-smart-ai-integration-1k65
  10. Definitive Rules – Discussions – Cursor – Community Forum https://forum.cursor.com/t/definitive-rules/45282
  11. What is .cursorrule and How to Use It Effectively | by Ashley | Towards AGI – Medium https://medium.com/towards-agi/what-are-cursor-rules-and-how-to-use-them-ec558468d139
  12. How to write great Cursor Rules – Trigger.dev https://trigger.dev/blog/cursor-rules
  13. PatrickJS/awesome-cursorrules – GitHub https://github.com/PatrickJS/awesome-cursorrules/blob/main/.cursorrules
  14. A Deep Dive into Cursor Rules (> 0.45) – Discussions https://forum.cursor.com/t/a-deep-dive-into-cursor-rules-0-45/60721
  15. What’s the difference between .cursorrules and .cursor/rules/* in v0.45? : r/cursor – Reddit https://www.reddit.com/r/cursor/comments/1ia1665/whats_the_difference_between_cursorrules_and/
  16. MDC file to help generate MDC files – GitHub Gist https://gist.github.com/patelnav/125ad1ac0c1b53243fefaf3ed53c1195
  17. What is a .mdc file? – Discussions – Cursor – Community Forum https://forum.cursor.com/t/what-is-a-mdc-file/50417
  18. Correct way to specify rule type? – How To – Cursor – Community Forum https://forum.cursor.com/t/correct-way-to-specify-rule-type/100672
  19. Cursor Rules Developer Guide — NVIDIA NeMo Agent Toolkit (1.2) https://docs.nvidia.com/nemo/agent-toolkit/1.2/extend/cursor-rules-developer-guide.html
  20. Allow escaping comma in cursor rules glob patterns https://forum.cursor.com/t/allow-escaping-comma-in-cursor-rules-glob-patterns/76648
  21. Correct way to specify rules globs? – Discussions – Cursor – Community Forum https://forum.cursor.com/t/correct-way-to-specify-rules-globs/71752
  22. Bug? How to make Chat/Composer edit a cursor rule? MDC Editor gotchas https://forum.cursor.com/t/bug-how-to-make-chat-composer-edit-a-cursor-rule-mdc-editor-gotchas/53208
  23. Cursor Rules: Why Your AI Agent Is Ignoring You (and How to Fix It) – Michael Epelboim https://sdrmike.medium.com/cursor-rules-why-your-ai-agent-is-ignoring-you-and-how-to-fix-it-5b4d2ac0b1b0
  24. Cursor AI IDE tips, tricks & best practices – Keyboard shortcuts, Composer mode, .cursorrules examples, and Reddit community wisdom – GitHub https://github.com/murataslan1/cursor-ai-tips
  25. cursor-ai-tips/tips/advanced-cursorrules.md at main – GitHub https://github.com/murataslan1/cursor-ai-tips/blob/main/tips/advanced-cursorrules.md
  26. Why Cursor does not follow my cursorrules? – Reddit https://www.reddit.com/r/cursor/comments/1im0zpo/why_cursor_does_not_follow_my_cursorrules/
  27. AI Rule that ACTUALLY works vs. cursorrules : r/cursor – Reddit https://www.reddit.com/r/cursor/comments/1hxi68d/ai_rule_that_actually_works_vs_cursorrules/
  28. Next.js React Standard.js Cursor Rules rule by Mathieu de Gouville – Cursor Directory https://cursor.directory/nextjs-react-vite-javascript-cursor-rules
  29. Cursor rules for Next.js Project · GitHub https://gist.github.com/thatbeautifuldream/2632dcfe708c362cff3be4ca5840a839
  30. Optimal structure for .mdc rules files – Discussions – Cursor – Community Forum https://forum.cursor.com/t/optimal-structure-for-mdc-rules-files/52260
  31. bmadcode/cursor-xml-rules-trial – GitHub https://github.com/bmadcode/cursor-xml-rules-trial
  32. awesome-cursorrules/rules/nextjs15-react19-vercelai-tailwind-cursorrules-prompt-file/.cursorrules at main · PatrickJS/awesome-cursorrules – GitHub https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/nextjs15-react19-vercelai-tailwind-cursorrules-prompt-file/.cursorrules
  33. awesome-cursorrules/rules/python-fastapi-best-practices … – GitHub https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/python-fastapi-best-practices-cursorrules-prompt-f/.cursorrules
  34. awesome-cursorrules/rules/cursorrules-file-cursor-ai-python-fastapi-api/.cursorrules at main · PatrickJS/awesome-cursorrules – GitHub https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/cursorrules-file-cursor-ai-python-fastapi-api/.cursorrules
  35. Cursor Clean Modular Flutter Architecture Ruleset · GitHub https://gist.github.com/Toglefritz/10ad4569d9868738d38bc18e0935c2f9
  36. awesome-cursorrules/rules/flutter-app-expert-cursorrules-prompt-file … https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/flutter-app-expert-cursorrules-prompt-file/.cursorrules
  37. Rules – Cursor Directory https://cursor.directory/rules
  38. PatrickJS/awesome-cursorrules: Configuration files that enhance Cursor AI editor experience with custom rules and behaviors – GitHub https://github.com/PatrickJS/awesome-cursorrules
  39. JhonMA82/awesome-clinerules: A curated list of awesome .cursorrules files – GitHub https://github.com/JhonMA82/awesome-clinerules
  40. Are Cursor Rules Not Working Right Now? – Reddit https://www.reddit.com/r/cursor/comments/1j4lgm1/are_cursor_rules_not_working_right_now/
  41. Cursor just ignores rules – Discussions https://forum.cursor.com/t/cursor-just-ignores-rules/69188
  42. .cursorrules doesnt seem to work reliably? : r/cursor – Reddit https://www.reddit.com/r/cursor/comments/1il1zxg/cursorrules_doesnt_seem_to_work_reliably/
  43. Cursor composer works great for me, but it requires context – Reddit https://www.reddit.com/r/cursor/comments/1fu02l6/cursor_composer_works_great_for_me_but_it/
  44. Composer not following .cursorrules – Page 2 – Bug Reports – Cursor – Community Forum https://forum.cursor.com/t/composer-not-following-cursorrules/25633?page=2
用語集