Gherkin入門｜「前提・もし・ならば」をどう書けばいいか、具体例で解説

「パスワードを再設定できる」だけだと、まだ完成条件が分かりません

「登録済みユーザーがパスワードを再設定できる」というUser Storyがあったとします。User Storyは、利用者が何をしたいかを書いたものです。ここまでは意味が分かります。

でも、未登録のメールアドレスならどうするのか、再設定用リンクは何分使えるのか、一度使ったリンクをもう一回使えたらどうするのかは書いてありません。

開発する人は「メールが届けば完成」と考えるかもしれない。確認する人は「期限切れも必要」と考えるかもしれない。事業側は「未登録の人にアカウントの存在を漏らしたくない」と考えるかもしれない。全部それっぽい。困る。

Gherkinは、このズレを具体的な利用場面にして、「前提・もし・ならば」の形で残すための書き方です。この記事では、Gherkinを実際にどう書けばいいかだけに絞って説明します。

まず、完成したGherkinを1本見ます

先に完成形を見ると、「前提・もし・ならば」の役割が分かりやすくなります。

シナリオ：登録済みユーザーが再設定メールを要求できる
  前提 登録済みユーザー「田中」のメールアドレスが存在する
  もし 田中がパスワード再設定を要求する
  ならば 田中のメールアドレス宛に再設定メールが送信される
  かつ 再設定用リンクは1時間後に無効になる

やっていることは単純です。「前提」で始まる前の状態、「もし」で起きる出来事、「ならば」でその結果どうなれば正しいかを書いています。

では、それぞれ何を書けばいいのか。順番に見ます。

「前提」には、その場面が始まる前の状態を書きます

「前提」は、結果を確かめるために必要な状態です。誰がどんな状態にいるのか、どんな情報が存在するのかを書きます。

前提 登録済みユーザー「田中」のメールアドレスが存在する
前提 商品「A」の在庫が1件ある
前提 承認待ちの申請「出張申請A」が存在する

「ユーザーがいる」「データがある」だけだと、読む人によって想像する状況が変わります。実際の利用場面が頭に浮かぶくらい具体的にした方が、認識を合わせやすくなります。

ただし、前提を全部書く必要はありません。その結果に関係するものだけで十分です。前提が10個も20個も並ぶなら、たぶん1本のシナリオに詰め込みすぎています。

「もし」には、結果を起こす中心の出来事を1つ書きます

「もし」は、その場面で利用者や外部から起きる中心的な出来事です。

もし 田中がパスワード再設定を要求する

ここに「ログインして、検索して、編集して、承認して、通知を見る」まで全部入れると、何を確認したいシナリオなのか分からなくなります。

それ、もう一機能じゃないな。 独立した出来事が複数あるなら、シナリオを分けた方が読みやすく、変更もしやすくなります。

原則として、1つのシナリオでは1つの中心的な出来事を見る。このくらいに考えておくと扱いやすいです。

「ならば」には「何が起きれば正しいか」を書きます

「ならば」は、このシナリオで一番重要な部分です。出来事のあとに、利用者や業務から見て何が変われば成功なのかを書きます。

ならば 再設定メールが送信される
ならば 注文が確定する
ならば 申請の状態が「承認済み」になる

「正常に処理される」「正しく保存される」では、何を確認すれば合格なのか分かりません。結果は、見て判断できる状態まで具体化します。

迷ったときは「ならば」から考えるのも有効です。「この機能が成功したら、最後に何が起きてほしい？」を先に決める。そこから「何が起きたらその結果になるか」を「もし」へ戻し、「その前に何が成立している必要があるか」を「前提」へ戻します。

文章は「前提」から並びますが、考える順番まで「前提」からである必要はありません。

Gherkinを書く前に、現実の具体例を出すと楽です

いきなり「前提・もし・ならば」を埋め始めると、書式を埋める作業になりやすいです。その前に「実際にはどんな場合があるか」を普通の日本語で出します。

この段階なら、事業側や顧客も会話に入りやすくなります。「未登録でも同じメッセージにする？」「期限は1時間？」と具体的な質問が出てくるからです。

『Writing Great Specifications』でも、抽象的な文章だけでなく、現実にありそうな具体例を使って認識を合わせる考え方が重視されています。まず例を出して、決まったものをGherkinへする。この順番の方が自然です。

画面のクリック手順ではなく、利用者の意図と結果を書きます

Gherkinでよくある失敗は、画面操作の手順書になることです。

前提 申請一覧画面を開いている
もし 3行目の詳細ボタンをクリックする
かつ 右上のメニューを開く
かつ 承認ボタンをクリックする
ならば 緑色の通知が表示される

この書き方だと、ボタンの場所を変えただけで仕様まで直す必要が出ます。でも、本当に決めたいことが「管理者が申請を承認できる」なら、画面の作りは本質ではありません。

前提 承認待ちの申請「出張申請A」が存在する
かつ 田中が申請を承認できる管理者である
もし 田中が「出張申請A」を承認する
ならば 「出張申請A」の状態が「承認済み」になる
かつ 申請者が承認されたことを確認できる

何を押すかではなく、何を達成したいのかを書く。画面そのものが契約条件でない限り、この方が実装方法が変わっても仕様の意味が残ります。

正常系を書いたら、異常系と境界値へ広げます

典型的なケースを1本書いただけでは、実際の仕様として足りないことがあります。次は「条件が変わったらどうなる？」を考えます。

たとえばパスワード再設定なら、正常系は「登録済みの利用者が再設定できる」です。そこから、未登録だったら、リンクが期限切れだったら、同じリンクを2回使ったら、短時間に何度も要求したら、と広げていきます。

• 正常系：典型的な使い方で期待どおりになるか
• 異常系：入力不正、権限不足、外部サービスの失敗などで安全に止まるか
• 境界値：0件、1件、上限、期限ちょうど、同時操作などで判断が変わらないか

「書けた」で終わらず、「まだ何を決めてない？」で見る。 ここで抜けが見つかるほど、実装後に揉める範囲が減ります。

書いたら、生成AIに一度壊してもらいます

書式がきれいでも、仕様が正しいとは限りません。正常系しかない、別のシナリオと結果が矛盾している、「適切に」「必要に応じて」のように意味が決まっていない、元の要求と食い違っている。こうした抜けは、書いた本人ほど気づきにくいです。

そこでBeekleでは、Gherkinを書いたあとに生成AIでレビューを入れています。少なくとも、正常系・異常系・境界値の抜け、シナリオ同士の矛盾、曖昧な表現、重複、元の要求との食い違いを探させます。

仕様を書いたAIに、今度は敵側へ回ってもらう。 文章を褒めてもらう工程ではなく、壊れる場所を探す工程です。

ただし、AIにも判断できないことを勝手に決めさせません。たとえば「再設定用リンクの期限は30分か1時間か」が決まっていないなら、それは顧客や事業側への質問です。回答を反映し、必要ならもう一度レビューしてから実装へ渡します。

レビューの目的は文章を綺麗にすることではなく、実装する前に「人によって答えが違う場所」を見つけることです。

仕様が変わったら、Gherkinも更新します

Gherkinは書いた時点の記録ではなく、今の完成条件を示すものです。仕様が変わったのにGherkinだけ古いままだと、テストに通っても今の要求を満たしているとは限りません。

たとえば再設定用リンクの有効期限が1時間から30分へ変わったなら、その条件を使うGherkinも直します。そして新しい条件で確認します。

結局、Gherkinで大事なのは文法を覚えることではありません。具体的な場面を使って「どこまで動けば正しいか」を関係者で共有し、その意味を実際の仕様と一緒に更新し続けることです。

関連記事

• 要件定義書テンプレート
• 要件定義の完全ガイド
• User Storyの書き方

参考：Kamil Nicieja, Writing Great Specifications（Manning）