チームでCursorを使い始めると、すぐに気づく問題があります。同じコードベースなのに、AIエージェントが人によって全然違う書き方のコードを出してくることです。ある人はテストを書かせ、別の人はテストなしでマージし、命名規則もばらつく。この差は、AIの性能差ではなく、AIに何を前提として渡しているかの差から生まれます。
先に結論です。チーム開発でCursorを揃えるには、`.cursor/rules` に「言語・フレームワークの版」「禁止事項」「テスト方針」「レビューで必ず見る観点」を明文化し、頻繁に変わる情報はドキュメント側に残す、という役割分担をします。ルールに書きすぎても、ドキュメントに書きすぎても機能しません。境界線を最初に決めることが、チーム開発を揃える一番の近道です。
なぜAIエージェントの出力がチームでばらつくのか
CursorのようなAIエージェントは、リクエストされた内容と、リポジトリから読み取れる文脈をもとにコードを生成します。個人開発なら、その人の頭の中の暗黙知がそのままAIへの指示になりますが、チームでは、各メンバーの暗黙知が微妙に違います。ある人は「テストは後で書く」文化で育ち、別の人は「テストがないとレビューに出さない」文化で育っている、というようなことが普通に起きます。
この暗黙知の差を、AIエージェントは埋めてくれません。むしろAIは指示されたことに忠実に従うため、暗黙知の差がそのまま出力の差になって表面化します。つまり、チーム開発でAIエージェントを揃えるということは、暗黙知を明文化する作業そのものです。
もう一つの要因は、リポジトリの文脈量です。大きなリポジトリの一部分だけを見ているとき、AIはその部分から読み取れる慣習を優先します。古いコードと新しいコードが混在しているリポジトリでは、AIがどちらの書き方を「正解」として学習するかが場所によって変わり、結果としてコードベース全体の一貫性がさらに崩れていきます。ルールで明示的に「新しい書き方はこちら」と示しておかないと、この揺れは自然には収まりません。
ルールに書くべきもの
`.cursor/rules` は、エージェントが毎回のリクエストで参照する前提知識です。ここには、変更頻度が低く、かつ守られないと問題が起きるものを書きます。
- 言語・フレームワークの版 — 例：PHP 8.4 / Laravel の使用バージョン。バージョン特有の書き方の指示に直結する
- 禁止事項 — 秘密情報をコードやログに貼らない、特定の非推奨APIを使わない、など
- テスト方針 — 新規ロジックには最低限どのレベルのテストを書くか
- PRの粒度 — 1つのPRで扱う変更範囲の目安
- 命名・ディレクトリ構成の原則 — 新規ファイルをどこに置くかの判断基準
これらは共通して、「守らないと後で手戻りが発生するもの」です。手戻りが起きないルールは、多少ばらついても実害が小さいため、ルール化の優先度は下がります。
ドキュメントに残すべきもの
一方で、次のような情報はルールファイルに書かず、READMEや別のドキュメントに残します。
- 環境構築の手順（頻繁に変わり、詳細な手順が必要なため）
- API仕様やデータベース設計の詳細（別ドキュメントの方が参照性が高い）
- プロジェクトの背景・ビジネス上の経緯（判断に必要だが、毎回のコード生成には不要）
- リリース手順やデプロイの詳細（運用手順書として別管理する方が事故が減る）
境界線の考え方はシンプルです。「AIへの毎回の指示として効かせたいか」「人間が必要なときに参照したいか」で分けます。前者はルール、後者はドキュメントです。両方に同じ内容を書いてしまうと、更新時にどちらかが古くなり、矛盾が生まれます。迷った場合は、まずドキュメント側に書き、実際にAIの出力で同じ問題が繰り返し起きたら、そのときにルール側へ移す、という順番にすると判断しやすくなります。
プロジェクト全体と、ディレクトリ単位のルール
1つのリポジトリの中でも、フロントエンドとバックエンド、あるいは複数のサービスが混在している場合、プロジェクト全体に共通するルールと、特定のディレクトリだけに適用したいルールが出てきます。すべてを1つのルールファイルに詰め込むと、フロントエンド向けの指示がバックエンドのコード生成にも影響してしまい、意図しない出力になることがあります。
この場合は、プロジェクト全体に効かせたい原則（禁止事項、命名の大原則など）と、特定領域だけに効かせたい詳細な指示を分けて管理します。範囲を絞ったルールは、該当ディレクトリで作業しているときだけ効くようにしておくと、余計な指示がノイズにならず、AIの出力がその場の文脈に合ったものになります。
ルールを作る手順
ゼロからルールを作る場合は、次の順で進めると負担が小さいです。
- 直近のPRレビューで指摘した内容を1週間分ざっと見返す
- 同じ種類の指摘が2回以上出ているものを洗い出す
- 洗い出した指摘を「禁止事項」「テスト方針」「命名規則」などのカテゴリに振り分ける
- 短い文章でルールファイルに書き、チームでレビューする
- 1〜2週間運用し、AIの出力が改善したか確認する
1番目と2番目がポイントです。想像で網羅的なルールを最初から作ろうとすると、実際には使われない項目が増え、メンテナンスの負担だけが増えます。実際に繰り返し起きている問題から逆算する方が、少ないルールで効果を出せます。
PRレビュー文化との関係
ルールを整備しても、PRレビューの文化が伴わないと効果が定着しません。ルールはAIの出力の初期品質を上げるものであり、最終判断はレビューする人間に残ります。次のような運用にすると、ルールとレビューがうまく噛み合います。
- ルールで防げるはずの指摘がレビューで頻発したら、ルールの見直しサインとして扱う
- レビューでの指摘は個人への指摘ではなく、ルール改善の材料として扱う文化にする
- ルールに書いてあることをAIが守れていない場合は、ルールの書き方自体を見直す
特に2番目は、チームの心理的な安全性に関わります。「あなたのミス」ではなく「ルールに書いていなかった」という捉え方にすることで、レビューが個人攻撃に見えなくなり、ルール整備が前向きな活動として続きやすくなります。
また、レビュー担当者自身もAIエージェントを使ってレビューの下読みをすることがあります。その場合、レビュー用のプロンプトにも同じルールを参照させると、コードを書く側とレビューする側で見ている基準が揃い、指摘の一貫性が上がります。書く側とレビューする側で別々の基準を使っていると、同じルールがあっても運用がずれてしまいます。
よくある失敗
- ルールファイルに、プロジェクトの背景や仕様の詳細まで全部書き込み、肥大化して誰も読まなくなる
- 一度作ったルールを更新せず、実際のコードベースの慣習と食い違ったまま放置する
- ルールを1人が作って共有だけし、チームでレビューしないまま運用する
- 禁止事項ばかりで、推奨する書き方の指示が少なく、AIの出力が守りに入って冗長になる
1番目は特に多い失敗です。ルールファイルは、エージェントが毎回参照する前提として機能するため、長すぎると本当に重要な項目が埋もれます。長さより、優先度の高い項目に絞ることを意識します。
2番目も見過ごされがちです。プロジェクトが成長すると、当初決めた方針が実情と合わなくなることは自然に起こります。ルールファイルをコードと同じようにPRで変更履歴が残る場所に置いておくと、「いつ、なぜこの方針に変わったか」を後から追跡でき、放置されにくくなります。
まだできないこと・やらないこと
- ルールを整備するだけで、コードレビューを人間が行わなくてよくなるとは考えない
- チームの暗黙知をすべて一度に明文化しようとはしない。頻出のものから順に進める
- 秘密情報や本番の認証情報を、ルールファイルやドキュメントに直接書かない
- ルールに書いたからAIが必ず守るとは断定しない。守られているかは定期的に確認する
まとめ
Cursorのルール設定でチーム開発を揃えるということは、各メンバーの頭の中にある暗黙知を、AIエージェントが参照できる形に明文化する作業です。ルールには変更頻度が低く実害の大きいものを書き、頻繁に変わる情報はドキュメントに残す。この役割分担ができれば、AIエージェントの出力のばらつきは大きく減り、レビューの負担も下がります。
次にやる1アクションは、直近1週間のPRレビューコメントを見返し、同じ指摘が2回以上出ている項目を1つだけルールファイルに追加することです。完璧なルールを目指すより、この地道な積み重ねの方が、チームの開発体験を確実に改善します。
ルール整備は一度作って終わる仕事ではなく、チームの開発文化そのものを言葉にしていく継続的な作業です。人数が増えるほど、暗黙知のずれは大きくなりやすいので、チームが拡大するタイミングこそ、ルールを見直す良い機会だと捉えてください。
道具としてのAIエージェントは日々進化していますが、チームの一貫性を作るのはツールの性能ではなく、人間側が用意した前提の質です。ルール整備は地味な作業に見えますが、その地味さこそが、長期的な開発スピードの差になって表れます。
※ 本記事はCursorのルール機能の一般的な使い方を整理したものです。仕様は更新されることがあるため、最新の設定方法は公式ドキュメントを確認してください。
