review-verification-protocol

レビュー検証プロトコル

コードレビューの指摘を報告する前に、このプロトコルに必ず従ってください。これらの手順を省略すると、誤検出が発生し、開発者の時間を浪費させ、レビューへの信頼を損ないます。

捏造の防止（ゲート 0 — すべてのレビュー／検証スキルに適用）

あらゆる判定（確認、却下、重大度の引き上げ、修正、裁定）を下す前に、このターンで読んだソースから引用して、判定対象となる正確な成果物を示す必要があります。

• コードの指摘の場合：今あらためて読み取った（セッションの以前の内容を思い出したものではない）ファイル名:行番号と、引用するコード。
• 差分のレビューの場合：レビュー対象の実際の差分ハンク。
• 構造化レポート（例：verify-llm-artifacts が findings[] を裁定する場合）の場合：解析したソースファイルから出力した、指摘の ID、ファイル、行番号、説明。記憶に頼ってはいけません。

成果物だけが唯一の信頼できる情報源です。ブランチ名、作業ディレクトリ、周辺ファイル、記憶から、レビュー対象を決して推測してはいけません。頭の中の認識と、今あらためて読み取ったソースが異なる場合は、ソースを優先してください。 対象を同じターン内に示さずに下した判定は無効です。先に対象を示すか、判定を出さないでください。

このゲートは、コンテキストによる誘導を受けた LLM が、ファイルに存在しない内容を自信たっぷりに裁定してしまう事態を防ぐためにあります。以下の各指摘に対するハードゲートよりも先に実施します。このプロトコルを使用するスキルは、具体的な手順としてこれを実装します。verify-llm-artifacts（読み込み＋対象提示＋ID ロックゲート）、review-llm-artifacts（JSON を書く前に指摘を提示）、llm-artifacts-detection（開いたバッファーから FILE:LINE を特定）。

ハードゲート（順番どおりに実施）

レビューに指摘を含める前に、指摘ごとに 1 回適用してください。ゲートを通過できない場合は、指摘を省略するか、情報提供レベルに引き下げる（重大度の調整に従う）か、質問の形に言い換えてください。根拠の弱い非難を報告してはいけません。

手順	実施内容	合格条件（客観的な基準）
1. 特定	差分ハンクだけでなく、その全体を囲むシンボルまたはモジュールを読みます。	判定対象のファイルパスと行の範囲（またはシンボル名＋ファイル）を示せます。
2. 根拠	この指摘の種類に応じて、問題の種類ごとの検証にあるチェックを実行します。	必要な各チェックに、貼り付けたツールの出力、ファイル名:行番号の引用、またはリポジトリ検索後の明確な 「該当なし」／「N 件一致」といった成果物があります。「確認した」という主張だけでは不十分です。
3. 重大度	重大度の調整を使用して重大度を割り当てます。	ラベルが表の基準と一致しています。対象範囲に存在しなかった新規コードの追加要求は、情報提供レベルに限ります。
4. 形式	レポート用に指摘を作成します。	[FILE:LINE] ISSUE_TITLE の形式に従っています。情報提供項目は、対応が必要な指摘の件数に含めません。

スタイルや好みに関する指摘は、ゲート 2 を通過しないか、指摘しないに該当します。重大度を割り当ててはいけません。

レポート前の検証チェックリスト

問題を指摘する前に、必ず次の項目を検証してください（これらはゲート 2 で根拠を提示する必要がある項目です）。

• 実際のコードを読みました — 差分のコンテキストだけでなく、関数／クラス全体を確認しました
• 使用箇所を検索しました — 「未使用」と主張する前に、すべての参照を検索しました
• 周辺のコードを確認しました — 問題が別の場所で処理されている可能性（ガード、前段のチェック）を確認しました
• 現在のドキュメントに照らして構文を検証しました — フレームワークの構文は変化します（Tailwind v4、TS 5.x、React 19）
• 「誤り」と「スタイルの違い」を区別しました — どちらの方法も妥当な場合があります
• 意図的な設計かどうかを検討しました — コメント、プロジェクトの規約（例：AGENTS.md または CLAUDE.md）、アーキテクチャ上の背景を確認しました

問題の種類ごとの検証

「未使用の変数／関数」

指摘する前に、必ず以下を行ってください。

1. コードベース内の参照をすべて検索します（grep/find）
2. エクスポートされているか、外部の利用者が使用しているかを確認します
3. リフレクション、デコレーター、動的ディスパッチを介して使用されていないか確認します
4. フレームワークに渡されるコールバックではないことを確認します

よくある誤検知：

• React の state セッター（値が未使用に見えても、再レンダリングをトリガーすることがあります）
• テンプレート／JSX で使われる変数
• 利用側のパッケージで使用されるエクスポート

「バリデーション／エラーハンドリングの不足」

指摘する前に、必ず以下を行ってください。

1. より上位のレベル（呼び出し元、ミドルウェア、ルートハンドラー）にバリデーションがあるか確認します
2. フレームワークによるバリデーション（Pydantic、Zod、TypeScript）があるか確認します
3. 「不足している」とされるチェックが、別の形式で存在しないか確認します

よくある誤検知：

• フレームワークがすでにバリデーションを行っている（FastAPI + Pydantic、React Hook Form）
• 親コンポーネントが props を渡す前にバリデーションを行っている
• 上位レベルのエラーバウンダリーがエラーを捕捉している

「型アサーション／安全でないキャスト」

指摘する前に、必ず以下を行ってください。

1. 実際にアサーションであり、型注釈ではないことを確認します
2. 該当箇所より前の実行時チェックによって型が絞り込まれていないか確認します
3. フレームワークが型を保証しているか確認します（ローダーデータ、フォームデータ）

誤って指摘されることが多い有効なパターン：

// Type annotation, NOT assertion
const data: UserData = await loader()

// Type narrowing makes this safe
if (isUser(data)) {
  data.name  // TypeScript knows this is User
}

「メモリリーク／競合状態の可能性」

指摘する前に、必ず以下を行ってください。

1. クリーンアップ関数が実際に存在しないことを確認します（別の場所にあるだけではないこと）
2. await の後に AbortController のシグナルがチェックされているか確認します
3. 非同期処理の実行中にコンポーネントが実際にアンマウントされる可能性があることを確認します

よくある誤検知：

• useEffect の return にクリーンアップがある
• シグナルがチェックされている（コードレビュー担当者が見落としている）
• アンマウントが可能になる前に処理が完了する

「パフォーマンスの問題」

指摘する前に、必ず以下を行ってください。

1. 影響が出るほど頻繁にコードが実行されるか確認します（レンダリング時かクリックハンドラー内か）
2. 最適化によって測定可能な効果が得られるか確認します
3. フレームワークがすでに最適化していないか確認します（React compiler、メモ化）

以下は指摘しないでください：

• クリックハンドラー内で作成される関数（クリックごとに一度実行されます）
• 小さな配列（100 項目未満）に対する配列メソッド
• イベントハンドラー内でのオブジェクトの作成

重大度の調整

重大（マージをブロック）

以下の場合にのみ使用します：

• セキュリティ上の脆弱性（インジェクション、認証のバイパス、データ漏えい）
• データ破損のバグ
• 正常系でクラッシュを引き起こすバグ
• 公開 API の破壊的変更

高（修正すべき）

以下に使用します：

• 機能に影響するロジックのバグ
• UX の低下を招くエラーハンドリングの不足
• 測定可能な影響があるパフォーマンスの問題
• アクセシビリティの違反

低（修正を検討）

以下に使用します：

• コードの明瞭さを改善するもの
• ドキュメントの不足
• 一貫性のないスタイル（妥当な範囲内）
• 重大ではないテストカバレッジの不足

情報提供（対応不要）

以下に使用します：

• 新しい依存関係やモジュールの追加が必要な改善
• これまでコードベースに存在しなかった新しいコード（新規モジュール、テストスイート、抽象化）の提案
• 将来の検討に向けたアーキテクチャのアイデア
• テスト基盤に関する提案（新しいモックライブラリ、振る舞いの抽出）
• 現在の状況では測定可能な影響がない最適化

これらはレビューをブロックするものではありません。 作成者への参考情報として記載してもかまいませんが、対応が必要な課題の件数には含めてはいけません。判定では情報提供項目を完全に無視してください。

まったく指摘しないこと

• どちらの方法も有効なスタイル上の好み
• 測定可能な利点のない最適化
• 本番環境向けの基準を満たさないテストコード（意図的に簡略化されています）
• ライブラリ／フレームワークの内部コード（shadcn コンポーネント、生成コード）
• 起こりそうにない条件を必要とする仮定上の問題

有効なパターン（指摘しないこと）

TypeScript

パターン	有効な理由
map.get(key) || []	Map.get() は T | undefined を返すため、フォールバックは適切です
型を別途エクスポートしないクラスのエクスポート	クラスは値と型の両方として機能します
リテラル配列に対する as const	読み取り専用のタプル型を作成します
変数宣言での型注釈	型アサーションではありません
as の代わりに satisfies を使用	アサーションなしで型チェックできます

React

パターン	有効な理由
キーとしての配列インデックス（静的なリスト）	次の場合は有効です：項目の並べ替えがなく、リストが静的で、項目の識別が不要
onClick 内のインライン矢印関数	パフォーマンスが重要でないハンドラーでは有効です（クリックごとに一度実行されます）
未使用に見える状態	ref、外部コールバック経由で設定される場合や、再レンダリングをトリガーする場合があります
ref を使う空の依存配列	ref は安定しているため、依存配列に含める必要はありません
チェック後の非 null アサーション	TypeScript の型の絞り込みでは、すべてのパターンを追跡できない場合があります

テスト

パターン	有効な理由
正規表現を使わない toHaveTextContent	ネストされたテキストを適切に処理します
モジュールレベルでのモック	一度だけ定義され、重複しません
インデックスベースのテストデータ	テストでは安定した識別情報は不要です
簡略化されたエラーメッセージ	本番環境向けの仕上げより、テストの明瞭さを優先します

一般

パターン	有効な理由
正規表現の +? 遅延量指定子	マッチしすぎるのを防ぎ、多くのパターンで適切です
文字列の直接連結	単純なケースではテンプレートリテラルより簡潔です
関数内の複数の return	可読性を向上させる場合があります
「なぜ」を説明するコメント	コメントがないより優れています

コンテキスト依存のルール

React のキー

次の条件がすべて当てはまる場合に限り、配列インデックスをキーとして使うことを指摘してください：

• 項目を並べ替えられる（ソート可能なリスト、ドラッグ＆ドロップ）
• 項目を途中に挿入・削除できる
• 利用可能な安定した識別子（id、uuid）が項目にある
• リストが一括で完全に置き換えられるわけではない

useEffect の依存関係

次の場合に限り、依存関係の不足を指摘してください：

• その値がコンポーネントのライフタイム中に実際に変化する
• 古いクロージャによって誤った動作が発生する
• その値が ref ではない（ref は安定しています）
• その値が安定したコールバックではない（依存配列が空の useCallback）

エラー処理

次の場合に限り、try/catch の不足を指摘してください：

• より上位のレベルでエラーバウンダリがエラーを捕捉しない
• フレームワークがエラーを処理しない（loader の errorElement）
• エラーによって処理が失敗するだけでなく、クラッシュが発生する
• この種類のエラーについて、ユーザーに具体的なフィードバックが必要である

レビュー提出前

最終確認： 0. 各指摘が捏造防止（ゲート 0）を通過していること。対象箇所は記憶や推測ではなく、このターンで読み取ったソースから引用されていること。

1. 各指摘がハードゲート（順序）（アンカー、成果物を伴う根拠、重大度、形式）を通過していること。
2. 各指摘を読み返し、「これが実際の問題であることを確認したか？」と自問すること。
3. 各指摘について、問題の存在を証明する具体的な行を示せるか？
4. その分野の専門家も問題だと判断するか、それともスタイル上の好みにすぎないか？
5. 修正によって実質的な価値が生まれるか、それとも無駄な作業か？
6. すべての指摘を次の形式にすること：[FILE:LINE] ISSUE_TITLE
7. 各指摘について、「この修正は既存コードを直すものか、それとも以前は存在しなかったコードを新たに求めるものか？」と確認すること。後者の場合は、情報提供レベルに引き下げてください。
8. 再レビューの場合は、以前の修正のみを確認してください。新しい指摘を追加しないでください。

指摘に確信が持てない場合は、次のいずれかを行ってください：

• その指摘を削除する
• 問題ではなく質問として示す
• さらにコードの文脈を読んで確認する