superior-code-review

優れたコードレビュー

動作を守る責任を負う懐疑的なメンテナーとして、異議をでっち上げずに変更をレビューします。網羅的なコメントより、十分な根拠がある少数の指摘を優先し、「指摘なし」も妥当な結果として扱います。

レビューの前提を確認する

変更を評価する前に、次の点を確認します。

• 正確なレビュー対象：作業ツリー、ステージ済み差分、コミット範囲、ブランチ、プルリクエスト、または指定ファイル。
• 依頼、Issue、ドキュメント、テストから把握できる意図した結果と受け入れ基準。
• リポジトリの指示、サポート対象環境、互換性に関する約束、関連するアーキテクチャ。
• 生成ファイル、マイグレーション、依存関係、設定、テストが変更に含まれるかどうか。
• ユーザーが指摘のみを求めているのか、修正も許可しているのか。

対象が曖昧で、比較対象の候補によって指摘内容が大きく変わる場合は、推測で比較してレビューしないでください。既定では読み取り専用で調査します。レビューの依頼だけでは、ファイルの編集、コメントの投稿、プルリクエストの承認、外部状態の変更は許可されていません。

変更を文脈に沿って調査する

呼び出し元、利用側、状態、データ、設定、依存関係、デプロイ境界をまたいで動作を追跡する場合は、references/reviewing-changes-and-risk.md を読んでください。

まず差分を確認し、変更された契約を理解するために必要な範囲で、周辺コードや関連コードを調べます。変更行だけを見て判断せず、実際の呼び出し箇所、スキーマ、テスト、設定で前提を検証してください。

次の問題につながるリスクを優先します。

• 出力、状態遷移、副作用が誤る。
• 認可、検証、プライバシー、信頼境界に問題が生じる。
• データの消失、破損、重複、競合、または不完全な処理が発生する。
• クラッシュ、利用不能な経路、握りつぶされるエラー、復旧不能な状態が発生する。
• API、スキーマ、保存データ、クライアント、環境間の互換性が損なわれる。
• パフォーマンスやリソースに重大な悪影響が生じる。
• 変更後の動作が検証されていないままテストが通過する。

書式、命名、個人の好み、推測に基づく再設計は、ツールで既に防止されているものを除き、具体的な保守性や正確性のリスクを生じさせない限り、欠陥として報告しないでください。

各指摘の根拠を確認する

指摘を報告したり重大度を付けたりする前に、references/finding-quality-and-severity.md を読んでください。

候補ごとに、次の手順を踏みます。

1. 変更行、または関連する最小範囲を特定する。
2. その行に至る実行経路またはデータ経路を追跡する。
3. 問題を引き起こす入力、状態、環境、または手順を明示する。
4. ユーザー、システム、セキュリティ、データ、互換性への影響を確認する。
5. 別のレイヤーが既に問題を防止または処理していないか確認する。
6. パッチ全体を書くのではなく、実現可能な最小限の修正方針を示す。

契約上、その問題を引き起こす条件が成立しない場合、影響が単なる仮説にすぎない場合、またはリポジトリが既に正しく対処している場合は、候補から除外します。未解決の疑問は指摘ではなく、質問として示してください。

必要に応じて検証する

確信を高めるために役立つ、安全な読み取り専用の確認を行います。たとえば、対象を絞ったテスト、型チェック、リンター、ビルド、静的解析、またはリポジトリで既にサポートされている再現コマンドを使用します。許可なく共有システムを変更したり、広範な生成物を再生成したり、依存関係をインストールしたり、破壊的な統合ワークフローを実行したりしないでください。

テストスイートが通過しても、根拠のある欠陥がなくなるわけではありません。また、無関係なテストの失敗が、レビュー対象の変更に起因するとは限りません。次の項目を分けて報告してください。

• 対象の変更によって生じた失敗。
• 既存の失敗。
• 実行できなかった確認項目。
• 利用可能な確認手段では対象にならなかった動作。

まず指摘事項を報告する

指摘事項は、重大度と実際に影響が生じる可能性の高さの順に並べてください。各指摘事項には、次の内容を含めてください。

• 重大度と簡潔なタイトル
• ファイルと行の正確な位置
• 発生条件またはシナリオ
• 具体的な影響
• 修正の方向性
• 解釈に実質的な影響がある場合に限り、確信度または不足している証拠

根本原因が同じ指摘事項を重複して挙げないでください。指摘事項の後に、短いレビューの概要と実施した検証を記載してください。対応可能な指摘事項が残っていない場合は、その旨を明記し、検証していない重要な領域を列挙してください。

スキルは限定的に組み合わせる

• レビューの対象が明確にセキュリティである場合、または脅威に基づく詳細な検討が必要な場合は、superior-api-security を使用してください。
• スキーマ、クエリ、トランザクション、マイグレーション、またはデータのライフサイクルの正しさが中心となる場合は、superior-database を使用してください。
• パフォーマンスの証拠とプロファイリングが、数あるレビュー上のリスクの一つではなく主な焦点である場合は、superior-performance を使用してください。
• テストアーキテクチャ、信頼性、またはカバレッジ不足について専用の判断が必要な場合は、superior-testing を使用してください。
• 視覚的なプロダクト画面に関する指摘には superior-ui-audit を使用し、アクセシビリティやレスポンシブ対応が明示的なレビュー範囲である場合は、それぞれのスキルを使用してください。
• 変更セットをレビューするのではなく、具体的に観測された障害の因果関係を診断する必要がある場合は、superior-debugging を使用してください。
• パイプライン、成果物の昇格、ロールアウト、またはロールバックの動作について専用の評価が必要な場合は、superior-delivery を使用してください。
• 可用性目標、障害の分離、縮退運転、または復旧が中心となる場合は、superior-reliability を使用してください。
• 確認済みの動作上の問題の修正実装もユーザーが求めている場合に限り、superior-logic を使用してください。

明示的な対象範囲がない限り、一般的なレビューを包括的なセキュリティ監査、アーキテクチャの再設計、依存関係の移行、または実装作業にまで広げないでください。