こんにちは。
エンジニアのm_mogiです。
今回は Claude Code を使って PR レビューの品質と効率を上げた話について書いていきます。
はじめに
コードレビューは大事ですが、時間がかかります。複数の観点（設計、コード品質、セキュリティ、テストなど）を漏れなくチェックしようとすると、1つのPRに対してかなりの集中力が必要です。
社内で Claude Code が使えるようになったので、レビューの一次チェックを任せられるようになりました。
やり方
基本の流れ
-
claude.md（グローバル設定）にレビュー用のプロンプトを記述 - Claude Code に PR の URL を貼り付ける
-
ghコマンドで差分を取得し、観点に沿ってレビューしてくれる
工夫したポイント
観点を列挙するだけでは漏れる
最初は「以下の観点でレビューして」と箇条書きで渡していましたが、出力にムラがありました。ある観点は詳しく見てくれるのに、別の観点はスキップされる、ということが起きます。
対策：出力フォーマットを固定した
「観点別チェック」として 1〜11 を順番に出力させ、該当なしでも明記するルールにしました。これで漏れがなくなりました。
指摘の確度レベルを分ける
AIの指摘は「明らかなバグ」から「好みの問題」まで混在しがちです。レビューを受ける側が優先度を判断しやすいように、確度レベルを定義しました。
- 🔴 要修正：明らかに問題がある
- 🟡 確認事項：改善の余地があるが、設計意図次第で妥当な場合も
- 🟠 推測：確認を求めたい
Notion連携で設計書も参照
Claude CodeにはMCP（Model Context Protocol）でNotionを接続できます。これを活用して、PRの説明文から設計書を自動取得し、レビュー観点に加えることができました。
具体的には、プロンプトに「レビュー前の準備」というステップを追加しました：
-
gh pr viewでPR説明文を取得 - 説明文にNotionリンクがあれば
notion-fetchでページを取得 - 取得した資料と実装の整合性を確認観点に追加
出力フォーマットにも「関連資料との整合性」セクションを設け、設計書の内容と実装が一致しているかを項目ごとにチェックさせています。
これにより、コードだけ見ても判断できない「設計意図との整合性」という観点でのレビューが可能になりました。
claude.md の設定例
# コードレビュー
GitHub PR URL が貼られたら、以下の観点でレビューを実行する。
## レビュー前の準備
1. `gh pr view` でPR説明文を取得
2. PR説明文にNotionリンクがあれば `notion-fetch` でページを取得
3. 取得した資料と実装の整合性を確認観点に追加
## 確認観点
### 1. 設計・アーキテクチャ
- 追加されたファイルの配置は妥当か、既存機能と重複していないか
- 変更が既存の設計パターンと一貫しているか
### 2. コード品質
- 型定義は適切か、Linterルールに準拠しているか
- 命名規則、単一責任、DRY原則は守られているか
### 3. エラーハンドリング・堅牢性
- 入力値検証があるか、エッジケース(null、空配列、境界値)を考慮しているか
- 例外処理、リトライ・タイムアウト制御が適切か
### 4. パフォーマンス
- 計算量・メモリ使用は適切か
- N+1クエリ、不要な再レンダリングはないか
### 5. セキュリティ
- 入力サニタイゼーション(XSS、SQLインジェクション対策)があるか
- 認証・認可、機密情報の取り扱いは適切か
### 6. 運用保守性
- ログ出力があるか、ロールバック可能性は考慮されているか
### 7. 保守性・拡張性
- 可読性が高いか、複雑なロジックにはコメントがあるか
### 8. プロジェクト固有
- （プロジェクト固有の観点があれば記載）
### 9. 影響範囲
- 既存コードへの影響・破壊的変更はないか
### 10. テスト
- テストは必要か、網羅性は十分か
### 11. PRスコープ
- 変更内容が単一の関心事に絞られているか
## 出力フォーマット
PR #XX レビュー結果
概要
- タイトル:
- 変更規模: +XX / -XX 行 (Xファイル)
- 変更内容サマリ: (テーブル形式)
- 関連資料: (Notionリンクがあれば記載、なければ「なし」)
---
関連資料との整合性 (Notionリンクがある場合のみ)
- 項目ごとに実装との一致/不一致を確認
---
観点別チェック
(1〜11を順番にチェックし、指摘事項または「該当なし」を記載)
---
総括
- 🔴 要修正: X件（具体的な箇所と内容）
- 🟡 確認事項: X件（具体的な箇所と内容）
- 🟢 良い点: X件
## 指摘の確度レベル
- 🔴 要修正: 明らかに問題がある
- 🟡 確認事項: 改善の余地があるが、設計意図次第
- 🟠 推測: 確認を求めたい
出力例
実際にPRをレビューさせた結果がこちらです（一部マスキング）。
⏺ PR #XX レビュー結果
概要
- タイトル: データ変換処理の機能追加
- 変更規模: +218 / -9 行 (8ファイル)
- 変更内容サマリ:
| カテゴリ | ファイル | 変更内容 |
|--------------|------------------------|----------------------------|
| 機能追加 | data_transformer.py | 新規データ形式への対応追加 |
| テスト基盤 | tests/, pyproject.toml | pytest環境の構築 |
| ドキュメント | README.md, docs/ | テスト関連ドキュメント追加 |
| 設定 | .gitignore | キャッシュ・ログ除外設定 |
- 関連資料: https://www.notion.so/example/Design-Doc-xxxxx
---
関連資料との整合性
- 資料種別: 設計書
- 入力パラメータ: ✅ 設計書通り（10項目）
- 出力形式: ✅ 設計書通り
- エラーハンドリング: ✅ 設計書記載の異常系を網羅
---
観点別チェック
(1) 設計・アーキテクチャ
🟢 良い点:
- 既存関数と同じパターンで新機能を追加しており、設計に一貫性がある
(2) コード品質
🟢 良い点:
- 命名規則、docstring形式が既存コードと統一されている
- 型ヒントが適切に使用されている
🟡 確認事項:
- コメントが古い表記のまま残っている箇所あり
(3) エラーハンドリング・堅牢性
🟢 良い点:
- 空配列のハンドリングが既存パターンと同様に実装
- インデックス境界チェックが適切
(4) パフォーマンス
🟢 該当なし
(5) セキュリティ
🟢 該当なし - 入力は内部システムからのみ
(6) 運用保守性
🟢 良い点:
- ログ出力設定追加でデバッグが容易に
- .gitignoreでキャッシュ混入を防止
(7) 保守性・拡張性
🟢 良い点:
- docstringに出力形式の例が記載されており可読性が高い
🟡 確認事項:
- 類似ロジックの関数が複数あり、今後共通化を検討する余地あり
(8) プロジェクト固有
🟢 該当なし
(9) 影響範囲
🟢 良い点:
- 既存の入力パラメータはそのまま維持されており後方互換性あり
(10) テスト
🟢 良い点:
- pytest基盤の追加
- 既存関数の単体テストが網羅的
🟡 確認事項:
- 新規追加した関数のテストがない。追加が望ましい
(11) PRスコープ
🟢 良い点:
- 機能追加とテスト基盤整備という関連性のある変更に絞られている
---
総括
- 🔴 要修正: 0件
- 🟡 確認事項: 3件
1. data_transformer.py:193 のコメントが古い表記のまま（「出力整形用」→「API連携用」への更新漏れ）
2. transform_to_format_a, transform_to_format_b, transform_to_format_c の3関数はロジックがほぼ同一。今後の拡張時に共通化を検討する余地あり
3. 今回追加した transform_to_format_c 関数のテストがない。主要な新規機能なのでテスト追加が望ましい
- 🟢 良い点: 5件
- 既存設計パターンとの一貫性
- 型ヒント・docstringの適切な使用
- pytest基盤の追加
- 後方互換性の維持
- 設計書との整合性が取れている
良かった点
- 短時間で明らかな問題に気づける：コメントの更新漏れ、テスト不足など、見落としがちな点を拾ってくれる
- 複数観点を一度にカバーできる：設計・品質・セキュリティ・テストなど、人力だと順番に見ていくところを並列でチェックしてくれる
- レビューの観点が標準化される：チーム内でレビュー品質のばらつきを減らせる可能性がある
課題
- 出力精度が安定しない：同じPRでも実行ごとに指摘内容が微妙に変わることがある。人力レビューを0にはできない
- 網羅的なレビューには至っていない：テスト観点、設計判断、命名の妥当性など、深い部分はまだ人間の目が必要
- コンテキストの限界：リポジトリ全体の設計思想や過去の経緯までは把握できない
まとめ
Claude Code を使った PR レビューは、人力レビューの「補助」として有効です。
特に「観点の漏れ防止」「一次チェックの時短」という点で効果を感じました。一方で、最終的な判断は人間が行う必要があり、AIレビューだけで完結させるのは現時点では難しいです。
今後は、レビュー観点のさらなる整備を進めつつ、GitHub Actionsなどと連携してPR作成時に自動でレビューを実行し、実装者がセルフチェック→修正するフローを組み込めると、より効率化できそうだと考えています。
最後まで読んでいただきありがとうございました。
Discussion