review

review

職人の目でコードレビューします。明らかな問題は自動修正し、本当のバグを見つけます。

プロジェクトの規約は @AGENTS.md を参照してください。そのパターンをレビュー基準として適用します。

重要なルール

1. 安全で明らかな問題は自動修正する - 当然の修正について許可を求めない
2. バグを探す - まずロジックエラー、エッジケース、競合状態を確認する
3. 確認を待つ - BUG/FIX は、ユーザーが「go」と言うまで実行しない
4. 簡潔にする - 各項目は1行で、選択肢は最後に記載する
5. クリック可能なリンクを使う - path/to/file.ts:123 形式のみ

カテゴリ

カテゴリ	内容	対応
[BUG]	ロジックエラー、セキュリティ、データ損失、競合状態	報告 → 待機
[FIX]	型の不足、エラーハンドリングの不足、テストの不足、不要なコード	報告 → 待機
[AUTO]	未使用のインポート、デッドコード、console.log、誤字	すぐに修正
[CONSIDER]	リファクタリング、スタイルに関する意見、あると便利な改善	指摘のみ

AUTO の基準（すべて満たすこと）

• 動作を壊すリスクがゼロ
• 修正が5秒未満でできる
• 判断が不要

AUTO の例：

• 未使用のインポート／変数
• 行末の空白
• console.log（意図的なものを除く）
• デッドコード／到達不能コード
• コメント／文字列の明らかな誤字

AUTO ではないもの（確認が必要）：

• 「未使用」の関数を削除する（別の場所で使われている可能性がある）
• 型の変更（動作が変わる可能性がある）
• ロジックの変更全般
• AI 生成の不要なコードの削除（意図的な可能性がある）

プロジェクト固有の確認項目

レビュー時は必ず次の点を確認してください。

もっとシンプルにできるか？

• 不要な抽象化はありませんか？コードを減らして実現できますか？
• 一度しか使わない処理のためにヘルパー／ユーティリティを作っていませんか？
• エラーハンドリング、フィーチャーフラグ、後方互換性のためのシムが過剰ではありませんか？
• 不要なラッパーコンポーネントや HOC はありませんか？

コードを削除できるか？

• デッドコード、未使用のエクスポート、コメントアウトされたブロックはありませんか？
• 再エクスポートやバレルファイルはありませんか（バレルファイルは使いません）？
• _vars への改名や // removed コメントのような後方互換性のためのハックはありませんか？
• エクスポートされた型／インターフェースが同じファイル内でしか使われていませんか？

先走った抽象化を避けつつ、DRY にできているか？

• 関数全体や大きなブロックの明らかなコピー＆ペーストはありませんか？ → リファクタリングする
• ただし、似た行が2～3行ある程度なら問題ありません。早まって抽象化しないでください
• 誤った抽象化は、重複よりも悪いものです

適切な構成になっているか？

• ページ固有のコンポーネントは、そのページの隣に配置する（ネストした components/ サブフォルダーには置かない。ルートディレクトリーではそうしません）
• 汎用／再利用可能なコンポーネントは apps/web/components/ に配置する
• API ルート：1つのルートにつき1つのリソースとし、複数のデータをまとめたエンドポイントにしない
• 更新処理には POST ルートではなく、サーバーアクションを使う
• バリデーションスキーマは個別の .validation.ts ファイルに配置する
• ヘルパー関数はファイルの先頭ではなく末尾に配置する
• すべてのインポートはファイルの先頭に置く。ファイル途中で動的にインポートしない
• バレルファイルは作らない（フォルダー内のすべてを再エクスポートする index.ts）

プロジェクトのパターンに従っているか？（@AGENTS.md を参照）

• GET ルートは withAuth または withEmailAccount でラップされているか？
• レスポンス型は Awaited<ReturnType<typeof fn>> としてエクスポートされているか？
• クライアント側のデータ取得には SWR を使っているか？
• ローディング／エラー状態には LoadingContent を使っているか？
• フォーム送信には next-safe-action/hooks の useAction を使っているか？
• 重複するインターフェースではなく、z.infer<typeof schema> を使った Zod スキーマになっているか？
• コードから意図が読み取れるか？コメントは「何を」ではなく「なぜ」を説明しているか？
• PII フィールドには logger.trace() を使っているか？
• テストの変更は .claude/skills/testing/SKILL.md に従っているか？
• テストで @/utils/logger をモックしていないか？
• 下書き生成プロンプト、検索、ルーティング、または後処理を変更した場合、分析用の apps/web/utils/ai/reply/draft-attribution.ts の DRAFT_PIPELINE_VERSION を更新したか？

学びの確認

• この変更から学んだことで、AGENTS.md またはこのレビューファイルに記録すべきことはありますか？
• 繰り返し見られるパターンで、文書化すべきものはありますか？

心構え

継承テスト： 前の作者を恨みたくなりませんか？午前2時でも理解できますか？

誇りテスト： 自分の名前をこのコードに添えられますか？

ワークフロー

ステップ 0：範囲を特定してファイルをグループ化する

自動検出：会話内の変更 → ステージ済み → 現在の差分

git diff --cached --name-only  # or HEAD

領域／依存関係ごとにファイルをグループ化：

Batch 1: apps/web/app/api/agent/* (3 files)
Batch 2: apps/web/app/(app)/[emailAccountId]/agent/* (related components)
Batch 3: apps/web/utils/actions/* (2 files)

出力： Found X files in Y batches

──────────

ステップ 1：レビュー計画を作成する（TODO）

ファイルの内容を読む前に、TODO リストを作成します。

- [ ] Batch 1: API routes (skills, allowed-actions)
- [ ] Batch 2: agent page components (agent-page, chat, tools)
- [ ] Batch 3: server actions (agent.ts, agent.validation.ts)

バッチの進捗管理には todo_write を使用します。

──────────

ステップ 2：各バッチを処理する

各バッチについて：

1. バッチ内のファイルのみ差分を読み取ります（git diff --cached -- path/to/files）
2. 問題をレビューして分類します
3. [AUTO] 項目をすぐに自動修正します
4. [BUG]／[FIX]／[CONSIDER] 項目を記録します
5. TODO でバッチを完了済みにします

問題の形式：

1. **[BUG]** Race condition in concurrent saves — `src/db.ts:45`
2. **[FIX]** Missing error boundary — `src/App.tsx:12`
3. **[CONSIDER]** Extract to custom hook — `src/Form.tsx:34`

各バッチの処理後：

Batch 1 done: AUTO: 2 fixed | BUG: 1 | FIX: 2

──────────

ステップ 3：概要と選択肢を提示する（すべてのバッチの処理後）

Total: BUG: X | FIX: X | CONSIDER: X (auto-fixed: Y)

Issues:
1. [BUG] ... — `path:line`
2. [FIX] ... — `path:line`

What to fix?
- a) BUG + FIX [recommended]
- b) BUG only
- c) All including CONSIDER
- d) Custom (e.g., "1,3")

I'll assume a) if you don't specify.

Learnings:
- Any patterns worth adding to AGENTS.md?
- Any new review checks to add to this file?

ここで停止し、選択を待ちます。

──────────

ステップ 4：修正を実行する

同じグループ分けに従って、バッチごとに修正を処理します。

1. 選択された修正内容で TODO リストを更新します
2. 各バッチについて：
   • 関連ファイルを読み取ります
   • 修正を適用します
   • 完了済みにします
3. 該当する場合はリンターを実行します

重大度ガイド

BUG（ロジック／セキュリティ）：

• ビジネスロジックの誤り、条件の誤り
• 競合状態、データ損失
• セキュリティ：インジェクション、XSS、シークレットの露出
• 認証ミドルウェアが欠落した API ルート
• Null／undefined が処理されていない
• 破損につながるエッジケース

FIX（品質）：

• 型安全性の不足、安全でない型キャスト
• エラーハンドリングの不足
• テストカバレッジの不足
• AI の粗雑なコード（WHAT コメント、不要な try/catch、as any）
• バリデーションの不足
• 分離すべき API ルートの統合
• サーバーアクションではなく、変更に POST ルートを使用
• バレルファイル／再エクスポートのパターン

CONSIDER（意見）：

• リファクタリングの機会
• 「別の方法で実装したい」
• パフォーマンスの微細な最適化
• スタイルの好み

Git コマンド

# Staged
git diff --cached
git diff --cached --name-only

# All uncommitted
git diff HEAD
git diff HEAD --name-only

エラーハンドリング

エラー	対応
変更なし	「git status を確認するか、ファイルを指定してください」
ファイルが見つからない	利用可能なファイルを一覧表示し、指定を依頼します
バイナリファイル	スキップし、概要でその旨を伝えます
大きなファイル（>10k）	「特定のセクションをレビューしますか？」