はじめに
こんにちは、今年 Sun* に新卒入社し、バックエンドエンジニアをしている dogadoga です！
普段は行政向けの予約管理システムでバックエンド開発を担当しています。
今回は Cursor を使って AI でコードのセルフレビューを自動化するために行った試行錯誤の結果を紹介したいと思います。
想定読者
- AI でセルフレビューを自動化したい人
- マイクロサービスで開発している人
TL;DR
- 課題: マイクロサービス開発では、サービスごとにコーディングルールが異なり、レビュー時に毎回適切なルールを読み込ませる必要があった
-
解決: Cursor の Rules でサービスごとのルールを定義し、カスタムコマンド でサービス専用のレビューフローを自動化
-
/review-a-service develop @docs/spec.mdのように呼び出すだけでセルフレビューが完了
-
やりたいこと
Cursor を使って PR を作成する前に AI でセルフレビューしてコードの品質を上げたい！
背景
これをやりたい背景として、コードのレビュー依頼をする前に
- 先輩の負荷を軽減するためにも潰せる問題は潰しておきたい
- 自分で実装しているがゆえに気づけない問題点(パフォーマンスや冗長なコードなど)に気づきたい
などの気持ちがあります。
課題
私のプロジェクトでは、1つのワークスペースに複数のマイクロサービス（A サービス、B サービスなど）をまとめて開発しています。各サービスにはそれぞれ異なるコーディングルール、ディレクトリ構造、エラーハンドリング規約があります。
これまでは、レビューしたい範囲を選択して Ask モードなどでセルフレビューを依頼していました。しかし、以下のような課題がありました。
- 毎回コードを手動で選択するのが大変
-
サービスごとにルールが異なるため、どのルールを適用すべきか判断が必要
- A サービスと B サービスでは命名規則やエラーハンドリングのルールが違う
-
毎回「このサービスのルール」「この機能の仕様書」など、複数のファイルを AI のコンテキストに手動で読み込ませる必要がある
- 読み込むファイルを間違えると、別サービスのルールでレビューされてしまう
もう少しスマートに、サービスを指定するだけで適切なルールが自動適用される仕組みが欲しいと考えていました。
Cursor の既存レビュー機能では自分のやりたいことができず...
また、執筆時点(2025/12/14)で、Cursor には既に以下のようなAIレビュー機能はありますが、自分のやりたいことには使えませんでした。
Agent Review は、Cursor Agent を差分中のバグ検出に特化したモードで実行します。このツールは提案された変更を行単位で解析し、マージ前に問題を検出して警告します。
コーディング規則を明示的に読ませるようなことはできませんでした。
また、差分の指定方法も現在の Git の差分を指定するか、メインブランチとの差分くらいでした。
私はメインブランチとの差分だけではなく、機能ブランチとの差分も確認したい（まさに PR のように）ため、要件に合いませんでした。
2025年11月に出たばかりの機能なので改善に期待ですね！
Bugbot はプルリクエストをレビューし、バグやセキュリティ問題、コード品質の問題を検出します。
「既存の PR コメントをコンテキストとして利用」 でき、かつ Rules も設定できる点が魅力的です。
一方で、私のプロジェクトでは Cursor をレビュワーとしてリポジトリに導入するにはセキュリティやプロセス上のハードルがありました。
また、自分は PR 作成前の段階で品質チェックをしたいので、PR 前提の仕組みとは目的が合いません。
Bugbot を導入できる環境にある方はこの機能を使うのが早いかもしれません！
解決方法
そこで、今回、以下のような Rules と カスタムコマンドを活用する方法を考えました。
手順
設定の手順としては大きく2つだけです。
- Rules でコーディング規則の整備
- カスタムコマンドの作成
ここからは具体的な手順を紹介します。
1. Rules でコーディング規則の整備
Rules とは？
AI が必ず従うべきガイドラインをまとめた設定ファイルを定義できる仕組みです。Claude Code だと CLAUDE.md などが対応する部分ですね。
.cursor/rules に .mdc ファイルを作成することで定義可能です。
ルールファイルの配置例
ここからは、バックエンドにAサービスとBサービスの2つのマイクロサービスがある場合を例とします。
理想的には各サービスのディレクトリ直下にルールファイルを置きたいところですが、Cursor の Rules にはワークスペースのルート直下の .cursor/rules/ しか読み込まれないという制限があります。
私の環境では project フォルダに全てのマイクロサービスをまとめて開いているため、以下のように全サービスのルールをプロジェクト直下の .cursor/rules/ フォルダへ集約しています。
※ セキュリティ、パフォーマンスなどの項目ごとにファイルを分ける場合もありますが、私はまだそこまでの量にはなっていないので、各サービス1ファイルにまとめています。
project/
.cursor/rules/
common-backend.mdc # プロジェクト全体のルール
a-service.mdc # Aサービス固有のルール
b-service.mdc # Bサービス固有のルール
プロジェクト全体のルール common-backend.mdc:
このファイルには以下のような項目のルールを記載しています。
- アーキテクチャ: Microservices, Clean Architecture...
- 命名規則: ファイル名・クラス名・メソッド名・変数名...
- TypeScript: 型注釈忘れ・any 原則禁止・短縮プロパティ...
- パフォーマンス: N+1 問題など
- セキュリティ
各サービス固有のルールa-service.mdc, b-service.mdc:
このファイルには以下のような項目のルールを記載しています。
- ディレクトリ構造
- DDD
- ユビキタス言語
- CQRS パターン
- リポジトリパターン
- …
- テスト
- エラーハンドリング
- ステータスコード・カスタムエラー...
- 実装の具体的なコードの例
2. カスタムコマンドの作成
カスタムコマンドとは？
チャット入力欄で「/」を付けるだけで呼び出せる再利用可能なワークフロー。
.cursor/commands に .md ファイルを作成することで定義可能。
こちらの機能は 2025年9月 に実装されたばかりです。
こちらのカスタムコマンド機能を使って、セルフレビューの指示を簡単に出せるようにしていきます！
カスタムコマンドファイルの配置例:
ルールファイルと同様の理由で、カスタムコマンドの定義ファイルもprojectフォルダ直下の .cursor/commands/フォルダにまとめています。
project/
.cursor/commands/
review-a-service.md # Aサービスのレビュー用コマンド
review-b-service.md # Bサービスのレビュー用コマンド
セルフレビュー用のカスタムコマンドのざっくりとした中身は以下のようになっています。
# タイトル
## 入力
-- 引数の定義 --
## 実行手順
-- AI が行うステップ --
## レビュー観点
-- チェック項目 --
## 出力形式
-- 結果のフォーマット --
【入力】
入力には以下の項目を引数として入れています。
- diff を取得する元のブランチ名
- 機能仕様のファイルパス
1つ目のブランチ名は、git diff コマンドで差分を取得するために使います。
2つ目の仕様ファイルは、差分コードが仕様書と整合しているかを確認するためのコンテキストとして渡します。複数指定も可能です。
【実行手順】
AI がレビューを実行する際の流れ（何を・どの順でやるか）を定義しています。
差分の取得には git diff を使い、未コミットのステージされた変更も含めたいので --cached オプションを付けています。
- 入力（比較元ブランチ名・仕様ファイル）を解析
- 仕様ファイルを読み込み、要件を把握
- レビュー対象の差分を取得
- 後述のレビュー観点に沿ってレビューし、所定の形式で結果を出力
【レビュー観点】
レビューでチェックする項目を定義します。
Rules ファイルを参照しつつ、具体的なチェック項目をカスタムコマンドに直接記載しています。
当初は「Rules ファイルから観点を動的に抽出してレビュー」という方針も試しました。しかし、Rules ファイルを毎回読み込むとトークン消費が増えることや、実際に試してみて直接記載の方がしっくりきたことから、現在の方針に落ち着きました。
チェック項目は以下のようなカテゴリに分けて、チェックボックス形式で記載しています：
- コーディング規約の遵守
- ビジネスロジックの正確性（仕様との整合性）
- セキュリティ
- パフォーマンス
- エラーハンドリング
- テストカバレッジ
これにより、レビュー観点の漏れを防止できます。
【出力形式】
レビュー結果の出力フォーマットを定義します。
「問題点」セクションでは、検出した問題を重要度別（🔴 重大 / 🟡 軽微）に分類して出力するようにしています。修正の優先度が一目で分かるので、効率的に対応できます。
具体例
【レビュー用カスタムコマンドの具体例】
Aサービスに対するレビュー用のカスタムコマンドの例を作ってみました。
カスタムコマンドの全文（クリックで展開）
---
description: Aサービスのセルフコードレビューを実行します
---
# Aサービス セルフコードレビュー
## 入力
- `$ARGUMENTS` - 以下の形式で入力
- 第1引数: diff を取得する元となるブランチ名（例: `develop`）
- 第2引数: 機能仕様のファイルパス（例: `@docs/a-service/new-feature.md`）
## 実行手順
1. **入力の解析**
まず入力を解析してください。`$ARGUMENTS` から以下を抽出します：
- ブランチ名（第1引数）
- 仕様ファイルパス（第2引数）
入力が不足している場合は、ユーザーに確認してください。
2. **仕様ファイルの読み込み**
指定された仕様ファイルを読み込み、実装すべき機能の要件を把握してください。
3. **差分の取得**
以下のコマンドで diff を取得してください：
```bash
cd <Aサービスディレクトリ> && git diff <ブランチ名> --cached --name-only
```
変更されたファイル一覧を確認後、詳細な diff を取得：
```bash
cd <Aサービスディレクトリ> && git diff <ブランチ名> --cached
```
4. **コードレビューの実行**
以下の観点でレビューを行ってください。各観点について問題点と改善提案を出力します。
## レビュー観点
### 1. コーディング規約の遵守
以下のルールファイルを読み込み、それに基づいて確認：
- `.cursor/rules/common-backend.mdc`
- `.cursor/rules/a-service.mdc`
- [ ] 上記ルールファイルを読み込み、「読み込みました」と出力
- [ ] 命名規則（クラス名: PascalCase、メソッド名: camelCase、ファイル名: kebab-case）
- [ ] 変数宣言時の型注釈
- [ ] 早期 return の使用
- [ ] 短縮プロパティ名の使用
### 2. ビジネスロジックの正確性（仕様との整合性）
仕様ファイルと実装を照らし合わせ、以下を確認：
- [ ] 仕様に記載された機能がすべて実装されているか
- [ ] フロントエンドに返すレスポンス形式が仕様通りか
- [ ] データの集約ロジックが正しいか
### 3. セキュリティ
- [ ] 認証・認可チェック
- [ ] リソースIDの適切な検証
- [ ] 入力バリデーションが適切か
- [ ] 機密情報のログ出力がないか
### 4. パフォーマンス
- [ ] 複数 API 呼び出しの並列化（`Promise.all`）
- [ ] 不要な API 呼び出しがないか
- [ ] ページネーション処理の適切性
### 5. エラーハンドリング
- [ ] 適切なカスタムエラーの使用
- [ ] 外部 API 呼び出しのエラーハンドリング
- [ ] エラーメッセージが明確で具体的か
### 6. テストカバレッジ
- [ ] 新規コードに対するテストが追加されているか
- [ ] Usecase のユニットテスト
- [ ] エッジケースのテスト
## 出力形式
以下の形式でレビュー結果を出力してください：
```text
# Aサービス セルフレビュー結果
## 概要
- 変更ファイル数: X
- 主な変更内容: （簡潔に記述）
## 仕様との整合性
### 実装済み
- ✅ （仕様項目1）
- ✅ （仕様項目2）
### 未実装/要確認
- ⚠️ （仕様項目3）- 理由や詳細
## 問題点
### 🔴 重大（修正必須）
1. **（問題のタイトル）**
- ファイル: `path/to/file.ts`
- 行: XX-YY
- 問題: （詳細）
- 提案: （改善案）
### 🟡 軽微（推奨）
1. **（問題のタイトル）**
- ファイル: `path/to/file.ts`
- 行: XX-YY
- 問題: （詳細）
- 提案: （改善案）
## 良い点
- ✨ （良かった点1）
- ✨ （良かった点2）
## 質問・確認事項
- ❓ （確認したい点）
```
【レビューコマンドの呼び出し例】
例えば develop ブランチから切ったブランチで作業している場合、以下のようにレビューコマンドを呼びます。
実際にやってみた感想
この方法を使ってから、レビューで返ってくる指摘と往復の回数も減っているのでセルフレビューの効果を実感しています。また、細かい部分の指摘が減り、本質的な部分での議論に集中できるようになったと感じます。
特に、PR に出す差分全体を一度に見てもらえるため、今まで見逃しがちだった細かいルール違反にも気づけるようになりました。例えば、TypeScript の型注釈忘れや、重複コードの検出など。
カスタムコマンドを使うと繰り返しレビューをする負荷も減って、試行回数を増やしやすくなったと感じます。
同じ差分を入力しても返ってくるレビューの感じがAIのモデルによって全然違っているので、そこはそれぞれのAIの性格が出ている感じがして面白かったです。
まとめ
今回、Rules とカスタムコマンドを整備したことで、セルフレビューの指示出しがスムーズになり、期待する結果により早くたどり着けるようになりました。
今後は、Cursor の進化、特に、サブエージェント機能やレビュー機能の改善など、に期待するとともに、先輩のレビューや勉強したことを参考にしながら逐次ルールやカスタムコマンドをアップデートしていきたいと思います。
また、AI にコンテキストとして渡すための仕様書の書き方も自分の中で確立していきたいです💪
参考記事
Discussion