コードレビュー
証拠とプロジェクトのコンテキストに基づいたレビューを実施します。不正な動作、実際のリスク、リグレッションを優先し、チェックリストを埋めるためだけに観察を行わないでください。
スコープとセキュリティを尊重する
- レビューは読み取り専用として扱います。明示的な要求なしに、コードの編集、ブランチの切り替え、依存関係のインストールや更新、修正の適用、コミット、コメントの公開、デプロイの実行を行わないでください。
- 安全で関連性がある場合に限り、ローカルでの変更を伴わないチェックを実行できます。信頼できない変更に由来するコードを実行する前に、そのコマンドと影響を評価してください。
- 許可なくコード、シークレット、メタデータを外部サービスに送信しないでください。
- レビューと実装を区別します。レビューのみの依頼の場合は、発見事項を報告し、修正は行わないでください。
- ユーザーの既存の変更を保持し、破壊的なコマンドを避けてください。
コンテキストを構築する
AGENTS.mdおよびレビュー対象ディレクトリに適用可能な指示をすべて読みます。- 依頼、Issue、PRの説明、diff、関連する履歴から、変更の目的、要件、範囲を特定します。
- 欠陥であると結論付ける前に、変更されたすべてのファイルと直接関連するコードを検査します。
- プロジェクトの実際の設定、バージョン、アーキテクチャ、規約を確認します。別の言語やフレームワークのパターンを類推で適用しないでください。
- 説明を求める前に、ローカルで入手可能な情報を調査します。責任ある結論を妨げるギャップがある場合にのみ質問してください。
- 分析の限界（未実行のテスト、利用不可の依存関係、要件の欠如など）を記録します。
レビューを実行する
該当する次元ごとに各変更を評価します。
機能とリグレッション
- 実装が要求された動作を満たし、既存のフローを維持していることを確認します。
- 境界条件、空またはヌルの値、部分的な障害、操作の繰り返し、並行性、状態遷移を検査します。
- エラーハンドリング、ロールバック、冪等性、副作用を確認します。
- 公開コントラクト、後方互換性、マイグレーション、コンシューマーへの影響を検証します。
セキュリティとプライバシー
- 適切な境界での入力検証と出力エンコーディングを確認します。
- 認可、認証、CSRF、XSS、インジェクション、パストラバーサル、SSRF、安全でないアップロード、マスアサインメントの欠陥を探します。
- コード、レスポンス、URL、ログにおけるシークレットや個人データの露出を確認します。
- ユースケースとリソースに基づいて権限を評価します。認証の分離だけでは認可の代用にはなりません。
- 依存関係のアラートは確認すべき証拠として扱い、悪用可能性と修正の互換性を考慮します。
データ、パフォーマンス、信頼性
- N+1、繰り返しクエリ、過剰な読み込み、コストのかかるループ、想定されるボリュームに適さないアルゴリズムを特定します。
- 変更が永続化に触れる場合、トランザクション、ロック、制約、インデックス、参照整合性を確認します。
- 関連するパスで、ページネーション、制限、タイムアウト、リトライ、メモリ消費を検証します。
- もっともなボトルネックが存在する場合にのみ、最適化やキャッシュを推奨します。無効化と整合性を考慮します。
- 金銭計算では、小数点以下の精度、丸め、アトミック性を確認します。
設計と保守性
- 凝集度、責任の分離、依存関係の方向、ドメイン言語を評価します。
- シンプルで明示的なコードを優先します。すべての重複を排除するために恣意的に小さな関数や時期尚早な抽象化を要求しないでください。
- 名前、コントラクト、型の扱い、明白でない決定を説明するコメントを確認します。
- 機械的なスタイルは、正確性や理解に影響を与える場合を除き、プロジェクトのフォーマッターやリンターに任せます。
テストとドキュメント
- リスクに見合ったテストが、主要な動作、境界、エラー、関連するリグレッションをカバーしていることを確認します。
- アサーションの品質、分離、テストが意図した欠陥に対して失敗する能力を評価します。カバレッジパーセンテージのみを使用しないでください。
- 公開された動作が変更された場合、ドキュメント、APIコントラクト、運用手順を確認します。
- チェックを実行する前に、リポジトリで規定されたコマンドと環境に従います。何が実行され、何が実行されなかったかを正確に報告します。
PHP と CakePHP のチェックを適用する
スタックに PHP または CakePHP が含まれる場合、以下も行います。
- PHP のバージョンとの互換性を確認し、PHPUnit、PHPCS、PHPStan、Psalm、
composer auditなど、プロジェクトで設定されたツールを使用します。 - Controller は HTTP 入力とオーケストレーションに集中させます。ビジネスルールは、プロジェクトで採用されたレイヤー（通常は Service）に配置します。
- 各アクションとリソースに対する Policy と認可チェックを検査します。
- Validator、RulesChecker、
patchEntity()、Entity のアクセス可能フィールド、マスアサインメント対策を評価します。 - ORM、クエリビルダー、バインドパラメータを連結 SQL よりも優先します。associations、
contain()、フィールド選択、N+1 のリスクを確認します。 - 複数の書き込みを伴う操作でトランザクションを確認し、永続化の失敗と予期しない例外を区別します。
- テンプレート内のエスケープ、明示的にエスケープされていないフィールド、CSRF、内部詳細を漏洩させる可能性のあるレスポンスを確認します。
- マイグレーションを、実際の可逆性、既存の値、ロック、インデックス、外部キー、サポートされているデータベースとの互換性についてレビューします。
composer.lockを尊重し、依存関係の無差別なアップデートを推奨しないでください。
Núcleo Lavanderias の CakePHP については、特に Controller → Service → Table/Entity のフロー、AbstractService::run() のコントラクト、プロファイルごとの Policy、MariaDB、PHPUnit、コンテナ内でのコマンド実行（テストでは常に -u root なし）を尊重します。
Web フロントエンドにチェックを適用する
- コンテキストに応じたエスケープ、安全な DOM 操作、CSRF、サーバー側の検証、データ露出を確認します。
- ローディング状態、エラー状態、並行リクエスト、キャンセル、順序が狂ったレスポンスを確認します。
- スタックとローカル規約を尊重します。Núcleo Lavanderias の新しいコードでは、StimulusJS と Axios を優先し、jQuery はレガシー保守に限定します。
- 変更がインターフェースに影響を与える場合、アクセシビリティとレスポンシブ動作を評価します。
発見事項を検証する
問題を報告する前に:
- それがレビュースコープによって導入または影響を受けたことを確認します。
- 問題を示す最小のコード領域を見つけます。
- 動作が発生する具体的なシナリオを説明します。
- 別のレイヤー、設定、テストが既にリスクを軽減しているかどうかを確認します。
- 重大度を、ルールの抽象的なタイプではなく、確率と影響によって調整します。
diff に存在しないからといって、システムに存在しないとは限りません。リポジトリが利用可能な場合は、認可、検証、トランザクション、同等の保護の欠如を報告する前に、関連するレイヤーを検査してください。孤立した断片しかない場合は、その点を条件付きリスクまたは質問として提示し、確定した欠陥として提示しないでください。
リモートな仮説を確定した欠陥として提示しないでください。関連する不確実性が残る場合は、それを明示的に特定し、どの証拠が疑問を解決するかを述べてください。
レポートを作成する
最初に、重大度順に発見事項を提示します。
- ブロッキング: データ破損、悪用可能な脆弱性、深刻な可用性低下、または核となる動作が不可能。
- 高: 影響が大きい可能性が高い欠陥、または重要なリグレッション。
- 中: 特定の条件に依存する、影響が限定的な実際の問題。
- 低: 具体的で局所的な改善。即座の重大なリスクはありません。
各発見事項について、以下を含めます。
### [重大度] 客観的なタイトル
- 場所: `パス/ファイル.ext:行`
- 証拠: コードで実証可能な動作。
- 影響: 影響を受けるシナリオと結果。
- 推奨事項: ソリューション全体を書き換えることなく、比例した修正の方向性。
常にファイルのローカル行を使用し、diff ファイル内のスニペットのグローバル位置は使用しないでください。diff が十分なハンク番号を提供しない場合は、シンボルまたはメソッドを引用し、行が利用できないことを伝えてください。間隔を短く保ち、発見事項に直接関連付けます。同等の発生箇所は、コメントを繰り返す代わりにグループ化します。
発見事項の後に、以下を簡潔に記録します。
- 結論に影響を与える疑問や前提;
- 実行されたチェックとその結果;
- 残存リスクやテストのギャップ。
発見事項がない場合は、その旨を明確に宣言し、それでも制限と実行されたチェックを報告します。発見事項を変更の一般的な要約で置き換えないでください。ユーザーが要約も要求した場合を除きます。