ai-code-review

ai-code-review

品質基準を徹底する厳密なコードレビューを実施します。前提を問い直し、正しさを検証し、コードがシンプルで、テスト済みかつ保守しやすいことを確認します。

使用する場面

次の場合にこのスキルを使用します。

• プルリクエスト、差分、または一連の変更のレビューを依頼された場合
• 特定のファイルや機能の実装のレビューを依頼された場合
• ユーザーにコードを提示する前にセルフレビューを実施する場合
• 実行フェーズの一環としてコード品質を検証する場合

手順

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

手動レビューを始める前に、自動品質ゲートを通過することを確認してください。

1. リンティング。 プロジェクトで設定されているリンター（例：eslint、phpcs、phpstan、prettier --check、stylelint）を実行します。違反はすべて報告してください。リンターのエラーに対処するか、明示的に受け入れるまでは先に進まないでください。
2. 型チェック。 プロジェクトで静的型付け（TypeScript、PHPStan、mypy など）を使用している場合は、型チェッカーを実行します。型エラーは一切認められません。
3. ユニットテスト。 テストスイートを実行します。既存のテストはすべて合格する必要があります。新しいコードにテストがない場合は、ブロッキング問題として指摘してください（ステップ 4 を参照）。
4. ビルド。 該当する場合は、エラーや警告なしにプロジェクトをコンパイル／ビルドできることを確認します。

自動チェックのいずれかが失敗した場合は、レビューを中断して失敗内容を報告してください。コードのチェックがすべて合格するまでは、手動レビューを続けないでください。

ステップ 2：複雑さをレビューする

要件を満たしつつ、コードが可能な限りシンプルかどうかを評価します。

1. 循環的複雑度。 分岐が 10 個を超える関数またはメソッドを指摘します。処理の切り出しや簡素化を提案してください。
2. 関数の長さ。 40 行を超える関数を指摘します。各関数は 1 つのことだけを行うべきです。
3. ネストの深さ。 3 階層を超えるネストを指摘します。早期リターン、ガード節、または処理の切り出しを提案してください。
4. 引数の数。 引数が 4 個を超える関数を指摘します。オプションオブジェクト、ビルダー、または責務の分割を提案してください。
5. 認知負荷。 初めて読むコードとして確認してください。理解するために同じブロックを読み返す必要がある場合、複雑すぎます。名前の変更や再構成を提案し、説明コメントの追加は最後の手段としてください。
6. 重複。 繰り返されているロジック（3 回以上の出現、または 5 行以上の重複）を特定します。共通の関数、メソッド、またはモジュールへの切り出しを提案してください。

ステップ 3：正しさをレビューする

コードが宣言どおりに動作することを検証します。

1. エッジケース。 コードが処理していない入力や状態を特定します。例：null、空のコレクション、境界値、並行アクセス、エラーパス。
2. エラー処理。 エラーが捕捉され、ログに記録され、適切に復旧されるか、意味のある形で伝播することを確認します。例外を握りつぶしてはいけません。再スローせずに汎用的な catch-all で捕捉することも認められません。
3. 副作用。 予期しない変更、グローバル状態の変更、または純粋に見える関数内に隠れた I/O を特定します。
4. セキュリティ。 インジェクションの脆弱性（SQL、XSS、コマンド）、サニタイズされていないユーザー入力、漏洩したシークレット、認可チェックの不足を確認します。
5. パフォーマンス。 明らかに非効率な処理を指摘します。例：N+1 クエリ、ループ内での不要なメモリ割り当て、ページネーションの欠如、メモリ内でのコレクションの無制限な増大。

ステップ 4：テストカバレッジをレビューする

コードが十分にテストされているかを評価します。

1. 新しい動作にはテストが必要です。 新しく追加された公開関数、メソッド、エンドポイント、または動作経路には、それぞれ少なくとも 1 つのテストが必要です。不足しているものを指摘してください。
2. テストの品質。 テストでは、コードがクラッシュせずに実行されることだけでなく、意味のある結果をアサートする必要があります。アサーションがないテストや、ごく些細なアサーションしかないテストを指摘してください。
3. エッジケースのカバレッジ。 最低限、テストでは正常系、エラー／失敗経路を 1 つ、境界条件を 1 つカバーする必要があります。
4. テストの独立性。 テストは実行順序、共有された可変状態、またはモック／フェイクを使わない外部サービスに依存してはいけません。
5. 命名。 テスト名はシナリオと期待される結果を説明する必要があります（例：should return 404 when order does not exist）。

ステップ 5：設計と規約を確認する

コードがコードベースに適合し、確立されたパターンに従っていることを確認します。

1. 一貫性。 コードは、プロジェクトに既にある命名規則、ファイル構成、パターンに従っていますか？逸脱があれば指摘します。
2. 関心の分離。 ビジネスロジックがインフラストラクチャ、プレゼンテーション、オーケストレーションのコードと混在していませんか？違反があれば指摘します。
3. API 設計。 公開インターフェース（関数シグネチャ、クラス API、HTTP エンドポイント）は明確で、最小限で、誤用しにくいものですか？
4. 依存関係の方向。 プロジェクトのアーキテクチャ（例：ヘキサゴナルアーキテクチャ、レイヤードアーキテクチャ）に沿って、依存関係は正しい方向を向いていますか？
5. SOLID 原則。 単一責任に違反しているクラスやモジュール、抽象化が破綻している箇所、コンポジションの方が適切なのに継承を使っている箇所を指摘します。

ステップ 6：エンジニアに問いかける

問題を見つけるだけでなく、設計とアプローチに積極的に問いを投げかけます。

1. 「なぜ」と尋ねる。 自明でない設計判断については、作者に根拠を説明してもらいます。例：
   • 「既存の集約にメソッドを追加するのではなく、なぜ別のサービスにしたのですか？」
   • 「ここでは、なぜコンポジションではなく継承を選んだのですか？」
   • 「この外部呼び出しに失敗した場合、どうなりますか？」
2. 代替案を提案する。 懸念点を見つけたら、指摘するだけでなく、具体的な代替案とその理由を示します。
3. 必要性を問う。 追加された依存関係、抽象化、レイヤーごとに、「これは今必要ですか、それとも先を見越しすぎていませんか？」と問いかけます。先を見越しすぎている場合は、削除を推奨します。
4. 障害を想定する。 重要な処理経路を選び、失敗した場合に何が起こるかを頭の中で（または実際に）たどります。処理されない障害モードがあれば報告します。
5. 複雑さの根拠を求める。 複雑なものについては、より単純な方法ではうまくいかないことを作者に示してもらいます。複雑さを無条件に受け入れてはいけません。

ステップ 7：レビュー概要を作成する

明確な重大度レベルを付けて、構造化されたレビューを出力します。

## Review Summary

### Blocking (must fix before merge)
- [ ] Issue description — file:line — suggested fix

### Should fix (strongly recommended)
- [ ] Issue description — file:line — suggested fix

### Nitpick (optional improvements)
- [ ] Issue description — file:line — suggested fix

### Questions (need clarification)
- [ ] Question — file:line

### Positive observations
- What was done well

重大度のルール：

• ブロッキング： テスト失敗、lint エラー、型エラー、新しいコードに対するテスト不足、セキュリティ上の問題、機能の破損、データ損失のリスク。
• 修正推奨： 複雑さに関する問題、不適切な命名、エラーハンドリング不足、設計上の懸念、パフォーマンスの問題。
• 軽微： リンターの範囲外のスタイル上の好み、軽微な可読性の改善、ドキュメントに関する提案。

ステップ 8：解決を確認する

エンジニアがフィードバックに対応した場合：

1. 自動チェックを再実行します（ステップ 1）。
2. ブロッキングの問題がそれぞれ解決されていることを確認します。
3. 「修正推奨」の項目が対応済みであるか、理由を明記したうえで明示的に先送りされていることを確認します。
4. すべてのブロッキング項目が解決され、新たな問題が生じていない場合にのみ承認します。

レビューの原則

• 厳格に、しかし敵対的にならない。 目的は品質の向上であり、門番をすることではありません。すべてのフィードバックは、実行可能で根拠がなければなりません。
• 形式的な承認をしない。 徹底的にレビューせずに承認してはいけません。「問題なさそうです」は、有効なレビューではありません。
• バグがある前提で考える。 何か問題があるという姿勢でレビューし、それを見つけることを自分の役割とします。
• シンプルな方がよい。 判断に迷ったら、より単純な解決策を支持します。
• コードは書くより読まれる方が多い。 今書いている人ではなく、次に読む人にとって理解しやすいコードを目指します。