code-review

コードレビュー

依頼されたレビュー範囲が正確で、必要かつ明確であり、想定される用途に使える状態かを確認します。対象ファイルまたは過去の指摘事項が明示されていない場合は、変更全体をレビューします。まずレビューを行い、修正は許可された修正モードの場合に限ります。

操作、修正、および境界

証拠を集める前に、操作を1つ選択します。

• 新規レビュー： 対象範囲を限定した変更を評価し、レビュー判定を提示します。
• 対象を絞った再検証： 選択された過去の指摘事項を再確認します。変更全体の評価は行いません。
• 組み合わせ： ユーザーが新規レビューを明示的に依頼し、かつ過去の指摘事項を提示した場合に限り、両方を実施します。出力と結論は分けて提示します。

修正は操作とは独立しています。

• デフォルトでは修正を行いません。安全なローカル調査を確認して実行しますが、ソース、テスト、設定、ドキュメントは編集しません。
• fix <finding IDs> は選択された指摘事項のみを修正します。fix-all は、対象範囲内で妥当性が確認されたすべての指摘事項を、1回の限定された作業で修正します。過去の指摘事項がある場合、どちらのモードでも編集できるのは、選択された指摘事項のうち still_present または changed に分類されたものに限ります。resolved、not_retestable、skippedOutOfScope に分類された指摘事項は編集しません。
• 修正モードで許可されるのは、ローカル編集と検証のみです。コミット、プッシュ、PR コメント、レビューコメントの変更、デプロイ、公開、共有状態の変更は許可されません。 重大な 製品、アーキテクチャ、セキュリティ、互換性、またはスコープに関する判断が必要な場合は、修正を中止します。
• JSON の保存依頼で許可されるのは、指定された指摘事項の成果物のみです。修正は許可されません。
• 正確なファイル一覧と過去の指摘事項の JSON は、追加の入力です。ユーザーから提示されない限り、これらによって対象範囲が指定されていないレビューの動作が変わることはありません。
• 報告プロファイルやしきい値によって変わるのは提示方法のみです。対応付けられた範囲全体について、候補をすべて収集して検証し、裏付けのある重大度をすべて正規の結果に保持します。どの重大度を表示するかは呼び出し元が判断します。
• 対応付けられた範囲全体を検索します。最初の問題や最も重大な問題が見つかっても、検索を打ち切りません。
• ホストがサブエージェントに対応しており、対象範囲が些細なものでない場合は、デフォルトでレビューのレーンを委任します。1つのファイル内の数行といった小さな変更は、ローカルでレビューします。no-subagents または同等のユーザー指示がある場合は、レビュー全体をローカルで行います。レビューのレーンを委任する場合は、レーンの割り当てを提示する前に references/subagent-lanes.md を読みます。レーンの作業中、コーディネーターはプロジェクトのゲート実行など、レーンに依存しない作業を続けます。

安全な調査には、宣言されたチェック、ローカルビルドとサーバー、使い捨ての再現環境、隔離されたテストデータ、ブラウザー操作、一時的な成果物、元に戻した状態を確認できる反証プローブが含まれます。反証プローブでは、関連するテストやゲートが正しい理由で失敗することを証明するため、一時的に対象を絞って誤った動作を導入します。最初のツリー状態を記録し、使い捨てのワークツリーまたはコピーを優先して使用し、変更は直ちに元に戻します。最終的なツリーと記録した状態をバイト単位で比較し、変更内容と観測された失敗を報告します。正確に復元できる安全性が確保できない場合はプローブを省略し、証拠は静的解析のみと記録します。使い捨ての成果物はクリーンアップし、保持したものがあれば報告します。永続的な副作用や外部から見える副作用を伴う操作は、事前に確認を求めます。

条件付き参照

条件に該当する場合は、各参照を読んでください。

• レビューでレーンを委任する場合は、レーンマップを公開する前に references/subagent-lanes.mdを参照します。
• ユーザーが正確なファイル一覧を指定した場合は、 references/file-scope.mdを参照します。
• ユーザーが過去の指摘事項を指定した場合は、JSON 出力を求めているかどうかにかかわらず、 references/prior-findings.mdと references/revalidation-json.mdを参照します。これらには、 指摘事項の選択、ファイル一覧との共通部分、および対象を絞った結果の契約が定義されています。
• 新規レビューで JSON 出力を求められた場合は、 references/findings-json.mdを参照します。
• 新規レビューでディスカバラビリティの軸が有効になった場合は、 references/discoverability.mdを参照します。
• 変更が認証、認可、決済、シークレット、破壊的な動作やデータ損失につながる動作、またはテナント分離に関わる場合は、 references/adversarial-review.mdを参照し、エンジニアリング品質の範囲内で、その指示に従って限定的なバイパス調査を行います。
• 構造上の証拠から設計上の問題が疑われるものの、具体的な影響や最小限の修正が不明な場合は、 references/engineering-smells.mdを参照します。調査のきっかけとして利用し、リポジトリの基準と実際に確認された影響を優先します。
• ユーザーがfix <finding IDs>またはfix-allを選択した場合は、 references/fix-mode.mdを参照します。

新規レビューの実施

新規レビューまたは複合レビューにはこのセクションを使用します。対象を絞った再検証のみの場合は、代わりに過去の指摘事項に関する参照に従います。

1. 適用されるプロジェクトの指示、現在のソース、テスト、設定、ロックファイル、コントリビューションまたは完了に関する契約を根拠としてレビューします。
2. 比較境界を特定します。
   • ユーザーがベースを指定している場合は、それを使用します。
   • プルリクエストの場合は、そのベースブランチを使用します。
   • それ以外の場合は、リモートのデフォルトブランチとのマージベースを使用します。
3. 委任の前に、固定点とヘッドを具体的なリビジョンに特定し、範囲を限定した差分を計算でき、その差分が空でないことを確認します。いずれかのリビジョンが利用できない場合、境界が曖昧な場合、または変更が空か無関係な場合は、レビューを開始せずに中止します。
4. コミット済み、ステージ済み、未ステージ、関連する未追跡の作業を含めます。ダーティな作業ツリーの指摘事項とコミット済み変更の指摘事項は分けます。
5. イシュー、プルリクエスト、確認済みの簡易仕様、必須の動作、コミットから主張を特定します。いずれも存在しない場合は、変更から根拠のある最も狭い主張を再構成し、推定であることを明記します。
6. 重複排除、主張と仕様、エンジニアリング品質を、すべての新規レビューで有効にします。ディスカバラビリティを有効にするのは、公開ページ、ルーティング、メタデータ、クロール制御、構造化データ、公開コンテンツ、またはウェブパフォーマンスの動作に関する変更に限ります。エンジニアリング品質では、正確性、簡素化、自己文書化、テストの価値、運用上の動作を確認します。UI／アクセシビリティ、信頼境界、永続化／マイグレーション、並行性、互換性、デプロイ／ロールバック、可観測性、パフォーマンスは、変更がそれらに関わる場合にのみ追加します。
7. 指摘事項の対象範囲に含まれる変更ファイルごとに変更量を測定します。また、履歴から確実に特定できる場合は、変更された関数、メソッド、クラス、モジュールごとにも測定します。名前変更を追跡し、履歴の対象期間を明記して、変更回数と行変更数を記録します。リポジトリで定められた変更量の期間を使用し、定めがない場合は90日とします。リポジトリで宣言されたコード健全性ツールを優先し、利用できない場合はGitのファイル履歴と、安定したシンボルにはgit log -Lを使用します。シンボル単位の履歴を利用できない場合は、ファイル単位で代用したことを明記します。

エビデンスの生成

マッピングされた指摘範囲全体に、以下の要件を適用してください。

• 現在のエビデンスからリポジトリに関連するゲートを特定するか、不足しているチェックを実行してください。複合ワークフローでは、集約ゲートの責任は呼び出し元にあります。内容、コマンド、環境、カバレッジが一致する場合は、合格済みのチェックと実際のインターフェースのエビデンスを再利用してください。変更後、失敗や不足があった場合、または未解決の懸念がある場合は、再実行してください。独立したレビュー判断を維持してください。明白なツールの失敗を言い直す必要はありません。
• 変更によって観測可能になった動作を、実際のインターフェースを通じてそれぞれ再現してください。意図された経路と、最も重大な失敗または境界の経路を検証してください。
• UI の変更では、レンダリングされたインターフェース、状態遷移、読み込み／空／エラー状態、アクセシビリティ、関連するビューポートを検証してください。UI 以外の変更では、実際の API、CLI、ライブラリのエントリーポイント、ジョブ、マイグレーション、パッケージ化、デプロイの経路を検証してください。
• セットアップ、操作またはコマンド、入力、期待される結果、実際に観測された結果を記録してください。返された結果または一致する保存済みエビデンスを評価対象にしてください。リクエスト、確認応答、期待される結果は、観測された結果ではありません。結果が返されなかったチェックは再実行してください。結果を取得できない場合は unverified とし、ソースのみから導いた結論には static only と記してください。
• 変更されたテストが、関連する誤った動作に対して失敗し、実装の詳細ではなく結果を検証することを確認してください。脆弱なカバレッジ、過剰にモックされたカバレッジ、偶発的なカバレッジ、スナップショットに偏ったカバレッジは評価対象にしないでください。

レビュー軸

一方の軸がもう一方を覆い隠さないよう、各軸を分けてください。有効な場合、発見可能性の軸は参照資料で定義されています。

重複の排除

範囲を限定した変更と、その変更を支える最小限のコンテキスト全体を対象に、次の4つのチェックを個別に行ってください。

• 実装： 重複するコード、ロジック、テスト、フィクスチャ、設定、スキーマ、ワークフロー、ドキュメント、または単一の概念を表す競合する表現を探してください。
• 作業： 同じ作業を繰り返すのではなく、現在の課題に関する判断、過去の指摘、調査、受け入れ済みの修正エビデンスを再利用してください。その範囲が変更と重なる場合は、新たに発見し直すのではなく再検証してください。
• エビデンス： 複数のチェック、ログ、ツールから報告された同一の事象は、すべての出典を保持したまままとめて、一度だけ数えてください。
• 出力： 原因、影響、対処方法が同じ候補は、出典情報を保持して1つの指摘にまとめ、矛盾するエビデンスを明示的に調整してください。

指摘の範囲を、限定された変更より広げないでください。支援コンテキスト内でのみ確認できる重複は、対象範囲内の指摘を裏付ける材料にはできますが、そのコンテキスト内の別個の指摘にはしないでください。

主張と仕様

不足または一部しか満たされていない要件、誤った動作、要求されていない範囲を見つけてください。根拠となる要件を引用するか、主張が推論であることを明示してください。

エンジニアリング品質

• 関連する場合は、変更された入力、認可、状態遷移、失敗、再試行、並行処理、冪等性、削除、サイドエフェクトを追跡します。
• 新しいヘルパー、パターン、形式、抽象化を受け入れる前に、現在のリポジトリを検索します。同じ概念を別の方法で表現または実装している場合、その理由がリポジトリに記載されていなければ欠陥です。
• 削除、再利用、直接的な制御フロー、既存の依存関係を優先します。未使用の経路、重複、推測的なレイヤー、不要なラッパー、一度しか使われない間接化、プラットフォームや依存関係がすでに提供しているカスタムコードを報告します。
• 名前、型、境界、インターフェースから意図が読み取れることを求めます。コメントではコードを言い換えるのではなく、根拠、制約、明白でない動作を説明します。周囲のコメント密度は要件ではありません。
• 同じシンボルやファイルへの変更が繰り返されていることは、それ自体を欠陥とせず、アーキテクチャリスクの兆候として扱います。測定された変更の多さが、責務の混在、修正やリバートの再発、競合する表現、広い影響範囲、不安定なインターフェース、弱い回帰テストのいずれかと重なる場合は、ARCHITECTURE_RISK の指摘を挙げます。期間、変更回数、粒度、併存する兆候を示します。
• 一般的なベストプラクティスや記憶に基づくライブラリの挙動は、調査の手掛かりとしてのみ扱います。指摘事項は、チェックアウト済みのコード、正確なインストール済みバージョン、最新の公式ドキュメントまたはソースで検証します。リポジトリの判断は一般的な好みより優先します。

新規レビューの報告

報告用語はインターフェースです。milestone-rush、レビュー用ツール、監査などの呼び出し元は用語を文字どおり照合するため、言い換えると引き継ぎが壊れます。レーンマップ、レビュー軸、レーンのステータス、役割には、以下の用語をそのまま使用します：review-axis-to-lane map、de-duplication、claim and specification、engineering quality、discoverability、complete、incomplete、coordinator、worker。用語の後に平易な説明を加えてもかまいませんが、用語自体を置き換えてはいけません。レーンを実行した場合は、そのセクションにマップの用語でラベルを付け、その中で自身の役割をcoordinatorと記述します。短い報告では表現を簡潔にしてもかまいませんが、該当する以下のフィールドはすべて保持します。

新規レビューでは、判定を先頭に記載します：APPROVE、APPROVE WITH IMPROVEMENTS、またはREQUEST CHANGES。報告をもって、このスキルのステップを終了します。単独で開始した場合は、delivery settingsに従って続行します。entry-points: deliverの場合、レビュー対象の変更と検証済みの指摘事項を/deliverに引き継ぎます。/deliverは指摘事項を修正し、変更を検証して、設定されたエンドポイントまで公開します（ORCHESTRATION.mdがない場合はready-to-merge）。stopの場合は、この報告で終了します。

以下を含めます：

• レビューした主張、比較範囲、コミット、未コミットの変更状態。
• 有効にしたレビュー軸とスキップしたレビュー軸、およびそれぞれの理由。
• 対象とした重要なエンジニアリング品質上の懸念と、変更されたランタイム経路が関係しないためスキップした条件付きの懸念。
• レビューでレーンに委任した場合は、各レーンのcompleteまたはincompleteステータスを記載したreview-axis-to-lane map、coordinatorが選外としたworker候補とその理由（指摘事項とは分けて記載）、およびcoordinatorが完了したすべての代替対応とその理由、または代替対応が不要だった旨。
• 変更の期間、対象としたシンボル／ファイル、アーキテクチャリスクのホットスポット。
• 正確な調査手順と確認項目、および観測された結果。
• de-duplicationの対象範囲、統合した証拠ソース、統合または競合した候補指摘事項。
• 実行可能な指摘事項を、以下の形式で記載します： [CR-N][BLOCKING|IMPORTANT|IMPROVEMENT|NITPICK][CLAIM|QUALITY|ARCHITECTURE_RISK| DISCOVERABILITY] file:line: 証拠、影響、改善点、未対応の場合、最小限の対処法
• 検証済みの主張、静的解析のみの対象または未到達の領域、保持した調査成果物。

リポジトリ内のすべてのリテラルなパス、拡張子のないファイルを含むファイル名、変数、関数、メソッド、クラス、型、その他のコード識別子は、すべてインラインコードとして表記します。コードスパンの外には説明文を記述します。 作成者にブランチの更新、コミット、公開方法を伝える対応策では、一般的な方法ではなく、リポジトリで文書化されている仕組みを示してください。まずプロジェクトの Git ワークフローを確認してください。通常のブランチでリベースが禁止されている場合は、「ベースブランチをマージする」と記述し、スタック用コマンドは、スタック内のブランチであることが確認できた場合に限り使用してください。同じことは、レポートから投稿するレビューコメントやプルリクエストの本文にも当てはまります。呼び出し元がプルリクエストにレビュー結果を記録している場合は、 PR の説明 の指示に従って記録してください。

BLOCKING は安全なリリースを妨げます。IMPORTANT は、正確性、セキュリティ、運用性、テストの価値、保守性、簡素化、理解しやすさに重大なコストをもたらします。IMPROVEMENT は、効果が確認された有益な簡素化、または現在の慣行との整合です。NITPICK は、明確な対応策があり、リポジトリの規約または現在のコードに根拠のある、小規模で局所的な仕上げの問題です。個人的な好みを示すものであってはなりません。称賛、差分の説明、主観的なスタイルの好み、具体的な影響を伴わない指摘は省いてください。

各指摘には、対応するかどうかの判断を示さず、次の3つの事実も記載します。影響：現在のコードで、その指摘が誰または何に影響するか。利点：修正した場合に何が改善されるか。未対応の場合：そのままにした場合に具体的に何が起きるか。リポジトリにこれらに基づいて判断するポリシーがある場合は、そのポリシーに従って対応する指摘を決定し、対応しないと判断された指摘は、その判断をもって解決とします。

未解決の BLOCKING または IMPORTANT の指摘がある場合、準備完了とはみなせません。任意の仕上げは準備完了を妨げませんが、合意された要件とのずれが確認された場合は、重要度にかかわらずすべて解決する必要があります。重要度を下げても、その要件は免除されません。