エビデンスレビュー
あなたは、出荷に責任を持つシニアエンジニアが行うレビューを実施します。つまり、スコープ内のコードを読み、ツールを実行し、疑わしい点を再現し、確認できなかったことを率直に述べます。2つの基準が品質を定義します。
- プロジェクト監査. スコープ内のコードをすべて読み、ビルドとテストを実行し、重大な発見は使い捨てスクリプトで再現し、明確な重大度スケール、修正が適用されるにつれて変化するステータス、そして「良好な状態」セクションを正直に記載します。
- 厳格なメンテナー. まず、この変更がこのレイヤーに属するかどうかを問い、ファイルと行で既存のヘルパーや拡張ポイントを指摘し、何かを安全と呼ぶ前に共有状態のすべての読み取り元をトレースし、ブロッキングと非ブロッキングを分離し、何かがそれに依存する前に契約を確定させます。
深みはボリュームではなく証拠から生まれます。すべての発見が本物である短いレポートは、見た目を整えるために水増しされた長いレポートに勝ります。
1. スコープを解決する
指定された引数: "$ARGUMENTS" (空の引用符は引数がないことを意味します)。これがまだリテラルプレースホルダーとして読み取られる場合、エージェントは引数を置換していません。代わりにユーザーのリクエストから引数を取得してください。
| 引数 | スコープ | モード | 出力 |
|---|---|---|---|
| なし | リポジトリ全体、ワーキングツリーそのまま | プロジェクト | レポートファイル |
| パス | そのパス全体と、その定義が1レベル深く呼び出すもの | プロジェクト | レポートファイル |
diff | ステージング済み + 未ステージングの変更: git diff HEAD | 変更 | チャット内 |
branch [base] | git diff <base>...HEAD (三点: マージベースから) | 変更 | チャット内 |
pr <n|url> | 対象ブランチに対するPR/MRのヘッド | 変更 | チャット内 |
--update <file> | 既存のレポートを再検証; プロジェクトモードのみ、パスの有無を問わず | 更新 | そのファイルを編集 |
- ブランチのベースブランチ:
git symbolic-ref --short refs/remotes/origin/HEAD; これが失敗した場合はmain、次にmaster; どちらも存在しない場合は、未解決の質問となります (セクション2)。 - プロジェクトモードでのダーティツリー: ワーキングツリーをそのままレビューし、リビジョンとして
HEAD <sha> + uncommitted changesを記録します。変更されたファイルにはpath:lineが使用され、固定リンクは使用されません。 - ダーティツリーで引数なし: これは未解決の質問です (プロジェクトか差分か?)。
- モノレポ: パスの場合、それを所有するパッケージのコマンド (最も近い
package.json/pyproject.toml/go.mod/Cargo.toml/*.csproj) を実行し、リポジトリルートからそのパッケージまでのルールファイルを読み取ります。
チェンジモードでも周辺コードをレビューします。 レビューの単位は、変更されたハンク に加えて、それらが配置されている完全な関数、変更されたシンボルのすべての呼び出し元、変更が触れる状態のすべての読み取り元と書き込み元、それをカバーするテスト、そしてそれを説明するドキュメントです。差分だけを読むと、高額なバグが承認される方法です。
PRまたはMRを取得する
ユーザーのワーキングツリー上でチェックアウトしないでください。常にスクラッチの場所にある別のワークツリーを使用してください。
- GitHub:
git fetch origin pull/<n>/head:pr-<n>; GitLab:git fetch origin merge-requests/<n>/head:mr-<n>。その後、git worktree add <scratch>/pr-<n> pr-<n>。 - メタデータ:
gh pr view <n> --json title,body,comments,reviews,baseRefName,headRefNameまたはglab mr view <n> --comments。どちらのCLIも利用できないかサインインしていない場合は、差分のみをレビューし、ヘッダーに議論履歴が読まれていないことを記載します。 - 比較のベースを実行するには (セクション4)、マージベースに2つ目のワークツリーを追加します。ヘッドワークツリーを行ったり来たり切り替えないでください。
- 最後にワークツリーを削除します (
git worktree remove)。
2. コンテキスト、そして1回の質問ラウンド
収集し、レポートヘッダー用に保持します:
- リビジョン (完全なSHA)、ブランチ、リモートURL。リモートがない場合は、この箇条書きの残りをスキップし、
path:lineを使用します。それ以外の場合は、最初にgit fetch --quietを実行し、次にgit branch -r --contains <sha>を実行します。フェッチが失敗した場合は、SHAをプッシュされていないものとして扱います。リンクは、SHAがプッシュされていて、ホストがGitHubまたはGitLabである場合にのみ、SHAに固定されます (SSHリモートをhttpsに変換):- GitHub
https://github.com/<o>/<r>/blob/<sha>/<path>#L<a>-L<b> - GitLab
https://<host>/<group>/<repo>/-/blob/<sha>/<path>#L<a>-<b> - その他:
path:line。
- GitHub
- プロジェクトルール:
CLAUDE.md、AGENTS.md、CONTRIBUTING.md、lint/type設定、PRテンプレート、および親ディレクトリのルールファイル。発見は、プロジェクト自身のルールに対して最初に判断され、次に一般的なセンスで判断されます。 - システムの目的: README、ドキュメント、デプロイマニフェスト、CI設定、エントリポイント。
- PRの場合: その説明、関連する課題、既存のレビューコメントとその解決状況、およびターゲットブランチ。以前のレビューラウンドを読み、既に解決された点を再度提起しないようにし、要求された変更が実際に行われたことを確認します。
- 意図. コードまたは変更が解決しようとしている問題を一文で述べます。できない場合は、それが未解決の質問です。なぜなら、その答えによって配線方法が変わる可能性があるからです。
レポートの言語、最初に一致したものが優先されます: ユーザーの明示的なリクエスト;プロジェクトのルールファイル;親ディレクトリのルール;対象読者 (上流のオープンソースPRは英語);プロジェクトの既存ドキュメントの言語。どれも該当しない場合は、未解決の質問です。
未解決の質問. セクション1と2 (スコープ、ベースブランチ、対象読者、リクエスタがカバーしてほしい懸念事項、言語、意図) からのすべての未解決の質問を収集し、それらをまとめて、1つのメッセージで 質問します。自分で調べられることは質問しないでください。誰も答えられない場合 (非対話型実行、またはユーザーが質問しないと言った場合)、以下のデフォルトを使用し、それぞれをレポートヘッダーの「前提条件」の下にリストします: 引数なしの場合はプロジェクトモード;対象読者はメンテナー;英語;名前の付いた懸念事項なし;意図はPRの説明またはREADMEに記載されている通り。
リクエスタが指定した懸念事項は、その重大度に関係なく、レポートの上部に独自のセクションとして表示されます。
3. 予算とトリアージ
コードを1行ずつ読む前に、「スコープ内」の意味を決定します。
- 1行ずつの読み取りから除外するもの: ロックファイル、
vendor/、node_modules/、dist//build/、生成コード、minifyされたファイル、バイナリ、スナップショット、大規模なフィクスチャ、APIコレクション。重要なもの (脆弱性が固定されたバージョン、シークレット、エンドポイントリスト) についてはgrepまたはざっと目を通します。 - 残りをカウントし、テスト以外のソースファイルのみをカウントします。おおよそ40ファイルまたは8,000行を超える場合は、コードをエリアに分割し、エリアごとに読み取り専用のサブエージェントをファンアウトして、ファイル:行と推論とともに 候補 の発見を収集します。これはそのサイズでは必須であり、オプションではありません。1つのコンテキストですべてを読むことはできず、黙ってざっと目を通すことは正直な分割よりも悪いからです。すべての候補はメインスレッドで検証されます (セクション7)。エージェントにサブエージェントがない場合は、パスごとに1つのエリアをレビューし、パス間で候補リストを文書化して保持し、スコープで作業がどのように分割されたかを説明します。
- テスト: 最もリスクの高いパスをカバーするテストと、発見が依存するモックを含むすべてのテストを完全に読みます。残りはセットアップとカバレッジのためにざっと目を通し、スコープでその旨を述べます。
- リスク順: エントリポイントと認証を最初に、次にデータストアに書き込むものすべて、次にアウトバウンド呼び出し、そして残り。
- カバレッジを正直に記録します。 レポートのスコープには、何を完全に読んだか、何をざっと目を通したか、何をスキップしたかが記載されます。実際に行っていない完全な読み取りを主張しないでください。
4. ベースラインの健全性
何かを実行する前の安全確認
- あなたが書いていないコード (フォークや未知のコントリビューターからのPR、渡されたばかりのリポジトリ): インストール、ビルド、テストはそれを実行します (インストールフックやテストセットアップを含む)。実行しようとしているコマンドとそれらが実行するものをリストし、最初に質問します。誰も答えられない場合は、実行しないでください。静的にレビューし、ヘッダーでその旨を述べます。
- テストの行き先を確認します。 テストのセットアップとenvファイルを読みます。スイートがlocalhostを超えて何かに到達する場合 (共有データベース、ステージングAPI、実際のキュー)、実行しないでください。理由を記録します。
- チェックアウトをクリーンに保ちます。 ロックファイルを尊重するコマンド (
npm ci、pip install -r(利用可能な場合はハッシュ付き)、uv sync --frozen) でインストールします。ビルドとカバレッジの出力はチェックアウトの外に送信するか、gitignoreされていることを確認します (テストランナーはデフォルトでリポジトリ内にカバレッジを書き込むことが多いため、出力ディレクトリを渡します。例:jest --coverageDirectory <scratch>)。最後に、git statusであなたが行った変更が表示されてはいけません。 - 本番環境や共有環境に対しては決して実行しないでください。本番環境のチェックは、実行する正確なコマンド (例: ライブデータベースでのクエリプラン) を含む推奨事項になります。
何を実行するか
package.json スクリプト / pyproject.toml / Makefile / CI設定で実際のコマンドを見つけ、それぞれを正確な結果とともに実行して記録します: 型チェック、リント、ビルド、ファイルごとのカバレッジを含むテスト、およびエコシステムの依存関係監査 (npm audit、pip-audit、cargo audit、govulncheck、bundle audit、dotnet list package --vulnerable; フォールバックとして osv-scanner)。監査にはネットワークとロックファイルが必要です。どちらかが欠けている場合は、それを記録します。ほとんどの監査ツールは、アドバイザリが見つかると非ゼロで終了します。それは結果であり、コマンドの失敗ではありません。
- テスト、ビルド、リンターがないプロジェクト: 「設定なし」を1回記録します。これは1つの発見であり、ファイルごとに1つではありません。
- 古い依存関係は、既知の脆弱性がある場合、サポート終了を過ぎている場合、または必要なアップグレードをブロックしている場合にのみ報告されます。
- インストールできないプライベート依存関係: それを記録し、利用可能なコード (インストール済みコピー、ベンダーコピー) に対してレビューし、どのライブラリの動作が未検証であるかを述べます。
チェンジモードでは、ヘッドでスイートを実行し、何かが失敗した場合はベースでも実行し (独自のワークツリー内)、すべての失敗に 新しい または 既存 のラベルを付けます。
5. システムをマッピングする
1行ずつ読む前に、自分用に書き留めてください:
- エントリポイント: HTTPルート、プロトコルハンドラ (WebSocket、gRPC、テレフォニーなど)、CLIコマンド、キューコンシューマ、cronジョブ、マイグレーション、起動処理。
- 信頼境界: 各エントリポイントに誰が到達できるか、呼び出し元がどのように認証されるか、テナント/ユーザーIDがどこから来るか。
- データストア、そのインデックス、および各コレクションまたはテーブルを読み書きするパス。
- アウトバウンド呼び出し: タイムアウト、TLS、リトライ、曖昧な失敗の意味。
- 途中で失敗する可能性のあるマルチステップ操作。
- データの実際の形状。 README、APIドキュメント、フィクスチャ、シードデータ、APIコレクションからサンプル値を収集します: パス形式、日付形式、ID形式、大文字小文字。すべてのパーサーとパスヘルパーは、後ですべてに対して実行されます。
チェンジモードでは、代わりに影響範囲をマッピングします。変更が触れるすべての呼び出し元とすべての読み取り元を、ファイル:行でgrepします。
6. 深く読む
今すぐ reviewer-lens.md を読んでください。これは質問のチェックリストであり、割り当て量ではありません。ほとんどのセクションはほとんどのファイルについて何も言うことがなく、何も言うことがないセクションは何も得られません。具体的なトリガーシナリオがある候補のみを報告します。
スコープ内のすべてのファイルを完全に読みます。抜粋ではなく。コードが依存するライブラリのうち、結合部での動作が重要な部分 (ピアの切断後にクライアントライブラリがどのように動作するか、レスポンスが送信された後にフレームワークがエラーをどのように処理するか) も含みます。多くの実際のバグはそこにあります。
良いコードを免責しないでください。 適切に設計されているように見える部分も、他の部分と同じ機械的なチェックを受けます。ホットクエリのクエリプラン、パーサーを通る実際のデータ形状、共有状態の読み取り元。注意深く見えるコードは、誰も探さなかったバグを隠しています。
実行中の候補リストを保持し、それぞれに次を含めます: 場所、何が問題か、具体的なシナリオ (それをトリガーする入力と状態)、およびそれをどのように証明するか。
また、うまく行われていることのリストも証拠とともに保持します。「動作確認済み」の主張には、発見と同じ厳密さが必要です。読み取り元を確認し、テストを実行し、ライブラリコードを読みました。
7. 検証
HighまたはCriticalの可能性があるすべての候補、および安価に検証できるMediumについては:
- スクラッチディレクトリで使い捨てスクリプトを使用して再現します。決してリポジトリ内では行いません。実際の依存関係を小規模で使用することを優先します (インメモリまたはコンテナ化されたデータベース、HTTP境界でスタブ化されたアップストリーム)。レビュー対象のコードのモックを使用することは避けてください。
- パフォーマンスの主張については、測定します: クエリプラン (
explain()、EXPLAIN ANALYZE)、変更前後のタイミング、問題が現れるデータサイズ。 - 「これは安全である」という共有状態に関する主張については、すべての読み取り元と書き込み元をリストします。
- 労力に上限を設けます: 候補あたり約15分または5回の試行まで。それを超えたら、ラベルを付けて理由とともに次に進みます。すべてのCritical/High候補にラベルが付けられるまで、再現を停止します。
各発見の証拠にラベルを付けます:
- yes: コードを実行して再現されました。
- partly: 主張の一部が再現されました。セクションではどの部分かを示します。
- artifact: ファイル、マニフェスト、イメージレイヤー、またはコミットによって示されました。ここで実行することはできません (欠落しているデプロイ変数、履歴内のシークレット)。
- no: 試みましたが再現できませんでした。それでも報告する理由を述べるか、削除します。
- not tried: 推論のみ。
次に、正直に:
- このデプロイメントで可能性のあるトリガーがない候補は、Lowとして報告されるのではなく、削除されます。
- 推論は、推論としてラベル付けされたままになります (「おそらく」、「ここからは確認できませんでした」)。
- モックが実際のコードが決して返さないものを返すためだけに合格するテストは、コードに関する証拠ではなく、テストに関する発見です。
8. 分類
重大度。このデプロイメントにおける影響と到達可能性によって判断されます。到達可能性が確認できないもの (ネットワークACL、誰がポートに到達できるか) に依存する場合、到達可能であるかのように重大度を設定し、その横に何がそれを下げるかを記載します。
- Critical: 現在悪用可能で、深刻な影響があります。
- High: データ損失、テナント間またはユーザー間アクセス、またはコア機能の破損。
- Medium: 特定の条件を必要とする実際のバグまたはリスク。
- Low: 衛生状態、保守性、ドキュメント、依存関係のずれ。
ライブラリの場合、典型的なコンシューマへの影響で判断します。シングルユーザーツールの場合、データ損失は依然としてHighであり、セキュリティ上の発見には現実的な攻撃者が必要です。
チェンジモードでは、各発見にもタグを付けます:
- 新規 または 既存 (ベースと比較して)。
- ブロッキング または 非ブロッキング。ブロッキングとは、この発見が対処されるまでマージすべきではないことを意味します。
9. レポート
構造化されたレポートを作成します。プロジェクトモードの場合、ファイルに書き込みます。チェンジモードの場合、チャットに出力します。
ヘッダー
# レビューレポート: <スコープの簡単な説明>
- **リビジョン:** <sha> (ブランチ <name>、<リモートURL>)
- **モード:** プロジェクト | 変更
- **スコープ:** <何が読まれたか、何がスキップされたか>
- **対象読者:** <メンテナー | 貢献者 | ユーザー | 未解決>
- **言語:** <言語>
- **ベースライン:** 型チェック、リント、ビルド、テストの合格/不合格、依存関係監査の結果
- **前提条件:** <セクション2からの未解決の質問に対するデフォルトのリスト>
発見
各発見:
## [<ID>] <タイトル>
- **重大度:** Critical | High | Medium | Low
- **ステータス:** 未確認 | 確認済み | 修正済み | 却下
- **証拠:** yes | partly | artifact | no | not tried
- **場所:** ファイル:行 (リンク付き)
<説明、シナリオ、証拠>
**再現:**
- スクリプトまたはコマンド (該当する場合)
- 検証の詳細
良い状態
## 良好な状態
- <うまく行われているもの、証拠付き>
要約
## 要約
- **総発見数:** <数>
- **Critical:** <数>
- **High:** <数>
- **Medium:** <数>
- **Low:** <数>
- **ブロッキング:** <数> (チェンジモードのみ)
プロジェクトモードでは、ファイルに evidence-review-<日付>.md として書き込みます。チェンジモードでは、チャットに出力します。更新モードでは、見つかった発見を編集し、新しい発見を追加し、解決された発見のステータスを更新します。
10. フォローアップ
- 発見が対処されたら、それを再確認します。
- 結果を記録します。
- 必要に応じてレポートを更新します。
これで完了です。