code-review

ユーザーが指定した fixed point と HEAD の間の diff を、2 軸でレビューします。

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

2 つの軸は、context が互いに影響しないよう並列 sub-agentsとして実行し、このスキルで findings を集約します。

Issue tracker はすでに提供されているはずです。docs/agents/issue-tracker.md がない場合は、ユーザーに /setup-matt-pocock-skills を実行するよう依頼してください。

フロー

1. fixed point を決定する

ユーザーが指定する内容は何であっても fixed point です。commit SHA、branch name、tag、main、HEAD~5 などが該当します。ユーザーが指定していない場合は、質問してください。

まず、diff command を一度取得します：git diff <fixed-point>...HEAD（three-dot なので、比較対象は merge-base です）。同時に git log <fixed-point>..HEAD --oneline で commits の一覧を記録します。

続行する前に、fixed point を解決できること（git rev-parse <fixed-point>）と、diff が空でないことを確認します。無効な ref や空の diff は、2 つの並列 sub-agents を起動してからではなく、この段階で失敗させてください。

2. 仕様の参照元を探す

以下の順序で、参照元の仕様を探します。

1. Commit messages 内の issue references（#123、Closes #45、GitLab !67 など）。docs/agents/issue-tracker.md に記載された workflow に従って取得します。
2. ユーザーが argument として渡した path。
3. branch name または feature に一致する、docs/、specs/、.scratch/ 内の仕様ファイル。
4. 見つからない場合は、仕様の場所をユーザーに質問します。ユーザーが仕様はないと答えた場合は、Spec sub-agent をスキップし、「no spec available」と報告します。

3. 規約の参照元を探す

リポジトリ内にある、コードの記述方法を定めた内容を探します。たとえば CODING_STANDARDS.md や CONTRIBUTING.md です。

リポジトリに記録された規約に加えて、Standards 軸には常に以下の smell baseline を適用します。これは Fowler の固定された code smells の一覧（Refactoring 第 3 章）であり、リポジトリに規約がまったくない場合にも適用されます。ルールは 2 つです。

• リポジトリの規約が優先されます。 記録されたリポジトリの規約は常に優先されます。baseline が指摘する内容をその規約が認めている場合、その smell は指摘しません。
• 常に判断を伴います。 各 smell はラベル付きの heuristic（例：「Feature Envy の可能性」）であり、絶対的な違反ではありません。ここに記載された他の規約と同様、tooling がすでに強制している内容はスキップします。

それぞれの smell を what it is -> how to fix の形式で確認し、diff と照らし合わせます。

• Mysterious Name：function、variable、type の名前から、何をするものか、何を格納するものかが分かりません。-> 名前を変更します。適切な名前が見つからない場合、設計自体が曖昧なのかもしれません。
• Duplicated Code：同じ logic shape が複数の hunk または file に現れています。-> 共通の形を抽出し、両方から呼び出します。
• Feature Envy：method が、自身の data よりも別の object の data に頻繁にアクセスしています。-> method を、その data を持つ object に移します。
• Data Clumps：同じ field 群や param 群がいつも一緒に現れます。-> まとめて 1 つの type にし、受け渡します。
• Primitive Obsession：独自の type を持つ価値のある domain concept が、primitive や string で表現されています。-> その concept に小さな type を与えます。
• Repeated Switches：同じ type に対する同じ switch／if cascade が、変更箇所で繰り返されています。-> polymorphism に置き換えるか、map を共有します。
• Shotgun Surgery：1 つの論理的な変更により、diff 内の多くの file を変更する必要があります。-> 一緒に変更されるものを 1 つの module にまとめます。
• Divergent Change：1 つの file または module が、互いに無関係な複数の理由で変更されています。-> 分割し、各 module が 1 つの理由だけで変更されるようにします。
• Speculative Generality：仕様にないニーズのために abstraction、params、hooks を追加しています。-> 実際の必要性が生じるまで削除し、inline に戻します。
• Message Chains：caller が依存すべきでない、a.b().c().d() のような長い連鎖的な navigation です。-> 最初の object の method 内にその navigation を隠します。
• Middle Man：class または function が、ほぼ単に処理を委譲しているだけです。-> それを削除し、実際の呼び出し先を直接呼び出します。
• Refused Bequest：subclass または implementer が、継承した内容の大部分を無視するか override しています。-> inheritance を取り除き、composition を使います。

4. 2 つの sub-agents を並列で起動する

Standards sub-agent の prompt には、以下を含めます。

• 完全な diff command と commit list。
• Step 3 で見つけた standards-source files の一覧、および Step 3 の smell baseline 全文。sub-agent が baseline を参照する方法は他にありません。
• Brief：「該当する場合は file／hunk ごとに、(a) diff が記録された規約に違反している箇所をすべて報告してください。規約（file + rule）を引用してください。(b) 気づいた baseline smell を報告してください。名前を挙げ、該当する hunk を引用してください。重大な違反と判断を伴う指摘を区別してください。記録された規約への違反は重大な場合がありますが、baseline smells は常に判断を伴う指摘であり、記録されたリポジトリの規約が baseline より優先されます。tooling が強制している内容はスキップしてください。400 words 未満で報告してください。」

Spec sub-agent の prompt には、以下を含めます。

• Diff command と commit list。
• 仕様の path または取得済みの内容。
• Brief：「以下を報告してください。(a) 仕様が求めているが欠けている、または部分的な要件。(b) diff 内にある、求められていない動作（scope creep）。(c) 実装済みに見えるものの、実装が誤っているように見える要件。それぞれの指摘について、仕様の該当行を引用してください。400 words 未満で報告してください。」

仕様がない場合は Spec sub-agent をスキップし、最終レポートにその旨を記載します。

5. 集約する

## Standards と ## Spec の headings の下に、2 つのレポートを掲載します。原文のままでも、軽微に整えてもかまいません。findings を統合したり、順序を変更したりしないでください。この 2 つの軸は意図的に分けています（2 つの軸を設ける理由 を参照）。

最後に 1 行で要約します。各軸の findings の総数と、各軸で最も深刻な問題（あれば）を記載してください。軸をまたいで総合優勝を決めてはいけません。軸を分けるのは、そうした再評価を避けるためです。

2 つの軸を設ける理由

変更は、一方の軸を通過しながら、もう一方の軸で不合格になることがあります。

• コードはすべての規約に準拠していますが、誤ったものを実装しています -> Standards pass, Spec fail.
• コードは issue の要件に完全に沿っていますが、プロジェクトの規約に違反しています -> Spec pass, Standards fail.

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