「欠品を防ぎたい」だけでは、まだ作れません
利用者が何をしたいのかを書くことは大事です。たとえば、次の一文なら目的は分かります。
店舗担当者は、欠品を防ぐために、発注が必要な商品を早めに知りたい。でも、「早め」とは何日前なのか、在庫と入荷までの日数が同じなら表示するのか、在庫情報を取得できないときはどうするのかまでは決まっていません。このまま開発へ渡すと、作る人ごとに答えが変わります。
そこで使うのが、日本語のGherkinです。難しい話ではありません。前提・もし・ならばの順で、実際の利用場面と正しい結果を書きます。
シナリオ：入荷までに在庫が足りなくなる商品を確認する
前提 商品Aの在庫は3日分である
かつ 商品Aの入荷まで5日かかる
もし 店舗担当者が発注候補を確認する
ならば 商品Aが発注候補に表示される利用者の目的だけで終わらず、どの条件で何が起きれば完成なのかまで決める。ここまで書いて、ようやく実装と動作確認に使える仕様になります。
日本語Gherkinは「前提・もし・ならば」で書きます
項目 | 書くこと |
|---|---|
シナリオ | 何を確認する場面なのか |
前提 | その場面が始まる前に成立している状態 |
もし | 利用者の操作や、外部から起きる出来事 |
ならば | その結果、何が起きれば正しいのか |
かつ | 同じ種類の条件や結果を追加するとき |
基本形は次の通りです。
シナリオ：[確認したい場面]
前提 [始まる前の状態]
もし [起きる操作や出来事]
ならば [期待する結果]書式を埋めることが目的ではありません。顧客、実装する人、確認する人が、同じ場面を見て同じ結論を出せることが目的です。
考えるときは「ならば」から始めると書きやすいです
文章は前提から並べますが、考える順番まで前提からにする必要はありません。最初に「最後に何が起きれば成功なのか」を決めると、必要な条件を逆算しやすくなります。
- ならば：何が起きれば成功か
- もし：何をしたら、その結果になるか
- 前提：その操作の前に、何が成立している必要があるか
たとえば「商品Aが発注候補に表示される」を先に決めます。次に「店舗担当者が発注候補を確認する」を置き、最後に在庫日数と入荷日数を前提として追加します。これなら、条件と結果がつながります。
在庫管理では、通常時だけでなく境目と失敗時も書きます
通常の場面
シナリオ：入荷までに在庫が足りなくなる商品を確認する
前提 商品Aの在庫は3日分である
かつ 商品Aの入荷まで5日かかる
もし 店舗担当者が発注候補を確認する
ならば 商品Aが発注候補に表示される判断が切り替わる境目
在庫日数と入荷日数が同じ場合に表示するかどうかは、会社の業務ルールです。たとえば「同じ日数なら表示する」と決めた場合は、次のように書きます。
シナリオ：在庫日数と入荷日数が同じ商品を確認する
前提 商品Aの在庫は5日分である
かつ 商品Aの入荷まで5日かかる
もし 店舗担当者が発注候補を確認する
ならば 商品Aが発注候補に表示される在庫情報を取得できない場面
シナリオ：最新の在庫情報を取得できない
前提 基幹システムから在庫情報を取得できない
もし 店舗担当者が発注候補を確認する
ならば 最新の在庫情報を取得できないことが表示される
かつ 古い在庫数を最新の値として表示しない通常時だけなら、だいたい何でも動きます。実際に揉めるのは、ちょうど境目の条件や、外部システムが止まったときです。だから最初から書いておきます。
経費精算も、承認後の状態まで決めます
シナリオ：領収書を添付して経費を申請する
前提 田中が12,000円の領収書を登録している
もし 田中が経費申請を提出する
ならば 申請の状態が「承認待ち」になる
かつ 承認者が申請内容を確認できる「申請できる」だけでは、保存された時点で完成なのか、承認者へ届いた時点で完成なのかが分かりません。結果として確認したい状態まで書けば、完成の判断がぶれません。
権限がない人の操作も別の場面として書きます
シナリオ：権限のない利用者は経費を承認できない
前提 田中には経費を承認する権限がない
かつ 承認待ちの申請Aが存在する
もし 田中が申請Aを承認しようとする
ならば 申請Aは承認されない
かつ 申請Aの状態は「承認待ち」のままであるエラーメッセージが出ることだけでなく、データが変更されていないことまで確認します。画面上では失敗に見えても、裏で承認済みになっていたら普通に事故です。
画面のクリック手順書にはしません
次のように書くと、ボタンの位置や画面構成を変えるたびに仕様まで直す必要が出ます。
前提 申請一覧画面を開いている
もし 3行目の詳細ボタンを押す
かつ 右上の承認ボタンを押す
ならば 緑色の通知が表示される本当に決めたいことが「承認権限を持つ人が申請を承認できる」なら、画面上の位置は本質ではありません。
前提 承認待ちの申請Aが存在する
かつ 田中には申請を承認する権限がある
もし 田中が申請Aを承認する
ならば 申請Aの状態が「承認済み」になる
かつ 申請者が承認結果を確認できる何を押したかではなく、利用者が何を行い、業務上どの状態になれば正しいかを書きます。
一つのシナリオでは、一つの中心的な出来事だけを確認します
ログインして、検索して、編集して、申請して、承認結果を見るところまで一つに詰め込むと、失敗した場所が分かりません。途中の仕様が変わったときの影響も大きくなります。
確認したい出来事が変わるなら、シナリオも分けます。たとえば経費精算なら、「申請する」「承認する」「差し戻す」「取り下げる」は別の場面です。
一つのシナリオを短く保つほど、実装、確認、変更がしやすくなります。
最低でも、三種類の場面を確認します
- 通常の場面：よくある使い方で期待通りになるか
- うまく処理できない場面：入力不足、権限不足、外部連携の失敗などで安全に止まるか
- 判断が切り替わる境目：0件、1件、上限ちょうど、期限ちょうどなどで結果がぶれないか
通常の場面を一本書いて終わると、決めていないことが実装中に出てきます。書き終えたら、「条件を一つ変えたら答えはどうなる？」と見直します。
利用者の目的は見出しにして、合意する内容は日本語Gherkinで書きます
利用者の目的を書く方法を捨てる必要はありません。大きな目的を共有するには役立ちます。
店舗担当者は、欠品を防ぐために、発注が必要な商品を早めに知りたい。ただし、この一文だけを完成した仕様として扱わないことが重要です。この目的の下に、通常時、失敗時、境目となる場面を日本語Gherkinで並べます。
つまり、利用者の目的は「何のために作るか」を示す見出し、日本語Gherkinは「どこまで動けば正しいか」を合意する本文です。この分け方の方が、実案件では使いやすいです。
書いた後は、抜けと矛盾を確認します
書式が整っていても、内容が正しいとは限りません。Beekleでは生成AIも使い、通常の場面しかない、似た場面で結果が食い違う、「適切に」「必要に応じて」のように判断基準がない、元の要求と結果がずれている、といった点を確認しています。
ただし、決まっていない業務ルールを生成AIに作らせません。在庫日数と入荷日数が同じ場合に発注候補へ入れるかどうかは、顧客や事業側が決めることです。決まっていないことは質問として戻し、回答を反映してから実装へ進みます。
日本語Gherkinは、書くより更新し続ける方が大変です
日本語Gherkinを数本書くだけなら、文書や表計算でも管理できます。ただ、実際の開発では利用場面が増え、要求も途中で変わります。すると、元の要求、利用者の目的、具体的な場面、実装、動作確認のどこを直すべきか、毎回探さなければなりません。
たとえば「在庫日数と入荷日数が同じなら発注候補に表示する」を、「同じなら表示しない」へ変えたとします。文章を一行直すだけでは終わりません。関係する利用場面、判定処理、動作確認も同じ内容へ直す必要があります。一か所でも古いまま残れば、仕様書には合っているのに確認で落ちる、あるいは確認には通るのに顧客の要求と違う、ということが起きます。
最初に書く作業より、変更後もすべてを同じ状態に保つ作業の方が重い。ここが普通にしんどい。 Beekleでも実案件でこの管理を続ける中で、人が関係を追い続けるやり方には限界があると感じました。
そのためBeekleでは、要求から利用者の目的、日本語Gherkin、実装、動作確認までをつないで管理するPM on Railsを作りました。
顧客の言葉から具体的な利用場面を整理し、決まっていない点は質問として戻します。内容が確定したら実装と動作確認へつなぎ、要求が変わったときは、見直す必要がある場所をたどれるようにします。
つまり、日本語Gherkinを自動で書くことだけが目的ではありません。書いた仕様が、実装中も変更後も、現在の要求とずれないように保つための仕組みです。
実装へ進む前に確認する項目
- 何を確認する場面かが、シナリオ名だけで分かる
- 前提に、結果へ関係する状態だけが書かれている
- 「もし」に中心的な出来事が一つだけ書かれている
- 「ならば」が、見て合否を判断できる内容になっている
- 通常時、失敗時、判断が切り替わる境目を確認している
- 画面の位置ではなく、利用者の行動と業務上の結果を書いている
- 決まっていない業務ルールを勝手に補っていない
- 変更時に、関係する実装と確認項目をたどれる
結局、日本語Gherkinで大事なのは文法ではありません。具体的な場面を使って、何が起きれば正しいのかを関係者で共有することです。