メインコンテンツまでスキップ

コードレビュー観点について（概念ベース・AI/Human共用）

このチェックリストは観点を揃えるためのものです。
具体ルールは各プロジェクトで決めてください【本書は“矛盾のない最小公倍数”を目指します】。

0. クイック判定について（最初にみる）​

  • 目的が一言で言える（PRタイトル/概要で伝わる）

  • 変更は小さく焦点化されている（無関係な差分なし）

  • テスト or 動作証跡があり、再現手順が簡潔（AI/人がすぐ確認できる）

1. 可読性（Readability）​

  • 名前だけで役割と粒度がわかる（関数＝動詞始まり、略語を避ける）

  • コメントは**なぜ（背景/前提/選択理由）**を説明（実装の逐語ではない）

  • 1関数に1責務。長文化していない（画面1枚程度を目安に分割）

  • 仕様の「入力→処理→出力」が追える

2. 厳密性（Precision）​

  • 比較は型を含めて明確（例：=== / ?? / ?. の適用が妥当）

  • 未定義/空/NaN/境界の扱いが曖昧でない（正常系で true になる式）

  • 数値・単位・範囲にマジックがない（根拠 or 定数化）

3. 体裁と差分（Diff Hygiene）​

  • フォーマッタ/リンタを通した差分（ノイズなし）

  • 命名/並び替え等の意味のない差分が混在していない

4. 命名・データ（Naming & Data）​

  • 変数/関数は用途が推測可能（必要なら型が想起できる）

  • 定数化（OAOO：一箇所で定義）。マジックナンバー禁止

  • データ構造の責務と境界が明確（DTO/Domain/表示用の混線なし）

5. 設計（Design）​

  • まず合成（composition）、継承は必要最小限

  • 外部からの直接アクセスを抑制（必要程度はゲッター/APIで明示）

  • 参照順序が読みやすい（「参照されるもの→参照するもの」）

6. 制御構造（Control Flow）​

  • ブロック {} は原則省略しない（1行のみ例外/改行禁止）

  • ループ/分岐は意図に合う構文（for…of/in、関数型は高階関数）

  • switch の fall-through は意図明示

7. エラー処理（Error Handling）​

  • 起こりうる論理的エラーのみ捕捉（揉みつぶし禁止）

  • 例外の伝播方針が一貫（呼び出し側にとって予測可能）

  • ログ/メッセージは原因追跡に十分

8. 可読性 vs 性能（Performance）​

  • 可読性を大きく損なう最適化は稀な例外（必要性の根拠あり）

  • 最適化した箇所にコメント：// performance optimized: <理由/前提/測定>

9. 変更の単位（Change Unit）​

  • 1PR=1目的（整形/リネームと機能変更は分離）

  • PR本文に目的・変更点・影響範囲・検証方法がある

10. AI連携の観点（Agent-Ready）​

  • **決定的（deterministic）**に再現できる：対話不要、コマンド1〜2個で検証可能

  • 外部依存の前提が明記（環境変数・サービス・権限・シード値）

  • 入出力がファイル/ログに残る（AIが後工程で参照できる）

  • 「人がボトルネックにならない」仕組み（自動でGreenになるまでの道筋）

11. SDD × TDD（仕様と検証）​

  • 最小の仕様断面が自然文で明示（何を満たすとDoneか）

  • 失敗するテスト→最小実装→Green→リファクタの痕跡がある

  • PRにテスト結果 or 実行ログが貼られている（再現手順が短い）

12. セキュリティ/秘匿（Minimal）​

  • 入力データのバリデーションが適切に行われているか（未検証入力はSQLインジェクションやXSSの原因）

  • ハードコードされた秘密情報が存在しないか（APIキーやパスワードなどは環境変数やシークレット管理を使用）

  • 使用している暗号アルゴリズムや鍵長が安全なものか、鍵管理が適切に行われているか

  • 危険な関数やパターン（SQLの文字列連続や eval 等）が使用されていないか

  • 認証とセッション管理が適切か（認証チェックの欠如やトークン漏洩がないか）

  • 認可・アクセス制御が適切か（権限ごとのアクセス制限が守られているか）

  • 依存ライブラリに既知の脆弱性がないか、サポート切れのバージョンを使用していないか

  • 秘密はコミットしない（.env* は除外。必要なら .env.example）

  • 外部APIは例外処理・タイムアウトを持つ

  • 個人情報/ライセンス/出典の扱いに問題がない

13. UI/UX（該当時）​

  • a11y（ラベル/ARIA/フォーカス）・レスポンシブ配慮

  • エラー表示や空状態の仕様が定義されている

14. 承認/差戻しの基準​

Approve：上記観点で将来の保守/連携に耐える
Request Changes：

  • 意図が読み取れない命名/多重責務

  • 比較/境界/未定義の扱いが曖昧

  • マジック/重複の放置

  • 過剰最適化で可読性崩壊（根拠なし）

  • 再現不能（手動前提・対話依存）や証跡不足

15. マルチエージェント開発の観点 (SDD, TDD, Non-Blocking)​

  • -DD（仕様駆動開発）：エージェント間の誤解を避けるために、自然言語だけでなく共有仕様を持つ

    • 仕様は requirements.md や OpenAPI など構造化文書として定義されている （「平日」など用語の定義やビジネスルールを明記）
    • 曖昧な自然言語の仕様が残っていない （誰が読んでも同じ理解になる）

  • TDD（テスト駆動開発）：実装前にテストを書き、ゴールを明確にする

    • 受け入れテストがユーザ視点で記述されている （シナリオと期待する動作を明示）
    • インタフェース/契約テストで境界条件やエッジケースをカバーしている （例：時間や日付の繰り上がり等）

  • ノンブロッキング（人間は進行を止めない）：エージェントの進行を妨げず、段階的にレビューする

    • エージェント間の対話や決定がログに記録されている （後から過程を追える）
    • テストがグリーンになり、設計レビューやドキュメント更新が済んだ後に人間がレビューする

  • 注意点については次のポイントを確認する

    • 複雑な業務ロジックやセキュリティは人間が最終判断する
    • 学習データの偏りや外部APIの費用など、エージェントでは気付けないリスクを確認する

倫理的整合性とアルゴリズムの公平性​

AIシステムは、訓練データに含まれる人間のバイアスを継承し、増幅させる可能性があります。これにより、特定のユーザーグループに対して不公平または差別的な結果を生むことがあります。AIが生成・レビューするコードは、このリスクを特に慎重に評価する必要があります。

  • 訓練データの代表性:

    モデルの訓練データは、対象となるユーザー層の多様性（性別、人種、年齢など）を適切に反映しているか？特定の層が過小評価または過大評価されていないかを確認する。

    • 悪い例: 採用判定AIが、過去の採用データ（男性が多数）のみで訓練されており、女性候補者の評価が不当に低くなる。

  • プロキシ変数の悪用:

    郵便番号や医療費の履歴など、一見中立に見える変数が、人種や社会・経済的地位といった保護されるべき属性の代理（プロキシ）として機能し、意図しない差別を引き起こしていないか？

    • 悪い例: 医療の必要性を判断するアルゴリズムが、過去の医療費を代理変数として使用した結果、医療へのアクセス機会が歴史的に少なかった黒人患者の健康リスクを過小評価した。

  • 公平性メトリクスの評価:

    モデルの出力は、異なるユーザーグループ間で公平性が保たれているか？「人口統計学的パリティ」や「均等化オッズ」などの公平性メトリクスを用いて評価されているか？

  • ステレオタイプの増幅:

    生成されたコードやその出力が、有害な社会的ステレオタイプ（例: 特定の職種と性別の関連付け）を強化・再生産していないか？

  • 透明性と説明責任:

    AIによる意思決定ロジックは、追跡・説明可能か？あるいは、中身が不明な「ブラックボックス」になっていないか？重要な判断については、人間が最終的な責任を負う仕組みが担保されているか？