AI生成コードの手戻りを減らす受け入れ基準テンプレ

CopilotやCursorが生成したコード、「動いたからOK」でマージしていないだろうか。その場では問題なくても、数日後にバグが見つかったり、レビューで大幅な修正を求められたりする。これが「手戻り」の正体だ。

結論から言うと、AIにコードを書かせる前に「受け入れ基準」を決めておくと、この手戻りが大幅に減る。GitHub公式ドキュメントでも、Copilotの提案は「必ず検証する前提」と明記されている。つまり、検証の基準を曖昧にしたままAIを使うのは、そもそも想定された使い方ではない。

この記事では、すぐに使える受け入れ基準のテンプレートと、その運用のコツを紹介する。

なぜ「受け入れ基準」が必要なのか

AI生成コードで手戻りが起きるパターンは、だいたい決まっている。

  • 境界値の処理が抜けている（0件、上限、null）
  • セキュリティの基本が甘い（入力検証がクライアント側だけ、など）
  • 動くけど読みにくい、既存コードと書き方が揃っていない
  • テストがない、または「動作確認しました」だけ

これらを後から指摘されて直すのは、最初から条件を決めておくより圧倒的に時間がかかる。レビュアーも「何を基準にOKとするか」が曖昧だと、指摘がブレる。

受け入れ基準を事前に決めておけば、AIに渡すプロンプトにも反映できるし、自分でチェックする観点も明確になる。

4ブロック構成のテンプレート

受け入れ基準は、以下の4つに分けると抜け漏れが減る。

1. 機能要件

- 入力: 
- 出力: 
- 例外ケース: 
- 境界条件:

「何を受け取って、何を返すか」を具体的に書く。例外ケースと境界条件が最も抜けやすいので、意識して埋める。

例：ユーザー検索API

- 入力: ユーザーID（文字列、1〜50文字）
- 出力: ユーザー情報オブジェクト or null
- 例外ケース: DBエラー時は500、認証エラーは401
- 境界条件: 空文字、51文字以上、存在しないID

2. 品質基準

- 可読性: 
- 保守性: 
- 既存コードとの整合:

「動けばいい」で済まさない部分。チームのコーディング規約があれば、ここで参照する。

例

- 可読性: 関数は30行以内、ネストは3段まで
- 保守性: マジックナンバー禁止、定数化する
- 既存コードとの整合: /src/utils配下の命名規則に従う

3. 安全性チェック

- 入力検証: 
- 出力処理: 
- 認証・認可:

OWASPのセキュアコーディングチェックリストから、特に重要な観点を抜粋するとこうなる。

例

- 入力検証: サーバ側で実施、検証失敗は拒否（エラーメッセージに詳細を含めない）
- 出力処理: HTMLに埋め込む場合はエスケープ必須
- 認証・認可: 認証済みユーザーのみアクセス可、権限チェックあり

ポイントは「許可リスト型で検証する」「型・範囲・長さを全て検証する」という方針を明記すること。AIは場当たり的な検証コードを生成しがちなので、方針を固定すると揺れが減る。

4. 検証方法

- ユニットテスト: 
- 統合テスト: 
- 自動ツール:

「どのテストで担保するか」を書く。ここが曖昧だと、「E2Eで確認したのでOKです」という状態になりやすい。

例

- ユニットテスト: 境界条件・例外ケースを網羅（追加必須）
- 統合テスト: DB接続を含む正常系1ケース
- 自動ツール: ESLint、型チェック、CodeQL通過

Googleのテストブログで紹介されている「テストピラミッド」の考え方では、ユニットテストを厚く（目安70%）、統合テストは必要な箇所だけ（20%）、E2Eは少数に抑える（10%）のが合理的とされている。E2Eは実行が遅く、不安定になりやすいからだ。この比率はあくまで目安だが、「E2Eで一発確認」に偏らない根拠として使える。

除外事項も書く

テンプレートには「やらないこと」も明記しておく。

## 除外事項・前提
- 既存APIの仕様変更は含まない
- 性能SLO（レスポンス時間など）は別チケットで対応
- 下位互換性は維持（既存クライアントを壊さない）

これがないと、AIが「ついでに最適化しておきました」みたいな過剰実装をしてきて、意図しない変更が混ざる。差し戻しになると時間の無駄だ。

実際の運用イメージ

  1. タスクに取りかかる前に、テンプレートを埋める（5分程度）
  2. AIへのプロンプトに受け入れ基準を含める
  3. 生成されたコードを基準に照らしてチェック
  4. 自動ツール（lint、型チェック、テスト）を通す
  5. 基準を満たさない部分は修正 or 再生成

慣れてくると、テンプレートを埋める段階で「この機能、境界条件が複雑だな」と気づけるようになる。それだけでも価値がある。

注意点

このテンプレートは汎用的に使えるが、万能ではない。

  • 業界固有の規制（金融、医療など）がある場合は、OWASPのチェックリストだけではカバーできない。法的要件や業界ガイドラインを別途確認する必要がある
  • チームの事情によってはテストの比率を調整すべき。フロントエンド中心のプロダクトなら統合テストの比重が上がることもある
  • 全てのコードに適用する必要はない。使い捨てのスクリプトや検証用コードまで厳密にやるとオーバーヘッドが大きい

「AIが生成したコードは人が責任を持つ」という前提を忘れなければ、テンプレートの粒度は自分で調整していい。

まとめ

AI生成コードの手戻りを減らすには、「動いたからOK」ではなく「何を満たせばOKか」を先に決めておくのが効果的だ。紹介した4ブロック（機能・品質・安全性・検証方法）のテンプレートは、そのまま使ってもいいし、チームの状況に合わせてカスタマイズしてもいい。

最初は面倒に感じるかもしれないが、レビューで指摘されて直す回数が減れば、トータルでは時間短縮になる。AIと一緒に働くなら、検証の仕組みもセットで整えておくのが結局は近道だ。

参考リンク