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）：独自の型にする価値があるドメイン概念を、プリミティブ型や文字列で表しています。→ その概念を表す小さな型を作ります。
• 繰り返される switch 文（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. 両方のサブエージェントを並行して起動する

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

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

• 完全な差分コマンドとコミット一覧。
• ステップ3で見つけた規約ソースファイルの一覧に加え、ステップ3のコードスメルのベースライン全文（サブエージェントはほかの場所から参照できないため、全文を貼り付けます）。
• 次の指示：「該当する場合はファイルや差分箇所ごとに、(a) 差分内で文書化された規約に違反している箇所をすべて報告し、規約（ファイル名とルール）を引用してください。(b) 気づいたベースラインのコードスメルを報告し、該当する差分箇所を引用してください。確定的な違反と判断の目安を区別してください。文書化された規約への違反は確定的な場合がありますが、ベースラインのコードスメルは常に判断の目安であり、文書化されたリポジトリの規約はベースラインより優先されます。ツールでチェックされているものは対象外とします。400語未満でまとめてください。」

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

• 差分コマンドとコミット一覧。
• 仕様のパスまたは取得した内容。
• 次の指示：「次の内容を報告してください。(a) 仕様で求められているものの、欠落している要件または部分的にしか実装されていない要件。(b) 差分内にある、仕様で求められていない動作（スコープクリープ）。(c) 実装済みに見えるものの、実装に誤りがあるように見える要件。指摘ごとに仕様の該当箇所を引用してください。400語未満でまとめてください。」

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

5. 集約

2つのレポートを、## Standards と ## Spec の見出しの下に、原文のまま、または軽く整えて記載します。2つの軸は意図的に分けているため、指摘事項を統合したり、順位を付け直したりしないでください（_2つの軸を設ける理由_を参照）。

最後に、各軸の指摘件数と、それぞれの軸で最も重大な問題（あれば）を1行でまとめます。2つの軸をまたいで単一の勝者を選ばないでください。軸を分けているのは、まさにそうした順位の付け直しを防ぐためです。

2つの軸を設ける理由

ある変更が、一方の軸には合格し、もう一方の軸には不合格となる場合があります。

• すべての標準に従っているものの、誤った機能を実装しているコード → 標準は合格、仕様は不合格。
• 課題の依頼どおりに実装しているものの、プロジェクトの規約に違反しているコード → 仕様は合格、標準は不合格。

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