code-review-web

Web のコードレビュー

本番環境で実際に問題を引き起こすパターンに重点を置いて、Web アプリケーションのコードをレビューし、デバッグします。スタックに依存しない原則は SKILL.md に、スタック固有のパターンは references に記載されています。

---

使用する場合

• マージ前にプルリクエストをレビューする
• 本番環境の問題をデバッグする
• ビルドの失敗を調査する
• 既存コードのセキュリティやパフォーマンスを監査する
• 環境変数や設定の問題を調査する
• 「サイトが壊れている」という報告をトリアージする

使用しない場合

• 新機能の仕様書を作成する（pm-spec-writing を使用）
• 稼働中のサイトをリリース前に QA する（qa-testing を使用）
• Core Web Vitals のパフォーマンスを深く分析する（performance-optimization を使用）
• アクセシビリティへの準拠を詳細にレビューする（accessibility-audit を使用）

---

必要な入力

• レビュー対象のコード、PR、エラーメッセージ、または症状
• デバッグする場合はログへのアクセス（ビルドログ、関数ログ、サーバーログ）
• スタック（フレームワーク、ホスティング、データベース）。概要レベルでも構いません

症状だけ（「サイトが壊れている」など）が提示された場合は、調査に必要な情報を十分に集めることからワークフローを開始します。

---

フレームワーク：5 つのレビュー観点

すべてのコードレビューで、次の 5 つの観点を確認します。状況に応じて深さを調整してください。

1. 正確性

コードは意図したとおりに動作しますか？

• ロジックが仕様書または PR の説明に記載された意図と一致している
• エッジケースが処理されている（空の状態、エラー状態、ネットワーク障害）
• オフバイワンエラー、null／undefined の処理、非同期処理の競合状態がない
• 変更に対するテストがある。またはテストがない理由が明確である
• 変更によって既存の機能が壊れない（リグレッションのリスク）

2. セキュリティ

機密情報が漏えいしたり、攻撃対象領域が生じたりしていませんか？

• シークレットの取り扱い。 クライアント側のコードやバージョン管理にシークレット、API キー、サービスロールの認証情報を含めない
• 認証チェック。 すべての変更用エンドポイントで、処理を行う前に呼び出し元を検証する
• 入力の検証。 クエリ、ファイルパス、HTML で使う前にユーザー入力をサニタイズする
• 外部リクエスト。 外部送信先 URL を検証する。ユーザーが制御する入力による SSRF を防ぐ
• CSRF 対策。 状態を変更するリクエストにはトークンまたは同一オリジンポリシーを必須とする
• レート制限。 公開されている変更用エンドポイントにレート制限を設ける
• HTTPS のみ。 本番環境のコードパスで HTTP を使用しない
• Cookie。 セッション Cookie に Secure、HttpOnly、SameSite 属性を設定する
• 環境変数。 サーバー専用のシークレットに、クライアントバンドルへ公開される接頭辞を付けない

3. パフォーマンス

このコードは規模が大きくなっても高速に動作しますか？

• データベースクエリ。 N+1 パターンを避ける。クエリをループ内で実行するより、JOIN または一括取得を優先する
• ページネーション。 大量の結果はページネーションし、全件を一度に読み込まない
• キャッシュ。 データの鮮度要件に適したキャッシュ戦略を採用する
• バンドルサイズ。 クライアント側の依存関係が妥当である。ツリーシェイキングが機能している
• 画像の取り扱い。 最新のフォーマットを使用し、遅延読み込みを行い、寸法を明示する
• バックグラウンド処理。 時間のかかる処理をリクエストの処理経路から移す
• コールドスタートへの配慮。 頻繁に実行されるコールドパスを最適化する

4. 信頼性

このコードで障害が発生した場合、どうなりますか？

• エラー処理。 エラーを握りつぶさず、捕捉して処理する。コンテキストを含めてエラーをログに記録する
• リトライ。 一時的な障害に備え、ネットワーク呼び出しにリトライロジックを設ける
• タイムアウト。 外部呼び出しに明示的なタイムアウトを設定する（無期限に待機しない）
• グレースフルデグラデーション。 重要でない処理の失敗でページ全体をクラッシュさせない
• 冪等性。 リトライされる可能性がある変更処理は、安全にリトライできるようにする
• ログ記録。 再現しなくても原因を特定できるだけのコンテキストをログに含める

5. 保守性

次の担当者（または半年後の自分）が、これを理解できるでしょうか？

• 命名。 関数や変数には、実装方法ではなく役割に基づいた名前を付けます。
• コメント。 何をするかではなく、なぜそうするのかを説明します。何をするかはコードに書かれています。
• 複雑さ。 関数は一つのことだけを行います。関数が200行あるなら、やることが多すぎます。
• 重複。 同じロジックが複数の場所にある場合は、切り出します。
• 依存関係。 新しい依存関係を追加する場合は、その必要性を説明します。依存関係は一つひとつが保守の負担になります。
• マジック値。 コードに 60000 のようなリテラル値を直接書きません。名前付き定数を使います。

---

よくあるバグのパターン（技術スタック非依存）

さまざまな技術スタックで繰り返し見られるパターンです。レビューのたびに確認する価値があります。

ビルドとデプロイ

• ビルド時のデータ取得がタイムアウトする。 静的生成中にデータベースへクエリを実行するルートは、大規模になると失敗することがあります。データを最新に保つ必要がある場合は、実行時にレンダリングするよう設定します。
• 環境変数が反映されない。 ローカルでは動作するのに本番環境で失敗する変数は、本番環境に追加されていないことが原因である場合がほとんどです。
• プレビュー環境と本番環境で環境変数が一致しない。 プレビュー環境では動作するのに本番ドメインで失敗するデプロイは、技術スタック固有の URL がハードコードされていることがよくあります。

URL とドメインの問題

• Canonical がステージングまたはプレビューの URL を指している。 クライアントに公開される環境変数が誤ったドメインを取得することが原因です。Canonical ドメインにはサーバー専用の環境変数を使います。
• API URL がメインドメインを指し、ループバックする。 DNS の切り替え後、メインドメインが別のアプリケーションを提供するようになっている場合があります。API は専用のサブドメインに配置します。
• HTTPS へのアップグレードに関する問題。 混在コンテンツ（HTTPS ページに読み込まれる HTTP リソース）は、ブラウザーのセキュリティモデルを損ないます。

キャッシュの無効化

• デプロイ後もコンテンツが古いまま。 キャッシュが無効化されていないか、無効化に手動操作が必要なのに実行されていません。
• CDN が同じファイル名の古いアセットを配信する。 アセットを置き換えるときは、必ず新しいファイル名を使うか、クエリ文字列でキャッシュを無効化します。
• キャッシュヘッダーの設定が強すぎる。 頻繁に変わるリソースに長い max-age を設定すると、ユーザーに数時間または数日間、古いコンテンツが表示されることがあります。

データベースとデータ

• N+1 クエリ。 ループ内でクエリを実行しています。一括取得または結合に置き換えます。
• テーブルスキャンの上限がない。 大規模なテーブルを対象にするクエリで LIMIT を忘れています。
• コネクションプールの枯渇。 同時接続が多すぎることが原因で、多くの場合、並列ルートでのビルド時データ取得が関係しています。
• バックフィルを伴わないスキーマ移行。 既存の行に値を設定せずに NOT NULL カラムを追加しています。

画像の処理

• アップロード後に画像が読み込まれない。 CDN に以前のファイル名がキャッシュされています。置き換えには新しいファイル名を使います。
• 画像によるレイアウトシフト。 width 属性と height 属性がありません。両方を必ず指定します。
• 画像が大きく、LCP が遅い。 ヒーロー画像がサイズまたは形式の面で最適化されていません。

外部連携

• ボット対策がサーバー間の呼び出しをブロックする。 CDN またはファイアウォールが正当な自動トラフィックにチャレンジを要求しています。サーバー IP を許可リストに追加するか、API エンドポイントではチャレンジを無効にします。
• 本番環境で API のレート制限に達する。 トラフィックがごく少ないローカルでは動作していました。バックオフとレート制限を考慮した処理を追加します。

セキュリティ

• 保護されていない再検証エンドポイントや管理者用エンドポイント。 必ずシークレットトークンを要求します。
• URL に含まれる個人情報（PII）。 サーバーログ、ブラウザー履歴、リファラーヘッダーに表示されます。
• クライアントバンドルで公開されるシークレット。 ブラウザーに送られるものはすべて公開情報です。

---

ワークフロー

1. コンテキストを収集します。 どのような技術スタックですか？何が壊れているか、またはレビュー中ですか？ログはありますか？
2. レビューの深さを決めます。 小規模な PR なら簡易チェック、大規模な変更なら全面的なレビュー、本番環境のインシデントなら詳細な調査を行います。
3. 5 つの観点から確認します。 問題を重大度（ブロッカー、重要、軽微）別に記録します。
4. 技術スタック固有のパターンを確認します。 該当する技術スタックのガイドを参照します。
5. インシデントの場合： 仮説に基づく最小限の修正を特定します。可能であれば、ローカルで再現します。
6. レビューを作成します。 正式なレビューには、references/review-template.md のテンプレートを使用します。

---

よくある失敗パターン

• 500 行の PR に「問題なさそうです」とだけコメントする。 大規模な PR のレビューが 5 分で終わるなら、レビューは行われていません。
• コードを実行せずにレビューする。 実行時にしか表面化しないバグもあります。ブランチをチェックアウトして実行してください。
• スタイルにこだわりすぎる。 書式について議論する一方で、ロジックのバグを見逃します。
• 「内部向け」機能のセキュリティレビューを省略する。 内部向けの機能が外部向けになるのは、予想よりも早いものです。
• 警告を飾りだと考える。 ビルド時の警告は、依存関係の更新後に本番環境のエラーになることがよくあります。
• エラーメッセージ全体を読まずにデバッグする。 スタックトレースの最初の行が実際の原因であるとは限りません。最後まで読んでください。

---

デバッグのワークフロー

本番環境の問題が報告された場合：

1. エラーメッセージ全体を読みます。 スタックトレースも含めて確認します。
2. ホスティング環境のビルドログと関数ログを確認します。 正確な失敗箇所は通常、ここに記録されています。
3. 最後に正常に動作したバージョンを特定します。 git log --oneline を実行して、最近のコミットを確認します。
4. ローカルで再現します。 環境の問題ではなく、コードの問題であることを確認します。
5. 環境変数を確認します。 特にデプロイ後や DNS の変更後は念入りに確認します。
6. キャッシュの状態を確認します。 コードのバグだと判断する前に、キャッシュを強制的に無効化します。
7. 最小限の修正を行います。 インシデント対応中の大規模なリファクタリングは、さらなるインシデントを招きます。
8. 本番環境で検証します。 デプロイが成功しただけでなく、実際に修正が機能したことを確認します。
9. 記録します。 根本原因は何でしたか？何をすれば防げましたか？得られた知見を記録します。

---

出力形式

PR レビューの場合：PR 上のインラインコメントと、必要に応じた要約を記載します。

正式なコードレビューの場合：次の内容を含む code-review-[date].md という Markdown ドキュメントを作成します。

1. 対象範囲（レビューした内容）
2. 要約（全体的な評価）
3. 重大な問題（ブロッカー）
4. 重要な問題
5. 軽微な問題
6. フォローアップの提案

インシデントの場合：事後検証ドキュメントを作成します。形式については after-action-report を参照してください。

---

参照ファイル

• references/review-template.md - 正式なコードレビュー用の Markdown テンプレートです。
• references/nextjs-patterns.md - Next.js（App Router、ISR、Server Components、よくあるバグ）に固有のパターンです。
• references/wordpress-headless-patterns.md - ヘッドレス WordPress 統合に固有のパターンです。