.cursor/ 配下の使い分けを整理してみた

はじめに

こんにちは！ EC事業部開発第二セクションの古賀です。

Cursor で AI 駆動開発をしていると、プロンプトの良し悪し以前に
開発の進め方そのものが安定しないという悩みが出てきます。
.cursor/ 配下には rule、 command、skill とAI の挙動を制御する仕組みが揃ってきましたが
それぞれの役割が似ていて、 どこに何を書くべきか迷うことが多いと感じていました。

そこで今回は、実際にいくつかのプロジェクトで .cursor/ 配下を試行錯誤してきた中で
自分なりに整理できた使い分けのルールをまとめてみました。
同じように迷っている方の参考になれば嬉しいです。

Cursor の公式ドキュメントでは、Rules と Skills の違い（短い指針なら rule、多段の手順なら skill 等）
を比較する表や、Commands（チャット上で / から呼ぶ定型作業）の説明がそれぞれ掲げられています。
一方で、rule・command・skill の三層をこの一つの枠組みで定義すると公式に一本化した記述は
執筆時点（2026年4月）では見当たりませんでした。
下記は、公式の個別説明の大枠に触れながら理解しやすいように私が実務上まとめた使い分けです。

この記事の内容

本記事では、具体的なコマンドの書き方や細かい構文には踏み込みません。
代わりに、rule、command、skill をどう使い分けるか
作るときに何を意識すると運用が楽になるかといった設計の考え方に焦点を当てています。

試行錯誤の末にたどり着いた三層構造

最初は rule に全部書いていました。ただ、ルールが増えてくると常時適用で読み込まれる量が膨らみ
AI が本来やるべきタスクから脱線することが増えてきました。
そこで command と skill を使い始めたのですが今度は「どれに何を書くか」で悩むようになります。

色々と試した結果、以下のように整理しました。

この三層で捉え直してから、.cursor/ 配下の編集が格段に楽になりました。

起動（読み込み）条件の表現を上の表に揃えると、rule と skill は
「ユーザーが明示的に指定するか、AI 判断で読まれるか」の軸は同じです。
（rule だけ alwaysApply や globs、手動 @ など、出方の種類が skill より多い）

skill は、AI 判断（関連）で読まれると SKILL.md の本文が一括で乗るため、本文の量や description との一貫性の影響を受けやすいです。
いずれも書き方次第で想定外の文脈に乗る／乗らないが起こり得ます。
一方、command はユーザーが / から明示的に呼び出す運用にしやすく、「いつ使うか」の判断を人間側の習慣に寄せやすいです。

Rule についての個人的な提案

rule はシンプルに見えて、一番注意が必要な要素だと感じています。常時適用の alwaysApply: true
にすると、全セッションで読み込まれるため、書きすぎると AI のコンテキストを圧迫します。

提案したい書き方

個人的には、rule を以下のように分けています。

• レイヤー1: alwaysApply: true にして、本当に揺らがせたくない原則だけを置きます
• レイヤー2: globs や手動適用にして、計画時や実装時など特定の場面だけ効かせます

例えば「テストなしに実装を完了しない」はレイヤー1、「Red-Green-Refactor の順を守る」はレイヤー2
といった切り分けです。

ここで気を付けたいこと

rule を書くときに一番やりがちな失敗は、同じ規約を複数の rule に書いてしまうことです。
片方だけ更新されて、後から「どっちが正なのか分からない」という状態になります。
私はこれを防ぐために rule ファイルに必ず「このルールの責務は何か」を冒頭に書くようにしています。
責務を被るルールを作りたくなったら、既存のルールを拡張するか
そもそも rule ではなく skill に寄せるか、を先に検討するようにしています。

command についての個人的な提案

command は、自分が一番恩恵を感じている仕組みです。
定型作業を markdown + script で定義しておくと、人間も AI も同じ手順を踏めるようになります。

提案したい作り方

command を作るときは、以下の順番で考えると失敗しにくいと感じています。
1. その command の責務を一文で書けるまで絞ります
2. script 側に処理本体を寄せ、markdown 側は目的と使い方だけを書きます
3. 出力の読み方と、失敗したときの停止条件を明記します

特に 3 番目は重要で、失敗時の挙動を書いておかないと
AI が勝手にリカバリしようとして意図しない動作をすることがあります。

ここで気を付けたいこと

command の落とし穴は、script が外部ツールやライブラリに依存しているケースです。
依存先のバージョンが上がって壊れたときに、markdown 側の説明と実態がズレると誤誘導の原因になります。
私はこれを防ぐために、script の冒頭に前提条件と想定バージョンをコメントで書き
command の markdown にも「依存先に変更があったら一緒に見直す」という一文を入れるようにしています。

Skill についての個人的な提案

skill は３つの中で一番奥が深いと感じています。
単なる手順書ではなく、AI がいつその skill を起動するかを含めて設計する必要があるためです。

提案したい作り方

skill を作るときに、個人的に意識しているポイントは次の 3 つです。

• 1 つの skill には 1 つの成果物を対応させます。
• SKILL.md では、frontmatter（特に いつ・何の依頼で読み込ませるかの description）に加え
  手順、スクリプトの起動、ドメイン上の制約などエージェントが従うべき内容を本文に具体的にまとめます。
  Cursor 公式の例（「When to use」「Instructions」など）のとおり
  　本文に詳しい作業手順を置く想定に近づきます。
  完了基準や禁止事項のように、振る舞いの境界を足すのは、自チーム向けの整理として有効だと感じています。
• 網羅的な補足、長大なリファレンス、随時引きたい副次資料は、Cursor の公式ドキュメントが案内するとおり references/ 内の REFERENCE.md など別ファイルに分け、必要に応じて段階的に読ませる形にします。

特に description の書き方は重要で、ここが曖昧だと AI が正しく skill を選んでくれません。
「ユーザーが〇〇を依頼したときに使う」というトリガーの条件まで書き切るのがコツだと感じています。

ここで気を付けたいこと

skill の失敗パターンで多いのは、長文化することです。最初はシンプルだった SKILL.md が
運用するうちに例外処理や補足説明でどんどん膨らんでいきます。膨らんで困るのは
一度 skill の本文がコンテキストに載ると、長いほど他のタスクに回せる余白を圧迫しやすい点です。
加えて手順の中に前提説明や但し書きが混ざると、AI はどこが実行すべきステップで
どこが参考情報かを区別しにくくなり、重要な指示が長文の中に埋もれて素通りされる事故が起きやすくなります。

もう一つ見落としがちなのが、起動判定への悪影響です。記述が増えると description
と本文の論点がぶれてきて、本来呼ばれるべき場面で AI が別の skill を選んでしまったり
逆に関係ない場面で誤って起動してしまう、といったミスマッチが発生しやすくなります。

私はこれを防ぐために、SKILL.md は 150 行以内を目安にし、超えそうなら同じ skill ディレクトリの
references/ 配下や REFERENCE.md などに切り出すようにしています。切り出す基準を先に決めておくと
編集時の判断が早くなるのでおすすめです。

三層の使い分けで迷ったときの判断軸

実際に運用していると、「これは rule か、skill か、それとも command か」と迷う場面が必ず出てきます。
個人的には、以下の 2 軸で考えると答えが出しやすいと感じています。

まとめ

今回は、.cursor/ 配下の rule、command、skill について、個人的に考えている使い分けをまとめてみました。
改めて整理して感じたのは、.cursor/ 配下の設計は、テンプレートを集める作業というより
チームの開発運用そのものを設計する作業に近いということです。
三層の境界を意識するだけで、AI の挙動はかなり安定します。

一方で、ここに書いた内容はあくまで個人の経験から得た考え方なので
プロジェクトの性質やチームの規模によって最適解は変わると思います。
気になった部分だけでも自分のプロジェクトで試してみて、合う合わないを判断してもらえれば嬉しいです。