記事

AI生成コードをチームで扱うための品質ルールとレビュー基準

Claude Codeなどで生成したコードをチーム共有のコードベースに取り込むときに、品質を担保するためのルール体系を整理します。責任者・テスト・セキュリティ・依存追加・ドキュメントの5観点と、コピペで使えるレビュー基準テンプレートまで扱います。

Claude Code・Cursor・GitHub Copilotなどで生成したコードをチームのコードベースに取り込むとき、「動いた」だけで通すと中期的にレビューが破綻します。AI生成コードはローカルでは通ってもCIで落ちる、過剰な抽象化が混入する、依存パッケージが勝手に増える、テストが「自明アサート」になっている、といった事故が特有のパターンとして出てきます。この記事では、チームでAI生成コードを扱うための品質ルールを5観点に整理し、レビュー基準としてそのまま使えるテンプレートまで提供します。

結論：AI生成コードは「責任者・テスト・セキュリティ・依存・ドキュメント」の5観点で評価

AI生成コードに特有の事故を防ぐため、レビュー基準を次の5観点に固定します。

責任者：マージApproveした人間が責任を持つ（AIに責任は分散しない）
テスト：トートロジーテスト・空アサートを弾く具体的な観点
セキュリティ：入力検証・認証・秘密情報・依存の脆弱性
依存追加：勝手なnpm installを許可しない
ドキュメント：必要な文書・不要な文書の判定

チーム導入時の合意は「チームでClaude Codeを導入するときに最初に決めるルール」、レビュー実装の詳細は「Claude Codeをコードレビューに使う方法と人間が見るべきポイント」で扱っています。

観点1：責任者を「Approveした人間」に固定する

AI生成コードで最初に決めるのは「誰が責任を負うか」です。曖昧にすると、事故発生時に「AIが書いたから」という言い訳が出てきます。

AI生成コードを含むPRにApproveした人間が責任者
AI生成行数の目安をPR本文に書く（雰囲気で構わない。50%／80%など）
Co-Authored-By: Claude等のトレイラーをコミットに含める（後から検索可能にする）
自動Approveは禁止：CIが通っただけでマージしない

「AIの寄与度」を測ることが目的ではなく、「責任が宙に浮かない」状態を作るのが目的です。

観点2：テスト品質の具体的なレビュー基準

AI生成テストでよく見るパターンと、それを弾く基準です。

危ないサイン	例	対処
トートロジー	`expect(result).toBe(result)`	期待値はリテラルまたは事前に計算した固定値
自明アサート	`expect(true).toBe(true)`	アサートに意味のある値を入れる
モック戻り値そのまま	`mock.return(x)`→`expect(out).toBe(x)`	モックは入力に対する出力の検証に使う
`any`受け	`const res: any = ...`	レスポンス型を明示
`describe.skip`混入	テスト一覧から見えない	CIで`skip`を検出して落とす
アサート0件	`it`内に`expect`がない	リント・カバレッジツールで検出

これらは「Claude Codeにテストコードを生成させるときの依頼文と注意点」で扱った観点と整合します。CIでは次のようにskipを検出します。

rg -n 'describe\\.skip|it\\.skip|test\\.skip' src tests && exit 1 || exit 0

観点3：セキュリティのチェック観点

AI生成コードに特有のセキュリティ落とし穴です。

入力検証の欠落：HTTPリクエストパラメータを型変換だけで使う
SQLインジェクション余地：文字列連結によるクエリ組み立て
XSS：dangerouslySetInnerHTMLを意味なく使う
認証バイパス：認証ミドルウェアの順序を変えてしまう
過剰なfallback：try/catchで例外を握りつぶす
Math.randomの暗号用途利用：トークン生成で使うと事故になる

レビューでは「なぜAIがこの実装を選んだか」を依頼文に立ち戻って確認します。仕様で要求していない過剰な防御コードはむしろ削除候補です。包括的な観点は「Claude Codeを使うときのセキュリティチェックリスト」を参照してください。

観点4：依存追加の制御

AIに任せると気軽に新しいパッケージが追加されがちです。次のように制御します。

package.jsonの差分を必ず人間が確認：CI上でも警告を出す
新規依存は別PRに切り出す：機能PRに混ぜない
採用基準を決める：週間ダウンロード数・最終更新日・メンテナの応答性・ライセンス
AIが「ライブラリで解決」を提案したら一度立ち止まる：標準APIで書ける場合が多い

CIでpackage.json差分を検出するスニペット例です。

- name: Block silent dependency additions
  run: |
    if git diff origin/main -- package.json | grep -qE '^\+\s*"[^"]+":\s*"\^?[0-9]'; then
      echo "::error::package.json に新しい依存が追加されています。別 PR に切り出してください。"
      exit 1
    fi

CI整備の詳細は「Claude CodeとGitHub ActionsでCIを整える手順」で扱っています。

観点5：ドキュメントの過剰生成を防ぐ

AIに任せると「READMEを各ディレクトリに作る」「全関数にJSDocを書く」「インラインコメントが冗長になる」といった事象が頻発します。チームで次を合意しておきます。

README.mdはリポジトリ直下にのみ作る（サブディレクトリには原則作らない）
コメントは「なぜ」を書く：「何をしているか」はコード自体に語らせる
JSDoc/docstringはAPI境界に限定：内部関数には書かない
生成されたdocs/ディレクトリは原則PRに含めない：必要なら別PRに切り出す

「AIが書いた文書」が増えすぎる問題は「AI開発でファイルが増えすぎる問題を防ぐ設計ルール」で扱っています。

レビュー基準テンプレート（コピペ用）

PRテンプレートに次のチェックリストを入れます。

## AI 生成コード レビューチェック

### 責任
- [ ] レビュアーは AI 生成コードの内容を理解した上で Approve している
- [ ] AI 生成行数の目安を PR 本文に記載した
- [ ] `Co-Authored-By: Claude` 等のトレイラーをコミットに含めた

### テスト
- [ ] `describe.skip` `it.skip` が混入していない
- [ ] アサートが意味を持つ（トートロジー・自明アサートがない）
- [ ] モックは「入力 → 出力」の検証に使われている
- [ ] テストファイルが実装ファイルと同じ単位で配置されている

### セキュリティ
- [ ] 外部入力に型検証＋値検証が入っている
- [ ] SQL は ORM またはパラメータ化クエリで組まれている
- [ ] `dangerouslySetInnerHTML` 等の危険APIに正当な理由がある
- [ ] 認証・認可の順序が変わっていない
- [ ] try/catch で例外を握りつぶしていない

### 依存
- [ ] `package.json` `package-lock.json` の差分を確認した
- [ ] 新規依存があれば別 PR に切り出されている
- [ ] 採用基準（ダウンロード数・最終更新日・ライセンス）を確認した

### ドキュメント
- [ ] サブディレクトリに勝手な README が増えていない
- [ ] コメントは「なぜ」を書いている（「何を」は書いていない）
- [ ] 既存ドキュメントとの矛盾がない

レビューに使うClaude Code自身のチェック

/reviewや/security-reviewで一次フィルタを通したPRだけを人間レビューに回す運用にすると、レビュアーの負担が下がります。

claude --from-pr 123 --permission-mode plan

依頼文の例：

依頼：このPRをチームの「AI生成コード レビューチェック」基準で評価してください。

## チェック項目
@.github/pull_request_template.md の "AI 生成コード レビューチェック" セクション

## 制約
- 実装変更は提案しない（指摘のみ）
- 指摘は Critical / Should / Nit の3段階でラベル付け
- Critical は責任・セキュリティ・依存に直接関わるものだけ

## 出力
- セクションごとに該当する違反項目を列挙
- 各違反について：違反内容、該当ファイル＋行、推奨される対処