rigorous-review

/rigorous-review

1 つの厳格な制約のもとで、コードベースを調査し、セキュリティ、パフォーマンス、正確性、リファクタリングの改善点を探します。**外部に公開されるページや API に、観測可能な変更を一切加えてはいけません。**修正後も、正当な呼び出し元に対する公開ルートのレンダリング済み HTML、URL 構造、JSON レスポンスの形式、認証フロー、管理 UI の動作は、すべてバイト単位で完全に一致していなければなりません。

成果物はレポートです。修正はユーザーから依頼された場合にのみ適用し、safe に分類されたものだけを適用します。

基本原則

1. **報告する前に検証する。**すべての指摘について、処理を最後まで追跡します（ルート → ヘルパー → クエリ。セキュリティについては、データの入口から危険なシンクまで追跡します）。また、file:line とコード引用を示します。根拠はコードの構造ではなく、観測可能な影響、つまりユーザー、攻撃者、運用担当者がどのような事象を経験するかを先に述べます。名前や推測に基づく指摘はしません。
2. 2 つの評価軸を設け、その後にゲートを適用します。各指摘には、重大度（P0～P3、影響度）と確信度（0/25/50/75/100、確実性）の両方を付与します。この 2 つは独立しています。実際に悪用可能でも、半分しか立証できない場合は P2 ではなく、P0 × 50 です。何を表面化させるかは、後述のゲートで決まります。このスキルで、ノイズ対シグナル比に最も大きく影響する要素です。
3. **予測可能な誤検知を抑制します。**ノイズの多い監査は無視されます。指摘を出す前に、指摘禁止リストと確定済み判例の表（references/scoring-gating-validation.md）に照らして確認します。「ミドルウェア／フレームワーク／並行するハンドラーですでに処理されている」は、最もよくある見落としです。指摘する前に呼び出し元を確認してください。
4. **safe と gated の区別は、保証の要です。**これにより、「外部に公開されるものに変更を加えない」という保証を守ります。
   • safe — 正当な呼び出し元に対して動作を維持し、スキーマ変更もインフラ変更も伴いません。**認可の修正は safe です。**未認可の呼び出し元を拒否するのが目的であり、リグレッションではありません。正当な呼び出し元がすでに満たしているガードについても同様です。
   • gated — 観測可能な変更、スキーマ／マイグレーションの変更、データの意味的変更、新たなインフラのいずれかのリスクがあります。レポートのみとし、黙って適用してはいけません。
5. **本番環境は読み取り専用です。**マイグレーション、drizzle-kit push、本番環境に対するスクリプトの実行、破壊的なコマンドは禁止です。スキーマ／インデックスの推奨事項はレポートにのみ記載します。
6. **修正は最小限にします。**修正に関係のない周辺コード、コメント、書式を「改善」してはいけません。

ゲート（重大度 × 確信度によって何を表面化させるか）

統合後、レポート作成前に適用します。

• 確信度 75 未満はすべて抑制します。ただし、確信度 50 以上の P0 は例外として残します。重大だが不確かな指摘が黙って破棄されることがないよう、バリデーターの確認工程に回します。
• **レーンごとに基準を変えます。**レーンによって見落としのコストが異なるため、基準も異なります。
  • **セキュリティ：基準を下げます。**確信度 50 のセキュリティ指摘は、通常、ゲートを通過するよう P0 として記録します。実際の脆弱性を見逃すコストは、誤報よりも高いためです。
  • **パフォーマンス：基準を上げます。**推測に基づく指摘や時期尚早な最適化の指摘は、確信度 50 の基準で回すのではなく、抑制します。誤ったパフォーマンス指摘は、エンジニアリングの時間を浪費します。
  • 正確性とリファクタリングには標準の基準を適用します。
• 工数ダイヤル（--effort、既定値は medium）：low／medium では確信度の高い指摘のみ（75 以上）を報告します。指摘の数を絞り、確実性を高めます。high／max では再現率を高めます（トリアージのために、ゲートで抑制される確信度 50 の指摘も表面化させ、より多くの指摘をバリデーターの確認工程に回します）。依頼に応じて調査の深さを調整してください。

アンカーの完全な定義、重複排除フィンガープリント、合意による昇格、バリデーター確認工程のプロトコル、判例の表については、references/scoring-gating-validation.md を参照してください。

手順

フェーズ 0：全体を把握する（並列レビューの前に、低コストで）

1. 技術スタックと認可モデルを特定します。特に、middleware.ts／中央認証レイヤーがあるのか、それとも各ルート／アクションが個別にガードしているのかを確認してください。回答を最初に明示します。これは、セキュリティレビューで各エンドポイントをどう読み解くかに影響します。 （アプリのルートで grep -r "middleware" を実行し、フレームワークの認証エントリポイントを確認します。）
2. 対象範囲を一覧化します。公開ルート、管理者ルート、API ルート、サーバーアクション／RPC、DB にアクセスするスクリプトが含まれます。読み取り専用の Explore エージェントが適しています。対応するガードがない対象要素については、必ず指摘を作成します（attack-surface-inventory ルール）。
3. CLAUDE.md／AGENTS.md に記載されたプロジェクトの不変条件（テナントスコープ、PII ルール、金額／単位の規約）を書き留めます。これらを「違反した場合は P0」として、レビュー担当者にそのまま渡します。
4. 労力レベル（既定値は medium）を選び、モデルのティアを割り当てます。セキュリティと正確性のレビュアーにはセッションモデルを割り当てます（重大なリスクがあり、見落としのコストが高いため）。パフォーマンスとリファクタリングのレビュアーには中位モデルを使用できます（品質を落とさず、リスクの低いレーンで約 3～4 倍のコスト削減になります）。割り当てを明示します。

フェーズ 1：4 人のレビュアーを並列に起動する

1 つのメッセージで 4 つの Agent を起動します（run_in_background: true）。それぞれに、読み取り専用であること、各指摘をコードパス全体に照らして検証すること、両方の軸でスコアを付けること、safe／gated に分類すること、指摘を出す前に担当レーンの「指摘禁止」リストを適用することを伝えます。各エージェントは、指摘（id、重大度、確信度、タイトル、file:line、証拠となる引用＋観測可能な影響、修正案、クラス、レーン）と、各項目に 1 語の判定を付けた短い一覧を返します。

4 つのレーンと詳細なチェックリストは、references/reviewer-lanes.md を参照してください。

• セキュリティ（セッションモデル、基準は低め）— すべてのミューテーションおよび管理者向け読み取りに対する認可（セッション確認と対象リソースに対するテナント／所有権確認の両方）；サーバーアクション／RPC を実際のエンドポイントとして監査；git で追跡されているファイルの必須シークレットスキャン；信頼できない入力からシンクまでの汚染追跡；SSRF、安全でないデシリアライズ、CSRF、危険なシンク（dangerouslySetInnerHTML、exec の補間、eval／new Function）；各指摘を OWASP Top 10:2025 ＋ CWE に対応付けます。
• パフォーマンス（中位モデル、基準は高め）— レンダリングあたりのクエリ数（N+1、逐次 await → Promise.all／JOIN。まずループが実際に存在することを確認します）；インデックスの不足（gated）；過剰なデータ取得；Core Web Vitals（LCP／INP／CLS、画像／フォント、バレルインポート、RSC のシリアライズ）；サーバーレス特有の落とし穴（呼び出し間で機能しないプロセス内キャッシュ、一時ファイルシステムへの書き込み、未認証の cron）。データ量が 10 倍／100 倍／1000 倍になった場合の影響を予測します。
• 正確性（セッションモデル、標準的な基準）— オフバイワンと境界条件／ページネーション（ページサイズの正確な倍数）；null／undefined が "undefined"／NaN に伝播する問題；エラーを覆い隠すフォールバック（失敗したクエリを伝播せず、空の配列を返すなど）；TOCTOU と半端に更新された状態；競合状態。
• リファクタリング（中位モデル、標準的な基準）— 実際のツールを使って証明されたデッドコード（バレルファイル、動的な import()、フレームワークのエクスポートを考慮した knip／ts-prune／ruff F401／ast-grep。単なる grep は不可）；ドリフトしやすい重複（コピー同士にすでに不一致がある場合は P1）；Fowler の 5 系統のコードスメル分類；削除テストと2 アダプター境界ルール（1 箇所だけで使う抽象化は提案しない）；TS の型安全性（noUncheckedIndexedAccess、Result と throw の使い分け、判別可能なユニオン）。削除の提案は gated です。

加えて、コアとなる不変条件を直接検証するAPI コントラクトチェック（追加か変更か、また「以前は count に削除済みの行を含めていたが、今は含めない」のような暗黙的な意味の変更）を実施します。references/behavior-preservation.md を参照してください。

フェーズ 2：統合（重複排除＋昇格＋ゲート適用）

4 つの出力を単純に連結しないでください。次の順に処理します。

1. フィンガープリント normalize(file) + line_bucket(line, ±3) + normalize(title) で重複排除します。2 つのレーンが同じバグを指摘した場合、指摘は 2 件ではなく 1 件です。
2. 合意による昇格 — 2 つ以上のレーンが同じフィンガープリントを指摘した場合、信頼度を 1 段階上げます（50→75、75→100）。独立した裏付けは証拠となります。
3. ゲートを適用（上記）：P0・信頼度 50 の例外を除き、信頼度 75 未満は除外します。レーンごとの非対称性と労力レベルを尊重します。残った弱い P2/P3 はメインの表ではなく、レポートの residual risks / advisory 層に記載します。

フェーズ 3：独立した検証ウェーブ（自己再確認に代わるもの）

統合結果を自分で再検証しないでください。指摘を統合したオーケストレーターは独立したセカンドオピニオンではありません（誤った事実には気づけても、自身のバイアスには気づけません）。代わりに、残ったすべての P0 と P1について、指摘に先入観のない新しい検証担当 Agent を立ち上げます（「誤検出はよくあります。確認しなければというプレッシャーを感じる必要はありません」）。指摘ごとに検証担当を 1 つ割り当てます（1 つの検証担当にまとめて処理させると、同じバイアスが生じます）。検証担当はコードパスを先入観なく読み、独自の証拠とともに確認／格下げ／却下を返します。

• クラッシュ時の劣化保持： 検証担当が応答しない場合（却下した場合は除く）、P2/P3 は除外します（保守的な対応）。一方、P0/P1 は保持し、「劣化 — 未検証」とマークします。一時的な障害によって重大な指摘が黙って削除されてはなりません。
• 労力レベルが low / medium の場合は P0/P1 を検証し、high / max の場合は P2 も検証します。

フェーズ 4：レポートの作成

docs/audits/YYYY-MM-DD-rigorous-review.md に次の内容を書きます。

• 実際に重要な少数の項目を、推奨順序とともにまとめた TL;DR。
• 4 つの指摘事項の表（セキュリティ／パフォーマンス／正確性／リファクタリング）。各行に次を記載します。 id、重大度、信頼度、タイトル、ファイル:行番号、分類、OWASP/CWE（セキュリティのみ）。
• ソフトバケットに分類された P2/P3 の残存項目をまとめた advisory / residual-risks 層。
• 確認した内容と安全であることが分かった内容を記す 「検証済み：問題なし」 セクション。これにより、誰も再監査する必要がなくなります。
• 推奨実施順序：まずシークレット／認証情報のローテーションと未認証の書き込み経路の閉鎖、次に安全に実施できるパフォーマンス改善、その後に承認を得てゲート対象の項目、最後に保守性の改善を行います。
• 本番データには触れておらず、修正も適用していないことを明記します。

フェーズ 5：安全な修正の適用 — 依頼があった場合のみ

ユーザーが apply-safe を指定した場合（または後から依頼した場合）：

• 安全な指摘のみを、信頼度の高いものから適用します。懸念事項ごとに 1 つのコミットを作成し、Conventional Commits 形式のメッセージを使用します。プッシュは決して行いません。
• 各修正後に、動作維持検証を実行します。変更されたコードが担うユーザーストーリーを推測し、境界ごとに（リクエスト → ハンドラー → データ → レスポンス）処理を追跡して、正当な呼び出し元に対する観測可能な結果が変わらないことを確認します。 **境界で破綻が最初に見つかった時点で停止します。**テストの合格は必要条件ですが、十分条件ではありません。検証では フロー を証明します。手順：references/behavior-preservation.md。
• 各修正後にプロジェクトのテストコマンドとビルドを実行します。両方が合格するまで次に進んではなりません。
• gated 項目は決して適用しません。コードを確認した結果、「安全」な修正でも観測可能な変化のリスクがあると分かった場合は、停止し、ゲート対象に再分類します。
• セキュリティ修正は、独立した専用ブランチで取り込むことを推奨します。

盛り込まれた注意点と教訓

• 確信度のない指摘は、指摘として不完全です。 深刻度は「実際に問題があった場合」の重大さを示し、確信度はそれが実際に問題かどうかの確かさを示します。推測にすぎない P0 を検証済みとして報告すると監査への信頼を損ない、不確かな P0 を見逃すと侵害を見逃すことになります。ゲートでは両方が必要です。
• シークレットのスキャンは必須ですが、見落としやすいものです。 テストでは、専用のセキュリティレビューで見逃されたコミット済みの DB 認証情報を、別のレビュアーが偶然見つけました。コミット済みのシークレットは P0 であり、削除だけでなくローテーションが必要です。Git の履歴に残っているためです。
• 自分で再確認しても検証にはなりません。 オーケストレーターが指摘をまとめたため、それを読み返しても自身の偏りを確認するだけです。独立した検証者による確認（Phase 3）が解決策です。エージェントを節約するために、これを省いて自己確認で済ませないでください。
• 問題を指摘する前に呼び出し元を確認してください。 最も多い誤検知は、ミドルウェア、フレームワークのデフォルト設定、または並行するハンドラーによってすでに保護されているコードに対する「ガード／検証の欠落」です。問題として指摘してはいけない項目のリストがあるのは、レビュアーがこうした指摘を絶えず出すためです。
• Phase 0 で認証モデルを明示してください。 そうしないと、中央のミドルウェアがなく、すべてのエンドポイントが個別にガードしていることをレビュアーが再確認するために時間を浪費します。
• 「リファクタリング」でデータを変えないでください。 重複した変換処理の結果がすでに異なる場合、どちらかの仕様を選ぶことはデータに関する判断です。これは gated とし、こっそり整理して済ませてはいけません。API コントラクトの変更も同様です。
• grep によるデッドコードの判定は誤りです。 バレルファイル、動的インポート、フレームワークのルートエクスポートがあると、シンボルが実際には使われているのに未使用に見えることがあります。実際のツールで削除を確認し、削除は gated としてください。
• スコープ： 任意のパス引数を指定すると監査範囲が狭まり、省略するとアプリ全体が対象になります。レビュアーの確認深度をスコープと --effort に合わせてください。

変更履歴

V1 (2026-06-10)

rigorous-review の初回リリースです。実際の本番 Web コードベース 2 件で運用して作成した実用プロトタイプ（internal-hardening-audit）を基に整理しました（Fable/Opus — 良好な結果を得られました。専用のセキュリティレビューで見逃されていた、コミット済みの DB 認証情報を検出しました）。その後、CE レビュアーエージェント、組み込みの code-review／security-review、Vercel スキル、Anthropic の security-review、Matt Pocock の アーキテクチャスキル、OWASP Top 10:2025、Fowler のコードスメル、Core Web Vitals を対象とする 3 エージェントによる調査結果の統合を通じて強化しました。設計の各要素は、次のとおり情報源まで 追跡できます。

• 2 つの評価軸とゲート（CE の ce-code-review における 5 段階の確信度アンカー、Anthropic の ≥0.8 のレポート基準）— 深刻度だけでは「重大だが未検証」を表現できません。精度を最も大きく左右するのは ゲートです（P0-at-50 を除き、75 未満は抑制します）。
• フラグを立てない項目のリストと確定済み先例の表（Anthropic の 18 項目の除外、CE の誤検出 カタログ）— シグナル対ノイズ比を最も大きく改善する単独の追加項目です。
• 自己再確認ではなく、独立した検証ウェーブ（CE：統合担当者は自身の作業を公平に確認できません） — P0／P1 ごとに新しいエージェントを割り当て、クラッシュ時は劣化した状態で維持します。
• レビュー担当者間の重複排除（フィンガープリント）＋合意に基づく昇格（CE の統合パイプライン） — 並列レビュー担当者が、同じ指摘を重複して列挙するのではなく、相互に裏付けます。
• レーンごとのしきい値の非対称性（CE：セキュリティは低め／パフォーマンスは高め）— 一律の基準では、 セキュリティの報告不足と時期尚早な最適化の過剰報告が起きます。
• 4 つのレーン — セキュリティ、パフォーマンス、リファクタリング、正確性 （オフバイワン、null の伝播、エラーの隠蔽、TOCTOU、競合状態）。組み込みの code-review と Anthropic は どちらも正確性を重視します。
• API 契約／動作保持のチェック — 中核となる不変条件を直接保護します （追加的変更か破壊的変更か、意味の変更が通知されずに起きていないか）。
• 対象範囲 — セキュリティ：SSRF（OWASP A01）、安全でないデシリアライズ、CSRF、危険なシンクの ウォッチリスト、OWASP-2025／CWE タグ。パフォーマンス：Core Web Vitals、画像／フォント、バレル インポート、RSC のシリアライズ、サーバーレスのキャッシュ／FS／cron。リファクタリング：実際の デッドコード検出ツール（knip／ts-prune／ast-grep）、Fowler の 5 分類、Pocock の削除テスト＋ 2 アダプターのシームルール、TS の型安全性。
• プロセス層 — 工数ダイヤル（精度↔再現率）、モデルの階層化（セキュリティ＋正確性 = セッションモデル、パフォーマンス＋リファクタリング = 中位モデル）、Phase-5 の動作保持検証。
• 重量級のチェックリストは references/ に置き、SKILL.md を簡潔に保ちます。

実証データに基づく精度／再現率の検証は、次回の実監査まで保留です。

参考資料

• references/reviewer-lanes.md — レーンごとの完全なチェックリスト （セキュリティ／パフォーマンス／正確性／リファクタリング）＋各レーンの「フラグを立てない」項目リスト。
• references/scoring-gating-validation.md — 確信度アンカー、ゲート、レーンごとの非対称性、重複排除フィンガープリント、合意に基づく昇格、 検証ウェーブのプロトコル、劣化時の維持、確定済み先例の表、工数ダイヤル、モデルの階層化。
• references/behavior-preservation.md — API 契約の追加的変更か 破壊的変更かのチェックと、意味の変更が通知されずに起きていないかのチェック、および Phase-5 の 境界ウォーク検証。

テスト

tests/eval.sh は、設計上の契約を構造的に検証します（2 つの評価軸＋ゲート、P0-at-50 の例外、 抑制リスト、独立した検証ウェーブ、重複排除＋昇格、正確性を含む 4 つのレーン、 API 契約チェック、OWASP／CWE＋SSRF／デシリアライズ、Core Web Vitals、実際のデッドコード検出ツール、 工数ダイヤル、モデルの階層化、動作保持検証、本番環境での読み取り専用、安全なものとゲート対象の区別）。 動作検証は次回の実監査で行います（同じコードベースを再監査し、プロトタイプのベースラインと比較して 指摘の精度／再現率を評価します）。