code-review

コードレビュー

目的

レビュー結果の大半はノイズです。誤りに「見える」項目を、優先順位も反証もなく、実行に移すこともできないまま並べたものです。このスキルはその逆を目指します。各指摘には、求められる動作、成立しうるトリガー、具体的な矛盾、観測可能な影響、そして確認済みの最も有力な反論を盛り込み、指摘の数を絞ります。

中心となる考え方は、レビュー担当者が見落とす欠陥は、一つのファイルの中に見つかることはほとんどないということです。それぞれ単独では妥当に見える二者間の食い違いです。呼び出し元と呼び出し先、プロデューサーとコンシューマー、書き込み側と後から読む側、同じ状態を確立するはずの二つの分岐などが該当します。ファイルごとにチェックリストを適用しても、二つの側面が同時に視野に入ることがないため、こうした食い違いは見つけられません。したがって、ここでのレビュー単位はファイルではなく合意です。

構成：一つのエンジン、三つの軸

コードレビューがこのスキルです。正しさがその中核です。汎用ツールが最も不得意とする観点であり、以下で詳しく説明します。パフォーマンスとセキュリティはその特殊ケースです。同じエンジン、同じ反証の規律、同じ報告形式を使いながら、軸を変え、それぞれに一つか二つの追加ルールを設けます。

特殊ケース	軸	ルールの記載場所
正しさ (中核、デフォルト)	境界を越えた参加者間の合意	このファイル + references/correctness-taxonomy.md
パフォーマンス	ワークロード → リソース需要 → 増加または競合 → 影響	references/performance-review.md
セキュリティ	ソース → 信頼境界 → シンク。ソースを攻撃者が制御	references/security-review.md

特殊ケースが選択された場合に限り、そのファイルを読んでください。意図的に短くしています。そこでは異なる点を説明し、それ以外は引き続きこのファイルに従います。

特殊ケースは相互排他的ではなく、それぞれ独立して有効化されます。一つの根本原因が正しさとセキュリティの両方に影響する場合は、両方の影響を添えて、一度だけ報告してください。

呼び出し方

/pm-ai-shipping:code-review
/pm-ai-shipping:code-review dimensions=correctness scope=changes
/pm-ai-shipping:code-review dimensions=performance,security
/pm-ai-shipping:code-review dimensions=all

Claude Code には独自の /code-review が同梱されています。こちらを指定する場合は、上記のプラグイン修飾形式を使ってください。

これらは指示の引数であり、シェルのフラグではありません。

• デフォルト：correctness。 「これをレビューして」や「バグを見つけて」とだけ指定された場合は、正しさのみを対象とします。
• 明示的なリストを指定すると、その特殊ケースのみが選択されます。all を指定すると三つすべてが選択されます。不明な選択肢や空の選択を黙って別の意味に解釈してはいけません。確認してください。
• スコープ： 指定された範囲を使います。指定がなければ、作業中の変更がある場合はそれを、なければリポジトリ全体をレビューします。
• 調査を始める前に、選択した観点、スコープ、比較の基準を明示してください。
• 変更をレビューする際は、変更行の先にある依存関係まで追跡し、変更によって生じた欠陥と、変更によって単に明らかになった欠陥を区別します。
• レビューして報告してください。依頼された場合に限り、修正を適用してください。

共通エンジン

すべての特殊ケースで、一つの骨格を使います。異なるのは軸と反証ルールだけです。

フローをマッピングする → 義務を特定する → すべての参加者を調べる → 違反が起きる実行を構成する → 影響を追跡する → 反証を試みる → 報告する。

まず、入力、主要な実行フロー、各状態の所有者、外部依存関係、観測可能な効果を含む最小限のマップを一つ作成します。選択された各特殊ケースはそのマップを拡充します。マップを三つ作ってはいけません。また、セキュリティのみを対象とする実行を、正しさのマッピングが終わるまで待たせてはいけません。

正しさ：合意のエンジン

境界は意味上のものであり、ファイルの分割ではありません。呼び出し元と呼び出し先、2つのコールバック、同じ関数の2回の実行、生成側と消費側、または今書き込まれて後から読み取られる値を隔てます。

影響の大きい合意ごとに、レポートではなく作業メモに次の事項を記録してください。

Participants:
Value, entity or effect exchanged:
Authority (who decides the real answer):
Identity and lifetime/version:
Required relationship:
Evidence for that relationship:
Relevant transitions or orderings:
Observable consumer or consequence:

意図を捏造せず、義務を確立します。 根拠となるのは、仕様、文書化された契約、言語やプロトコルのセマンティクス、期待を示すテスト、または必要不可欠な生成側と消費側の関係です。消費側の実装だけでは、消費側が正しいことの証明にはなりません。参加者の間で意見が食い違う場合、その不一致がなぜ誤った結果を生むのかを述べます。矛盾自体は確実でも、どちらを変更すべきかは真に未確定の場合があります。文書がないことは制約であり、自動的に指摘事項となるわけではありません。

合意が最も崩れやすい箇所から始めます。 変換または交渉される値、再割り当てされる識別子、非同期になる処理、保存して再読み込みされる状態、複数の効果が一致しなければならない箇所です。その後、通常の判断、算術、境界、エラー分岐を局所的に確認します。アンカーを理由に、ありふれたバグを見落としてはなりません。

違反する実行を強制する

疑念は、それを破る実行を構成するまでは指摘事項ではありません。実装が許す範囲で、次のことを行います。

• 要求された値と、受け入れられた値または実効値を異なるものにする。
• 2つの操作を同時に有効にし、完了順序を変える。
• 観測してから使用するまでの間に、関連する識別子または世代を変更する。
• 同等の状態に至るべき、異なる遷移を比較する。
• 効果の間に障害を注入し、完了前に処理を中断する。
• 空の入力、境界ちょうどの入力、境界に隣接する入力を試す。

それぞれのケースが実際に発生可能であることを確認してください。発生可能だと思い込んではなりません。

言及ではなく、強制的なプローブが必要な2つの観点

実際のコードベースに仕込まれた実行時の欠陥を大規模に評価したところ、優秀なエージェントでさえ、2つの種類の欠陥は報告すらほとんどされませんでした。チェックリストに挙げても役に立ちません。それぞれに明示的なプローブが必要です。

1. 権限の調整。 提案された値が検証、正規化、交渉、または確定を経る流れを追い、権限側から異なる値が返される可能性があるのに、後続の状態が依然として提案値から導出されている箇所を探します。要求された値は、適用された値ではありません。 プローブ：両者を異なる値にし、要求値を読み続けている箇所を調べます。
2. 識別と相関付け。 操作の結果が、どのようにその操作を開始したエンティティに結び付けられるかを追跡し、重複実行、順序の入れ替わり、削除、再利用が起きた場合にも、キーが十分な期間、一意で安定し、有効であることを確認します。ラベル、位置、到着順序は、それらの性質が損なわれる可能性がある場合に限り、疑わしいものとなります。プローブ：2つの操作を同時に実行し、順序を逆にして完了させます。

検出の手がかりを含む13の診断観点の全リストは、references/correctness-taxonomy.mdにあります。これらは互いに重複する観点であり、すべてを埋めるためのノルマではありません。

反証：これを実行する価値を生み出す規律

候補を指摘事項として扱えるのは、次の5つすべてを満たす場合だけです。

1. 裏付けのある義務 — 何が成立すべきか、またその根拠は何か。
2. 実行可能な実行経路 — 入力、状態、順序が、実際のシステムで許容されていること。
3. 具体的な矛盾 — 義務がどこで成立しないか。
4. 観測可能な結果 — 誤った出力、状態、効果、完了、または進捗。
5. 検討済みの反論 — それを防止または修復する、最も有力な仕組み。

反証を積極的に探してください。実行を不可能にする上位の保証、インターリーブを排除する同期、影響のある読み取りの前に行われる照合、意図された契約、入力を除外する前提条件、または別の責任者が対応する仕組みです。

結果	基準
維持	根拠によって不具合が立証され、検討した反論では防止できません。
却下	引用した根拠により、実行経路、義務、または結果が否定されます。
未解決	本質的な契約またはランタイムの事実が不明です。指摘事項とは分けて列挙してください。

正確性の問題に、セキュリティの個別ケースにおける攻撃者／被害者のテストを持ち込まないでください。**正確性の不具合は、それを引き起こした本人にしか害を及ぼさなくても、深刻な場合があります。**同様に、「反証されない限り維持する」という基準も緩すぎます。具体的な実行経路を構成できない、根拠のない疑念は指摘事項ではありません。両方の個別ケースを扱う場合は、それぞれのテストを該当する側面にのみ適用してください。

吸収は防止ではありません。反証で最も大きな誤りにつながるのは、下流に不具合をたまたま隠すものを見つけて指摘事項を却下してしまうことです。たいてい値を保持しているキャッシュ、たいてい成功する再試行、たいてい正しいデフォルト値などです。これは保証ではなく、確率の高い偶然にすぎません。吸収する側が空、削除済み、または再設定された日に破綻します。その実行を不可能にする仕組みがある場合にのみ却下し、どの仕組みかを明示してください。同じ理由で、「ほとんどの場合は動く」は反証ではなく競合状態の説明です。たいてい正しく解決するタイミングウィンドウは指摘事項であり、どちらがたいてい勝つかを推論する必要があったという事実が根拠になります。

テストの合格、見慣れないコード、疑わしい名前、テストの欠如、類似コードとの差異は、調査の手がかりにはなりますが、どれも証明でも反証でもありません。ファイル単位ではなく、違反された合意と根本原因によって重複を整理してください。指摘事項にノルマはありません。裏付けのある指摘事項がゼロでも、有効な結果です。

並列処理

ファイル単位ではなく、完全なフローまたは相互につながった契約のグループを分担してください。分類クラスごとにエージェントを1つ割り当てることも避けてください。ファイル単位で分けると、境界をまたぐ欠陥が見えなくなります。発見する価値があるのは、まさにそのような欠陥です。

1. コーディネーターが初期マップを作成し、共有状態を特定します。
2. 各ワーカーに、範囲を限定したフロー、その参加者、選択したサブケース、未解決の疑問点を割り当てます。
3. ワーカーは契約の両側を調査し、担当リスト外の依存関係も追跡できます。
4. ワーカーは候補、引用付きの証拠、完了した反証、未解決の関係を返します。
5. コーディネーターは前提と、割り当てをまたぐ関係を調整します。
6. 有力な候補は、報告前に別途検証します。

読み取りの重複を許容してください。 同じ権威ある情報源を2人のワーカーが読むコストは、どちらか一方が契約の半分しか把握できないコストよりはるかに低くなります。統合のための余力を確保してください。2つの割り当てにまたがる未解決の関係は、誰かが解決するまで調査されないままです。ファンアウトは1階層にとどめるのが目標です。委任できない場合や範囲が小さい場合は、同じ手順を逐次実行します。

利用可能な最も高性能なモデルでワーカーを実行し、現在のセッションと同じ努力レベルに合わせてください。 これは再現率を優先する作業です。境界をまたぐフローの見落としは重大な失敗であり、ワーカーがひそかに安価なモデルや低い努力レベルに切り替わることは、見落としを招く最も簡単な方法です。ワーカーが別のモデルに振り替えられたり、ダウングレードされたりした場合は、レポートにその内容を記載してください。すべてを1つのモデルが確認したと思い込む読者は、カバー範囲を誤って判断します。

すべてのワーカーに同じモデルを指定してください。 ここでのファンアウトは、セカンドオピニオンではなくカバー範囲を広げるためのものです。各ワーカーの起動時に、コーディネーター自身のモデルを明示的に指定してください。「継承」は振り分けの判断ではなく、ワーカーがひそかに安価なモデルに割り当てられると、調査結果を見落としやすくなります。明示的に依頼されない限り、レビューやクロスチェックに別のモデルを使わないでください。モデルを混在させると結果の帰属が不明瞭になり、このスキルをモデル間で測定または比較している場合、別のモデルを使ったワーカーが1つでもいれば、その数値は無効になります。独立した別モデルによる確認は別個の明示的な手順（/ship-check の Step 6）であり、このスキルが独自に行うことはありません。

ワーカーには、編集ではなく読み取りを行うよう伝えてください。 レビューワーカーに必要なのは読み取り、検索、移動であり、ツリーを変更してはなりません。ワーカーへの指示にその旨を明記してください。編集を始めるワーカーは、レビューから「親切な」修正へと逸脱し、ひそかに修正した内容を報告しなくなるため、調査結果を説明対象のコードと照合できなくなります。ホスト側が強制すると思い込まず、プロンプトで伝え、実行終了時にツリーが変更されていないことを確認してください。

レポート

裏付けのある調査結果を、影響の大きい順に先頭に記載します。重大度と証拠の強さは分けて扱ってください。

Review scope:
Comparison baseline:
Selected dimensions:

[Severity] [Dimension] Concrete consequence
  Expectation:  required behaviour, and the evidence for it
  Trigger:      feasible preconditions and execution
  Defect:       the violated relationship
  Evidence:     source locations for EVERY participant
  Impact:       observable consequence and affected scope
  Refutation:   strongest counterargument checked, and why it fails
  Remedy:       minimal correction to the violated relationship
  Verification: what was executed, versus established from source

Coverage:
Unexamined areas and essential unknowns:

境界をまたぐ欠陥については両方の参加者を引用し、調査結果をファイルごとにまとめないでください。ファイルごとにまとめると、レビューの目的である関係性が見えなくなります。

カバー範囲とは、作業を実施したことを意味し、項目にチェックを付けたことではありません。 選択した各サブケースについて、次のいずれかを報告してください。裏付けのある調査結果を伴って調査済み · 調査済みだが裏付けのある調査結果なし · 該当なし（理由を記載） · 未調査（理由を記載）。あるカテゴリで調査結果が0件でも、**「対象外」**という意味にはなりません。また、チェックマークだけの表は完全性の証拠にはなりません。「調査した範囲に裏付けのある調査結果はありません」と記載し、コードにバグがないとは決して断言しないでください。

注意事項

• よくできている点を明確に述べてください。非難だけに終始するレビューは、簡単に退けられてしまいます。
• 2 つのサブケースには、成熟したコマンドが用意されています。/security-audit-static（信頼境界、シンク、OWASP による確認）と /performance-audit-static（過剰なデータ取得、インデックス、キャッシュ）です。サブケースが作業のすべてを占める場合はコマンドを実行し、より広範なレビューの一側面である場合はリファレンスファイルを使用してください。このスキルでは、どちらの内容も繰り返しません。
• ドキュメントとコードの整合性を確認する場合は、intended-vs-implemented スキルを使用してください。
• 静的レビューで得られるのはコードレビュー上の指摘であり、確認済みのエクスプロイトや、測定済みの性能劣化ではありません。