code-review

コードレビュー

目的

変更されたコードにある影響の大きい不具合を、根拠とともに見つけます。スタイル上の細かな指摘よりも、正確性、セキュリティ、データの整合性、シェル／設定の安全性、リグレッションを優先します。

引数

• パス、パターン、コミット／範囲、または対象範囲を示す語句：スコープ解決のステップ 2 で使用します。
• --fix：指摘事項を内部で作成し、重大度の高い順に修正を適用してから、最終レポートを 1 件作成し、「検証」セクションに従って検証します。修正前のレポートは別途出力しません。
• --with-profile <name>：名前の語幹またはファイル名（例：--with-profile shell）で任意のドメインプロファイルを強制的に適用します。複数回指定できます。
• --skip-profile <name>：名前の語幹またはファイル名（例：--skip-profile naming）で任意のドメインプロファイルをスキップします。複数回指定できます。--with-profile と --skip-profile の両方で同じプロファイルが指定された場合は、スキップが優先されます。
• デフォルト：指摘事項を報告し、編集前に確認を待ちます。

スコープ解決

スコープは一度だけ解決し、実行中はその結果を固定して扱います。

1. リポジトリのコンテキストを確認します：git rev-parse --git-dir。失敗した場合は停止し、ユーザーに Git リポジトリから実行するよう伝えます。
2. リクエストで対象が指定されている場合（ファイルパス／パターン、コミット／範囲、自然言語で指定された一部の対象（例：「パーサーの変更」）、またはリポジトリ相対パスを 1 行に 1 つ記載した resolved-scope フェンスコードブロック）は、スコープをその対象のみに限定します。自然言語で指定された対象は、先に具体的なパスに対応付けてから続行します。
3. それ以外の場合、スコープはこのセッションで変更されたファイルのみです。つまり、このセッション中に作成または編集されたファイルです。他の未コミット変更は含めません。
4. このセッションで変更されたファイルがない場合、またはこのコンテキストで以前の会話履歴を参照できない場合は、未コミットのファイルすべてに切り替え、各コマンドを 1 回ずつ実行します。
   • 追跡対象：git diff --name-only --diff-filter=ACMR
   • 未追跡：git ls-files --others --exclude-standard
   • 両方の一覧を結合し、重複を削除します。
5. 明示的に依頼された場合を除き、生成物、ベンダーコード、一括データ、シグナルの少ないファイルは手動レビューの対象外とします。例：ロックファイル、圧縮済みバンドル、ビルド出力、生成された出力、ベンダーコード、大規模なデータスナップショット。対象外のファイルが正確性に関係する場合は、excluded-scope タグ付きの任意のフェンスコードブロックを出力し、リポジトリ相対パスまたは glob を 1 行に 1 つ記載して、検証または不変条件のチェックで扱います。
6. スコープに含まれるファイルが 0 件の場合は、その旨を報告して停止します。
7. スコープを、リポジトリ相対パスを 1 行に 1 つ記載した resolved-scope タグ付きのフェンスコードブロックで出力します。このブロックが正式なスコープです。以降、スコープ解決コマンドを再実行したり、対象外ファイルを見直したりしてはいけません。

ワークフロー

1）スコープを解決する

• 「スコープ解決」セクションを適用し、差分と必要最小限の周辺コンテキストを読みます。
• excluded-scope ブロックの対象は手動レビューの範囲外としますが、検証計画には含めます。

2）チェックを適用する

• 変更された動作と、影響を受けるリスク領域に基づいてファイルを分類します。
• プロファイルの適用ルールに従ってコアチェックと該当するプロファイルを適用し、--with-profile と --skip-profile を尊重します。
• 生成物、ベンダーコード、一括データ、またはシグナルの少ないファイルについては、生成された各行やファイルを逐一レビューする代わりに、それらを生成または制約するジェネレーター、スキーマ、コントラクト、不変条件をレビューします。

3）指摘事項を作成する

• 場所、影響、根拠、確信度、具体的な修正方法を含む指摘事項を作成します。
• 重大度モデルに従って重大度を割り当てます。

4）修正する、または確認を待つ

• デフォルト：指摘事項を報告し、編集前に確認を待ちます。
• --fix が指定された場合：重大度の高い順（CRITICAL -> HIGH -> MEDIUM -> LOW）に提案された修正をすべて適用し、「検証」セクションに従って検証します。ユーザーに提示する最初の指摘レポートは、修正後の最終レポートです。

5）報告する

以下の「レポート」セクションに従ってレポートを作成します。

レビューレンズ

差分を評価する際の境界として、ユーザーの依頼を扱います。

• 隠れた前提を明らかにします。動作の意図が曖昧な場合や、複数の解釈によって修正内容が異なる場合は、推測せずに作業を中断するか、その前提を残存リスクとして記録します。
• 正当化できる範囲で最小の修正を優先します。リスクやレビュー負担を増やす場合は、単一用途の抽象化、根拠のない設定可能性、追加機能、広範な書き換えを指摘します。
• 無関係な変更は疑わしいものとして扱います。隣接するリファクタリング、書式だけの編集、既存の不要コードの削除、スタイル変換には、依頼との直接的な関連性が必要です。
• 目標への適合性を確認します。動作変更には具体的な成功基準と範囲を絞ったチェックが必要です。実務上可能であれば、バグには再現テストを、検証の変更には無効な入力のテストを、リファクタリングには変更前後の安全性チェックを追加します。

主なレビュー項目

毎回適用します。

• CORE-001 動作のリグレッション（HIGH）：変更された分岐や状態遷移が外部向けの動作を変えている。
• CORE-002 エラーパスの安全性（HIGH）：失敗が連鎖したり、クラッシュしたり、安全でないデフォルト値を返したりする可能性がある。
• CORE-003 境界の処理（HIGH）：null、空、オーバーフロー、境界値の入力が処理されていない。
• CORE-004 リソースの適切な管理（MEDIUM）：タイマー、リスナー、ハンドル、接続がリークしている。
• CORE-005 複雑性の集中箇所（MEDIUM）：変更によって、避けられる結合や隠れた副作用が生じている。
• CORE-006 テストの不足（MEDIUM）：変更された動作に対する的を絞ったテストがない。
• CORE-007 変更範囲の過剰（MEDIUM）：変更された行が、ユーザーの依頼や、変更によって生じたことを確認済みのクリーンアップに直接結び付いていない。
• CORE-008 根拠のない複雑性（MEDIUM）：新しい抽象化、設定可能性、柔軟性、または起こり得ないケースへの対処が、必要性の裏付けなしにコードを増やしている。
• CORE-009 成功基準の曖昧さ（MEDIUM）：変更すると主張する動作に、明確な検証目標がない。

プロファイルの選択

プロファイルはリスクに基づいて選択し、網羅的に適用します。変更対象のリスク領域に対するバグ検出に実質的に役立つ、スキップされていないプロファイルをすべて読みます。基本チェックで変更をカバーできる場合でも、ファイル拡張子だけで判断してはいけません。選択した各プロファイルは、一度だけ全体を読みます。どのプロファイルも一度の読み込みで収まるため、分割して読んだり、再読したりしてはいけません。

まず --skip-profile による除外を適用します。その後、--with-profile のプロファイルを追加します。除外されていない限り、references/profiles/naming.md を含めます。

• references/profiles/security.md：認証、外部入力、シークレット、暗号化、パブリックネットワークのサーフェス、安全でない解析。
• references/profiles/configuration.md：環境変数や設定、タイムアウト、リトライ、プール、上限、リソース調整、ロールアウト制御。
• references/profiles/go.md：Go サービス、CLI、並行処理、コンテキストの伝播、エラー処理、モジュール、テスト。
• references/profiles/typescript-react.md：型、レンダリング、ランタイム、パッケージ、非同期処理のセマンティクスが関係する、TypeScript／JavaScript／React／Node の動作変更。
• references/profiles/python.md：Python サービス、スクリプト、非同期ワークロード、パッケージング、データ処理、または I/O 負荷の高い変更。
• references/profiles/shell.md：シェルスクリプト、CI のコマンドブロック、デプロイスクリプト、インストーラーコマンド、またはコマンドの引用符。
• references/profiles/data-formats.md：CSV／JSON／YAML／バイナリの取り込み・エクスポート・解析、スキーマ、生成データ、マイグレーション、またはフィクスチャの更新。
• references/profiles/naming.md：命名と意図の明確さ。スキップされていない限り、すべてのレビューで実行します。

生成ファイルと大量ファイル

• ユーザーから明示的に確認を求められない限り、生成ファイル、ベンダー提供ファイル、大量のファイル、シグナルの弱いファイルは手動レビューの対象から除外してください。
• 生成コード、スキーマ、マイグレーション、テンプレート、ロックファイル更新の意図、フィクスチャの契約、シリアライズ／デシリアライズの経路など、それらを生成または制約するソースを優先してレビューしてください。
• 再生成時の差分、スキーマ検証、パーサーのラウンドトリップ、行数、チェックサム、対象を絞ったフィクスチャテスト、パッケージマネージャーのロックファイルチェックなど、不変条件のチェックで影響を受ける出力を検証してください。
• 除外したファイルが確信度に影響する場合は、「スコープ」または「検証」で言及してください。

重大度モデル

• CRITICAL：悪用可能なセキュリティ上の欠陥、データ損失につながる経路、または重要な経路での停止リスク。
• HIGH：コア動作を損なう可能性があるロジックの欠陥またはパフォーマンス上の障害。
• MEDIUM：近いうちに不具合を引き起こす可能性が高い、保守性または信頼性の問題。
• LOW：局所的な明瞭さ、スタイル、ドキュメントの改善。

エビデンスのルール

• すべての指摘を、実在を確認した具体的なコード箇所に結び付けてください。ファイルパスや行番号を捏造してはいけません。
• 失敗を引き起こす入力または状態と、その原因となる変更行または欠落しているガードを示してください。
• 影響範囲と障害モードを簡潔に記述してください。
• 重複する指摘はまとめてください。
• 広範な書き換えより、対象を絞った修正を優先してください。
• スコープまたは単純さに関する指摘では、変更行と、それが要求された動作に寄与しない理由を示してください。
• 無関係な未使用コードは残存リスクとして言及してください。ユーザーがクリーンアップを求めていない限り、削除を提案してはいけません。
• スタイルのみの問題は、運用上のリスクを生じさせない限り、LOW としてください。

検証

変更した動作を検証するため、範囲を最小限に絞ったチェックを実行してください。

• 変更したファイルのフォーマッター／リンター
• 変更したモジュールの対象テスト
• 関連する場合は型チェック
• 関連する excluded-scope の出力に対する不変条件チェック

リスクに応じてのみ、より広範なチェックを実行してください。特に、共有契約に変更を加える場合は実施してください。実行を省略したチェックとその理由をすべて記載してください。

レポート

次の見出しをこの順序で使用してください。該当しないセクションは省略し、番号を付けたり、空欄やプレースホルダーを残したりしないでください。

スコープ

レビューしたファイル、および検証方法とともに記載する excluded-scope の対象。

指摘事項

重大度の順に記載してください：CRITICAL -> HIGH -> MEDIUM -> LOW。各指摘には次の項目を含めてください。

• [SEVERITY] タイトル — path/to/file.ext:line
• 影響：ユーザーまたはシステムへの具体的な影響。
• エビデンス：コードの正確な動作または差分のエビデンス。
• 修正：実用的な最小限の修正。
• 確信度：high | medium | low。

修正案

--fix を使用していない場合のみ記載してください。

適用した修正

--fix を使用した場合のみ記載してください。各変更をファイル参照とともに列挙してください。

検証

実行したコマンドと結果、および省略したチェックを記載してください。

残存リスク

リスクごとに1行で記載してください：「<前提>を仮定しています。誤っていた場合は<何が壊れるか>。<コマンドまたは確認方法>で確認してください。」平易な言葉を使い、専門用語には説明を加えるか、わかりやすく言い換えてください。ユーザーの判断が必要な質問は、直接尋ねる形で記載してください。該当するものがない場合は None. と記載してください。

停止条件

次の場合は作業を止め、方針を確認してください。

• 修正に API／契約の再設計が必要な場合。
• 動作の意図が曖昧すぎて、重大度を判断できない場合。
• 解釈によって指摘内容や修正内容が大きく異なる可能性が複数ある場合。
• 必要な検証ツールが利用できず、リスクが高い場合。