code-review

HEAD とユーザーが指定した固定点との差分を、2 つの軸でレビューします。

• Standards：コードは、このリポジトリに文書化されたコーディング規約に準拠していますか？
• Spec：コードは、元となる issue／仕様を忠実に実装していますか？

両方の軸は、互いのコンテキストに影響しないよう並列サブエージェントで実行され、その後、このスキルが結果を集約します。

issue トラッカーはすでに提供されているはずです。提供されていない場合は、ユーザーに /setup-matt-pocock-skills を実行するよう伝えてください。

プロセス

1. 固定点を特定する

ユーザーが指定したもの（コミット SHA、ブランチ名、タグ、main、HEAD~5 など）を固定点とします。指定がない場合は、ユーザーに確認してください。

差分コマンド git diff <fixed-point>...HEAD（3 点リーダーを使い、マージベースとの差分を比較します）を一度だけ記録します。また、コミット一覧を git log <fixed-point>..HEAD --oneline で記録します。

先に進む前に、固定点を解決できること（git rev-parse <fixed-point>）と、差分が空でないことを確認します。不正な参照または空の差分の場合は、2 つの並列サブエージェント内ではなく、ここで失敗させてください。

2. 仕様の出典を特定する

以下の順に、元となる仕様を探します。

1. コミットメッセージ内の issue 参照（#123、Closes #45、GitLab の !67 など）。トラッカードキュメントのワークフローを使って取得します。
2. ユーザーが引数として渡したパス。
3. ブランチ名または機能に一致する、docs/、specs/、.scratch/ 配下の仕様ファイル。
4. 見つからない場合は、仕様の場所をユーザーに尋ねます。仕様はないと回答された場合、Spec サブエージェントはスキップし、「利用可能な仕様なし」と報告します。

3. 標準の情報源を特定する

リポジトリを検索し、コードの書き方を説明しているファイルをすべて探してください。CODING_STANDARDS.md または CONTRIBUTING.md がある場合は、必ず一覧に含めてください。

リポジトリに記載されている内容に加えて、標準の軸には常に以下のコードの臭いの基準が含まれます。これは Fowler のコードの臭い（Refactoring 第3章）から固定したもので、リポジトリに何も記載されていない場合にも適用されます。これには、次の2つのルールが適用されます。

• リポジトリの規定を優先します。 リポジトリに標準が記載されていれば、常にそれが優先されます。基準では指摘されるものでも、リポジトリの標準が認めている場合は、その臭いの指摘を抑制します。
• 必ず判断を伴います。 各コードの臭いは「Feature Envy の可能性」のようにラベル付きのヒューリスティックであり、確定的な違反ではありません。ここに記載されたほかの標準と同様、ツールによってすでに強制されているものは対象外にしてください。

各コードの臭いは、それが何か → どう修正するか の順に説明しています。差分に照らして確認してください。

• わかりにくい名前（Mysterious Name）：何をするのか、何を保持するのかが名前からわからない関数、変数、型です。→ 名前を変更してください。適切な名前を付けられない場合、設計が不明瞭です。
• コードの重複（Duplicated Code）：変更内の複数の差分箇所やファイルで、同じロジックのパターンが繰り返されています。→ 共通するパターンを抽出し、両方から呼び出してください。
• 機能への執着（Feature Envy）：自分自身のデータよりも、ほかのオブジェクトのデータに頻繁にアクセスするメソッドです。→ そのメソッドを、執着しているデータ側に移してください。
• データのまとまり（Data Clumps）：同じいくつかのフィールドやパラメーターが繰り返し一緒に使われています（型としてまとめるべきものです）。→ 1つの型にまとめ、その型を渡してください。
• プリミティブ型への執着（Primitive Obsession）：独自の型にする価値のあるドメイン概念を、プリミティブ型や文字列で表しています。→ その概念に独自の小さな型を用意してください。
• 繰り返される条件分岐（Repeated Switches）：同じ型を対象とする switch や if の連鎖が、変更内で繰り返されています。→ ポリモーフィズムに置き換えるか、両方の箇所で共有する1つのマップを使ってください。
• ショットガン手術（Shotgun Surgery）：1つの論理的な変更によって、差分内の多くのファイルに散在する編集が必要になります。→ 変更される内容を1つのモジュールにまとめてください。
• 変更理由の分散（Divergent Change）：1つのファイルやモジュールが、互いに無関係な複数の理由で編集されています。→ 各モジュールが1つの理由で変更されるよう、分割してください。
• 投機的な汎用化（Speculative Generality）：仕様では必要とされていない抽象化、パラメーター、フックが追加されています。→ 削除してください。実際の必要性が明らかになるまで、インライン化して戻してください。
• メッセージチェーン（Message Chains）：呼び出し元が依存すべきでない長い a.b().c().d() のようなナビゲーションです。→ 最初のオブジェクトにメソッドを用意し、辿る処理を隠してください。
• 仲介人（Middle Man）：ほとんど委譲するだけのクラスや関数です。→ 取り除き、実際の対象を直接呼び出してください。
• 継承の拒否（Refused Bequest）：継承したものの大部分を無視またはオーバーライドするサブクラスや実装です。→ 継承をやめ、コンポジションを使ってください。

4. 両方のサブエージェントを並行して起動する

両方のサブエージェント呼び出しを同時にフォアグラウンドで実行し、返されたレポートをまとめます。

Standards サブエージェントへのプロンプトには、次の内容を含めます。

• 完全な diff コマンドとコミット一覧。
• 手順 3 で見つけた標準の参照ファイルの一覧と、手順 3 の smell baseline 全文（サブエージェントはそれ以外から参照できません）。
• 次の概要：「該当する場合はファイル／ハンクごとに、（a）diff 内で文書化された標準に違反しているすべての箇所（標準をファイル名とルールで示す）、および（b）気づいた baseline smell を報告してください。ハードな違反と判断の余地がある指摘を区別してください。文書化された標準への違反はハードな指摘になり得ますが、baseline smell は常に判断の余地がある指摘であり、文書化されたリポジトリ標準は baseline より優先されます。ツールで強制される事項は除外してください。各指摘にファイルと行を記載し、マージをブロックすべき場合に限り blocking と記してください。ブロックすべき指摘には、失敗を確認する方法も記載してください。/code-review を呼び出したり、ほかのエージェントを起動したりせず、このレビューを直接行ってください。400 語未満で記述してください。」
• これ以外は含めないでください。ユーザーの依頼、仕様、変更に関する独自のメモは渡さないでください。このサブエージェントは、標準だけを基準に diff を評価します。

Spec サブエージェントへのプロンプトには、次の内容を含めます。

• diff コマンドとコミット一覧。
• 仕様のパスまたは取得した内容。
• 次の概要：「（a）仕様が求めているもののうち、欠落または一部しか実装されていない要件、（b）求められていない diff 内の動作（スコープクリープ）、（c）実装済みに見えるものの、実装に誤りがある要件を報告してください。各指摘について、該当する仕様の行を引用し、diff 内のファイルと行を記載してください。マージをブロックすべき場合に限り blocking と記し、ブロックすべき指摘には失敗を確認する方法も記載してください。/code-review を呼び出したり、ほかのエージェントを起動したりせず、このレビューを直接行ってください。400 語未満で記述してください。」

仕様が見つからない場合は Spec サブエージェントを省略し、その旨を最終レポートに記載します。

5. 集約

レポートを提示する前に、blocking とした指摘すべての根拠を確認します。引用されたファイルと行を開き、指摘内容が記載どおりであることを確かめてください。根拠が確認できた指摘は残し、確認できなかったものは、確認した場所を添えて unconfirmed と記します。サブエージェントのレポートは主張であり、根拠ではありません。

2 つのレポートは ## Standards と ## Spec の見出しの下に提示します。原文のまま、または軽く整える程度にしてください。各軸の中では、blocking の指摘を先に記載します。2 つの軸の指摘を統合したり、順位を付け直したりしないでください。詳しくは「2 つの軸を設ける理由」を参照してください。

最後に、各軸の指摘件数と、各軸で最も重大な問題（あれば）を 1 行で要約します。軸をまたいで単一の最優先事項を選ばないでください。軸を分けている目的に反するためです。

2 つの軸を設ける理由

変更は、一方の軸を通過し、もう一方の軸では失敗することがあります。

• すべての標準に従っているコードが、依頼された内容を誤って実装している → Standards pass, Spec fail.
• 課題の依頼どおりに実装していても、プロジェクトの規約に違反している → Spec pass, Standards fail.

別々に報告することで、一方の軸がもう一方の問題を覆い隠すことを防げます。