AIコーディングエージェント向けAcceptance Criteriaの書き方――「完了しました」を検証可能にする7項目
AIコーディングエージェントへ、こんな依頼を出したことはないでしょうか。
ログイン画面のボタンがスマホで崩れるので直して。
数分後、AIは返します。
修正しました。
問題はここからです。
本当に直ったのか。
320px幅でも崩れないのか。既存のPC表示は壊していないのか。テストは通ったのか。スクリーンショットを見たのか。
AI Agent時代に不足しやすいのは、依頼文の長さより Doneの定義 だと私は感じています。
この記事では、AIへコードを書かせるためのプロンプトではなく、 「何を満たせば完了と言ってよいか」を書くAcceptance Criteria を7項目に分けます。
まず、依頼とAcceptance Criteriaを分ける
依頼は「何を変えたいか」です。
Acceptance Criteriaは「どうなっていれば成功か」です。
たとえば、
依頼:
ログイン画面の送信ボタンがスマホで横にはみ出すので直す。
だけでは、AIがCSSを変更した時点で「修正した」と判断する可能性があります。
一方、完了条件を次のように置くと、外から確認できます。
Acceptance Criteria:
- 320px / 375px / 768px 幅で横スクロールが発生しない
- ボタン幅がコンテナを超えない
- 1024px以上の既存レイアウトを変更しない
- 既存テストがすべて通る
- 対象3幅のスクリーンショットを確認する
コードの書き方を指定していません。
それでも「何を直したと言えるか」はかなり明確になります。
1. User-visible outcomeを書く
最初に書くのは、内部実装ではなく 利用者から見える結果 です。
悪い例:
CSSを修正する。
良い例:
320px幅でも送信ボタンが画面外へはみ出さない。
AIは内部実装を別方式へ変えることがあります。
Flexboxを直すかもしれない。min-width を消すかもしれない。DOM構造を調整するかもしれない。
そこを先に固定しすぎるより、まず外部挙動を固定します。
2. ScopeとNon-goalを書く
AI Agentは、問題を広く解釈すると周辺も「ついでに」直すことがあります。
そこで、触ってよい範囲と今回やらないことを分けます。
Scope:
- login formのレイアウト
- submit buttonのレスポンシブ表示
Non-goal:
- フォームデザイン全面刷新
- 認証API変更
- 文言変更
特に既存コードベースでは、 直してほしい場所より、変えてほしくない場所を書く方が効く 場面があります。
3. Invariantを書く
Invariantは、変更後も維持すべき条件です。
例:
- デスクトップ表示は既存レイアウトを維持する
- Enterキー送信を維持する
- 既存のフォームバリデーションを維持する
「バグが直った」だけでは不十分で、別機能を壊していないこともDoneに含めます。
回帰バグをAcceptance Criteriaへ入れるイメージです。
4. Failure behaviorを書く
正常系だけでなく、失敗時にどうなるべきかを書きます。
たとえばAPI通信なら、
- 401では再ログイン導線を表示する
- 500では再試行可能なエラー表示にする
- 失敗時に送信中表示が残り続けない
という形です。
AIへ「例外処理もして」と書くより、 観測可能な失敗時挙動 を置いた方が検証しやすくなります。
5. Verification commandを書く
テスト方法が分かっているなら、AIに推測させず明示します。
npm test
npm run lint
npm run build
E2Eがあるなら、それも書きます。
npm run test:e2e -- login
ポイントは「テストを書いて」で止めず、 どの検証が通れば受け入れ可能か を書くことです。
既存Repositoryに正式な検証手順があるなら、それをSource of Truthにします。
6. Evidenceの種類を書く
Agentが「確認しました」と言うだけでは、確認方法が分かりません。
なので、必要なEvidenceも決めます。
| 対象 | Evidence例 |
|---|---|
| ロジック | unit test結果 |
| UI | screenshot / visual diff |
| 互換性 | 既存test suite |
| ビルド | build command結果 |
| Repository変更 | git diff |
| 外部サービス | 実際の外部状態 |
UI修正なのにコードだけ見てDoneにすると、表示崩れを見逃します。
逆にロジック変更なのに毎回スクリーンショットを要求しても意味がありません。
成果物の種類に合わせてEvidenceを選ぶ のが重要です。
7. Stop conditionを書く
これは特に外部サービスや不可逆操作で重要です。
たとえば、
- 認証が切れていたら停止する
- CAPTCHAが出たら停止する
- 公開ボタン押下後、結果が不明なら再押下しない
- 既存仕様と依頼が矛盾したら実装前に報告する
AI Agentは「最後までやり切る」ことが長所ですが、曖昧な状態で最後まで進むと事故になります。
Doneだけでなく、 Doneへ進んではいけない条件 も契約に含めます。
コピペ用テンプレート
私は、複雑すぎない作業なら次くらいから始めます。
## Objective
何を変えるか。
## Acceptance Criteria
- 利用者から見た成功状態
- 主要な境界条件
- 維持すべき既存挙動
## Scope
- 触ってよい範囲
## Non-goals
- 今回はやらないこと
## Verification
- 実行するtest / lint / build / E2E
## Evidence
- Done判定に必要なdiff / test結果 / screenshot / 外部状態
## Stop Conditions
- 認証切れ、仕様矛盾、不可逆操作の不確実性など
毎回全部を書く必要はありません。
1行修正までこのテンプレートを埋めると、今度は人間側の負担が大きくなります。
使う目安は、
- 変更範囲が複数ファイルにまたがる
- 回帰リスクがある
- UIや外部状態の確認が必要
- 別のAgentへ引き継ぐ可能性がある
- 「完了」の解釈が複数ある
あたりです。
Before / After
Before
プロフィール編集画面のバグを直して。
テストもしておいて。
After
Objective:
プロフィール編集画面で、表示名を空にして保存したときに
不明なエラーになる問題を修正する。
Acceptance Criteria:
- 表示名が空なら保存前に入力エラーを表示する
- APIリクエストを送信しない
- 有効な表示名では従来どおり保存できる
- 他のプロフィール項目の保存挙動は変えない
Verification:
- 対象validationのunit testを追加
- 既存test suiteを実行
- lint / buildを実行
Evidence:
- 変更diff
- test / lint / build結果
Stop Conditions:
- 既存仕様上、空文字が有効値なら実装せず報告する
後者は長いですが、内部実装をほとんど指定していません。
Agentへ自由を残しながら、Doneだけを狭くしています。
人間の仕事は「コードを書く」から消えるのか
2026年9月10日のQiita AI Summitは、「AI駆動開発を実現するエンジニアリング戦略」と「エンジニアの新たな役割」をテーマにしています。
AIが書けるコード量が増えるほど、人間の役割がなくなる、という見方もあります。
私が実運用で感じている変化は少し違います。
人間が細部の実装を全部指定する必要は減る一方、何を成功と呼ぶかを決める仕事はむしろ前へ出てくる。
Acceptance Criteriaは、その役割をAgentへ渡せる形にするための一つの方法です。
AIの「完了しました」を疑い続けるのではなく、最初から完了を外部から検証できる形にしておく。
その方が、人間にもAgentにも分かりやすい開発になります。