コードレビュースキル は何をしますか?
Gregory Brown の「Effective Code Reviews」(『Programming Beyond Practices』、2015年)に基づく、アウトサイドイン、リスク駆動型のコードレビュー手法です。
プラットフォーム統合やプロジェクト固有のチェックは、プロジェクトのルールとは別に定義されます。
セットアップ
このスキルのセットアップ、設定、オンボーディング、またはルールファイルの作成を求められた場合:
- 既存のプロジェクトルール(
.claude/rules/、CLAUDE.md)をすべて読み、既に設定されている内容を把握します。プロジェクトの設定に既に存在する規約、コマンド、チェックを複製しないでください。 - プロジェクトの Issue/PR リンク規則、CI 設定、リンター/フォーマッター設定、コードレビュープラットフォームの指標を検査します。
- 各スキル固有の決定について、ユーザーにインタラクティブな選択肢を提示し、各オプションの選択ダイアログを使用します:
- コンテキスト収集 — PR の関連 Issue やチケットを特定する方法(ブランチ名、PR 本文のキーワード、タスク管理統合)
- ビルド検証 — ビルドが成功していることを確認する方法(CI ステータスチェック、特定のコマンド)
- コーディング規約 — スキルのデフォルトを超えるプロジェクト固有のチェック(アーキテクチャルール、リンターで既に適用されているスタイルルール)
- 出力形式 — レビュー出力のカスタム構造、または組み込みフォーマットを使用
- 投稿メカニズム — レビューの投稿方法(GitHub PR コメント、インラインコメント、標準出力)
- 再レビュースレッド処理 — 再レビュー時に、自身の以前のフィンドスレッドをどう扱うか: 返信して解決(デフォルト — スレッド内で返信し、修正または回答されたスレッドを解決する)、返信のみ(スレッド内で返信するが、解決は人間に委ねる)、または サマリーのみ(以前のスレッドには決して触れず、サマリーでのみそのステータスを報告する)
- CI 統合 — このレビューをすべての PR で自動実行する GitHub Actions ワークフローを生成することを提案します。
.github/workflows/ディレクトリがまだ存在しない場合でも、常にこれを尋ねてください。これがプロジェクトの最初のワークフローになる可能性があります。モデルの選択肢を提示します: Opus(推奨) / Sonnet / Skip。デフォルト: Opus。
- ユーザーの選択のみを含む
.claude/rules/code-review.mdを作成します。ユーザーがデフォルトを受け入れた決定は省略します。スキルの組み込み動作がそれらを処理します。 - ユーザーが CI 統合を選択した場合:
a. このスキルにバンドルされているテンプレートファイル
assets/code-review.ymlを読み取ります。 b. ユーザーが別のモデルを選択した場合、--model opusを--model <選択されたモデル>に置き換えます。 c. プロジェクトに.github/workflows/code-review.ymlが既に存在する場合、差分を表示し、上書き前に確認を求めます。 d. ワークフローを.github/workflows/code-review.ymlに書き込みます(.github/workflows/が存在しない場合は作成します)。 e. リポジトリシークレットとしてCLAUDE_CODE_OAUTH_TOKENを追加するようユーザーに促します:- トークンをローカルで生成:
claude setup-token - 追加先: GitHub リポジトリ → Settings → Secrets and variables → Actions → New repository secret
- トークンをローカルで生成:
人間に委ねること(CI 統合): ユーザーは CLAUDE_CODE_OAUTH_TOKEN シークレットを追加し、ブランチ保護ルールがアクションによるレビューコメントの投稿を許可していることを確認する必要があります。セットアップではこれらを確認したり設定したりすることはできません。
ユーザーがすべてのデフォルトを受け入れ、選択がなかった場合、ルールファイルが不要であることを確認して停止します。
フェーズ 0: 以前のレビューステータス(再レビュー)
レビューを開始する前に、既に述べられていることを確認します。
この変更に関する既存のレビュー会話を収集します:
- すべてのインラインディスカッションスレッド(返信とその解決/未解決状態を含む)。あなたのものも人間のレビュアーのものも含みます。
- もし存在すれば、あなた自身の以前のレビューサマリー(フェーズ6で説明する非表示マーカーで識別)。
プロジェクトがプラットフォームの投稿メカニズムを定義している場合は、それを使用してこのステータスを取得します。プラットフォームメカニズムが設定されていない場合(たとえば、レビューが標準出力に出力される場合)、これを初回レビューとして扱い、サマリーで以前のレビューステータスを確認できなかったことを記載します。
以前のレビューステータスが存在しない場合、これは初回レビューです。フェーズ1に進み、フェーズ6の再レビューステップをスキップします。
すべてのスレッドを読み、自分のものにのみ行動します。 人間のレビュアーのスレッドはレビューの情報源として扱います。人間のレビュアーが既に提起した懸念を(回答の有無に関わらず)再提起しないでください。あなた自身のスレッドは、各フィンドに埋め込まれた非表示マーカー(フェーズ6参照)によって識別し、投稿アカウントでは識別しないでください。アカウントは CI 実行とローカル実行で異なります。
あなた自身の以前のフィンドごとに分類し、その処分をレビューの残りの部分に引き継ぎます:
- 修正プッシュ — 作成者がフィンドに応じてコードを変更した。現在の差分で修正をレビュー中に確認します。実際に修正済み: スレッド内でそれを確認(例:「<リビジョン> で修正されたことを確認しました」)し、スレッドを解決します。修正を主張しているが未修正: 何がまだ不足しているかを説明し、スレッドを開いたままにします。
- 回答済み — 作成者がフィンドを説明または異議を唱えた。その回答は信頼できるものとします。再提起しないでください。それを認める返信をし、スレッドを解決します。
- 未解決のまま — 応答なし、修正なし。重複コメントを投稿しないでください。スレッドには触れず、新しいサマリーの「以前のフィンド」セクションにリストします。
このレビューからの真に新しいフィンドは、通常通りフェーズ6で投稿されます。
プロジェクトが再レビュースレッド処理モード(セットアップ参照)を設定している場合は、それに従います。一部のチームではスレッド解決を人間が行うように予約しています。デフォルトは返信して解決です。
人間に委ねること: 意見の相違の調停。作成者が反論した場合、このスキルは譲歩します。問題のある点が依然として重要である場合、人間のレビュアーが判断を下さなければなりません。自動レビュアーがスレッドを解決できるかどうかは、チームの慣習です。人間が所有します(セットアップで設定)。
フェーズ 1: 問題の検証
ここから開始します — コードを1行も読む前に。
2つの質問をします:
- このコードは、解決すべき問題を実際に解決していますか?
- この改善を出荷することで、プロジェクト全体としての価値は高まりますか?
どちらかの答えが「いいえ」の場合 — 停止します。 コードをレビューしないでください。何を構築すべきかを決定する責任者に連絡し、話し合ってください。本番環境で生き残れないコードをレビューすることは時間の無駄です。
これらの質問に答えるために: リンクされた Issue またはチケット、関連ドキュメント、関連する議論を読みます。プロジェクトが関連 Issue やチケットを見つける方法(タスク管理統合、ブランチ命名規則)を定義している場合は、それに従います。Issue が存在しないか、統合が設定されていない場合は、PR のタイトルと説明を信頼できる情報源として使用します。差分が、説明された内容に妥当に対処しているかを確認します。
人間に委ねること: 実際に機能を実行し、ユーザーの視点から動作することを確認すること。述べられた問題と差分の間の論理的な整合性を検証することはできます。人間が実際に動作することを確認する必要があります。
フェーズ 2: ビルドと実行可能性
- ビルドは成功していますか?成功していない場合、レビューを一時停止します。壊れたビルドは信頼できません。新しい変更が正しく動作する場合でも、他の部分が壊れている可能性があります。ビルド障害が無害であると想定しないでください。
- コードは作成者のマシン以外のどこかで実行されていますか?本番環境が理想的です。ステージング環境または別の開発者のマシンでも、十分なスモークテストとなります。
- コードを実行するために誰かに助けを求める必要がありましたか?そうであれば、ドキュメントが不足しているか、セットアップを自動化する必要があるか、またはその両方です。
プロジェクトがビルドステータスの確認方法(CI システム、ステータスチェック)を定義している場合は、それを使用します。それ以外の場合は、変更コンテキスト内で利用可能なビルド指標を確認します。
人間に委ねること: コードをローカルまたはステージングで実行し、それを使用する人々の視点から機能を試し、ユーザビリティ、エラーハンドリング、または予期しない動作に関する懸念を提起すること。
フェーズ 3: テスト監査
変更または削除されたテストは危険信号です — 他の何よりも先に調査します。
既存のテストへの変更を見つけた場合、速度を落とします。理由を尋ねてください: なぜ変更されたのですか?意見を形成する前に理由を理解してください。
多くの変更は比較的無害です — 誤った動作のテストを削除する、テストの粒度を変更する、またはこの PR が置き換えるものを置き換える。これらのいずれも本質的に危険ではありませんが、思考を必要とします。重要な質問は次のとおりです: この変更は、コードベースの他の部分が依存する契約を変更しますか?
- 独立した自己完結型コードに対するテストの変更 = 比較的安全
- 共有または再利用されるコードに対するテストの変更 = リスクが高い。明確な正当化が必要
差分だけから質問に答えられない場合は、一時停止して作成者に尋ねてください。これらの会話は共通の理解を構築し、実際の損害が発生する前に誤った仮定を表面化させます。
フェーズ 4: カバレッジ評価
変更を分類し、リスクに適した期待値を適用します。合格したテストスイートは、それが記述する振る舞いと同じくらいしか価値がありません。テストをレビューするプロセスを自動化することはできません。
バグ修正
すべてのバグ修正にはリグレッションテストを伴うべきです。最低でも、バグ報告に記載された同じパスをたどる高レベルの受け入れテストを1つ — 実際のユーザーが取る可能性のあるアクションにマッピングし、内部障害の直接的なトリガーだけではないもの。
複雑または重大なものについては、ユニットテストで受け入れテストを補完し、将来何かが壊れたときに、よりきめ細かいフィードバックを提供します。
炭鉱のカナリアパターンも探します: このバグは本当にユニークなのか、それともより深く広範な問題の兆候なのか?コードベースの他の場所に類似のパターンが存在するか確認します。もし存在する場合、チケットを発行します — 今すぐすべてを修正する必要はありませんが、それらを明らかにすることは大きな貢献です。
新機能
ゼロテスト思考実験を適用します: 以下の条件がすべて満たされる場合、最小限のテストカバレッジでも許容されます:
- 変更がほぼすべて新しいコードで構成され、インフラストラクチャ、フレームワーク、ライブラリ、および汎用データアクセスオブジェクトにのみ依存している
- 新しい機能が独自の領域(独自のページ、名前空間、またはエンドポイント)に分離されている
- 新しいシステム全体の副作用を導入しない(依存関係、設定、または共有リソースへの負荷が変更されていない)
- ロードマップ上の他の機能の構成要素として使用される予定がない
- 他の機能を結びつけるワークフローチェーンの中間ステップではない
- 障害が外部に漏れて他の場所で不安定性を引き起こすことがない
- 考えられる障害がステークホルダーに受け入れ可能であり、重大な損害を引き起こさない
- テストを受け入れられないコストや遅延なしに後で作成できる
満たされない条件ごとに、そのリスクに特に対処するテストを期待します。障害が許容され、完全に分離され、後で簡単にテストできる機能は大きなリスクではありません。既存のワークフローに結びつき、他の場所で障害を引き起こす可能性がある、またはその上に構築される予定の機能は — そうです。
拡張: アドオン
既存の機能と並んで存在する新しいコード。上記の新機能の基準を適用し、さらに深く進みます。既存の機能の隣に存在するため、障害の分離が主要な関心事です。
アドオンの障害が既存の機能をダウンさせる可能性がありますか?最悪の障害シナリオを考えてみてください。エッジケースと境界条件はカバーされていますか?
拡張: エクステンション
既存のコンポーネントを再利用して、既存の動作上に構築します。新しいコードを評価する前に、再利用されているもののミニ監査を実施します:
- 再利用されたコンポーネントにはテストがありますか?
- ビジネスレベルおよび/またはコードレベルで文書化されていますか?
- 再利用を念頭に置いて設計されましたか、それとも元の目的を超えて引き伸ばされていますか?
- 最近または未解決のバグ報告に登場しましたか?
- 変更される可能性はどのくらいですか?もし変更された場合、このエクステンションは壊れますか?
これに数分以上費やす必要はありません。思考実験であり、深い調査ではありません。しかし、既知で計算されたリスクは、常に驚きよりも優れています。追跡する価値があるものにはチケットを発行します。
拡張: リファインメント
既存のシステム動作を変更します。最もリスクの高いカテゴリ。 まず、上記のエクステンションレビューのすべてを適用します。次にさらに深く進みます。
変更されるコードに依存する機能をすべて見つけます。各依存関係は潜在的に影響を受けます。理想的にはそれぞれを完全なレビュープロセスに通しますが、実際にはそれはほとんど不可能です。最低限: 依存関係を特定し、それらのテストがまだ有効かどうかを確認し、完全なリストを人間のレビュアーが手動でテストするためにフラグを立てます。
フェーズ 5: プロジェクト固有のチェック
プロジェクトがコーディング規約、アーキテクチャパターン、またはスタイルルールを定義している場合、それらを差分に適用し、違反がないか確認します。
プロジェクトの規約が定義されていない場合、以下を確認します: 差分内の一貫性のない命名、変更によって導入されたデッドコード、明白な重複、システム境界での欠落したエラーハンドリング、およびセキュリティ上の懸念(サニタイズされていない入力、ハードコードされたシークレット、過度に広い権限)。
プロジェクトがプラットフォーム固有の投稿メカニズム(レビューの投稿方法、インラインコメントの形式など)を定義している場合、次のフェーズでそれらに従います。
フェーズ 6: リスク評価と出力
リスクレベルを割り当てます:
- 低 — 隔離された変更、共有コードに触れていない、テストはクリーンで変更タイプに適切
- 中 — 既存の動作または共有コードに触れているが、十分にテストされ、依存関係が理解されている
- 高 — 依存関係を持つ共有コンポーネントを変更、変更タイプに対してテストが変更または欠落している、セキュリティや認証が関与
レビューサマリーを作成します。 以下を含めます:
- コンテキスト: PR が何をするか、どの問題を解決するか
- 良かった点
- 見つかった懸念事項(一般的なものと、該当する場合は行レベルのもの)
- 再レビューの場合: 新しい懸念事項の前に、以前のフィンドセクション。各以前のフィンドをステータスとともにリストします — 解決済み(修正を確認)、回答済み(作成者の回答を受け入れ)、または 未解決のまま。初回レビューではこのセクションを省略します。
- リスクレベルとその理由
人間のレビュアー向けのエグゼクティブサマリーを生成します:
- 指摘された各懸念事項の箇条書きリスト
- レビュアーが特に注目すべき項目のフラグ
- 注意が必要なテスト変更(存在する場合)
各フィンドに一意の非表示マーカーを埋め込みます。このマーカーにより、再レビュー中にツールが自身の以前のフィンドを識別できます。人間のレビュアーはこれを見る必要はありません。
プロジェクトが定義する投稿メカニズムに従います(フェーズ5で決定)。メカニズムが定義されていない場合、サマリーとすべてのフィンドを標準出力に出力します。
---
<!--- レビューツールマーカー: [一意のレビューID] -->
**レビューサマリー**
**コンテキスト**
このPRは…
**良かった点**
- …
**懸念事項**
- …
**リスクレベル:** [低/中/高]
**理由:** …
**人間のレビュアー向けエグゼクティブサマリー**
- 懸念事項1: …(高い注意が必要)
- 懸念事項2: …(中程度の注意)
このスキルは、Gregory Brown の「Effective Code Reviews」方法論に基づいています。詳細は著書『Programming Beyond Practices』(O'Reilly Media、2015年)を参照してください。