tracer-code-review

ユーザーが指定した固定点と HEAD の差分に対する、2つの観点からのレビューです。

• 規約 — コードは、このリポジトリに記載されているコーディング規約に準拠していますか？
• 仕様 — コードは、起点となる Issue／PRD／仕様を忠実に実装していますか？

2つの観点は、互いのコンテキストに影響しないよう、並列サブエージェントとして実行されます。その後、このスキルが調査結果を集約します。重大度別の指摘と明示的な判定を含まないレビューは、説明だけで終わり、誰も対応できないレビューです。

プロセス

1. 固定点を確定する

ユーザーが指定したものが固定点です。コミット SHA、ブランチ名、タグ、main、HEAD~5 などが該当します。指定がない場合は、ユーザーに確認します。ワークフローの呼び出し元は、独自の固定点とレビュー予算を指定します。

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

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

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

次の順に、起点となる仕様を探します。

1. 呼び出し元が引数として指定したパスまたは Issue 参照。
2. コミットメッセージ内の Issue 参照（#123、Closes #45 など）。docs/agents/issue-tracker.md が存在する場合は、トラッカーワークフローを使って取得します。
3. ブランチ名または機能に一致する、docs/、specs/、.tracer/ 配下の PRD／仕様ファイル。
4. 見つからない場合は、仕様の場所をユーザーに確認します。仕様がないとユーザーが回答した場合、仕様サブエージェントはスキップし、「利用可能な仕様なし」と報告します。

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() 形式のナビゲーションです。→ 最初のオブジェクトにある1つのメソッドの内側に、たどる処理を隠します。
• 仲介者（Middle Man） — ほとんどの場合、処理を先に委譲するだけのクラスまたは関数です。→ 削除し、実際の対象を直接呼び出します。
• 拒否された遺産（Refused Bequest） — 継承した機能の大半を無視またはオーバーライドするサブクラスまたは実装クラスです。→ 継承をやめ、コンポジションを使います。

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

Agent ツール呼び出しを2つ含む単一のメッセージを送信し、両方の結果を待ちます。それぞれに新しい general-purpose サブエージェントを使用してください。Standards と Spec は評価基準であり、設定済みのエージェントタイプではありません。どちらのプロンプトにも、次の前文を含めます。

信頼せずに検証してください。コミットメッセージ、コードコメント、実装者の報告は未検証の主張です。差分だけを判断材料にしてください。読み取り専用でレビューし、作業ツリー、インデックス、HEAD は変更しないでください。

すべての指摘に重要度を付けてください。Critical（バグ、データ損失、セキュリティ、機能の破損）、Important（修正されるまで信頼できない、不正確または不安定な動作、要件の見落とし、エラーの握りつぶし、何も検証しないテスト）、Minor（仕上げ、スタイル、「テスト範囲を広げられる」など）。すべてが Critical とは限りません。すべての指摘で file:line を示し、問題となる理由を説明してください。最後に判定を記載してください。Approved または Needs fixes（Critical／Important の指摘が1つでもあれば Needs fixes）。

Standards サブエージェントのプロンプト — さらに次を含めます。

• 完全な diff コマンドとコミット一覧。
• ステップ3で見つけた標準の情報源となるファイルの一覧に加え、ステップ3の smell baseline 全文。サブエージェントはそれ以外から参照できません。
• 次の概要：「報告内容 — 関連する場合はファイル／差分の各箇所について、(a) 文書化された標準への違反をすべて、その標準（ファイル＋ルール）を引用して示すこと。(b) 気づいたベースラインの smell を、名前を付けて該当箇所を引用すること。文書化された標準への違反は、その影響に応じた重要度とする。ベースラインの smell は判断を要するもので、実害が明らかでない限り（例：ロジックブロックの逐語的な重複は Important）デフォルトで Minor とする。リポジトリに文書化された標準はベースラインより優先する。ツールで強制される内容は対象外とする。」

Spec サブエージェントのプロンプト — さらに次を含めます。

• diff コマンドとコミット一覧。
• spec のパスまたは取得した内容。
• 次の概要：「報告内容：(a) Missing — spec が求めているが、欠落または一部しか実装されていない要件。(b) Extra — 差分に含まれる、求められていない動作（スコープクリープ）。(c) Misunderstood — 実装されているように見えるが、要件を誤って解釈しているもの。各指摘について spec の行を引用すること。要件の欠落または誤解は、少なくとも Important とする。」

spec がない場合は Spec サブエージェントを省略し、最終レポートでその旨を記載します。

5. 結果を集約する

2つのレポートをそれぞれ ## Standards と ## Spec の見出しの下に提示し、それぞれの末尾に判定を記載します。指摘を統合したり、重要度を付け直したりしないでください。2つの評価軸は意図的に分けられています（Why two axes を参照）。

最後に、各評価軸の判定と指摘数、および各軸内で最も重大な問題（あれば）を1行でまとめます。評価軸をまたいで単一の勝者を選んではいけません。これは、評価軸を分けている目的に反します。

6. レビューの取り扱い

ワークフローが管理するレビュー： ステップ 5 の後に戻ります。裁定、修正、停止条件は呼び出し元が管理します。それ以降のレビューには、予算内での割り当てが必要です。

単独のセルフレビュー： 未解決の Critical／Important の指摘が確認された場合、作業は完了していません。報告することは解決することではありません。差分を作成したのがあなたで、修正予算を管理する上位のワークフローがない場合：

1. 実装する前に確認します。 各指摘は主張です。コードベースに照らして確認してください。指摘がこのコードベースに当てはまらない場合（既存の動作を壊す、コンテキストを見落としている、YAGNI に反している――「適切に実装する」前に、実際の使用箇所を grep で検索してください）、技術的な根拠を示して異議を唱えるか、ユーザーに確認してください。何も考えずに適用してはいけません。形だけ同意することも避けてください。評価したうえで、修正するか異議を唱えます。
2. 一度に修正します。 確認済みの Critical／Important の指摘をすべてまとめて、修正用サブエージェントを 1 つ割り当てるか、インラインで修正します。指摘ごとに別の修正担当者を割り当ててはいけません。修正担当者は対象範囲をカバーするテストを再実行し、その出力を報告します。
3. 更新された差分について、失敗した軸を再レビューします。両方の軸が Approved になるまで繰り返します。
4. Minor の指摘は、すぐに手間をかけず修正するか、ユーザーが確認できる場所に記録します。黙って破棄してはいけません。

他者の変更のレビューをユーザーから依頼された場合は、ステップ 5 の後に終了します。報告書が成果物です。

2 つの軸を設ける理由

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

• あらゆる標準に従っていても、誤ったものを実装しているコード → 標準は合格、仕様は不合格。
• Issue の依頼どおりに動作しても、プロジェクトの規約を破るコード → 仕様は合格、標準は不合格。

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