AIコーディングエージェントに明確な「完了の定義」を与える方法

人間のチームメイトは、曖昧なチケットを引き受けたとき、判断で隙間を埋め、質問をする。AIコーディングエージェントはそのどちらもしない。あなたのリクエストを読み、コードを書き、できる限りのチェックを実行し、機能は完了だと宣言する。多くの場合、確認の質問を一つもせずに。あるガイドが言うように、曖昧な要件をエージェントに渡すと、「その緩みは吸収されるのではなく、そのまま作り込まれてしまう」のだ。

そのため、あなたが書けるもののうち最もレバレッジが効くのは、完了の定義である。本ガイドでは、エージェントが実際に行動に移せる完了の定義の書き方を扱う。

受け入れ基準と完了の定義

関連しつつも、分けて考える価値のある二つの考え方がある。

• 受け入れ基準は機能ごとのものだ。この特定の作業が正しいと見なされるために何を満たさなければならないか。
• 完了の定義はプロジェクト全体のものだ。すべての変更が出荷前に通過しなければならない品質ゲート、すなわちテスト、レビュー、ドキュメント、シークレットをコミットしていないこと、などである。

受け入れ基準を「正しいものを作ったか」、完了の定義を「自分たちの基準どおりに作ったか」と考えるとよい。あなたのエージェントには両方が必要だ。(この区別についてはAtlassianに優れた入門記事がある。)

願望ではなく、テスト可能なものにする

良い基準かどうかを判定するテスト。スクリプト、あるいはエージェント自身が、それが真かどうかをチェックできるだろうか。「ログインフォームは速く感じられるべき」は検証不能だ。輪郭のあるものへ書き換えよう。

• 有効な認証情報を送信すると、500ms以内に/dashboardへリダイレクトされる
• 誤ったパスワードを送信すると、インラインでエラーが表示され、他のページへは遷移しない
• 空のフィールドを送信すると、ネットワークリクエストが発生する前にクライアント側でブロックされる
• ログイン失敗はIPごとに毎分5回までにレート制限される

どの行も、エージェントが実装の目標にでき、かつ確認できるものだ。AIエージェント向けの良い仕様を書くことについてのAddy Osmaniの助言は、一行一行の「どうやって」ではなく、何を、なぜに焦点を当てるというものだ。意図と制約を記述し、実装はエージェントに選ばせよう。

具体例

同じタスクに対する二つのプロンプトを比べてみよう。

曖昧なもの:

ユーザーがパスワードをリセットできる仕組みを追加して。

完了の定義を伴うもの:

パスワードリセットのフローを追加して。完了とは以下を意味する:

• POST /auth/reset-requestエンドポイントはメールアドレスを受け取り、常に200を返す(メールアドレスが存在するかどうかは決して明かさない)
• 1時間有効な、署名付きで一度きり使えるトークンを、既存のメーラーsrc/lib/mail.ts経由で送信する
• POST /auth/reset-confirmはトークンを検証し、現行のパスワードポリシーを適用し、使用後にトークンを無効化する
• テストは次をカバーする: 正常なリセット、期限切れトークン、再利用されたトークン、未知のメールアドレス
• 新しい依存関係は、まず知らせてからでなければ追加しない

二つ目のバージョンが長いのは、官僚的だからではない。長いのは、そうでなければエージェントが推測してしまう曖昧さのすべてが、いまや決定されているからだ。セキュリティに関わる選択(アカウントの存在を漏らさない、トークンを期限切れにする、一度きりの使用)は、エージェントに即興で決めさせたくないものの筆頭である。

「完了」をエージェントのループに組み込む

テスト可能な完了の定義が持つ真の威力は、それがエージェントのフィードバックループを閉じることにある。コード → テスト → 修正 → 繰り返しというエージェント的なサイクルは、狙うべき明確な目標があってはじめて収束する。あなたの基準が実際のテストに対応していれば、エージェントはそれを実行し、失敗を確認し、あなたに返す前に自分の仕事を修正できる。

だから、完了を記述するだけで終わらせず、エージェントにそれをチェックする手段を与えよう。

• テストコマンド(npm test、pytest)を指し示し、それらが通るまで機能は完了ではないと伝える。
• 可読性や、既存のパターンへの追従といった、コードで断言しづらいものには、LLM-as-a-judgeのパスを使う。すなわち、出力をあなたの品質基準と照らし合わせてレビューする二つ目のプロンプトだ。Anthropicをはじめとする各社は、主観的なチェックにこれが有効だと確認している。
• セキュリティと「プレースホルダー/モックコードなし」は、プロジェクト全体の完了の定義に含めておこう。そうすれば、あなたが言及し忘れたものだけでなく、すべての変更に適用される。

エージェントの目に入る場所に置く

プロジェクト全体の完了の定義は一度だけ、エージェントが自動的に読むファイル、すなわちリポジトリのルートにあるAGENTS.mdやCLAUDE.mdに書こう。機能ごとの受け入れ基準は、タスクのプロンプト自体に書く。そうすれば「自分たちの基準」は常にコンテキストに含まれ、あなたはその日の作業に固有のことだけを書き出せばよい。

この変化は微妙だが、それこそが勝負のすべてだ。有能なエージェントを相手にすると、あなたの受け入れ基準は同僚へのメモであることをやめ、コードがそれに向けて作られる仕様そのものになる。そのつもりで書こう。