CodeCraft Lab

コードレビューをClaude Codeに任せる

レビュー観点の構造化、段階的レビュー、チーム基準のドキュメント化まで、コードレビューを体系的に設計する方法を学びます

実践23分で読了
コードレビューREVIEW.mdCLAUDE.mdチーム運用

このレッスンで学ぶこと

  • レビュー観点（セキュリティ・パフォーマンス・可読性・設計）を構造化して指示する方法
  • 差分レビュー → 設計レビュー → 全体レビューという段階的なレビュー戦略
  • チームのレビュー基準をCLAUDE.md / REVIEW.mdに落とし込み、組織として再現性のあるレビューを行う方法

前提条件

  • 入門コースを修了していること（特にLesson 5「日常ワークフロー」でコードレビューの基本に触れていること）
  • gh CLIがセットアップ済みで、GitHubリポジトリで作業していること

なぜ「レビュー観点」を構造化する必要があるのか

Claude Codeに「このコードをレビューして」とだけ伝えても、それなりに有用な指摘は返ってきます。しかし、実務でのコードレビューが難しいのは、観点が一つではないことです。

セキュリティの専門家なら入力値検証や認可漏れを探します。パフォーマンスに詳しいエンジニアならN+1クエリや不要な再レンダリングを疑います。可読性を重視する人は命名や責務の分離を気にします。設計を見る人はモジュール間の依存関係や拡張性を評価します。一人の人間がこれら全部を同時に高い精度で行うのは難しいように、Claude Codeも「とにかくレビューして」という指示だけでは、観点が偏ったり、表面的な指摘に留まったりします。

入門コースでは /code-review コマンドや基本的なレビュー依頼の方法を扱いました。このレッスンでは一歩進んで、レビューを「観点の集合」として設計し、目的に応じて使い分ける考え方を身につけます。

Claude Codeの標準レビューが見ているもの

/code-review のデフォルト動作は「正確性」に焦点を当てています。つまり、フォーマットの好みやテストカバレッジの不足ではなく、本番環境を壊しうるバグを探すように設計されています。セキュリティやパフォーマンスなど、それ以外の観点を見てほしい場合は、明示的に指示するか、後述するREVIEW.mdでガイダンスを追加する必要があります。

レビュー観点を4つの軸で構造化する

実務でのコードレビューを体系的に行うために、観点を4つの軸に分けて考えると指示が作りやすくなります。

観点主なチェック項目向いている変更
セキュリティ入力値検証、認証・認可、機密情報の取り扱い、インジェクション系の脆弱性認証まわり、外部入力を扱うAPI、ログ出力
パフォーマンスN+1クエリ、不要な再計算・再レンダリング、メモリリーク、スケーラビリティデータアクセス層、ループ処理、UIコンポーネント
可読性命名、関数の長さ、責務の分離、コメントの過不足長期的に保守されるコア機能
設計モジュール間の依存関係、抽象化の妥当性、拡張性、既存パターンとの整合性新機能の追加、アーキテクチャに関わる変更

すべての変更にすべての観点を適用する必要はありません。例えば設定ファイルの変更ならセキュリティと可読性だけで十分ですし、ホットパスのループ処理ならパフォーマンスを重点的に見るべきです。変更の性質に応じて観点を選ぶこと自体が、レビュー設計の一部だと考えましょう。

変更の性質を分類する

レビューを依頼する前に、変更がどのカテゴリに該当するかを自分で判断します。

このブランチの変更内容を要約して。
変更の性質（新機能/バグ修正/リファクタリング/設定変更）と、
影響を受けるレイヤー（API/DB/UI/インフラ）も教えて

観点を組み合わせてレビューを依頼する

分類結果に応じて、必要な観点を組み合わせて指示します。

この差分を以下の観点でレビューして:
 
1. セキュリティ: 入力値検証、認可チェックの漏れ、SQLインジェクション・XSSのリスク
2. パフォーマンス: N+1クエリの有無、不要なループ内DB呼び出し
 
可読性やコードスタイルの指摘は不要です。上記2点に絞ってください

観点を絞ることで、Claude Codeの注意がその領域に集中し、指摘の精度が上がります。

重大度を明示させる

指摘をそのまま受け取ると、軽微な指摘と致命的な指摘が同列に並んでしまいます。重大度の分類を依頼しましょう。

見つかった問題を重大度で分類して報告して:
- Critical: マージ前に必ず修正すべき
- Warning: 修正を推奨するが緊急ではない
- Note: 参考情報・将来的な改善提案

Claude Codeの組み込みレビュー機能でも、Important（修正必須）、Nit（軽微）、Pre-existing（既存バグ）という重大度タグが使われています。同じ考え方を自分のプロンプトにも取り入れると、レビュー結果の優先順位付けがしやすくなります。

観点を増やしすぎない

一度に4つすべての観点を詰め込むと、それぞれの観点でのレビューが浅くなりがちです。重要な変更ほど、観点ごとに分けて複数回レビューを依頼するか、後述するサブエージェントによる並行レビューを検討しましょう。

段階的レビュー戦略: 差分 → 設計 → 全体

経験豊富なレビュアーは、PRのサイズに応じてレビューの深さを変えます。Claude Codeでも同じように、3段階のレビュー戦略を使い分けることで、レビューの質とコストのバランスを取れます。

flowchart LR
    A["差分レビュー<br/>(diff単位)"] --> B{"設計に関わる<br/>変更か?"}
    B -->|Yes| C["設計レビュー<br/>(モジュール単位)"]
    B -->|No| E["完了"]
    C --> D{"大規模な<br/>機能追加か?"}
    D -->|Yes| F["全体レビュー<br/>(コードベース横断)"]
    D -->|No| E
    F --> E
 
    style A fill:#e8f4fd,stroke:#1a73e8
    style C fill:#fff3e0,stroke:#e65100
    style F fill:#fde8e8,stroke:#c0392b

第1段階: 差分レビュー

日常的な変更のほとんどは、差分レビューだけで十分です。/code-review がカバーするのもこの範囲で、アップストリームブランチからの差分と未コミットの変更が対象になります。

/code-review

特定のファイルや範囲を絞りたい場合は、対象を指定します。

/code-review src/api/payment.ts
/code-review main...feature/new-checkout

第2段階: 設計レビュー

新しいモジュールの追加や、複数ファイルにまたがる変更では、差分だけを見ても全体像はつかめません。変更箇所の「周辺」も含めてレビューしてもらう必要があります。

src/services/payment/ ディレクトリ全体の設計をレビューして。
今回追加したPaymentGatewayクラスが、既存のOrderServiceや
InventoryServiceとどう連携しているか、責務の分離が適切かを確認して。
 
具体的には:
- 各クラスが単一責任の原則に沿っているか
- 依存関係が循環していないか
- 既存のサービス層のパターンと一貫性があるか

設計レビューでは、Claude Codeに「diffだけでなく、関連ファイルを読んで判断してほしい」という意図を明確に伝えることが重要です。

第3段階: 全体レビュー

大規模な機能追加やアーキテクチャ変更の場合、コードベース全体への影響を確認する必要があります。この段階では、サブエージェントを使った並行レビューが有効です。

サブエージェントを使って、今回の決済機能追加がコードベース全体に
与える影響を多角的にレビューして:
 
1. セキュリティ: 決済情報の取り扱いに関するセキュリティリスク
2. 既存機能への影響: OrderService, NotificationServiceなど
   関連サービスとの整合性
3. テストカバレッジ: 重要なロジックがテストで保護されているか
 
それぞれの観点を独立したサブエージェントで調査し、結果を統合して報告して

サブエージェントは独立したコンテキストで動作するため、メインの会話のコンテキストウィンドウを圧迫せずに、複数の観点から深く調査できます。

段階を飛ばしてもいい場面

すべての変更で3段階すべてを踏む必要はありません。タイポ修正や1行のバグ修正であれば、差分レビューすら省略して直接マージすることもあるでしょう。段階的レビューは「変更の影響範囲に応じてレビューの深さを調整する」ための考え方であり、形式的な手続きではありません。

レビューコメントの品質を上げるテクニック

Claude Codeのレビュー指摘をそのまま使うと、抽象的すぎたり、逆に冗長すぎたりすることがあります。コメントの質を上げるための具体的なテクニックを紹介します。

根拠を求める

「ここは問題があります」という指摘だけでは、レビューを受ける側が納得できないことがあります。根拠を明示するよう求めましょう。

指摘事項には、なぜ問題なのか（根拠）と、
該当箇所のfile:line を必ず含めて報告して。
推測ではなく、実際のコードを読んだ上での指摘にして

修正案までセットで出させる

指摘だけでなく、修正の方向性も併せて提示させると、レビューを受ける側の手戻りが減ります。

問題点の指摘に加えて、簡潔な修正案も提示して。
ただし、コードを直接書き換えず、まずは提案として報告して

ノイズを抑える

軽微な指摘が大量に出ると、本当に重要な指摘が埋もれてしまいます。件数を制限する指示が有効です。

重大な問題（Critical/Warning）のみを報告して。
スタイルの好みレベルの指摘は、まとめて1行で件数だけ報告して
フィードバックループを意識する

Claude Codeの組み込みレビュー機能には、各指摘に👍/👎で評価する仕組みがあります。これは「このレビューが役に立ったか」をチームで蓄積していく考え方です。自分のプロンプトでも、「過去にこの種の指摘は不要だった」という学びをCLAUDE.mdやREVIEW.mdに反映していくと、レビューの精度が継続的に上がっていきます。

チームのレビュー基準をドキュメント化する

個人のプロンプト力に依存したレビューは、チームに展開できません。レビュー基準を文書として残すことで、誰がClaude Codeを使っても一定の品質のレビューが行えるようになります。

CLAUDE.mdとREVIEW.mdの使い分け

ファイル役割適用範囲
CLAUDE.mdプロジェクト全体の共有コンテキスト（コーディング規約、アーキテクチャ方針など）すべてのタスク（レビューだけでなく実装・調査全般）
REVIEW.mdレビュー専用のガイダンス。重大度の基準やスキップルールなどレビュー時のみ

CLAUDE.mdに書いたルールへの違反は、レビュー時には軽微な指摘として扱われる傾向があります。一方REVIEW.mdの内容は、レビューのたびに最優先の指示として扱われます。「レビューでは厳しくチェックしたいが、通常の実装作業では気にしなくてよい」ようなルールはREVIEW.mdに書くのが適切です。

REVIEW.mdの設計例

# レビュー指示
 
## Importantの基準
以下に該当する場合のみCriticalとする:
- データの不整合を引き起こすロジックエラー
- セキュリティ脆弱性（SQLインジェクション、XSS、認証バイパス等）
- 本番環境でクラッシュする可能性のあるバグ
 
スタイルや命名の指摘は最大でもWarning止まりとする。
 
## 指摘の上限
1回のレビューで報告するWarning以下の指摘は最大5件まで。
それ以上見つかった場合は、件数のみをサマリーで報告する。
 
## レビュー対象外
- フォーマットやスタイルの指摘（CI/リンターに任せる）
- `src/gen/` 以下の自動生成コード
- *.lock ファイル
 
## リポジトリ固有のチェック
- 新しいAPIエンドポイントには統合テストがあること
- ログにメールアドレスやユーザーIDを含めないこと
- 決済関連の変更には、必ずセキュリティ観点のチェックを含めること
ドキュメントは短く保つ

REVIEW.mdもCLAUDE.mdも、長くなるほど重要なルールが埋もれます。「このルールを削除したら、Claude Codeは間違った判断をするか?」と自問し、答えがNoなら削除しましょう。長すぎるドキュメントは、結果的にレビュー精度を下げます。

チームへの展開フロー

flowchart TD
    A["個人でレビュープロンプトを<br/>試行錯誤する"]
    B["うまくいったパターンを<br/>言語化する"]
    C["REVIEW.md / CLAUDE.mdに<br/>ルールとして追加する"]
    D["PRでチームメンバーに<br/>レビューしてもらう"]
    E["実際の指摘結果を見て<br/>ルールを調整する"]
 
    A --> B --> C --> D --> E --> C
 
    style C fill:#e8f4fd,stroke:#1a73e8

ルールは一度書いたら終わりではなく、実際のレビュー結果を見ながら継続的に調整していくものです。「想定外の指摘が多い」「重要な指摘が漏れる」といった気づきがあれば、その都度ドキュメントを更新しましょう。

レビュー結果をPRコメントとして自動投稿する

レビュー結果をローカルで確認するだけでなく、PR上にコメントとして残すことで、チームメンバーにも結果を共有できます。

/code-review --comment

このオプションを使うと、問題が見つかった行にインラインコメントとして投稿されます。投稿前に内容を確認したい場合は、まず --comment なしで実行し、内容を確認してから投稿しましょう。

# まず確認
/code-review
 
# 内容に問題なければ投稿
/code-review --comment

gh CLIと組み合わせれば、特定のPRに対してカスタムフォーマットでコメントを投稿することもできます。

gh pr diff 123 を取得して、セキュリティとパフォーマンスの観点でレビューして。
結果を以下のフォーマットでPR 123にコメントとして投稿して:
 
## レビュー結果
### Critical
（あれば記載）
### Warning
（あれば記載）
### 良かった点
（ポジティブな指摘も1つ以上含める）
自動投稿は人間のレビューの代替ではない

自動レビューの結果を過信せず、最終的なマージ判断は必ず人間が行いましょう。Claude Codeのレビューは「明らかな問題を事前に潰す」ためのものであり、ビジネスロジックの妥当性や設計判断の良し悪しは、文脈を理解した人間が確認する必要があります。

よくある質問

Q. レビュー観点を全部指定すると逆に遅くならないですか?

観点を増やすほど一度のレビューにかかる時間とコストは増えます。日常的な小さな変更では1〜2観点に絞り、重要な変更（決済・認証まわりなど）でのみ複数観点を組み合わせるのが現実的なバランスです。

Q. REVIEW.mdとCLAUDE.mdの内容が重複したらどうなりますか?

REVIEW.mdの指示はレビューパイプラインで最優先として扱われるため、内容が競合する場合はREVIEW.mdが優先されると考えてよいでしょう。ただし重複自体は読みにくさにつながるので、レビュー専用のルールはREVIEW.mdに一本化し、CLAUDE.mdには汎用的なプロジェクト知識だけを残すのがおすすめです。

Q. 個人開発でもREVIEW.mdを作る意味はありますか?

あります。チーム展開を考えなくても、「過去に何度も同じ指摘をされた/見落とした」パターンをルール化しておけば、未来の自分に対する一貫したレビュー基準になります。

まとめ

  • レビュー観点（セキュリティ・パフォーマンス・可読性・設計）を構造化し、変更の性質に応じて組み合わせる
  • 差分レビュー → 設計レビュー → 全体レビューの3段階で、変更の影響範囲に応じてレビューの深さを調整する
  • 根拠の明示、修正案の提示、件数制限などでレビューコメントの品質を上げる
  • レビュー基準はCLAUDE.md（汎用）とREVIEW.md（レビュー専用）に分けてドキュメント化し、チームで再現性のあるレビューを実現する
  • /code-review --comment でレビュー結果をPRコメントとして自動投稿できるが、最終判断は必ず人間が行う
さらに実践的な手順を知りたい場合

PRレビューの具体的なコマンド操作やgh CLI連携の詳細は、実践レシピ「PRレビューをClaude Codeで効率化する」も参考にしてください。このレッスンで学んだ「観点の構造化」を、実際のワークフローに落とし込む際のヒントになります。

次のステップ

レビューで「問題がある」とわかったコードを、どう安全に直していくか。次のLesson 2では、リファクタリングを安全に進めるための計画立案とワークフローを学びます。

レビューと同様、リファクタリングも「思いつきで進める」と事故につながります。次のレッスンで、影響範囲の特定からリスク評価、段階的な実施までを体系的に扱います。