AI IDE の文脈におけるルールとは、LLM 駆動のアシスタントの振る舞いを制約し導くために開発者が書く、テキストの指示や指令である。ルールはプロジェクトのルートや設定用ディレクトリにあるルールファイルに保持され、開発者がアシスタントとやり取りするときに、IDE が関連する内容を取り出してモデルのコンテキストウィンドウに注入する。この仕組みは永続的なプロンプトエンジニアリングに相当する。本来ならセッションのたびに打ち直すことになる内容を一度だけ書いておけば、自動的に適用されるのである。
その目的は、アーキテクチャ上の制約、コーディングスタイル、ライブラリの好み、開発ワークフローといった特定のプロジェクトに、IDE の出力を合わせることにある。ルールファイルは通常自然言語で、たいていは Markdown で書かれる。置き場所はツールによって異なり、Cursor では .cursor/rules/、Windsurf では .windsurf/rules/、Trae では .trae/rules/、Qoder では .qoder/rules/、Kiro では .kiro/steering/ である。Kiro はこの仕組みを Steering と呼び、デフォルトでそこに三つのファイルを生成する。Cursor と Windsurf はいずれも単一ファイルの形式（.cursorrules、.windsurfrules）から始まったが、後にディレクトリベースの管理に取って代わられた。
Alibaba Cloud は通义灵码（Lingma）と呼ぶ製品のユーザーガイドを公開しており、その製品のルールディレクトリを .lingma/rules としている。一方、上記の研究は Qoder について .qoder/rules/ を記録している。ここでは両方のパスを、それぞれの文書が示すとおりに記録しておく。
用法
AI IDE におけるルールの分類法と進化：マイニングと調査による研究 は、83 のオープンソースプロジェクトから 7,310 件のルールを収集し、それらを五つの主要カテゴリーに分類した。アーキテクチャと設計（技術スタックの選定、設計原則とパターン、システムアーキテクチャ、設計上の参照と制約）、コード実装（フレームワークの使い方、コードスタイルの規約、パフォーマンス最適化、言語機能、エラーと例外の処理、ビジネスロジック）、開発ワークフローとプロジェクト管理（ワークフローの規約、プロジェクトのドキュメント、ディレクトリ構造、環境設定、バージョン管理、依存関係の管理）、品質保証（テスト戦略、セキュリティプラクティス、コード品質の基準、ロギングの基準、コードレビュー）、そして AI 協働の仕様（AI の振る舞いと意思決定の戦略、AI の出力内容のガイドライン、AI のコンテキスト管理、AI のツール利用）である。最後のカテゴリーは、コードについてのルールとは区別される、モデル自身の振る舞い、対話スタイル、ツール利用に対するメタ制御として働く。
この研究が実際に見出したのは、開発者が重要だと言うものと、ルールファイルに実際に書かれているものとの間のギャップである。アーキテクチャとコンテキスト管理のルールは最も重要だと評価されており（システムアーキテクチャは 5 点満点中 4.25、AI のコンテキスト管理は 4.17）、それでいて収集されたルールに占める割合はそれぞれ 2.67% と 1.76% にすぎない。リポジトリ内で最大のカテゴリーであるワークフローの規約（9.29%）は重要度の最下位四分位に入り、2 番目に大きいテスト戦略（8.76%）は中位の評価である。研究による説明は、ルールがどのように書かれるかに由来するものである。調査対象の開発者の 71.72% は AI でルールを生成してから手直ししており、48.48% は AI がミスをしたときにだけルールを追加する。そのためファイルは、開発者が重要だと挙げるものではなく、生成中に目に見える摩擦を引き起こすものの周りに蓄積していく。
ほとんどのプロジェクトはルールを一元化している。43.4% はルールファイルがちょうど一つ、26.5% は二つであり、20 を超えるプロジェクトはまれである。ルールの数は数十から百数十程度に集中している。
ルールは静的なものではない。この研究では 83 プロジェクトのうち 55 でルールファイルが変更されており、主な操作は追加で、各カテゴリーの変更のうち典型的には 50〜80% を占める。コミットの証拠から六つの要因が特定された。拡張（Expansion）（エージェントの範囲を新しいモジュールに広げたり、IDE の新機能を採り入れたりする）、コンテキストの充実（Context Enrichment）（モデルのコンテキストの欠落を埋めるために、暗黙のプロジェクト背景を補う）、同期（Synchronization）（変化するコードベースとルールの整合性を保つ）、洗練（Refinement）（意図を変えずに言い回しを引き締める）、修正（Correction）（ハルシネーションや不適切な出力を観察した後に否定的な制約を加える）、そして刈り込み（Pruning）（古くなったルールを削除する）である。これらの相対的な比重については、マイニングの証拠と開発者の自己申告が大きく食い違う。コミットでは拡張とコンテキストの充実が支配的である一方、調査対象の開発者の 77.78% は修正を主なきっかけとして挙げており、研究はこのギャップをネガティビティ・バイアスと解釈している。修正する場合でさえ、開発者は主に追加を行う。修正の 68.75% は既存のテキストの編集ではなく追加として行われていた。
第二の軸 — ルールがいつ発動するか。 上記の分類法は、ルールを何についてのものかで分類する。Alibaba Cloud の Lingma のガイドは、代わりにルールがどのように発動されるかで分類し、それに基づいて四つの型を定義している。手動（Manual） ルールは、開発者がチャット欄で名前を指定して呼び込んだときにだけ効力を持つ。モデル判断（Model Decision） ルールは、それがどのような状況のために書かれたかの説明を持ち、エージェントモードで、あるいはチャットでツール利用が有効になっていれば、モデルがそれを適用するかどうかを自ら判断する。挙げられている例は、単体テストを生成するときや、コメントを書くときに効くことを意図したルールである。常時（Always） ルールは、チャットとインラインチャットのすべてのリクエストに適用され、ドキュメントはプロジェクト全体の規約、すなわちコーディングスタイル、好ましい形式、デフォルトの回答ロールをここに置くとしている。特定ファイル（Specific Files） ルールはカンマ区切りの glob パターンによって範囲が定められ、一つの言語や一つのディレクトリなど、一致するファイルに適用される。これは複数のツールにまたがる知見ではなく一つのベンダーの製品設計だが、上の内容による分類法が暗黙のままにしている区別に名前を与えている。ルールがいつ適用されるかは、ルールが何を言うかとは別に設定される、という区別である。
同じドキュメントは、それが課す仕組みについても述べている。一つのルールファイルは 10,000 文字が上限で、それを超えると切り捨てられる。ルールは自然言語で書かねばならず、画像やリンクは解析されない。ファイルはプロジェクトディレクトリに置かれるため、他のファイルと同様に Git を通じてリポジトリとともに移動し、ルールを一人の開発者だけのものにしておくための方法として、そのディレクトリを .gitignore に追加することが示されている。ルールとアシスタントのメモリが矛盾する場合は、ルールが優先されると述べられている。
適用される場面
ルールが適用されるのは、アシスタントにセッションのたびに伝えなければならない規約をプロジェクトが持っており、かつその規約をモデルが従う自然言語で述べられる場合である。研究によるコンプライアンスの測定は、二つ目の条件がどこで成り立つかに直接関わる。ルールを更新すると成果物のコンプライアンスは平均で 22.99% 向上したが、その効果は具体的で静的に検査可能な制約に集中していた。依存関係の管理は 64.82%、テスト戦略は 52.73% 向上した一方、プロジェクトのドキュメントは 6.25%、システムアーキテクチャは 3.33% の向上にとどまった。
この非対称性から二つの失敗モードが導かれる。一つ目は、従来のリンターのほうが確実に強制できる書式や構文に、限られたコンテキストウィンドウを費やすことである。研究はそれらを委ね、ウィンドウはドメイン固有のビジネスロジックとアーキテクチャのパターンのために取っておくことを推奨している。二つ目は、非機能要件を抽象的に述べることである。パフォーマンス最適化とセキュリティプラクティスについてのルールはめったに変更されず、変更される場合はたいてい削除である（変更のうちそれぞれ 65.22% と 61.90%）。研究はこれを、これらが本質的に抽象的な要件であり、プロンプトの中で正確に述べるのが難しいためだと説明する。あいまいだが厳格な制約は、モデルの過度に防御的な振る舞いや、ハルシネーションによる偽陽性を引き起こしうる。研究の助言は、それらを具体的なコードパターンに変換するか、代わりに静的解析に頼ることである。
AIエージェント向けコーディングルールをArchUnitで機械的に検証する運用 にあるあるチームの説明は、この最後の助言を最後まで実践している。彼らは、ルールの遵守が、生成されたコードを誰がたまたまレビューしたかに依存していることに気づいた。その負荷はエージェントが生み出す量とともに増え、やがてレビューが追いつかなくなると彼らは主張する。そこで、パッケージ構造とクラス間の関係で表現できるルールを、ビルド時に実行されるアーキテクチャテストにまとめ、それを実行するジョブをプルリクエストのマージ前の必須チェックにした。彼らが報告していることのうち二つは、ルールをどう検査するかではなく、どう書くかに関するものである。彼らは各ルールを、他のルールを相互参照するのではなく単独で完結するように書き直した。読み手はエージェントであり、実装やレビューのたびにルールを読み直すので、参照をたどるたびに誤読の機会が一つ増える、という前提からである。これで予想された重複は、彼らの説明によれば目立っては現れなかった。また、背景の説明と強制可能な制約を別々のディレクトリに分けた。両方が一つの文書にあると、どの記述が検証の候補なのか区別がつかないからである。その後、各ルール文書は、自身の制約のうちどれがすでに機械的に検査され、どれがまだレビューに頼っているかを明記するようになり、保証の境界が文書だけから読み取れるようになった。
この説明は二つのコストも記録している。ルール文書、テスト、コードは別々のファイルであるためずれていき、一方に書いた例外はもう一方にも手作業で書かなければならない。現在は、例外を追加する人にテストを更新するよう促す注記で対応しているが、それでもやはり人が読んで行動しなければならないものだと彼らは述べている。そして、ルールは他へ持ち出しにくいことがわかった。ルールを他のリポジトリに配布する計画は、ほとんどどのチームも他チームのルールを採り入れなかったため断念された。彼らはその原因を、測定ではなく自分たちの振り返りによる推論として、本当に移植可能なルールが予想より少なかったこと、そして取り込んだルールをそのテストやローカルのコードと整合させ続けるための継続的なコストに求めている。
三つ目の失敗モードは蓄積である。修正が追加という形で行われるため、ルールファイルは長くなり、矛盾を含むようになりうる。研究は定期的に統合し刈り込むことを推奨している。コンプライアンスも減衰する。ルールを導入したコミットで最高となり、その後のコミットにわたって 65% 前後まで下がっていく。研究はこれを、ルールが古くなること、そしてビジネスコードと会話が蓄積するにつれてコンテキストウィンドウが複雑になることに帰している。
同じガイドにある Alibaba Cloud の書き方の助言は、測定ではなくベンダーに由来するもので、別の問いに答えている。どのルールが費やすコンテキストに見合うかではなく、モデルが従うルールをどう書くかである。ガイドは、長すぎたりあいまいだったりするルールはアシスタントを混乱させるという理由で、簡潔で具体的かつ明確なルールを求める。構造化、すなわち長い段落ではなく箇条書き、番号付きリスト、Markdown を使うことを求め、そのほうがモデルにとって理解しやすいとする。良いコードの実例を示すことを求め、それが意図を伝えるうえで大いに役立つと述べる。そして反復、すなわちルールを書いてから、実際の生成や質問を通じてテストし、それから洗練させることを求める。この最後の点は、実際にはルールファイルは事前に仕様として定められるのではなく、観察された振る舞いの後の手直しによって積み上げられていく、という研究の知見と並ぶものである。
証拠の基盤は一つの混合研究法による研究であり、その研究自身が挙げる注意点のうち二つがここで重要になる。外的妥当性については、対象プロジェクトが主に TypeScript の Web 開発であり、研究自身のデータセットの概要によれば、個人開発者か 1〜3 人のチームによって構築されていると述べている。これとは別に、内的妥当性については、コンプライアンスの数値が、自動スクリプトで検査できるものに絞り込んだ 160 件のルールに基づいており、そのため静的に検証可能なカテゴリーが中心になっていると記している。
関連用語
- AI IDE — この仕組みが属するツールの分類
- AI IDE におけるルールの分類法と進化：マイニングと調査による研究 — 上記の分類法、変化の要因、コンプライアンスの数値の基になった研究
- AGENTS.md — 特定の IDE に縛られない、同等のコンテキストファイルの慣習
- コンテキストエンジニアリング — この仕組みがその一つの手段となっている、より広いプラクティス
- プロンプトエンジニアリング — ルールがその永続的な形にあたるもの
- AIエージェント向けコーディングルールをArchUnitで機械的に検証する運用 — ルールのうち強制可能な部分をビルド時のテストにまとめた、あるチームの説明