code-review

複雑なソフトウェア開発タスク完了後のコードレビュー

対象範囲の変更を、構造化された手順でレビューします。モードは 2 つあります。

• 自分が完了した作業、または修正を指示された作業をレビューする場合 - レビュー後、修正を適用して検証します。
• レビューのみを依頼された場合 - 明確で実行可能なフィードバックを提示した時点で終了し、対応するかどうかはユーザーに委ねます。編集を始めないでください。

ワークフロー

1. コードの書き方を説明するファイルをすべて、リポジトリ内で検索します。存在する場合は、CODING_STANDARDS.md と CONTRIBUTING.md を必ずリストに含めます。そのリストをサブエージェントに渡します。
2. レビューの観点（以下を参照）またはコードベースの領域ごとに作業を分け、サブエージェントを並行して起動し、変更を批判的にレビューさせます。
3. サブエージェントの指摘をまとめ、重要度（critical／medium／low）を付けた簡潔な番号付きリストを作成します。
4. 報告または対応する前に、指摘をすべて実際のコードと照合して確認します。サブエージェントの指摘には誤検出が含まれることがあり、実在しない問題に対応すると、コードの質を損なうおそれがあります。

修正の適用

修正モードのみ。レビューのみを依頼された場合は、手順 4 で終了し、指摘を報告します。

1. 確認済みの問題を修正します。
2. プロジェクトの lint／テスト／ビルドのパイプラインを再実行します。
3. 各修正を確認し、指摘が解消されていること、元のタスクを損なっていないこと、新たな問題を生んでいないことを確かめます。パイプラインの成功が証明するのは、機械的な正しさだけです。
4. この 1 回の検証を終えたら、そこで終了します。新たな全体レビューを繰り返さないでください。

指摘が特に複雑な場合や繰り返し発生する場合は、systematic-debugging スキルを使って根本原因を突き止めます。

レビューの観点

サブエージェントには、以下の各観点から変更を評価するよう指示します。以下の質問は例であり、固定のチェックリストではありません。コードベースの言語、ドメイン、規約に合うものを適用し、実際に重要な懸念点を挙げてください。

• 正確性 - タスクの要件どおりに動作しますか？正常系だけでなく、エッジケース（null、空、境界値）やエラー処理にも対応していますか？テストは新しい動作を実際に検証していますか？
• 可読性 - 作成者以外の人にも、名前や制御フローが分かりやすくなっていますか？より簡潔にできますか？各抽象化には、複雑さに見合う価値がありますか？
• アーキテクチャ - 既存のパターンやモジュール境界に従っていますか。それとも、正当な理由なく新しいパターンを導入していますか？共有すべき重複はありますか？既存のスタックですでに対応できる依存関係を新たに追加していませんか？
• セキュリティ - 信頼できない入力を境界で検証していますか？コードやログに秘密情報はありませんか？インジェクション（SQL、シェル、パス）、認可チェックの欠落、外部データのロジックや出力での安全でない使用はありませんか？
• パフォーマンス - この種のコードでコストがかかる処理は何ですか？アルゴリズムの計算量、ホットパスでの繰り返し処理やメモリ確保、N+1 クエリ、上限のないフェッチ、ページネーションの欠如、同期処理、クリティカルパス上のブロッキング処理などを確認します。

レビューを十分に網羅できるよう、自分用またはサブエージェント用のチェックリストや TODO を作成してください。

においのベースライン

リポジトリに記載されている内容に加えて、可読性とアーキテクチャの観点では、Fowler のコードスメル（Refactoring 第3章）の固定リストを常に適用します。これは、リポジトリに独自の規約が記載されていない場合にも適用されます。次の2つのルールに従います。

• リポジトリの規約が優先されます。 文書化されたリポジトリの規約が常に優先されます。その規約がベースラインで指摘される内容を認めている場合は、そのスメルを指摘しないでください。
• 常に判断が必要です。 各スメルは「フィーチャーエンヴィーの可能性」のようなラベル付きのヒューリスティックであり、絶対的な違反ではありません。ツールですでに強制されているものは対象外にしてください。

このリストをそのままサブエージェントに渡してください。サブエージェントがこのリストにアクセスできるのはこの方法だけです。各スメルについて、その内容 → 修正方法 を確認し、差分と照合して、指摘にはスメル名を明記してください。

• 不明瞭な名前 - 関数、変数、型の名前から、その機能や保持する内容が分からない。→ 名前を変更してください。明確な名前が思いつかない場合は、設計が曖昧です。
• コードの重複 - 変更内の複数の箇所やファイルに、同じロジックの形が現れる。→ 共通部分を抽出し、両方から呼び出してください。
• フィーチャーエンヴィー - 自分自身のデータよりも、別のオブジェクトのデータに頻繁にアクセスするメソッド。→ そのメソッドを、対象のデータを持つオブジェクトに移してください。
• データの塊 - 同じ少数のフィールドやパラメーターが常に一緒に渡される（独自の型にすべきもの）。→ それらを1つの型にまとめ、その型を渡してください。
• プリミティブ執着 - 独自の型にする価値があるドメイン概念を、プリミティブ型や文字列で表現している。→ その概念を表す小さな型を作ってください。
• スイッチ文の繰り返し - 同じ型に対する同じ switch／if の連鎖が変更内の複数箇所に繰り返し現れる。→ ポリモーフィズム、または両方の箇所で共有するマップに置き換えてください。
• ショットガン手術 - 1つの論理的な変更のために、差分内の多くのファイルに散在する編集が必要になる。→ 変更が一緒にまとまるよう、1つのモジュールに集約してください。
• 変更理由の分散 - 1つのファイルやモジュールが、互いに無関係な複数の理由で編集される。→ 各モジュールが1つの理由で変更されるよう分割してください。
• 投機的な汎用性 - タスクで必要とされていない抽象化、パラメーター、フックが追加されている。→ 削除してください。本当に必要になるまではインライン化してください。
• メッセージチェーン - 呼び出し元が依存すべきでない、長い a.b().c().d() のようなナビゲーション。→ 最初のオブジェクトにメソッドを1つ用意し、その中に一連のアクセスを隠してください。
• 仲介者 - ほとんど単に処理を委譲するクラスや関数。→ 取り除き、実際の呼び出し先を直接呼び出してください。
• 継承の拒否 - 継承した内容の大半を無視またはオーバーライドするサブクラスや実装クラス。→ 継承をやめ、コンポジションを使ってください。

評価基準

• 基準は「コードベースの改善になるか」であり、「自分ならこう書くか」ではありません。指摘を出すためだけに問題をでっち上げたり、スタイルの好みで動作しているコードを書き換えたりしないでください。
• 一方で、実際の問題を過小評価したり、安易に問題なしとしたりもしないでください。問題は率直に述べ、可能であれば影響を定量化してください（「この N+1 によって行ごとに約50ミリ秒増加する」は「遅いかもしれない」より適切です）。
• テストの成功は必要条件ですが、十分条件ではありません。テストではアーキテクチャ、セキュリティ、可読性の問題を検出できないため、それらも必ずレビューしてください。

デッドコード

リファクタリングによって不要なコードが残ることがあります。コードを変更した後、使用されなくなったもの（置き換えられた関数、コンポーネント、定数など）をすべて列挙し、黙って削除したり放置して劣化させたりするのではなく、削除する前に確認してください。

サブエージェントのガイドライン

適切な場合は、作業を並列化し、メインの会話のコンテキスト肥大化を抑えるためにサブエージェントを使用してください。

• サブエージェントには、出力を簡潔で実行可能な内容にし、細かなスタイル上の指摘ではなく、変更点に焦点を当てるよう伝えてください。
• コード自体から推測できないコンテキストだけを与えてください。
• エージェントごとに明確な範囲を割り当て、作業が重複したり、無関係なコードをレビューしたりしないようにしてください。

報告

修正内容または指摘事項が成果物です。前置きや作業手順の説明ではなく、簡潔な結果から始めてください。

• レビューのみ： 重大度の高い順に指摘事項を並べ、それぞれを file:line、問題点、具体的な修正方法の形式で記載してください。実質的な問題が見つからなかった場合は、その旨を一行で伝えてください。
• 修正モード： 修正した内容を記載し、次に修正しなかった内容とその理由を記載してください。保留または対象範囲外の指摘事項は、ユーザーが判断できるよう、それぞれ一行で記載し、パイプラインの結果も記してください。

実際の問題は明確に述べ、「検討してもよいかもしれません」「可能性があります」といった曖昧な表現は避けてください。任意の項目には「低」と記して先に進んでください。スタイル上の細かな指摘は、あちこちに散らさず、一つの注記にまとめてください。記載内容を繰り返す要約で締めくくらないでください。明らかな内容で水増しした長い報告より、重要な点を絞った短い報告のほうが望ましいです。