コードレビュー

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をスキップ — トリアージ結果の summary を使用する

• リファレンスの選択的読み込み — required_references に含まれるものだけを読む

• 表層チェックの省略 — surface_issues に含まれるMinor/Suggestion問題は既にチェック済みとして、Critical/Major分析に集中する

• 差分の効率的な確認 — 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へ進む。

変更内容を理解する。

• 変更ファイル一覧を確認 - 変更の範囲とスコープを把握

• コード差分を確認 - 追加・変更・削除された内容を把握

• 変更の意図を理解 - 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

検出された問題

良い点

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

判定

• 結果: [Approve / Conditional Approve / Reject]
• 理由: [判定理由の要約]

次のステップ

• [修正が必要な場合の具体的なアクション]

重要な注意事項

• レビューはコードの品質向上が目的であり、批判ではない。建設的なフィードバックを心がける

• 問題の指摘には必ず具体的な改善案を添える

• 変更の意図を尊重し、スタイルの好みではなく客観的な基準で判断する

• 自動検出が困難なドメイン知識やビジネスロジックの判断は、人間のレビュアーに委ねる

• Suggestionは強制ではなく、採用するかどうかは著者の判断に任せる