コードレビュー

PRやコード変更を体系的にレビューするための汎用スキルです。 言語非依存の共通レビュー基準と、言語/フレームワーク固有のベストプラクティスを組み合わせて使用します。

ディレクトリ構成

code-review/
├── SKILL.md (このファイル)
└── references/
    ├── typescript-best-practices.md       # TypeScript固有のチェック
    ├── authorization-review-general.md    # 認可レビュー観点（一般編）
    ├── authorization-review-postgres-rls.md  # 認可レビュー観点（PostgreSQL RLS編）
    ├── github-pr-review-actions.md        # GitHub PRレビューアクション
    ├── ci-optimized-workflow.md           # CI環境でのコスト最適化ワークフロー
    ├── incremental-review.md             # インクリメンタルレビューの詳細
    ├── skill-review.md                    # Claude Codeスキル（SKILL.md）レビュー基準
    ├── skill-overview.md                  # スキル概要（公式ドキュメント）
    └── skill-best-practices.md            # スキルベストプラクティス（公式ドキュメント）

ランタイムファイル

CI実行時に自動生成されるファイル。リポジトリにはコミットしない。

ファイル	用途	ライフサイクル
.pr-triage.json	トリアージ結果	毎回生成
.pr-review-state.json	レビュー状態	actions/cache で実行間永続化

外部スキル連携

React / Next.js のベストプラクティスは、Vercel提供の vercel-react-best-practices スキルを使用する。

• リポジトリ: https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices
• インストール: npx -y skills add vercel-labs/agent-skills --skill vercel-react-best-practices --agent claude-code --yes
• カバー範囲: 非同期ウォーターフォール排除、バンドルサイズ最適化、サーバー側パフォーマンス、クライアント側データ取得、再レンダリング最適化、レンダリングパフォーマンス、高度なパターン、JavaScriptパフォーマンス（8カテゴリ、40以上のルール）

コスト最適化（CI環境）

GitHub Actions等のCI環境で実行する場合、トリアージフェーズを軽量モデル（Haiku）に委任することでコストを大幅に削減できる。 詳細は references/ci-optimized-workflow.md を参照。

トリアージ結果の活用

CI環境で事前トリアージが実行されている場合、作業ディレクトリに .pr-triage.json が存在する。 このファイルが存在する場合、以下の最適化を適用する：

1. ステップ1をスキップ — トリアージ結果の summary を使用する
2. リファレンスの選択的読み込み — required_references に含まれるものだけを読む
3. 表層チェックの省略 — surface_issues に含まれるMinor/Suggestion問題は既にチェック済みとして、Critical/Major分析に集中する
4. 差分の効率的な確認 — files のカテゴリ分類を活用し、重要度の高いファイルから優先的にレビューする

// .pr-triage.json の構造
{
  "pr_number": 123,
  "summary": "認証ミドルウェアの追加とユーザーAPI新規作成",
  "files": {
    "added": ["src/middleware/auth.ts", "src/api/users.ts"],
    "modified": ["src/routes/index.ts"],
    "deleted": []
  },
  "languages": ["typescript"],
  "frameworks": ["express"],
  "change_categories": {
    "has_auth_changes": true,
    "has_db_changes": false,
    "has_rls_changes": false,
    "has_api_changes": true,
    "has_test_changes": false,
    "has_config_changes": false,
    "has_skill_changes": false
  },
  "required_references": [
    "typescript-best-practices.md",
    "authorization-review-general.md"
  ],
  "surface_issues": [
    {
      "severity": "Minor",
      "file": "src/api/users.ts",
      "line": 15,
      "issue": "`any`型が使用されている",
      "suggestion": "具体的な型に変更する"
    }
  ],
  "diff_summary": "認証ミドルウェアを新規追加。JWTトークン検証を実装。ユーザーCRUD APIを新規作成。テストは未追加。",
  "estimated_complexity": "medium",
  "focus_areas": ["セキュリティ: JWT検証の実装", "認可: ユーザーAPIのアクセス制御"]
}

.pr-triage.json が存在しない場合は、従来通りステップ1から全ステップを実行する（後方互換性あり）。

インクリメンタルレビュー（PR更新時の差分最適化）

PR更新（synchronizeイベント）時に、前回のレビュー状態を活用してトークン消費を削減する。 詳細は references/incremental-review.md を参照。

.pr-review-state.json が存在しない場合（初回レビュー）は、インクリメンタル最適化は適用されず、フルトリアージを実行する。不正な形式の場合も警告を出力してフルトリアージを実行する。

レビューワークフロー

以下のチェックリストをコピーして進行状況を追跡します：

レビュー進捗：
- [ ] ステップ1: 変更概要の把握
- [ ] ステップ2: 共通品質チェック
- [ ] ステップ3: 言語/フレームワーク固有チェック
- [ ] ステップ4: approve/reject判定
- [ ] ステップ5: レビュー結果の出力

ステップ1: 変更概要の把握

.pr-triage.json が存在する場合: このファイルを読み込み、summary、files、change_categories、diff_summary を使用する。以下の手動確認はスキップしてステップ2へ進む。

変更内容を理解する。

1. 変更ファイル一覧を確認 - 変更の範囲とスコープを把握
2. コード差分を確認 - 追加・変更・削除された内容を把握
3. 変更の意図を理解 - PR説明やコミットメッセージから目的を確認

確認すべきポイント：

• 変更は単一の目的にフォーカスしているか
• スコープが適切か（1つのPRで多すぎる変更をしていないか）
• 関連する変更が漏れなく含まれているか

ステップ2: 共通品質チェック

.pr-triage.json が存在する場合: surface_issues に含まれるMinor/Suggestionの問題は既にチェック済み。ここではCritical/Majorレベル（セキュリティ、ロジック・正確性、パフォーマンスの重大問題）の検出に集中する。表層的な問題（命名規則、デストラクチャリング等）は再チェック不要。

言語に依存しない汎用的なチェックを実施する。

2-1. セキュリティ

チェック項目	重要度
ハードコードされた秘密情報（APIキー、パスワード、トークン）がないか	Critical
ユーザー入力の適切なバリデーション・サニタイズがあるか	Critical
SQLインジェクション、XSS、コマンドインジェクションの脆弱性がないか	Critical
認証・認可のチェックが適切に実装されているか	Critical
機密データが不用意にログ出力されていないか	Major
CORS設定が適切か	Major

認可（Authorization）の詳細レビュー：認可に関わる変更がある場合は、references/authorization-review-general.md を参照して詳細なチェックを行う。PostgreSQL RLSを使用している場合は、追加で references/authorization-review-postgres-rls.md も参照する。

2-2. ロジック・正確性

チェック項目	重要度
エッジケースが適切に処理されているか（null、空配列、境界値）	Major
エラーハンドリングが適切か（例外の握りつぶし、不適切なcatch）	Major
条件分岐のロジックが正しいか（off-by-one、論理演算子の誤り）	Major
非同期処理の競合状態（race condition）がないか	Major
リソースの確実な解放（ファイル、接続、ロック）	Major

2-3. 設計・保守性

チェック項目	重要度
関数/メソッドの責務が単一か	Minor
DRY原則: 不要な重複コードがないか	Minor
命名が意図を正確に表しているか	Minor
マジックナンバーや意味不明な文字列リテラルがないか	Minor
適切な抽象度で設計されているか（過剰な抽象化・不足）	Minor
循環参照・不適切な依存関係がないか	Major

2-4. パフォーマンス

チェック項目	重要度
N+1クエリなど非効率なデータアクセスパターンがないか	Major
不要なループやネスト、計算量の大きい処理がないか	Minor
メモリリークの可能性がないか	Major
大量データの適切なページネーション・ストリーミング処理	Minor

2-5. テスト

チェック項目	重要度
変更に対応するテストが追加/更新されているか	Major
エッジケースのテストが含まれているか	Minor
テストが実装詳細でなく振る舞いをテストしているか	Minor
テスト名がテスト対象の振る舞いを明確に表しているか	Suggestion

ステップ3: 言語/フレームワーク固有チェック

.pr-triage.json が存在する場合: required_references に記載されたリファレンスのみを読み込む。リストにないリファレンスは読み込まない（トークン節約）。

変更ファイルの言語/フレームワークに応じて、対応するリファレンスファイルを参照する。

参照可能なリファレンス：

言語/FW	参照先	種別
TypeScript	references/typescript-best-practices.md	内部リファレンス
React / Next.js	vercel-react-best-practices スキル（Vercel提供）	外部スキル

観点	参照先	種別
認可（一般）	references/authorization-review-general.md	内部リファレンス
認可（PostgreSQL RLS）	references/authorization-review-postgres-rls.md	内部リファレンス
GitHub PRレビュー	references/github-pr-review-actions.md	内部リファレンス
Claude Codeスキル	references/skill-review.md	内部リファレンス

参照ルール：

• TypeScriptの変更 → 内部リファレンスを読み込む
• React / Next.js の変更 → vercel-react-best-practices スキルを併用する（インストール済みの場合）
• 認可に関わる変更（認証/権限チェック、データアクセス制御等） → 認可リファレンス（一般編）を参照
• PostgreSQL RLSを使用している場合 → 認可リファレンス（RLS編）も追加で参照
• GitHub Actions等のCI環境でPRレビューを実行する場合 → GitHub PRレビューアクションを参照（コメント投稿・評価方法）
• SKILL.mdファイルが含まれる変更 → スキルレビューリファレンスを参照し、スキル品質チェックを追加実施する
• 複数の言語/FWにまたがる変更の場合は、すべての該当リファレンスを参照する
• リファレンスが存在しない言語の場合は、ステップ2の共通チェックのみで判断する

ステップ4: approve/reject判定

すべてのチェック結果に基づき、以下の基準でapprove/rejectを判定する。

問題の重要度と減点

重要度	説明	減点
Critical	マージ前に必ず修正が必要。セキュリティ脆弱性、データ損失リスク、重大なバグ	-3点/件
Major	優先的に修正すべき。ロジックの問題、パフォーマンス劣化、テスト不足	-2点/件
Minor	改善が望ましい。設計改善、可読性向上、軽微な問題	-1点/件
Suggestion	提案。ベストプラクティスの推奨、より良いアプローチの提示	-0.5点/件

判定基準

満点は10点とし、以下の基準で判定する。

判定	条件	アクション
Reject	Critical問題が1件以上ある	REQUEST_CHANGES
Reject	Major問題が3件以上ある	REQUEST_CHANGES
Reject	スコアが5点未満	REQUEST_CHANGES
Conditional Approve	Critical問題なし、Major 1-2件、スコア5点以上	APPROVE（改善点をコメント）
Approve	Critical/Major問題なし、スコア8点以上	APPROVE

判定フローチャート

Critical問題あり？ → Yes → Reject（REQUEST_CHANGES）
       ↓ No
Major問題が3件以上？ → Yes → Reject（REQUEST_CHANGES）
       ↓ No
スコア5点未満？ → Yes → Reject（REQUEST_CHANGES）
       ↓ No
Major問題が1-2件？ → Yes → Conditional Approve
       ↓ No
スコア8点以上？ → Yes → Approve
       ↓ No
Conditional Approve

ステップ5: レビュー結果の出力

.pr-triage.json が存在する場合: トリアージフェーズの surface_issues をレビュー結果の「検出された問題」テーブルにマージする（重複を除外）。スコアリングにはトリアージの指摘も含める。

以下のフォーマットでレビュー結果を出力する。

GitHub上でのレビュー投稿：GitHub Actions等のCI環境でPRレビューを実行している場合のみ、references/github-pr-review-actions.md を参照して、ghコマンドやインラインコメントを使用してレビュー結果をGitHub上に投稿する。ローカル環境での実行時は、結果を標準出力に表示するのみとする。

修正済み問題のフォローアップ：.pr-triage.json に resolved_issues が含まれる場合（インクリメンタルレビュー時）、元のインラインコメントにリプライして修正を報告する。レビュー完了後、投稿したコメントIDを .pr-review-state.json に記録する。

## Code Review: [判定結果]

### 変更概要
- **スコープ**: [変更の概要を1-2文で]
- **変更ファイル数**: [N]ファイル
- **主な言語/FW**: [検出された言語/FW]

### スコア: X/10

### 検出された問題

| # | 重要度 | ファイル | 問題 | 推奨される対応 |
|---|--------|---------|------|---------------|
| 1 | [Critical/Major/Minor/Suggestion] | [ファイルパス:行番号] | [問題の説明] | [対応方法] |

### 良い点
- [コードの良い点を具体的に記載]

how to use code-review
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use code-review on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add code-review
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/xtone/ai_development_tools --skill code-reviewcopy
The skills CLI fetches code-review from GitHub repository xtone/ai_development_tools and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/code-review
Reload or restart Cursor to activate code-review. Access the skill through slash commands (e.g., /code-review) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?