code-review

コードレビューの方法論

template-ts のコードベースに対して、PR 前に体系的なレビューを実施します。まず重大なリスクを特定し、その後、具体的な修正方法とともに主要な問題と軽微な問題を報告します。

レビュープロセス

1. 対象範囲を特定する — レビュー対象を正確に判断します。
2. 変更を調査する — template-ts のレビューカテゴリに照らして分析します。
3. 不確かなパターンを検証する — 不確実性が残る場合に限り、外部情報を調べます。
4. 指摘事項を分類する — Critical、Major、Minor に分類します。
5. レポートを作成する — 実行可能なレビュー概要をまとめます。
6. 自動チェックを実行する — リポジトリ標準の品質チェックを実行します。

---

ステップ 1：対象範囲を特定する

次の順序で対象範囲を判断します。

1. まずユーザーが明示した対象範囲を使用します。 ユーザーが指定した正確なファイル、PR、コミット、またはブランチ間の比較をレビューします。
2. 対象範囲が指定されていない場合は、直近のコミットから推定します。 対象範囲が示されておらず、リポジトリのコンテキストを利用できる場合は、git log -5 --oneline と git diff HEAD~5..HEAD --stat を使用します。
3. 必要な場合に限り、対象範囲を絞り込む質問を 1 つだけします。 リポジトリの状態を確認できない場合、または対象範囲の候補が複数あり、推定の信頼性が低い場合に限って質問します。

---

ステップ 2：template-ts のレビューカテゴリを適用する

references/review-pattern-catalog.md に記載されているカテゴリチェックリストと例をすべて使用します。

次のカテゴリグループを適用します。

• TRPC のパターン
• TanStack Router と Query のパターン
• コードの重複排除（DRY）
• コード品質とスタイル規約
• セキュリティ
• パフォーマンス
• テスト
• Effect のパターン（Effect コードが対象に含まれる場合）

より深い専門知識が必要な場合は、関連するスキルを読み込みます。

• trpc-patterns
• tanstack-frontend
• effect-ts
• scan-effect-solutions（Effect の詳細な監査用）

---

ステップ 3：不確かなパターンを検証する

ローカルのコードベースから得られる根拠が不十分な場合に限り、検索ツールを使用します。

外部ライブラリや変更の続く API の実際の使用パターンに不確かな点がある場合は、Exa を使用して検証します。

公式ドキュメントの詳細（正確な API 名、バージョン固有の動作、非推奨事項）を確認する場合は、Context7 を使用します。

リポジトリ内に明確で標準的なパターンがすでにある場合は、どちらも使用しません。

---

ステップ 4：テスト要件を変更内容に応じて適用する

動作の変更にはテストを必須とします。

次の変更は、動作の変更として扱います。

• 新規または変更されたビジネスロジック
• API コントラクトの変更
• クエリやローダーの動作の変更
• セキュリティまたは認可ロジックの変更
• ユーザーに見えるコンポーネントの動作の変更

次の変更はリスクが低く、新しいテストは任意とします。

• ドキュメントのみの更新
• コメントのみの更新
• ロジックの変更を伴わない機械的なリファクタリング（例：名前の変更のみ、フォーマットのみ、インポートの並べ替え）

最終レビュー概要では、テストに関する判断の根拠を明示します。

---

ステップ 5：自動チェックを実行する

リポジトリで標準の template-ts 品質チェック用スクリプトが使用されている場合は、bun run check を実行します。

別の規約が使用されている場合は、リポジトリに相当するコマンド一式を実行します（例：lint、型チェック、テストを個別に実行）。

コマンドの実行結果を最終レポートに記載します。

---

重大度の分類

CRITICAL（マージ前に必ず修正）

• セキュリティ上の脆弱性
• SQL インジェクションまたはハードコードされたシークレット
• 保護されたエンドポイントにおける認証の欠如
• 公開 API の破壊的変更

MAJOR（修正を推奨）

• 誤った TRPC v11 のパターン（.queryOptions の代わりに .useQuery を使用）
• N+1 データベースクエリ
• ページの読み込みが遅くなるプリフェッチの欠如
• RouterInputs／RouterOutputs を使わず、型を手動で定義している
• DRY に反するコードの重複

MINOR（修正を検討）

• スタイルの不統一
• ドキュメントの不足
• 重要度の低いリファクタリングの機会

---

レポートのテンプレート

# Code Review Report

**Scope:** [What was reviewed]
**Date:** [Current date]

---

## CRITICAL ISSUES

[List with file:line, description, fix]

---

## MAJOR ISSUES

[List with file:line, description, fix]

---

## MINOR ISSUES

[List with file:line, brief description]

---

## TEST EXPECTATIONS

- Behavior-changing code paths covered: [Yes/No + details]
- Low-risk changes with test exemption: [Yes/No + rationale]

---

## AUTOMATED CHECKS

- Commands run: [List]
- Result: [Pass/Fail]

---

## POSITIVE OBSERVATIONS

- [Good patterns found]

---

## SUMMARY

**Assessment:** [APPROVE / NEEDS_WORK / REJECT]
**Next steps:** [Specific actions]

## Quick Stats

- Files reviewed: [N]
- Issues: Critical: [N], Major: [N], Minor: [N]

---

評価基準

承認

• 重大な問題がない
• TRPC と TanStack の主要なパターンが正しい
• リポジトリの品質ゲートチェックに合格している

要対応

• 重大なパターン違反がある
• 動作変更に必要なテストが不足している
• パフォーマンスの問題が信頼性または UX に影響している

却下

• セキュリティ上の脆弱性がある
• 移行手段なしに破壊的変更が導入されている
• 変更を安全にマージできない根本的な設計上の欠陥がある

---

関連スキル

• trpc-patterns — TRPC のルーターパターン、プロシージャ、エラーハンドリング
• tanstack-frontend — Router、Query、Form のパターン
• effect-ts — Effect のサービス、レイヤー、ManagedRuntime、エラーハンドリング
• scan-effect-solutions — Effect の準拠状況を詳細にスキャン
• production-troubleshooting — パフォーマンスの調査