code-review

コードレビュー

プルリクエスト、ブランチやコミット範囲の差分、あるいは完了と判断する前の自分の作業など、変更の種類、言語、分野を問わず、コード変更をレビューするときは必ずこの機能を使用してください。このスキルは単独で完結しており、必要なルールはすべてここに記載されているため、ほかのスキルと併用せずにインストールしても正しく機能します。ホストプロジェクトに独自のコードレビューポリシーやレビュー投稿ポリシーがある場合は、プロジェクト固有のルールと優先順位についてはそちらに従ってください。このドキュメントの方法論は、プロジェクトのガイダンスで定められていない部分すべてに引き続き適用されます。

レビューの目的は1つです。変更を安全にマージできるかを判断し、根拠を示してその理由を説明することです。出力も1つ、レポートです。コードは書き換えません。問題の発見と修正は分けてください。

レビュー対象。 対象は、現在レビュー中の変更です。デフォルトではベースブランチに対するワーキングツリーを指します。プルリクエストの特定の参照、ブランチ名、コミット範囲が指定されている場合は、それを対象とします。ほかの内容を読む前に、対象の差分を確定してください（scoping.mdを参照）。

このドキュメントに記載されている「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、「OPTIONAL」は、RFC 2119に記載された意味で解釈してください。

レビューループ

すべてのレビューで同じループを実行します。レビューモードにリセットし、差分から変更の範囲を定め、レビューの観点に沿ってその差分を評価し、指摘事項を重要度別に分類し、根拠を示して報告し、自分で承認するにはリスクが高すぎるものがあればエスカレーションします。リセットを行うことで、その後の手順の信頼性が保たれます。レビュー担当者は、コードを生み出した推論を追認するのではなく、ほかの人が書いたかのようにコードの 動作 を調べます。作者とレビュアーが同じエージェントであるセルフレビューでは、特に重要です。リセット前にコードを読んではいけません。これは最初に行うべき必須の手順であり、scoping.mdで定められています。以下のセクションでは、レビューの進行順に、各手順を定義するリファレンスを案内します。

ガイドライン：

• 変更を評価する前に、必ずreview-lenses.mdを読んでください。そこに記載された受け入れ基準の境界と、範囲を限定したリファクタリングの確認は、すべてのレビューに適用されます。

レビュー範囲の決定

scoping.mdでは、以下について説明しています。

• レビューモードにリセットし、git status／git diff／PRの差分から対象範囲を定める
• 対象範囲内（差分）と対象範囲外（既存）のコードを区別する
• 変更された箇所のあるファイル全体と、その周辺にあるすべての呼び出し元／呼び出し先を読む
• 変更で主張されている境界、すなわち変更が所有者として挙げている隣接要素について、その実際の記述内容を確認する。差分だけで判断しない
• 未追跡ファイル、差分が空または不明瞭な場合、生成ファイルやツール管理対象ファイルに対処する

重要度の分類

severity.mdでは、以下について説明しています。

• Critical／Major／Minor／Nitの定義と、それぞれに対応するマージへの影響および不具合の種類
• コミット済みのシークレット、アクセス制御の欠落、サニタイズされていない入力、導入されたテストやlintの失敗などに対する、固定の重要度下限
• 重要度別の指摘件数を、Approve／Approve with Nits／Request Changesの判定に対応付ける方法
• 重要度に確信が持てない場合に、上位の重要度へエスカレーションし、前提を明示する方法

指摘すべき内容：レビューの観点

review-lenses.md では、次の内容を説明しています。

• 正確性の観点：ロジックエラー、エッジケース、エラー処理と非同期処理、契約の変更
• 外部検証の制約ではなく、コードの調査に基づく受け入れ基準に関する指摘
• 変更されたコード内の具体的なリファクタリングの機会の検討。推測に基づく整理や無関係な整理は対象外
• 保守性の観点：命名、構成、抽象化の境界、複雑さ、デッドコード、スコープの規律、コンテンツを追加する変更で削除すべきものの明示
• セキュリティとプライバシーの観点：シークレット、入力検証、アクセス制御、インジェクション、SSRF、認証、データ漏えい、サプライチェーン
• テストと検証の観点：カバレッジ、安定したテストフック、スナップショット、不安定さ、手動確認
• パフォーマンスと信頼性の観点：データアクセスのコスト、並行処理、キャッシュ、アセットとバンドルのサイズ、障害モード

根拠と報告

evidence-and-reporting.md では、次の内容を説明しています。

• 各指摘に必須の file:line 形式の引用と、問題のあるコードの引用
• Critical および Major の各指摘に対する、差分形式（-／+）の修正スニペット
• Summary から Recommended Actions まで、レビュー報告書の正確なセクション順
• 根拠と断定の違い、およびレビュアーが検証できなかった指摘の示し方
• 変更について著者自身が示した説明（検証表、著者が作成した受け入れ基準、開示された数値）が証明することと、証明しないこと

レビューのトーン

tone.md では、次の内容を説明しています。

• 著者ではなくコードを対象にし、各指摘の具体的なリスクを明示すること
• 実際の長所を認めつつ、些細なものを過大評価しないこと。これは内部レビュー報告書には求められますが、投稿するレビューの概要には求められません
• スタイルや好みを、ブロッキングとなる重大度の根拠にしないこと
• 前提を明示し、人間が作成した文章には手を加えないこと

エスカレーションと判断

escalation.md では、次の内容を説明しています。

• レビューの報告に徹すること。コードを変更せず、レビューを他者に委任しないこと
• 各修正を簡単に適用できるようにし、検証手順を併記すること
• リスクの高い変更は自ら承認せず、外部ゲートへエスカレーションすること
• 真に判断が分かれるトレードオフは、番号付きの「判断が必要」項目として呼び出し元に委ねること

投稿レビューと CI レビュー

posted-review-policy.md では、次の内容を説明しています。

• レビューを内部のセルフレビューとして保持せず、プルリクエストに 投稿 する場合（CI レビュアーまたは管理対象のレビュープロダクト）
• 明示的に採用されたプロジェクト固有の表示形式と報告範囲を、矛盾する作成者側の報告形式の既定値より優先しつつ、実質的なチェックと元の指摘を維持すること
• 内部の4段階トリアージを、1行の集計を添えた既定の2ラベル（Important／Nit）報告にまとめること
• リポジトリで必須のチェックを実行し、報告対象外の条件を遵守すること。該当する指摘だけを無効にするチェックを列挙し、「CI が強制するすべての内容」といった一括指定はしないこと
• 差分に紐づくコメントを投稿できるプラットフォームのレビュー機能を使い、既定の作成者形式の報告を1回の投稿として行うこと。投稿は差分を読む前に選び、助言を行うレビュアーの判定はゲートを通さないものにすること
• 既定の概要は、集計、確認できなかった内容、行に紐づけられない指摘の3項目だけからなる許可リストに限定すること。ただし、ホスト側で各ラウンドの列挙が必須の場合は例外とすること