AIエージェントに「証拠は？」と詰めよう
AIエージェントがプルリクエストを作っただけでは、要求された機能が本当に動くかは分かりません。Figma MCPで画面設計を参照し、画面上の利用場面と業務上のルールを分けてGherkinを設計して実装後にエビデンス付きで検証するAI開発フローを解説します。
AIエージェントに開発を任せると、コードを書いてプルリクエストを作るところまでは、かなり速くなりました。
既存コードを読み、必要な変更を加え、自動テストを実行し、プルリクエストを作る。以前なら人間が数時間かけていた作業を、短時間で終わらせられることもあります。
ただ、実際の開発では、プルリクエストができたところで仕事が終わるわけではありません。
コードが変更されたことと、要求された機能が本当に利用できることは同じではない。
自動テストが通っていても、検証環境で操作すると動かないことがあります。画面は正しく見えていても、裏側ではデータが保存されていないこともあります。
AIエージェント時代の完了条件は、「プルリクエストができた」ではなく、要求された検証項目を実行し、結果を証拠付きで確認できることへ変える必要があるんだと思います。
ただし、AIエージェントにスクリーンショットやログを返させれば、それだけでよいわけでもありません。証拠を集める前に、何をもって合格とするのかをGherkinで作り込む必要があります。
検証の証拠は、Gherkinの品質で決まる
曖昧な検証項目に対してスクリーンショットやログを大量に残しても、「曖昧な要求を満たしたように見える証拠」が増えるだけです。
たとえば、検証項目に「メール未確認ユーザーは認証必須機能を利用できない」としか書かれていなければ、次のどれを実装すべきか定まりません。
- ボタンを非表示にする
- ボタンを無効にする
- 操作後にエラーを表示する
- サーバーが403を返す
- データを保存しない
- メール確認画面へ移動する
どれも「利用できない」と表現できます。この状態で証拠を提出させても、AIエージェントは都合のよい画面を一枚撮って「合格」と判定できてしまいます。
証拠は要求を具体化するものではありません。すでに具体化された要求が成立したことを証明するものです。
Figma MCPで画面設計を正確に参照する
画面を実装する場合、AIエージェントにはFigma MCPを接続し、対象の画面やコンポーネントを直接参照させます。
スクリーンショットだけを渡すよりも、Figma MCPを使うことで、対象フレーム、コンポーネント構造、表示文言、レイアウト、画面状態、プロトタイプ上の遷移などを正確に取得できます。
ただし、Figmaから読み取れるのは、主に画面の構造とインタラクションです。Figma上に送信ボタンが置かれていても、誰が押せるのか、どの状態なら押せるのか、押した結果どのデータが変わるのか、二重送信をどう防ぐのかまでは、必ずしも確定しません。
つまり、Figmaは非常に重要ですが、Figmaだけでは業務仕様にならないんですよね。
そこで、Figma MCPで画面設計を参照したうえで、PM on Rails上にGherkinを作り込みます。
画面上の利用場面と業務上のルールを分ける
Gherkinを作るうえで重要なのが、画面上の検証項目と、業務上のルールの検証項目を分けることです。
一つの検証項目に画面操作、表示文言、権限判定、データ更新、通知処理まで全部書いてしまうと、仕様が読みにくくなります。それだけでなく、画面を少し変更しただけで、ビジネスルールの検証項目まで修正しなければならなくなります。
たとえば「メール未確認の回答者は回答を送信できない」というルールがあるとします。このルール自体は、画面上のボタンが右側にあるか、下部にあるか、モーダルを使うか、別画面へ遷移するかとは関係ありません。
業務上のルールの検証項目
Feature: 回答送信の可否
Rule: メール未確認の回答者は回答を確定できない
Scenario: メール未確認の回答者による回答送信を拒否する
Given 回答者としてログイン済みである
And 回答者の email_verified_at が未設定である
And 回答可能な案件が存在する
When 回答者が案件への回答を送信する
Then 回答は登録されない
And 案件の回答状態は変更されない
And メール確認が必要であることを示す結果を返す</code></pre><p>ここでは、画面上でどのボタンを押すかは書いていません。定義しているのは、システムとして守るべきルールです。</p><ul><li>メール未確認なら回答を登録しない</li><li>案件の状態も変更しない</li><li>メール確認が必要であることを呼び出し元へ返す</li></ul><p>画面が変わっても、画面以外から操作しても、このルールは変わりません。</p><h3 id="h5d50fedb83">画面上の利用場面</h3><pre><code class="language-gherkin">Feature: 回答画面でのメール確認案内
Scenario: メール未確認の回答者に確認導線を表示する
Given メール未確認の回答者としてログイン済みである
And 回答者が案件回答画面を表示している
And 必須項目への入力が完了している
When 回答者が「回答を送信する」を実行する
Then 回答は完了状態として表示されない
And メールアドレスの確認が必要であることを画面上に表示する
And 確認メールを再送できる導線を表示する
こちらは、利用者から観測できる振る舞いを表しています。どの画面で、どの操作を行い、何が表示されるのか。見た目やコンポーネントの詳細はFigmaを参照しつつ、利用者が達成できること、確認できることをGherkinへ記述します。
分けるが、切り離さない
画面上の利用場面と業務上のルールを分けるといっても、別々に管理して関係が分からなくなっては意味がありません。
重要なのは、分離したうえで追跡可能につなぐことです。
ユーザーストーリー
├─ 業務上のルールの検証項目
│ └─ メール未確認の場合、回答を登録しない
│
└─ 画面上の利用場面
└─ 回答画面でメール確認の案内と再送導線を表示する
画面上の利用場面は、対応する業務上のルールの検証項目を参照します。これにより、画面上の表示だけが正しく、裏側では回答が保存されてしまっているような不具合を防ぎやすくなります。
反対に、バックエンドでは正しく拒否しているものの、画面上では何の説明もなく操作が失敗する、といった状態も検出できます。
画面側と業務上のルール側の両方が合格して、初めて利用者に提供できる機能になります。
画面の細部はFigma、振る舞いはGherkin
画面上の利用場面を詳しく書くことと、Figma上の見た目をすべてGherkinへ転記することは違います。
たとえば、次のような記述は避けた方がよいと思います。
Then 画面右上から24pxの位置に赤色のモーダルを表示する余白や色、フォント、コンポーネントの形状までGherkinに書くと、デザイン変更のたびに検証項目を修正することになります。
Gherkinには、利用者から見た意味を書きます。
Then メール確認が必要であることを画面上に表示する
And 確認メールを再送できる導線を表示するその表示をモーダルにするのか、インラインメッセージにするのか。どのコンポーネントを使い、どの位置に表示するのか。それはFigmaを参照します。
Figmaは、どのように見せるかを決める正本。
Gherkinは、何が起きるべきかの正本。
コードは、それを実現する実装。
検証記録は、実際に成立したことの証拠。
AIエージェントへ渡す前に、人間がGherkinを確認する
FigmaからGherkinを生成する作業にもAIを使えます。AIにFigma MCPと既存の要求を読ませれば、画面ごとの正常系、異常系、権限差分、状態遷移の候補をかなりの速度で洗い出せます。
ただし、生成されたGherkinをそのまま実装へ渡すのは危険です。Gherkinは単なる実装指示ではなく、何をもって開発完了とするかを決める契約だからです。
実装前に人間が、少なくとも次の点を確認します。
- アクターは正しいか
- 前提状態が不足していないか
- 操作が曖昧ではないか
- 結果が観測可能になっているか
- 画面とビジネスルールが混ざっていないか
- データが変更される場合、変更後の状態が書かれているか
- 失敗時に変更されないものも定義されているか
- 権限、重複操作、期限切れなどの例外が漏れていないか
ここを作り込まずにAIエージェントへ実装を任せると、実装速度は上がっても、確認と手戻りが増えてしまいます。
AI開発では、コードを書く前のGherkin設計が、以前より重要になるんですよね。
実装後は、同じGherkinで検証する
Gherkinを作り込んだら、AIエージェントへFigmaと検証項目を渡して実装させます。
要求
↓
ユーザーストーリー
↓
Figmaによる画面設計
↓ Figma MCPで参照
業務上のルールの検証項目 / 画面上の利用場面
↓ 人間によるGherkinレビュー
実装作業
↓ AIエージェントが実装
プルリクエスト
↓ プレビュー環境 / 検証環境へデプロイ
検証項目を実行
↓
証拠
↓
合格 / 不合格重要なのは、実装時に参照した検証項目と、検証時に実行する検証項目が同じであることです。
実装用の指示と受け入れテストが別々に書かれていると、途中で解釈がずれます。Gherkinを実装と検証の両方に使うことで、何を作るように依頼したのか、何が作られたのか、何を確認して合格としたのかを一つの線で追えるようになります。
検証記録も、画面側と業務上のルール側で分ける
検証項目を分けると、必要な証拠も明確になります。
画面上の利用場面の検証記録
- 操作前後のスクリーンショット
- 一連の操作を記録した動画
- 検証用URL
- ブラウザの開発者画面
- 通信ログ
- 表示された文言や画面状態
業務上のルールの検証記録
- サーバーとの送受信内容
- 応答コード
- 実行前後のデータ
- 状態遷移
- アプリケーションログ
- 発行された処理通知
- 非同期処理の実行結果
- データが作成されなかったことの確認
エラーメッセージが表示されたスクリーンショットは、画面上の利用場面の検証記録にはなります。しかし、「回答が登録されなかった」というビジネスルールの証拠には、それだけでは不十分です。
どの証拠が必要かは、Gherkinの「Then（結果）」から逆算できます。
PM on Railsでは検証項目と証拠をすでにつなげている
私たちは、PM on RailsというAIエージェント型の開発管理システムを、実際の開発で使っています。
PM on Railsでは、要求からユーザーストーリー、Gherkinの検証項目、Task、実装、テストまでをつなげています。
さらに、検証項目の実行結果には次の情報を登録できます。
- 検証環境
- 検証用URL
- 合格 / 不合格
- スクリーンショット、動画、ログ
- 実行者
- 実行日時
- 対象のコミットや公開版
CursorなどのAIエージェントからも、コードだけではなく、検証項目の実行結果と証拠を登録できるようにしました。
そのため、AIエージェントの仕事を「コードを変更してプルリクエストを作る」ところで終わらせず、対象の検証項目を実行し、期待された結果になったことを証拠付きで登録するところまで広げられます。
ただし、この仕組みが有効に働くかどうかは、最初に作るGherkinにかかっています。曖昧な検証項目からは、曖昧な実装と曖昧な証拠しか生まれません。
「できました」から「この証拠で確認できます」へ
AIエージェントは、これからさらに多くのコードを書くようになると思います。そのとき、プルリクエストの本数や変更行数だけを見ても、開発が進んでいるかは判断できません。
確認すべきなのは、要求された振る舞いが、対象環境と対象バージョンで成立したかです。
そのためには、まずFigma MCPで画面設計を正確に参照する。次に、画面上の利用場面と業務上のルールを分けてGherkinを作り込む。人間がそのGherkinを確認してから、AIエージェントへ実装を任せる。
最後に、同じ検証項目を対象環境で実行し、スクリーンショット、動画、ログ、サーバーからの応答、データの状態を証拠として残す。
AIエージェント時代の完了報告は、
「実装できました」
ではなく、
「このGherkinを、このコミットが反映された環境で実行し、この証拠によって合格を確認できます」
へ変わっていくんだと思います。
プルリクエストは実装の入口です。
作り込まれたGherkinと、それに対応する証拠が揃って、初めて完了を判断できます。