コード変更レビュー は何をしますか?
変更を、経験豊富なシニアエンジニアのようにレビューします。意味のある欠陥を見つけ、それぞれを証明し、作成者が迅速に対処できるように報告します。本当のバグを3つ含む短いレビューは、30の「かもしれない」を含む長いレビューよりも優れています。なぜなら、偽陽性が増えると読者は内容を読み飛ばすようになるからです。
ワークフロー
1. 変更セットを特定する
コードを読む前に、何がレビュー対象かを正確に特定します。ユーザーが指定しなかった場合、デフォルトでベースブランチにまだ含まれていないすべての変更が対象となります。
| 対象 | 取得方法 |
|---|---|
| コミットされていない作業 | git diff HEAD (さらに git status で追跡されていないファイルを確認し、それらを読む) |
| ステージングのみ | git diff --cached |
| 現在のブランチ | git diff $(git merge-base HEAD <base>) ( <base> は通常 main/master ) |
| コミット範囲 | git diff A..B |
| プルリクエスト (番号またはURL) | gh pr view <n-or-url> で説明、ベース、ヘッドを取得; gh pr diff <n-or-url> で差分を取得; gh pr diff <n-or-url> --name-only でファイル一覧を取得 |
| 特定のファイル | ファイルを読み、何から変更されたかが重要な場合はユーザーに尋ねる |
プルリクエスト。 「PR 123をレビューして」や「review PR #123」は、現在のリポジトリのPR 123を意味します。URL (https://github.com/<owner>/<repo>/pull/<n>) はそのまま gh に渡すことができ、別のリポジトリでも任意のディレクトリから機能します。GitLabのマージリクエストの場合は glab mr view / glab mr diff を使用します。差分だけでは十分なコンテキストが得られないため(ステップ3)、PRバージョンのファイルも読む必要があります:
-
PRが現在のリポジトリからのものである場合、ブランチを切り替えずに、PRとそのベースを専用のrefにフェッチします。このrefは強制更新されるため、リベースされたPRは以前のレビューのコピーを置き換えます。PRのベースリポジトリを指すリモートからフェッチします(
git remote -vで確認)。フォークの場合、通常はoriginではなくupstreamです:git fetch <remote> <base> +refs/pull/<n>/head:refs/review/pr-<n> git rev-parse refs/review/pr-<n> # must equal: gh pr view <n> --json headRefOid --jq .headRefOidフェッチが失敗した場合、またはコミットが
headRefOidと一致しない場合は、処理を停止してその旨を伝え、間違ったコピーや古いコピーをレビューしないようにします。その後、git show refs/review/pr-<n>:<path>でファイルを読み、$(git merge-base refs/review/pr-<n> <remote>/<base>)と比較します。gh pr checkout <n>は、ユーザーがワーキングツリーの変更を許容する場合にのみ使用します。 -
別のリポジトリの場合は、
gh api "repos/<owner>/<repo>/contents/<path>?ref=<head-sha>"を使用してPRヘッドのファイルを読みます(?はzshでグロブ文字として解釈されるため引用符で囲む)。レビューに多くのコンテキストが必要な場合は、一時ディレクトリにクローンします。 -
既存のフィードバックを読み、すでに指摘されたり回答されたり解決されたりした内容を繰り返さないようにします。
gh pr view <n> --commentsはトップレベルのコメントのみを表示します。インラインのレビュースレッド、その返信、および解決済みかどうかはGraphQLから取得します:gh api graphql --paginate -F owner=<owner> -F repo=<repo> -F n=<n> -f query='query($owner:String!,$repo:String!,$n:Int!,$endCursor:String){repository(owner:$owner,name:$repo){pullRequest(number:$n){reviewThreads(first:100,after:$endCursor){pageInfo{hasNextPage endCursor} nodes{id isResolved isOutdated path line comments(first:100){totalCount nodes{author{login} body}}}}}}}'--paginateは最初の100件を超えてスレッドをたどります。comments.totalCountが100を超えるスレッドにはさらに返信があります。それらに依存する前に、node(id:<thread id>){... on PullRequestReviewThread{comments(first:100,after:<cursor>){…}}}でフェッチします。
また、意図も取得します: PRの説明、コミットメッセージ、関連するIssue、または存在しない場合はユーザーに1行で尋ねます。コードが何をすべきかを知らなければ、正しいかどうかを判断できません。
非常に大きな変更(約1,500行を超える変更行)の場合は、まずトリアージを行います。ファイルをリスク順にランク付けします(認証、支払い、データマイグレーション、並行性、公開API、削除されたものは、ドキュメント、生成コード、ロックファイルの前に来ます)。どのファイルが簡易チェックになったかを伝えます。
2. 変更が影響する言語のガイダンスをロードする
変更セット内の言語とファイルタイプに対してのみリファレンスファイルをロードし、すべてをロードすることは決してありません。各ファイルは、レビュー対象のコードを圧迫するコンテキストを追加します。
Pythonが利用可能な場合(python または python3)、検出器を実行します:
python <skill-dir>/scripts/detect_languages.py --git <base> # ブランチ vs ベース
python <skill-dir>/scripts/detect_languages.py --git HEAD # コミットされていない作業
python <skill-dir>/scripts/detect_languages.py --git <remote>/<base> --head refs/review/pr-<n> # フェッチしたPR
git diff --name-only ... | python <skill-dir>/scripts/detect_languages.py # 任意のファイルリスト
プルリクエストの場合は、ステップ1でフェッチしたrefを --head で使用します。これにより、検出器はPRのコミットからシェバングを読み取ります。これは、ワーキングツリーにPRの新しいスクリプトがないか、異なるバージョンが存在する可能性があるためです。別のリポジトリのPRの場合、gh pr diff <url> --name-only | python <skill-dir>/scripts/detect_languages.py でファイルリストが得られますが、ファイルの内容は参照できません。リスト内のすべての拡張子のないファイルの最初の行をチェックします。マッピングされているかどうかを問いません(migrations/ 以下のPythonスクリプトは既に sql.md にマッピングされていますが、python.md も必要です)。PRヘッドで読み取るか、PRが削除する場合はベースで読み取り、以下のシェバングテーブルでルーティングします。
これにより、読み取るリファレンスファイルと、それぞれをトリガーした変更ファイルが出力されます。Pythonがない場合は、以下のテーブルを使用します。これは検出器と完全に一致します。ファイル名は大文字小文字を区別せずに一致します。
| 変更されたファイル | 読み取るファイル |
|---|---|
.py, .pyi, .pyw, .ipynb, pyproject.toml, setup.py, setup.cfg, requirements.txt, Pipfile, Pipfile.lock, poetry.lock, uv.lock | references/languages/python.md |
.js, .jsx, .mjs, .cjs, .ts, .tsx, .mts, .cts, .vue, .svelte, .astro, package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, tsconfig.json | references/languages/javascript-typescript.md |
.go, go.mod, go.sum, go.work | references/languages/go.md |
.rs, Cargo.toml, Cargo.lock | references/languages/rust.md |
.java, .kt, .kts, .scala, .sc, .groovy, .gradle, pom.xml, build.gradle, settings.gradle, gradle.properties | references/languages/java-kotlin.md |
.cs, .fs, .fsx, .vb, .csproj, .fsproj, .vbproj, .sln, .razor, .cshtml, Directory.Build.props, Directory.Packages.props, NuGet.config, global.json | references/languages/csharp-dotnet.md |
.c, .h, .cc, .cpp, .cxx, .c++, .hpp, .hh, .hxx, .inl, .ipp, .m, .mm, CMakeLists.txt, Makefile, meson.build, conanfile.txt, vcpkg.json | references/languages/c-cpp.md |
.rb, .erb, .rake, .gemspec, .ru, Gemfile, Gemfile.lock, Rakefile, config.ru | references/languages/ruby.md |
.php, .phtml, composer.json, composer.lock | references/languages/php.md |
.swift, .pbxproj, Package.swift, Package.resolved, Podfile | references/languages/swift.md |
.sql, .psql, .pgsql, .ddl、および migration/、migrations/、migrate/、alembic/versions/、flyway/、liquibase/ 以下の任意のファイル | references/languages/sql.md |
.sh, .bash, .zsh, .ksh, .fish, .ps1, .psm1, .psd1, .bat, .cmd | references/languages/shell.md |
.tf, .tfvars, .hcl, .dockerfile, Dockerfile, Dockerfile*, Containerfile, .dockerignore, compose*.yml, compose*.yaml, docker-compose*.yml, docker-compose*.yaml, Chart.yaml, values.yaml, kustomization.yaml, .gitlab-ci.yml, azure-pipelines.yml, bitbucket-pipelines.yml, Jenkinsfile、.circleci/ 以下の任意のファイル、および .github/workflows/、.github/actions/、k8s/、kubernetes/、helm/、charts/、manifests/、deploy/、deployment/、kustomize/、argocd/ 以下のYAMLファイル | references/languages/infrastructure.md |
拡張子のないファイルは、そのシェバング行のインタプリタによってルーティングされます(#!/usr/bin/env deno、#!/usr/bin/python3)。バージョンサフィックスは無視されます。
| シェバングインタプリタ | 読み取るファイル |
|---|---|
python | references/languages/python.md |
node, deno, bun, ts-node, tsx | references/languages/javascript-typescript.md |
ruby | references/languages/ruby.md |
php | references/languages/php.md |
sh, bash, zsh, ksh, dash, fish, pwsh | references/languages/shell.md |
1つのファイルが2つのリファレンスを必要とする場合があります。RailsやAlembicのマイグレーションは、その言語ファイルと sql.md を必要とし、検出器は両方を報告します。リファレンスファイルがない言語でも、完全なレビューが行われます。以下の一般的な観点がカバーし、その言語の一般的な落とし穴についてあなたが知っていることを適用する必要があります。埋め込まれた言語もカウントされます: Python内のSQL文字列やGoで構築されたシェルコマンドは、sql.md または shell.md をロードする理由になります。
3. 差分を超えたコンテキストを構築する
差分は何が変更されたかを示しますが、何に影響するかは示しません。何かを判断する前に:
- 変更行だけでなく、各ハンクの周辺コードを読む。多くのバグは、新しい行が古い行とどのように相互作用するかに存在します。
- 変更されたすべての関数、型、スキーマ、設定キー、エンドポイントの呼び出し元と依存先を見つける(grep、LSPの参照検索)。爆発半径は差分からは見えません。
- プロジェクトの規約を学ぶ: リンターとフォーマッターの設定、
CLAUDE.md/CONTRIBUTING.md、そして近くのコードがエラー、ロギング、テストをどのように処理しているか。一般的な好みではなく、このコードベースとの一貫性を基準に判断します。 - 新しいユーティリティコードを受け入れる前に、既存のヘルパーを検索する。リポジトリが既に持っているものを再実装することは、差分の外を見なければわかりません。
4. 観点ごとに、優先順位に従ってレビューする
このリストの上から順に作業します。ティア1のバグは、ティア3の指摘がいくつあっても重要です。references/review-angles.md に各観点の完全なチェックリストがあります。重要なレビューの場合は必ず読んでください。
- 正しいか? 正確性とエッジケース、意図の忠実性(主張することを完全に実行しているか?)、エラーハンドリングと障害モード、並行性と共有状態、呼び出し元への爆発半径。
- リリースしても安全か? セキュリティ、API/スキーマ/ワイヤー互換性、データ整合性とマイグレーション、運用性(ロールアウト、ロールバック、可観測性)、新しい依存関係、プライバシー。
- 良いコードか? パフォーマンスと効率性、抽象度(修正は適切なレイヤーにあるか?)、重複と再利用、シンプルさ vs 過剰エンジニアリング、規約との一貫性、可読性。
- 検証されているか? 変更なしでは実際に失敗するテスト、ドキュメントとコメントの同期維持。
これらの観点の中に、ロードされた言語ファイルのチェックを適用します。それらは、その言語でこれらの問題が取る具体的な形式です。
5. 報告する前にすべての指摘を検証する
各候補の指摘について:
- 障害シナリオを書く: 具体的な入力または状態、次に誤った結果。書けない場合、それはおそらくバグではありません。
- コードを再読して、問題が既に処理されていないかを確認します: 上流のガード、バリデーター、それを除外する型、それをカバーするテスト。
- それが安価で安全な場合(単体テスト、REPLスニペット、型チェッカー、リンター)は実行し、指摘が不確かな場合に行います。
- 信頼度を評価する: 確認済み(追跡または再現済み)または 可能性あり(完全に証明できなかった信頼できるパス)。それより弱いものはすべて破棄します。不明瞭だが指摘しても害がない場合は、バグを主張するのではなく、質問として尋ねます。
6. 報告する
references/reporting.md を、重大度タグ、コメント形式、出力テンプレートに使用します。要約:
- 1行の判定から始めます: マージしても安全か、そして最大の問題があればそれ。
- 各指摘は、その重大度タグ
[CRITICAL]、[MAJOR]、[MINOR]、または[NIT]で始まり、次に1行の主張とそのファイル:行。本文では、この順序で、問題は何か、なぜ問題なのか(具体的な障害シナリオ)、および可能な場合は提案する修正または改善を説明します。 - 指摘を最も重大なものから順にリストします。デフォルトの上限は約10件です。省略した低重大度項目の数を記載し、ユーザーが尋ねた場合はそれらをリストします。
- 実際の欠陥がない場合、またはユーザーが徹底的なパスを求めた場合を除き、
[NIT]は含めないでください。 - カバーしなかったこと(スキップしたファイル、実行できなかったこと)で終わります。正直なスコープ注記はレビューの一部です。
プルリクエストに投稿するコメントにも同じタグファースト形式を使用し、指摘がレポートとPRで同じように読まれるようにします。ユーザーが要求した場合にのみPRに投稿します。references/reporting.md は、それらをインラインコメント付きの1つのレビューとして投稿する方法を示しています。
ホストが構造化された指摘ツールを提供する場合は、リストを印刷する代わりに同じ順序でそのツールを通じて報告し、それでも各指摘の要約をタグで開始します。
原則
- 意見よりも証拠。 すべての指摘はコードを引用します。「Xを検討してください」という理由のないものはノイズです。
- コードベースではなく、変更をレビューする。 変更が悪化させるか、それに依存する場合にのみ既存の問題をフラグし、それらを既存としてラベル付けします。
- 作成者の選択を尊重する。 異なるが同等に有効なアプローチは指摘ではありません。具体的なコストを挙げられる場合にのみ異議を唱えます。
- レビュー中に修正しない(依頼された場合を除く)。修正を提案し、ユーザーがそれらを適用するかどうかを決定できるようにします。