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