変更理由まで追える「AIコード検証パック」の作り方
AIが生成したプルリクエストを開いたものの、変更理由が分からず、レビュー担当者が差分を一行ずつ推測する。そんなチームのテックリード向けに、マージ判断に必要な証拠を一枚へまとめる「AIコード検証パック」の作り方を紹介します。
完成形は「コード」ではなく判断材料
レビュー対象はコードだけではありません。要件から差分、検証結果、戻し方までを追える状態が完成形です。NISTのセキュア開発フレームワークも、コードレビューでは既存の解析・テスト結果を確認し、発見した問題と修正内容を記録するよう示しています。[1]
まず、次のひな型をプルリクエスト本文に置きます。
AIコード検証パック
- 目的：何を変え、どの状態を完成とするか
- 変更範囲：触った機能、API、データ
- 変更しない範囲：意図的に対象外としたもの
- 主要な判断：採用案と、見送った案
- テスト証拠：実行条件、結果、ログへのリンク
- 静的解析：使用した検査と未解決の指摘
- 依存関係：追加・更新・削除
- 未解決事項：担当者と期限
- 戻し方：切り戻し手順と判断者
完了条件は、レビュー担当者が「要件→差分→証拠→切り戻し」を往復できることです。AIとの会話をすべて載せる必要はありません。採用した判断と検証可能な証拠を残します。
5段階で検証パックを作る
1. 目的を一文で固定する
「処理を改善する」ではなく、「外部APIの一時失敗時に、同じ要求を安全に再試行できるようにする」のように、対象と完成状態を書きます。ここが曖昧なら、テストもレビューも収束しません。
2. 影響範囲と対象外を分ける
変更したファイル一覧ではなく、利用者、データ、外部接続、権限への影響を書きます。同時に「請求確定後の再実行は対象外」のような境界を置きます。
3. 失敗モードからテストを作る
正常系を一度通すだけではなく、重複、タイムアウト、部分失敗、権限不足を列挙し、それぞれにテストを対応させます。NISTは、リスクに応じてテストを設計・実施し、結果と修正を記録することを求めています。[1]
4. ツール出力を証拠に変える
「CI成功」とだけ書かず、どの条件を検査し、どの結果を確認したかを示します。GitHubのステータスチェックは、ビルド、テスト、コードスキャンなどの状態と詳細をプルリクエストに提示でき、保護ブランチでは必須チェックをマージ条件にできます。[2] CodeQLを使う場合は、検出結果をコードスキャンのアラートとして確認でき、独自ルールも追加できます。[3]
5. 未解決事項と戻し方を残す
警告を消せない場合は隠さず、受容する人、期限、再確認条件を記録します。切り戻しは「元に戻す」ではなく、無効化する設定、実行者、確認する指標まで書きます。
たとえば、AIに決済APIの再試行処理を書かせた場面では、重複請求を防ぐキー、タイムアウト時の状態、ログへの機密情報混入、機能を止める設定を検証パックに並べます。AIはテスト候補と説明文を作れますが、マージ可否は決済責任者とレビュー担当者が証拠を見て決めます。
マージ条件を二つに分ける
自動判定と人の判断を混ぜないことが重要です。
| 項目 | 判定方法 | 不合格時 |
|---|---|---|
| 整形・単体テスト | CIで自動判定 | マージを止める |
| 静的解析 | チームの基準で自動判定 | 修正または例外承認 |
| 振る舞いの変更 | 機能責任者が確認 | 目的と境界を再記述 |
| 未解決事項 | 担当者・期限を人が確認 | 所有者がなければ止める |
| 切り戻し | 実行者が手順を確認 | 手順を試してから再審査 |
文書変更や、影響が局所的でその場で容易に差し戻せる修正だけを扱うという場合には、九項目すべてを求める運用には向きません。変更リスクに応じて項目を減らします。一方、権限、決済、個人情報、外部への書き込みを伴う変更では、証拠を省かない方がよいでしょう。
明日から使える実装チェックリスト
- [ ] 一つのリポジトリと一種類の変更から試す
- [ ] プルリクエストのテンプレートに九項目を追加する
- [ ] 必須チェックと、人が承認する項目を分ける
- [ ] 失敗モードごとにテストを一つ以上対応させる
- [ ] 未解決事項に担当者と期限を付ける
- [ ] 切り戻し手順をレビュー中に一度確認する
- [ ] 10件のプルリクエスト後に、使われなかった項目を削る
検証パックの目的は書類を増やすことではありません。レビュー担当者が推測する時間を減らし、AIが書いたコードでも、人が根拠を持ってマージ可否を決められる状態を作ることです。
参考資料
- NIST SP 800-218, Secure Software Development Framework (SSDF) Version 1.1
- GitHub Docs: About status checks
- GitHub Docs: About code scanning with CodeQL
本記事はAIを活用して作成し、公開前に自動レビューを実施しています。情報の確認日：2026-09-29。
Tác giả
ELYSAI編集部