code-review

フレッシュアイズレビュー

体系的なプリコミット品質ゲート → チェックリストベースのレビュー → 検出事項 → サマリー。

<when_to_use>

• プリコミットのコードレビューと品質ゲート
• マージ前のプルリクエストレビュー
• デプロイ前の体系的なコード監査
• 重要な変更に対する品質検証
• セカンドオピニオンのレビュー依頼

次には使用しません: 簡単な健全性チェック、些細なタイポ修正、フォーマットのみの変更

</when_to_use>

<announcement_protocol>

レビューの開始

レビュースコープ: { レビュー対象のファイル／領域 } フォーカス領域: { 具体的な懸念事項または一般的な品質ゲート } チェックリスト: { 全体または対象を絞ったカテゴリ }

レビュー中

発見した検出事項をその都度出力します:

• {SEVERITY} {FILE_PATH}:{LINE} — { 問題の説明 }
• 影響: { リリースされた場合の結果 }
• 修正: { 具体的な改善策 }

レビューの完了

レビュー完了

検出事項のサマリー:

• ◆◆ 重大: {COUNT} — ブロッキング問題
• ◆ 中程度: {COUNT} — マージ前に修正すべき
• ◇ 軽微: {COUNT} — 対応を検討

推奨: { リリース可 / ブロッカーの修正が必要 / 再作業が必要 }

{ 検出事項があれば以下に詳細を記載 }

</announcement_protocol>

型安全性

• ✓ 正当化コメントのない any 型がない
• ✓ Null／undefined を明示的に処理している（オプショナルチェーン、nullish 合体）
• ✓ ユニオン型に型ガードを使用している
• ✓ 状態機械に判別可能なユニオンを使用している
• ✓ 必要に応じてジェネリック制約を指定している
• ✓ パブリック関数の戻り値型を明示している
• ✓ 安全性コメントのない型アサーションがない

エラーハンドリング

• ✓ すべてのエラーパスを処理している（サイレント障害なし）
• ✓ コンテキストを含む意味のあるエラーメッセージ
• ✓ エラーを適切に伝播またはログ出力している
• ✓ 想定される失敗に Result 型を使用している
• ✓ try/catch ブロックに具体的なエラーハンドリングがある
• ✓ Promise の拒否を処理している
• ✓ finally ブロックでリソースをクリーンアップしている

セキュリティ

• ✓ 使用前にユーザー入力を検証している
• ✓ ハードコードされたシークレットや認証情報がない
• ✓ 認証／認可チェックが存在する
• ✓ パラメータ化クエリを使用している（SQL インジェクションなし）
• ✓ XSS 対策（サニタイズされた出力）
• ✓ 該当する場合は CSRF 対策
• ✓ 機密データを暗号化／ハッシュ化している
• ✓ 公開エンドポイントにレート制限がある

テスト

• ✓ 新機能に対するテストが存在する
• ✓ エッジケースをカバーしている
• ✓ エラーシナリオをテストしている
• ✓ 実際のアサーションがある（実行だけでなく）
• ✓ テスト汚染がない（適切なセットアップ／ティアダウン）
• ✓ モックを適切に使用している（過剰使用していない）
• ✓ テスト名が振る舞いを説明している
• ✓ クリティカルパスの統合テストがある

コード品質

• ✓ 名前が意図を表している（関数、変数、型）
• ✓ 関数が 50 行未満（単一責任）
• ✓ ファイルが 500 行未満（分割を検討）
• ✓ マジックナンバーがない（名前付き定数を使用）
• ✓ DRY 違反を排除している
• ✓ ネストした条件文が 3 段未満
• ✓ 循環的複雑度が妥当
• ✓ デッドコードを削除している

ドキュメント

• ✓ パブリック API に JSDoc/TSDoc がある
• ✓ 複雑なアルゴリズムを説明している
• ✓ 自明でない決定を文書化している
• ✓ 破壊的変更を記載している
• ✓ TODO にコンテキストと担当者がある
• ✓ 振る舞いが変わる場合は README を更新している
• ✓ 複雑な使用方法に例を提供している

パフォーマンス

• ✓ 明らかな N+1 クエリがない
• ✓ 適切なデータ構造を使用している
• ✓ 不要な割り当てを避けている
• ✓ 重い処理を非同期／バッチ化している
• ✓ 有益な箇所でキャッシュしている
• ✓ データベースインデックスを検討している

Rust 固有（該当する場合）

• ✓ rustfmt と clippy が通っている
• ✓ panic よりも Result を優先している
• ✓ テスト／起動時以外で unwrap/expect を使用していない
• ✓ 所有権／借用が慣用的である
• ✓ Send/Sync 境界を守っている
• ✓ unsafe コードにコメントで正当化している
• ✓ 適切なエラー型（thiserror/anyhow）

1. アナウンス（activeForm: レビューをアナウンス中）

開始プロトコルを出力します:

• レビューのスコープ
• フォーカス領域
• チェックリストのアプローチ（全体または対象を絞った）

2. チェックリスト（activeForm: チェックリストレビューを実行中）

各カテゴリを体系的に検証します:

• 型安全性 → エラーハンドリング → セキュリティ → テスト → 品質 → ドキュメント → パフォーマンス
• 違反を重大度とともに即座に指摘する
• 問題のない領域は簡潔に記録する

3. 詳細調査 (activeForm: 調査結果の検証)

各調査結果について:

• 実際に問題であることを確認する (誤検出ではない)
• 重大度と影響を評価する
• 具体的な修正方法を決定する
• コードベース全体にパターンが存在するか確認する

4. 要約 (activeForm: レビューサマリーをコンパイル中)

完了プロトコルを出力します：

• 重大度別の指摘件数
• 推奨事項（リリース可 / ブロッカーの修正 / 再作業）
• 詳細な指摘リスト
• 任意：気づいたパターン、今後の提案

レビュー段階を追跡するために maintain-tasks スキルをロードします。

<finding_format>

{SEVERITY} {FILE_PATH}:{LINE_RANGE}

Issue: { 問題の明確な説明 }

Impact: { リリースした場合の結果 — セキュリティリスク、ランタイムエラー、メンテナンス負担など }

Fix: { 修正するための具体的な手順 }

Pattern: { 問題が複数回出現する場合は、範囲を記載 }

---

例：

◆◆ src/auth/login.ts:45-52

Issue: パスワードが定数時間比較ではなく == を使用して比較されている

Impact: タイミング攻撃の脆弱性 — 攻撃者は応答タイミングを通じてパスワードの長さと内容を推測できる

Fix: crypto.timingSafeEqual() または bcrypt の組み込み比較を使用する

Pattern: 単一の出現

---

</finding_format>

<severity_guidance>

◆◆ 重大（ブロッキング）：

• セキュリティ脆弱性
• データ損失のリスク
• 一般的なパスでのランタイムクラッシュ
• 移行措置のない破壊的変更
• テストの失敗または重要なテストの欠如

◆ 中程度（修正すべき）：

• 型安全性の違反
• 未処理のエラーケース
• 不十分なエラーメッセージ
• エッジケースに対するテストの欠如
• 重大なコード品質の問題
• パブリック API のドキュメントの欠如

◇ 軽微（対応を検討）：

• コードスタイルの不整合
• 過度に複雑だが機能するコード
• 軽微なパフォーマンス最適化
• ドキュメントの改善
• コンテキストのない TODO
• 命名の改善

</severity_guidance>

ループ：スキャン → 検証 → 記録 → 次のカテゴリ

1. レビューを告知 — 範囲、フォーカス、アプローチ
2. チェックリストを実行 — 各カテゴリを体系的に検証
3. 指摘を記録 — 重大度、場所、問題、影響、修正
4. パターンを調査 — 指摘は繰り返されているか？より広範な問題か？
5. ブロッカーを深掘り — 重大度評価を検証し、修正が明確であることを確認
6. サマリーをコンパイル — 重大度別の件数、推奨事項
7. 指摘を提示 — 詳細リストを含む完了プロトコル

各指摘において：

• 実際に問題であることを検証する
• リリースした場合の影響を評価する
• 具体的な修正を決定する
• ファイルをまたぐパターンかどうかを記録する

レビューを完了する前に：

カバレッジを確認：

• ✓ すべてのチェックリストカテゴリを検証したか？
• ✓ ハッピーパスとエラーパスの両方をレビューしたか？
• ✓ テストを実際のアサーションについて調査したか？
• ✓ セキュリティに敏感な領域を特に精査したか？

指摘の品質を確認：

• ✓ 重大度は正確に評価されているか？
• ✓ 影響は明確に説明されているか？
• ✓ 修正は実行可能で具体的か？
• ✓ 誤検知は排除されているか？

推奨事項を確認：

• ✓ 指摘の重大度と整合しているか？
• ✓ ブロッカーは明確にマークされているか？
• ✓ 進むべき道は明確か？

常に：

• 範囲とフォーカスを示してレビュー開始を告知する
• 体系的なチェックリストを実行し、カテゴリをスキップしない
• 指摘は発見次第出力し、最後にまとめてバッチ処理しない
• 重大度を正直に評価する（慎重側に傾ける）
• 不満だけでなく、具体的な修正を提供する
• サマリーと推奨事項で完了する
• チェックリスト項目が該当しない場合は誤検知としてマークする
• パターンを考慮する（単一の問題か、体系的な問題か？）

決して：

• 「簡単な確認」のためにチェックリストレビューをスキップしない
• 検証なしにコードが安全であると仮定しない
• スタイルの好みをブロッカーとしてフラグ立てしない
• 修正ガイダンスのない曖昧な指摘を提供しない
• 重大な指摘を「後で修正」として承認しない
• 告知プロトコルなしでレビューを完了しない
• ユーザー入力パスのセキュリティチェックを欠かさない
• テスト品質を無視しない（実行 ≠ 検証）

コアメソドロジー：

• checklist.md — 拡張チェックリストの詳細、例、重大度ガイダンス

関連スキル：

• codebase-recon — 証拠に基づく調査（レビューの基盤）
• debugging — 構造化されたバグ調査