AIエージェントに「動いた証拠は？」と詰めよう

AIエージェントに開発を任せると、コードを書き、変更内容をまとめ、確認を依頼するところまではかなり速くなりました。

既存のコードを読み、修正し、自動テストを実行し、変更内容の確認依頼（プルリクエスト）を作る。以前なら人間が数時間かけていた作業を、短い時間で終わらせることもあります。

ただ、実際の開発では、プルリクエストができたところで仕事が終わるわけではありません。

コードが変更されたことと、要求された機能を実際に使えることは同じではありません。

自動テストが通っていても、確認用の環境で操作すると動かないことがあります。画面は正しく見えていても、裏側では意図しないデータが保存されていることもあります。

AIエージェント時代の完了条件は、「コードを変更した」ではなく、要求された動きを実際に確かめ、その結果を証拠付きで示せることへ変える必要があると思います。

ただし、AIエージェントに画面画像やログを返させれば、それだけでよいわけでもありません。

証拠を集める前に、何が起きたら合格なのかを具体的に決めておく必要があります。この記事では、その確認項目を「受け入れ条件」と呼びます。受け入れ条件を書くために使うのが、前提・操作・期待する結果を一定の形式で表すGherkinです。

以下のコード例に出てくる英単語は、Gherkinで決められている記法です。この記事のコード例では、Gherkinの標準である英語のキーワードをそのまま使っています。

動作証拠の質は、受け入れ条件の質で決まる

例えば、次のような受け入れ条件しか書かれていなかったとします。

Scenario: メール未確認ユーザーを制限する
  Given メールアドレスが未確認である
  When 認証が必要な機能を利用する
  Then 利用できない

この書き方では、何を実装し、何を確認すればよいのかが十分に定まりません。

「利用できない」とは、ボタンを表示しないことなのか、操作後にエラーを表示することなのか、サーバーが要求を拒否することなのか、データを保存しないことなのか。どれも「利用できない」と表現できます。

このままAIエージェントに動作証拠を提出させても、都合のよい画面を一枚撮って「合格」と判定できてしまいます。

動作証拠は、曖昧な要求を具体化するためのものではありません。すでに具体化された要求が成立したことを証明するものです。

だから、証拠を管理する仕組みを作る前に、実際に確認できる受け入れ条件を作る必要があります。

Figmaだけでも、Gherkinだけでも足りない

画面を実装する場合、AIエージェントにはFigma MCPを接続して、対象の画面や部品を直接参照させます。Figma MCPとは、AIエージェントがFigmaの設計データを直接読めるようにする接続方法です。

これを使えば、対象画面、部品の構造、表示文言、配置、画面の状態、操作後の遷移などを、単なる画面画像より正確に取得できます。

ただし、Figmaから読み取れるのは、主に画面の構造と操作の流れです。

Figma上に送信ボタンが置かれていても、誰が押せるのか、どの状態なら押せるのか、押した結果どのデータが変わるのか、二重送信をどう防ぐのかまでは、必ずしも決まりません。

Figmaは重要ですが、Figmaだけでは業務の決まりになりません。

そこで、Figmaで画面設計を確認したうえで、PM on Railsに受け入れ条件を作り込みます。

• Figma：どのような画面にするかを判断する基準
• Gherkin：何が起きるべきかを判断する基準
• コード：決めた動きを実現するもの
• 動作証拠：決めた動きが実際に成立した記録

この四つを一本につなげることが、AIエージェントへ開発を任せるうえで重要です。

画面の動きと、業務ルールを別々に書く

受け入れ条件を作るうえで、私が特に重要だと考えているのが、利用者から見える画面の動きと、システムが守るべき業務ルールを分けて書くことです。

一つの項目に、画面操作、表示文言、権限の判定、データ更新、通知処理まで全部書いてしまうと、仕様が読みにくくなります。

それだけでなく、画面を少し変更しただけで、変わっていない業務ルールまで書き直さなければならなくなります。

例えば、「メールアドレスを確認していない回答者は、回答を確定できない」というルールがあるとします。

まず、システムが守るべき業務ルールを書きます。

Feature: 回答送信の可否

  Rule: メール未確認の回答者は回答を確定できない

    Scenario: メール未確認の回答者による回答送信を拒否する
      Given メール未確認の回答者が回答可能な案件を持っている
      When 回答者が案件への回答を確定しようとする
      Then 回答は登録されない
      And 案件の回答状態は変更されない
      And メール確認が必要であることを示す結果を返す

ここでは、画面上でどのボタンを押すかは書きません。

定めているのは、メール未確認なら回答を登録しないこと、案件の状態も変えないこと、メール確認が必要だと画面などの呼び出し元へ返すことです。

画面が変わっても、別のシステムから利用されるようになっても、このルールは変わりません。

一方で、利用者から見える画面の動きは別に書きます。

Feature: 回答画面でのメール確認案内

  Scenario: メール未確認の回答者に確認導線を表示する
    Given メール未確認の回答者が案件回答画面を表示している
    And 必須項目への入力が完了している
    When 回答者が「回答を送信する」を実行する
    Then 回答完了とは表示されない
    And メールアドレスの確認が必要であることを表示する
    And 確認メールを再送できる導線を表示する

こちらは、利用者が実際に確認できる動きを表しています。

どの画面で、どの操作を行い、利用者に何が表示されるのか。部品の形や配置はFigmaを参照しつつ、利用者にとって意味のある動きを受け入れ条件へ書きます。

画面とサーバーの間のやり取りまで明確に確認する必要がある場合は、その確認項目も別にします。

Scenario: メール未確認の回答送信要求に識別可能なエラーを返す
  Given メール未確認の回答者による有効な回答送信要求である
  When 回答送信APIが要求を受け付ける
  Then APIは要求を拒否する
  And 呼び出し元がメール未確認を識別できるエラーを返す
  And 回答データは作成されない

ここでいうAPIは、画面や別のシステムがサーバーへ処理を依頼するための窓口です。HTTPの403や422といった具体的なエラー番号まで決まっているなら、この項目に書きます。

ただし、画面の表示とデータが変わらないことを、一つの長い項目へ詰め込まないことが重要です。

本には「画面操作をGherkinに書くな」とある

Kamil Niciejaの『Writing Great Specifications: Using Specification by Example and Gherkin』では、ボタンや入力欄のような画面操作ではなく、利用者の意図と業務上の結果を書くことが推奨されています。

画面を変更するたびに受け入れ条件が壊れるのを避け、業務側の人にも読める仕様として保つためです。

同書は、一般的な文字列や日付の入力確認、膨大な入力の組み合わせ、データベースの都合だけで必要になる準備までGherkinへ持ち込むことにも否定的です。

Gherkinですべてのテストを置き換えようとすると、仕様書が読めなくなるからです。

この指摘は、今でも正しいと思っています。

ボタンの位置、余白、色、データベースの表の構造、文字列の全組み合わせまでGherkinに書く必要はありません。

そうした細部はFigmaや、より細かな自動テストに任せるべきです。

AIエージェントで運用した結果、画面の受け入れ条件も必要だった

一方で、この本は2018年に出版されたものです。

私は実際にPM on Railsで受け入れ条件を作り、Cursor AgentなどのAIエージェントへ実装と確認を任せる運用を試してきました。

その結果、画面の受け入れ条件をGherkinからなくしてしまうのも違うと考えるようになりました。

以前のGherkinは、主に人間同士が要求を確認し、実装とともに更新していく仕様書でした。

現在はそれに加えて、AIエージェントが次の作業を行うための指示にもなっています。

• どの画面を実装するのか理解する
• どの操作を実行するのか判断する
• 何を満たせば合格なのか確認する
• どの場面を画面画像として残すのか決める
• 顧客にどの確認用URLを案内するのか記録する

つまり、Gherkinを読むのは人間だけではなくなっています。

また、以前は受け入れ条件を増やすほど、人間が書き、保守し、自動テスト用の処理を整備する負担も増えました。

今はAIがFigmaや既存の要求を読み、受け入れ条件の案を作り、実装後には実際の操作と証拠の収集まで行えます。もちろん人間による確認は必要ですが、一件増やすための手間は以前より下がっています。

だから私は、本の原則を捨てるのではなく、次のように広げるのがよいと考えています。

業務ルールの中に画面操作を混ぜない。ただし、利用者が実際に見る動きは別の受け入れ条件として書き、Figma、実装、確認用URL、動作証拠までつなぐ。

これは、本の内容を否定しているわけではありません。

本の原則を、AIエージェントが実装と確認まで行う現在の開発環境に合わせて広げているという方が近いと思います。

エラー時の動きも、一つの曖昧な項目にまとめない

例えば、利用できない形式のプロフィール画像が選択された場合を考えます。

まず、業務ルールとして、未対応の形式の画像が保存されないことを確認します。

Scenario: 利用できない形式のプロフィール画像を拒否する
  Given 調査者が利用できない形式の画像を選択している
  When 調査者がその画像をプロフィールに使用しようとする
  Then システムは画像を受理しない
  And プロフィール画像は変更されない
  And 利用可能な形式が示される

次に、画面側では、利用者が理由を理解し、自分で修正できることを確認します。

Scenario: 利用できない形式の画像を選んだ項目を画面上で確認できる
  Given 調査者がプロフィール編集画面を表示している
  And 利用できない形式の画像を選択している
  When 調査者がプロフィールを保存する
  Then 利用できない形式であることを示すメッセージが表示される
  And プロフィール画像の入力欄がエラー状態として示される
  And 調査者は別の画像を選択できる

ここで、すべてのファイル形式や文字コードの組み合わせまでGherkinに並べる必要はありません。それは、より細かな自動テストで網羅します。

しかし、利用者がエラーの理由を理解し、問題のある箇所を確認し、自分で修正できるという重要な動きまで、「一般的な入力確認だから」と消してはいけません。

AI時代には、利用者に影響するエラー時の動きをGherkinで明示したうえで、業務ルール、システム間のやり取り、画面のどこで何を保証するのかを分ける方が合理的です。

分けるが、関係は切らない

画面の受け入れ条件と業務ルールを分けても、別々に管理され、関係が分からなくなっては意味がありません。

重要なのは、役割ごとに分けたうえで、元の要求からたどれるようにつなぐことです。

利用者の要望
  ├─ 業務ルールの受け入れ条件
  │    └─ メール未確認なら回答を登録しない
  │
  ├─ システム間のやり取りの受け入れ条件
  │    └─ 呼び出し元が理由を識別できるエラーを返す
  │
  └─ 画面の受け入れ条件
       └─ 回答画面で確認案内と再送導線を表示する

これにより、画面上の表示だけは正しいのに、裏側では回答が保存されてしまっている不具合を防ぎやすくなります。

反対に、サーバー側では正しく拒否しているものの、画面上では何の説明もなく操作が失敗する状態も見つけられます。

画面と業務ルールの両方が合格して、初めて利用者へ提供できる機能になります。

実装にも確認にも、同じ受け入れ条件を使う

受け入れ条件を作り込んだら、AIエージェントへFigmaの設計と受け入れ条件を渡して実装させます。

要求
  ↓
利用者の要望
  ↓
Figmaによる画面設計
  ↓ AIエージェントがFigmaを参照
業務ルール・システム間のやり取り・画面の受け入れ条件
  ↓ 人間が内容を確認
実装作業
  ↓ AIエージェントが実装
コード変更の確認依頼
  ↓ 確認環境へ反映
受け入れ条件に沿った動作確認
  ↓
動作証拠
  ↓
合格／不合格

重要なのは、実装時に参照した受け入れ条件と、確認時に実行する受け入れ条件が同じであることです。

実装用の指示と、完成後の確認条件が別々に書かれていると、途中で解釈がずれます。

同じ受け入れ条件を実装と確認の両方に使えば、何を作るよう依頼し、何を実装し、何を確認して合格としたのかを一本の線で追えるようになります。

必要な動作証拠は、確認する内容ごとに違う

受け入れ条件を役割ごとに分けると、必要な動作証拠も明確になります。

画面の動きを確認する証拠

• 操作前後の画面画像
• 一連の操作を記録した動画
• 顧客が確認できるURL
• ブラウザに出たエラーの記録
• ブラウザとサーバーの通信記録
• 表示された文言や画面の状態

業務ルールを確認する証拠

• 実行前後のデータ
• 状態がどのように変わったか
• 誰が何をしたかを残す記録
• 処理の結果として発生した通知や後続処理
• 作られてはいけないデータが作られていないこと

システム間のやり取りを確認する証拠

• 送ったデータと返ってきたデータ
• 処理結果を表す番号
• エラーの種類を識別する番号や文字列
• アプリケーションの実行記録

例えば、エラーメッセージが表示された画面画像は、画面の動きを確認する証拠にはなります。

しかし、「回答が登録されなかった」という業務ルールの証拠としては、それだけでは不十分です。

どの証拠が必要かは、受け入れ条件に書いた期待結果から逆算できます。

PM on Railsでは、受け入れ条件と動作証拠をつないでいる

私たちは、PM on RailsというAIエージェント型の開発管理システムを、実際の開発で使っています。

PM on Railsでは、要求から利用者の要望、Gherkinで書いた受け入れ条件、実装作業、コード変更、動作確認までをつなげています。

受け入れ条件ごとの確認結果には、次の情報を登録できます。

• どの環境で確認したか
• 顧客が開ける確認用URL
• 合格か不合格か
• 画面画像、動画、実行記録
• 誰が、いつ確認したか
• どのコード変更と、どの反映済み版を確認したか

Cursor AgentなどのAIエージェントからも、コードだけではなく、受け入れ条件に沿った確認結果と動作証拠を登録できるようにしました。

AIエージェントの仕事を、コードを変更して確認依頼を作るところで終わらせず、対象の受け入れ条件を実行し、期待した結果になったことを証拠付きで登録するところまで広げています。

ただし、この仕組みが有効に働くかどうかは、最初に作る受け入れ条件にかかっています。

曖昧な受け入れ条件からは、曖昧な実装と曖昧な動作証拠しか生まれません。

「できました」から「この証拠で確認できます」へ

AIエージェントは、これからさらに多くのコードを書くようになると思います。

そのとき、コード変更の確認依頼の本数や変更行数だけを見ても、開発が進んでいるかは判断できません。

確認すべきなのは、要求された動きが、確認対象の環境とコードの版で本当に成立したかです。

そのためには、まずFigmaから画面設計を正確に読み取ります。

次に、業務ルール、システム間のやり取り、画面の動きを分けて、Gherkinで受け入れ条件を作り込みます。

人間がその内容を確認してから、AIエージェントへ実装を任せます。

最後に、同じ受け入れ条件を確認環境で実行し、画面画像、動画、実行記録、サーバーから返った内容、データの状態を動作証拠として残します。

AIエージェント時代の完了報告は、

実装できました。

ではなく、

この受け入れ条件を、このコード変更が反映された環境で実行しました。こちらの動作証拠で、期待した結果を満たしていることを確認できます。

へ変わっていくと思います。

コード変更の確認依頼は、完了ではなく確認の入口です。

具体的な受け入れ条件と、それに対応する動作証拠がそろって、初めて完了を判断できます。

参考にした書籍

Kamil Nicieja, Writing Great Specifications: Using Specification by Example and Gherkin, Manning Publications, 2018.