code-review

HEAD とユーザーが指定した固定ポイントの間の差分を、次の2つの観点からレビューします。

• 標準：コードは、このリポジトリで文書化されているコーディング標準に準拠していますか？
• 仕様：コードは、起点となる課題／仕様を忠実に実装していますか？

2つの観点は、互いのコンテキストを汚染しないよう、並列のサブエージェントでそれぞれ確認します。その後、このスキルが調査結果を集約します。

課題トラッカーは、すでに提供されているはずです。docs/agents/issue-tracker.md が見つからない場合は、/setup-agent-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. コミットメッセージ内の課題参照（#123、Closes #45、GitLab の !67 など）。docs/agents/issue-tracker.md に記載されたワークフローを使って取得します。
2. ユーザーが引数として指定したパス。
3. ブランチ名または機能に一致する、docs/、specs/、.scratch/ 配下の仕様ファイル。
4. 何も見つからない場合は、仕様の場所をユーザーに尋ねてください。仕様がないと回答された場合、仕様サブエージェントは処理をスキップし、「仕様を利用できません」と報告します。

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. 両方のサブエージェントを並行して起動する

標準サブエージェントのプロンプトには、次の内容を含めてください。

• 完全な差分コマンドとコミット一覧。
• 手順3で見つけた標準の情報源となるファイルの一覧に加え、手順3のコードの臭いのベースライン全体を貼り付けてください（サブエージェントはそれ以外の方法で参照できません）。
• 次の依頼文：「該当箇所について、ファイル／ハンクごとに報告してください。(a) 差分が文書化された標準に違反する箇所をすべて挙げ、標準（ファイル名＋ルール）を引用する。(b) 該当するベースラインのコードの臭いを特定し、そのハンクを引用する。確定的な違反と判断の余地があるものを区別する。文書化された標準への違反は確定的な場合がありますが、ベースラインのコードの臭いは常に判断の余地があり、リポジトリに記載された標準はベースラインより優先されます。ツールによって強制されているものは対象外にしてください。400語未満で回答してください。」

仕様サブエージェントのプロンプトには、次の内容を含めてください。

• 差分コマンドとコミット一覧。
• 仕様のパスまたは取得した内容。
• 次の依頼文：「次の点を報告してください。(a) 仕様で求められているのに、未実装または一部しか実装されていない要件。(b) 差分に含まれる、仕様で求められていない動作（スコープの逸脱）。(c) 実装済みに見えるものの、実装に問題がある要件。各指摘について仕様の該当箇所を引用してください。400語未満で回答してください。」

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

5. 集約

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

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

2つの軸を設ける理由

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

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

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