code-review

コードレビュー

ステップ 0 — スコープの選択

何よりも先に、ユーザーに以下の質問を投げかけ、回答を待ってください:

---

何をレビューしますか？

1. 未コミットの変更 — 変更されているが、まだステージまたはコミットされていないファイル (git diff HEAD)
2. ステージされた変更のみ — インデックスに追加されているが、まだコミットされていないファイル (git diff --cached)
3. 現在のブランチとベースブランチの比較 — このブランチが導入したすべてのコミットを、マージベースと比較します (例: git diff main...HEAD)
4. 特定のコミット — 単一のコミットが導入した変更 (コミットハッシュを指定してください)
5. コミット範囲 — 複数のコミットにわたる変更 ( <from>..<to> を指定してください)

選択した番号を入力してください。オプション 4 または 5 の場合は、コミットハッシュまたは範囲も指定してください。

---

ユーザーが回答したら、適切な git コマンドを実行して diff を取得し、以下のレビューに進みます。

選択肢	実行するコマンド
1	git diff HEAD
2	git diff --cached
3	質問する: 「ベースブランチは何ですか？ (例: main, develop)」 — その後 git diff $(git merge-base HEAD <base-branch>)...HEAD を実行
4	git show <commit-hash>
5	git diff <from>..<to>

---

検出結果は重大度レベルとともに報告する必要があります:

• Critical: マージをブロックする。マージ前に必ず修正する必要があります
• Warning: マージ後すぐに修正すべき。ブロッカーではありません
• Suggestion: 任意の改善。マージをブロックしません

---

ステップ 1 — コードベースの調査

何かをレビューする前に、以下のファイルを検査してプロジェクトのスタックを特定してください (存在するものだけを読み取ります):

• package.json → JS/TS フレームワーク、バンドラー、ツールを特定します
• composer.json → PHP フレームワークを特定します (Laravel、Symfony など)
• pyproject.toml / requirements.txt / setup.py → Python
• go.mod → Go
• *.csproj / global.json → .NET / C#
• pom.xml / build.gradle → Java / Spring Boot
• pubspec.yaml → Flutter / Dart
• vite.config.* / webpack.config.* → バンドラーとフロントエンドスタック
• tailwind.config.* → Tailwind CSS
• tsconfig.json → TypeScript
• Dockerfile / docker-compose.yml → Docker
• *.tf → Terraform / IaC
• トップレベルのディレクトリ構造 → アーキテクチャパターンのシグナル (DDD、クリーンアーキテクチャなど)

見つかった内容に基づき、このプロジェクトに一致するスタックファイルとパターンファイルのみを読み込んで適用してください。存在しないテクノロジーについて評価または報告しないでください。

API 検証: ライブラリ API の誤用を指摘する前に、package.json または composer.json で検出されたバージョンについて、mcp__plugin_context7_context7__query-docs を使用して構文とベストプラクティスをライブドキュメントと照合して検証してください。古いトレーニングデータによる誤検知を回避できます。

該当する場合に読み込むスタックファイル:

このスキルファイルのディレクトリからの相対パスを使用して、これらのファイルを読み取ってください。ファイルを読み取れない場合は、上記の汎用ルールで続行してください。

• ./stacks/laravel.md
• ./stacks/vue.md
• ./stacks/nuxt.md
• ./stacks/react.md
• ./stacks/angular.md
• ./stacks/svelte.md
• ./stacks/typescript.md
• ./stacks/tailwind.md
• ./stacks/node.md
• ./stacks/python.md
• ./stacks/go.md
• ./stacks/java-spring.md
• ./stacks/dotnet.md
• ./stacks/react-native.md
• ./stacks/flutter.md
• ./stacks/docker.md
• ./stacks/terraform.md
• ./stacks/kafka.md
• ./stacks/inertia.md
• ./stacks/pest.md

該当する場合に読み込むパターンファイル:

このスキルファイルのディレクトリからの相対パスを使用して、これらのファイルを読み取ってください。ファイルを読み取れない場合は、上記の汎用ルールで続行してください。

• ./patterns/clean-architecture.md
• ./patterns/ddd.md
• ./patterns/event-driven.md
• ./patterns/microservices.md
• ./patterns/cqrs.md

---

ステップ 1.5 — 一貫性チェック

パターン違反を指摘する前に、コードベースで既に何が行われているかを確認してください。Laravel、Vue などのフレームワークは複数の有効なアプローチを提供しています。最良の選択は、たとえ別の方法が理論的に優れていても、プロジェクトで既に確立されているものです。一貫性のなさは、最適とは言えないパターンよりも悪いです。

• 兄弟コントローラー、サービス、コンポーネント、またはテストを確認し、確立された慣習を把握する
• プロジェクトが既に非標準のパターンを一貫して使用している場合は、それに従う — せいぜい 提案 として報告し、ブロッカーとはしない
• これらのチェックリストのルールは、まだパターンが存在しない場合のデフォルトであり、機能している慣習を上書きするものではありません

---

1. セキュリティ

• インジェクション脆弱性: SQL インジェクション、コマンドインジェクション、XSS、LDAP インジェクション
• 認証と認可: 適切なアクセス制御チェック、ハードコードされた認証情報の排除、シークレットの漏洩防止
• 入力の検証とサニタイズ: すべてのユーザー入力がシステム境界で検証されている
• 機密データの露出: ログ、レスポンス、ソースコードにシークレット、トークン、PII が含まれていない
• CSRF 保護: 状態を変更する操作がクロスサイトリクエストフォージェリから保護されている
• 依存関係の脆弱性: 追加・更新された依存関係に既知の CVE がない
• ファイルアップロードの処理: ファイルの種類、サイズ、保存パスが適切に検証されている
• レート制限と悪用防止: 公開されているエンドポイントに適切な制限がある
• 安全なデフォルト設定: 暗号化、HTTPS、セキュア Cookie、適切な CORS 設定
• マスアサインメント保護: オブジェクトがすべてのユーザー入力フィールドを無差別に受け入れていない

---

2. パフォーマンス

• N+1 クエリ: データアクセスパターンが不必要な繰り返しクエリを回避している
• インデックス: 新しいクエリをサポートする適切なデータベースインデックスがある
• キャッシュ: 高コストまたは繰り返される操作に適切なキャッシュを使用している
• ページネーション: 大規模なデータセットがページネーションされ、すべてメモリに読み込まれていない
• 遅延読み込みと積極的読み込み: ユースケースに応じてリレーションが効率的に読み込まれている
• 不必要な計算: 冗長なループ、再計算、再レンダリングがない
• メモリリーク: イベントリスナー、サブスクリプション、参照が宙に浮いたままになっていない
• バンドルサイズ: 小さな機能のために不必要に大きな依存関係が追加されていない
• データベーストランザクション: 長時間実行されるトランザクションを回避し、トランザクションのスコープが最小限になっている
• 非同期操作: I/O バウンドの処理が利用可能な場合は非同期パターンを使用している

---

3. テストとカバレッジ

• 新しいコードにテストがある: すべての新しいパブリックメソッド／エンドポイントに対応するテストがある
• エッジケースがカバーされている: null 値、空のコレクション、境界条件、エラー状態
• ハッピーパスとサッドパス: 成功シナリオと失敗シナリオの両方がテストされている
• テストの分離: テストが互いに依存したり、外部状態に依存したりしていない
• モック: 外部サービスと I/O が適切にモックされ、ユニットテストで実際の API 呼び出しが行われていない
• アサーションが意味を持つ: テストが実装の詳細ではなく、振る舞いをアサートしている
• カバレッジ: テストカバレッジ率が著しく低下していない
• リグレッションテスト: バグを修正する場合、それを検出できたはずのテストが存在する

---

4. アーキテクチャと設計原則

SOLID

• 単一責任: 各クラス／モジュール／関数が 1 つのことを適切に行う
• 開放閉鎖: 既存の振る舞いを変更せずにコードを拡張できる
• リスコフの置換: サブタイプが振る舞いを壊すことなく基底型を置き換えられる
• インターフェース分離: インターフェースが小さく焦点を絞っており、肥大化していない
• 依存性逆転: 高レベルモジュールが具象実装ではなく抽象に依存している

DRY (Don't Repeat Yourself)

• ファイルやメソッドをまたいだロジックの重複がない — 重複が一貫性のなさのリスクをもたらす場合は、共有の振る舞いを抽出する

KISS (Keep It Simple, Stupid)

• ソリューションが機能する最もシンプルなアプローチを使用している。過剰な設計がない
• 時期尚早な抽象化や不必要なデザインパターンがない

全般

• 関心の分離: ビジネスロジック、データアクセス、プレゼンテーションが明確に分離されている
• 命名規則: 変数、関数、クラスには明確で説明的な名前が付けられている
• エラーハンドリング: エラーは意味のあるメッセージを伴って適切に処理される。無言のキャッチは行わない
• コードの可読性: コードは自己文書化されている。複雑なロジックには簡潔な説明コメントがある
• デッドコードの排除: 未使用のインポート、変数、関数、コメントアウトされたブロックは削除されている
• 一貫したパターン: 新しいコードはコードベースで既に確立されているパターンに従っている
• 不変性: 適切な場面では不変のデータ構造を優先する。共有状態の変更は避ける
• 純粋関数: 副作用は分離され明示されている。コアロジックは可能な限り純粋関数として書かれている

コードとファイルサイズ

• メソッド・関数の長さ: 30 行を超えるメソッドは正当化が必要です。50 行を超えるメソッドはリファクタリングが必要です — 多くのことをやりすぎています（Clean Code / Rule of 30）
• クラスの長さ: 200 行を超えるクラスは単一責任違反の観点でレビューする必要があります。500 行を超えるクラスは分割が必要です
• ファイルの長さ: 300 行を超えるソースファイルは複数の責任の兆候です。500 行を超えるファイルは調査して分割する必要があります
• コンポーネントの長さ (Vue/React): 合計 300 行を超える SFC やコンポーネントは分割する必要があります。<template> と <script> ブロックは、可能な限りそれぞれ 150 行未満に保ちます
• git 内のバイナリファイル: 画像、PDF、動画、データベースダンプ、コンパイル済みバイナリはリポジトリにコミットしません。.gitignore でそれらを対象にします。バージョン管理が必要な大きなアセットには Git LFS を使用します
• 実行時のファイル読み込み: ファイルサイズが制限されておらず大きくなる可能性がある場合、ディスクから読み込むファイルはストリーミングを使用します（メモリに全体を読み込まない）

---

5. 潜在的なバグの調査

スタイルや構造を確認するだけでなく、変更されたコードを積極的に追跡して潜在的なバグを探します。以下の各項目について、変更されたコードパスを論理的にたどり、誤った動作、データ破損、または実行時障害を引き起こす可能性のあるものを報告します。

• null / undefined / ゼロの参照外し: 変数が使用される時点でガードなしに null、undefined、0、または空のコレクションになり得るパスを特定します
• オフバイワンエラー: ループの境界、スライスのインデックス、ページネーションのオフセット、および < と <= を使用した比較を確認します
• 反転または不完全な条件: 逆になっているように見えるロジック条件（=== を意図していたのに !== になっている）、else 分岐の欠落、または default のない switch ケース
• 状態に関する暗黙の前提: レコードが存在すること、リストが空でないこと、値が既に設定されていること、または前のステップが成功したことを検証せずに前提としているコード
• 依存先との契約の破壊: メソッドシグネチャ、戻り値の形、イベントペイロード、またはデータベースカラムへの変更が、すべての呼び出し元、コンシューマー、または下流モジュールに反映されていない
• 非同期フローにおける競合状態: 状態を共有し、インターリーブによって一貫性のない結果を生み出す可能性がある複数の非同期操作
• データ変更の副作用: 呼び出し元が予期しない方法で入力引数、共有コレクション、またはグローバル状態を変更する関数
• クエリ・マイグレーションのデータハザード: データを黙って失う可能性がある、既存の行で誤った結果を生み出す可能性がある、または空のテーブルと非空のテーブルで異なる動作をする可能性がある SQL の変更
• 黙って成功するエラーパス: 例外を握りつぶして成功レスポンスを返す catch ブロック、再スローの欠落、ログに記録されるが伝播されないエラー
• 型強制の予期せぬ挙動: 変更されたコードの境界で誤った結果を生み出す可能性がある暗黙の型強制（PHP の緩い比較、JavaScript の ==、文字列から数値への変換）
• 到達不能またはデッドなロジック: 周囲のコンテキストを考慮すると決して真になり得ない条件、無条件の return の後のコード、以前のガードと矛盾する分岐

---

6. アクセシビリティ (diff にフロントエンド/UI の変更が含まれる場合のみ)

• セマンティック HTML: 見出し、ランドマーク、リスト、ボタン、フォーム要素を正しく使用している
• ARIA 属性: aria-label、aria-describedby、role などを正しく、かつネイティブのセマンティクスでは不十分な場合にのみ使用している
• キーボードナビゲーション: すべてのインタラクティブ要素にキーボードで到達し、操作できる
• フォーカス管理: フォーカス順序が論理的である。モーダル/ダイアログではフォーカストラップが適切に使用されている
• 色のコントラスト: テキストと UI 要素が WCAG AA のコントラスト比を満たしている
• 画像とアイコン: 意味のある画像には alt テキストがある。装飾的な画像には alt="" を使用している
• フォームラベル: すべての入力に紐づく <label> または aria-label がある

---

7. 可観測性

• 構造化ログ: ログは構造化フォーマット (JSON または key=value) を使用している。本番コードに console.log / var_dump が残っていない
• ログ内の機密データ: パスワード、トークン、PII、シークレットが、たとえ一部であってもログに出力されていない
• ログレベル: 適切なログレベル (debug、info、warning、error) を使用している。重大なイベントが debug でログ出力されていない
• 相関 ID: リクエストと非同期ジョブが、ログを通じてトレース/相関 ID を保持している
• エラーレポート: 例外が捕捉され、エラー追跡システム (例: Sentry、Bugsnag) に転送されている
• メトリクス: 重要な新しい操作 (キュージョブ、外部呼び出し、キャッシュヒット) が、該当する場合に計測されている

---

8. API 設計 (diff に API エンドポイントまたは API クライアントコードが含まれる場合のみ)

• HTTP メソッド: 正しい動詞を使用している (読み取りには GET、作成には POST、更新には PUT/PATCH、削除には DELETE)
• ステータスコード: 正しい HTTP ステータスコードを返している (作成には 201、コンテンツなしには 204、バリデーションエラーには 422、見つからない場合には 404 など)
• バージョニング: API バージョンが URL またはヘッダーに反映されている。破壊的変更ではバージョンを上げている
• 一貫したエラーレスポンス: エラーペイロードがすべてのエンドポイントで統一された構造に従っている
• ページネーション: 一貫した戦略を使用している (カーソルまたはオフセット)。メタデータがレスポンスに含まれている
• フィルタリングとソート: クエリパラメータが確立された慣習に従っている
• 冪等性: PUT/PATCH/DELETE 操作が冪等である。POST 操作は適切な場合に冪等である (例: 冪等キーを使用)
• URL に機密データを含めない: トークン、パスワード、PII はクエリ文字列やパスではなく、ヘッダーまたはボディで渡す
• GraphQL (プロジェクトが GraphQL を使用している場合のみ): DataLoader で N+1 を防止し、クエリの深さを制限し、本番ではイントロスペクションを無効化し、ミューテーションで入力を検証している

---

9. レジリエンスとフォールトトレランス (diff が外部呼び出し、キュー、または重要なフローに関わる場合のみ)

• タイムアウト: すべての外部 HTTP 呼び出し、データベースクエリ、キュー操作に明示的なタイムアウトがある
• バックオフ付きリトライ: 一時的な失敗は指数バックオフとジッターを伴ってリトライされる。リトライ不可のエラーはリトライされない
• サーキットブレーカー: 外部依存への繰り返しの失敗でサーキットブレーカーが作動し、カスケードを防止する
• グレースフルデグラデーション: 重要でない依存が利用できない場合、システムはグレースフルに機能低下する
• 冪等性: リトライされる可能性のある操作は冪等である (複数回実行しても安全)
• バルクヘッド分離: 遅い、または失敗している依存が共有リソース (スレッドプール、コネクション) を枯渇させない

---

10. ゼロダウンタイムのデータベースマイグレーション (差分にマイグレーションが含まれる場合のみ)

• 追加的な変更を先に行う：新しい列は、アプリケーションコードで使用する前に、NULL 許容にするか、デフォルト値を設定して追加します
• デフォルト値なしで即座に NOT NULL にしない：大きなテーブルにデフォルト値なしの NOT NULL 列を追加すると、テーブル全体がロックされます
• 列／テーブル名の変更時の安全性：移行期間中は新しい列と並行して古い列を保持し、コードのデプロイ後に後続のマイグレーションで名前を変更します
• 列削除時の安全性：コードから参照されなくなり、デプロイが安定してから列を削除します
• インデックスの作成：ロックを回避するため、大きなテーブルのインデックスは並行して作成します（例：CREATE INDEX CONCURRENTLY）
• 可逆性：down メソッドがデータを失うことなく up メソッドを正しく元に戻します

---

11. 並行処理とスレッドセーフティ (差分が共有状態、バックグラウンドジョブ、または並行処理に関係する場合のみ)

• 競合状態：共有状態に対する操作はアトミックであるか、適切に同期されています
• ロックとミューテックス：ロック戦略が適切で、デッドロックの可能性がありません（ロック取得順序が一貫しています）
• アトミック操作：カウンターやフラグはアトミックに更新されます（例：データベースのアトミックなインクリメント、比較交換）
• ジョブの一意性：同時に実行してはならないバックグラウンドジョブは、一意のロックで保護されています
• 共有された可変状態：グローバルまたは静的な可変状態を避け、依存関係は共有せずに注入します

---

12. 国際化（i18n）(プロジェクトが複数の言語またはロケールに対応している場合のみ)

• 文字列のハードコード禁止：ユーザー向けのテキストにはインライン文字列ではなく、すべて翻訳キーを使用します
• 日付と時刻の書式設定：日付、時刻、期間は、手動で文字列を組み立てず、ロケールに対応したユーティリティで書式設定します
• 数値と通貨の書式設定：数値と通貨額は、ユーザーのロケールに従って書式設定します
• 複数形処理：手動の条件分岐ではなく、i18n ライブラリを使って複数形を正しく処理します
• RTL 対応：RTL がサポートされている場合、右から左に記述する言語でもレイアウトが崩れません
• URL またはヘッダーでのロケール指定：ロケールはハードコードせず、ユーザー設定または Accept-Language から取得します

---

13. プライバシーとデータコンプライアンス (差分がユーザーデータ、PII、またはデータ保存に関係する場合のみ)

• データ収集の最小化：機能に厳密に必要なデータのみを収集して保存します
• PII の取り扱い：個人データを特定し、必要に応じて保存時に暗号化し、アクセスを制御します
• データ保持：定められた保持ポリシーに従って、データを削除または匿名化します
• 同意：ユーザーの同意が必要なデータ収集は、明示的なオプトインを条件とします
• 監査証跡：機密データへのアクセスと変更を、監査のために記録します
• サードパーティとのデータ共有：外部サービスと共有するデータを文書化し、必要な範囲に限定します

---

14. 適切に行われた点

問題を列挙する前に、この変更で適切に行われた点を認めてください。優れた設計上の判断、十分なテストカバレッジ、明確な抽象化など、評価し、今後も繰り返すべき点を挙げてください。

---

15. 出力形式

各指摘について、次の形式で報告してください。

### [Category] — [Severity]

**File:** `path/to/file.ext:line`
**Issue:** Brief description of the problem.
**Fix:** Suggested correction or approach.

最後に、評価したすべてのカテゴリを含む要約表を提示してください（この変更に該当しないカテゴリには N/A を使用してください）。

## Summary

| Category              | Critical | Warning | Suggestion | N/A |
|-----------------------|----------|---------|------------|-----|
| Security              | 0        | 0       | 0          |     |
| Performance           | 0        | 0       | 0          |     |
| Tests/Coverage        | 0        | 0       | 0          |     |
| Architecture          | 0        | 0       | 0          |     |
| Code & File Size      | 0        | 0       | 0          |     |
| Potential Bugs        | 0        | 0       | 0          |     |
| Accessibility         | 0        | 0       | 0          |     |
| Observability         | 0        | 0       | 0          |     |
| API Design            | 0        | 0       | 0          |     |
| Resilience            | 0        | 0       | 0          |     |
| DB Migrations         | 0        | 0       | 0          |     |
| Concurrency           | 0        | 0       | 0          |     |
| i18n                  | 0        | 0       | 0          |     |
| Privacy/Compliance    | 0        | 0       | 0          |     |
| Architecture Patterns | 0        | 0       | 0          |     |
| Stack-Specific        | 0        | 0       | 0          |     |
| **Total**             | **0**    | **0**   | **0**      |     |

問題が見つからなかった場合は、**「コードレビューに合格しました — 問題は見つかりませんでした。」**と記載してください。