まず、完成した要件定義を見てください
要件定義書のテンプレートを探すと、目的、機能要件、非機能要件、制約、みたいな項目だけが並んでいることがあります。項目名は分かる。でも、で、何を書けばいいの？ となりやすい。
なので、先に完成形を置きます。例は「パスワードを忘れた利用者が、自分で再設定できるようにする」です。
# パスワード再設定
## 要求
パスワード忘れの問い合わせを減らしたい。
### 背景
利用者がパスワードを忘れるたびに、
サポート担当者が本人確認と手動リセットを行っている。
### 期待する価値
利用者自身でログインを回復できるようにし、
サポート対応時間を減らす。
### 根拠
問い合わせ記録、サポート担当者へのヒアリング。
## User Story
登録済みの利用者は、ログインできない場合に、
サポートへ問い合わせず自分でパスワードを再設定できる。
- アクター：登録済みユーザー
- ビジネス価値：自力でログインを回復でき、手動対応を減らせる
## 具体例
- 登録済みのメールアドレスなら再設定メールが届く
- 未登録でも、アカウントの存在有無は漏らさない
- 期限切れのリンクでは再設定できない
- 一度使ったリンクは再利用できない
## Gherkin
シナリオ：登録済みユーザーが再設定メールを要求できる
前提 登録済みユーザー「田中」のメールアドレスが存在する
もし 田中がパスワード再設定を要求する
ならば 田中のメールアドレス宛に再設定メールが送信される
シナリオ：未登録でもアカウントの存在有無を漏らさない
前提 入力されたメールアドレスが登録されていない
もし パスワード再設定が要求される
ならば 登録済みの場合と同じ受付完了メッセージが表示される
かつ 再設定メールは送信されない
シナリオ：期限切れのリンクでは再設定できない
前提 パスワード再設定用リンクの有効期限が切れている
もし 利用者がそのリンクを使う
ならば パスワードは変更されない
かつ 新しい再設定を要求する案内が表示される
## 非機能要件・制約
- 権限のない利用者へ他人の情報を返さない
- 通常条件では主要画面を2秒以内に表示する
- メール送信に失敗しても内部情報を利用者へ見せない
## 未確定事項
- 再設定用リンクの有効期限を何分にするか
- 短時間に何回まで再設定要求を許可するか
## 実装・検証
- 上記のGherkinを満たすように実装する
- 正常系、異常系、境界値を確認する
- 仕様が変わった場合は、影響するGherkinとテストを見直す長さは機能によって変わりますが、考える順番はだいたい同じです。ここから、この文章を上から分解します。
要求には「何を作るか」ではなく「なぜ必要か」を書きます
最初に残すのは解決策ではなく、今どんな問題があり、何を改善したいのかです。今回なら「パスワード再設定画面が欲しい」ではなく、「パスワード忘れの問い合わせを減らしたい」が要求になります。
ここで解決策まで決めてしまうと、後からもっと簡単な方法が見つかっても戻りにくくなります。まず問題を固定して、解き方はその後に考える。要件定義の入口はここです。
あわせて、なぜそう言えるのかも残します。問い合わせ記録なのか、現場への聞き取りなのか、顧客からの要望なのか。根拠があると、後から「そもそも何のために作ってたんだっけ」が起きにくくなります。
次に「誰が何をできるようになるか」へ分けます
要求のままだと、まだ実装する単位としては大きすぎます。そこで、利用者が何を達成したいかへ分けます。これがUser Storyです。
登録済みの利用者は、ログインできない場合に、
サポートへ問い合わせず自分でパスワードを再設定できる。この形にすると、要求が利用者の行動へ変わります。そして「登録済みなら分かった。未登録は？」という次の問いが自然に出てきます。
そう、ここから細かい仕様が出てくる。 User Storyは完成した仕様ではなく、具体的な話を始めるための単位です。
そのUser Storyで起こりそうな具体例を先に出します
いきなり細かな文章を書くより、「実際にはどんな場合があるか」を並べた方が抜けを見つけやすくなります。
- 登録済みなら再設定メールが届く
- 未登録ならどうするか
- 期限が切れたらどうするか
- 同じリンクを2回使ったらどうするか
- 短時間に何度も要求されたらどうするか
ここで大事なのは、答えを全部知っている必要はないことです。「リンクは何分使えるんだっけ？」と分からなければ、それが未確定事項です。
要件定義で怖いのは、分からないことがあることではありません。決まっていないのに、決まっている感じで実装へ行くことです。
決まった具体例をGherkinで「完成条件」にします
具体例のうち、実装後に「これが動けば正しい」と確認したいものをGherkinで残します。Gherkinは、「前提・もし・ならば」の3つで具体的な振る舞いを書く方法です。
シナリオ：登録済みユーザーが再設定メールを要求できる
前提 登録済みユーザー「田中」のメールアドレスが存在する
もし 田中がパスワード再設定を要求する
ならば 田中のメールアドレス宛に再設定メールが送信されるここではGherkinの書き方自体には深入りしません。重要なのは、User Storyの「再設定できる」を、実際に確認できる条件まで具体化することです。
「前提」「もし」「ならば」をどう書くか、正常系・異常系・境界値をどう広げるかは、別のGherkin入門で詳しく説明しています。
機能ごとの例だけでは足りないので、共通の条件を分けて書きます
Gherkinは具体的な利用場面を書くのに向いていますが、システム全体へ共通する条件まで毎回書くと重複します。そこで、性能、権限、外部システムとの関係などは、非機能要件・制約として分けます。
性能：通常条件では主要画面を2秒以内に表示する
権限：権限のない利用者へ他人の情報を返さない
外部制約：メール送信サービスが失敗しても内部情報を表示しないこの欄の役割は「機能として何ができるか」ではなく、どの機能でも守らないといけない条件を見えるようにすることです。
同じ条件を複数の場所へ何度も書くと、片方だけ直して古いものが残ります。普通に面倒なので、共通のものは共通で持った方が扱いやすいです。
Gherkinを書いたら、実装前に一度レビューします
Gherkinを書いた時点では、まだ完成とは考えません。書いた本人には見えない抜けや矛盾が普通に残るからです。
Beekleでは、生成AIにも正常系・異常系・境界値の抜け、シナリオ同士の矛盾、曖昧な表現、重複、元の要求との食い違いを探させています。
仕様を書いたAIに、今度は敵側へ回ってもらう。 褒めてもらう工程ではなく、壊れる場所を探す工程です。
ただし、AIが「有効期限は1時間にしましょう」と勝手に決めるのは違います。判断できないものは未確定事項として人へ戻し、顧客や事業側の回答を反映してから、必要ならもう一度レビューします。
レビューを通して「何を作れば正しいか」が明確になったら、その最新版を基準に実装し、同じ条件でテストします。
この方法は、マークダウンや既存の管理ツールでも使えます
ここまでの形は、専用の道具がなくても使えます。1機能ずつマークダウンで書いたり、既存のプロジェクト管理ツールで階層を作ったりして、要求、User Story、具体例、Gherkin、共通条件、未確定事項をつなげても構いません。
ただ、機能が数十、数百と増えると、どの要求からどのUser Storyが生まれ、どのGherkinが完成条件で、仕様変更がどこへ影響するのかを人が追うのが重くなります。生成AIに実装させる場合も、文章の束だけでは関係を安定して読み取れないことがあります。
そこでBeekleでは、この運用自体をPM on Railsで仕組み化しています。お客さんの要求を取り込んでUser StoryとGherkinへ整理し、AIレビューで抜けや矛盾を確認し、未確定事項は質問へ戻します。確定した仕様は、Cursor Cloud Agentsのような生成AIの開発エージェントへ渡して実装まで一気につなげています。
宣伝だからというより、実際に自分たちで使っていて、これは本当に便利なプロダクトだと思っています。従来の「作業が終わったかを見る道具」ではなく、要求・仕様・レビュー・実装・テスト・生成AIまでをつなぐ、次世代の開発管理OSに近い感覚です。
もちろん、やり方自体はマークダウンや既存の管理ツールでも再現できます。まずはこの記事のテンプレートを1機能だけ使ってみてください。そのうえで、要求から仕様作成、レビュー、変更影響の追跡、生成AIによる実装まで自動化したくなったら、PM on Railsも試してみてください。
導入やAI開発について相談したい場合は、Beekleまでお問い合わせください。
空欄のテンプレートを、自社案件で使える粒度にする 目的、作る範囲、必要な機能、運用条件など、埋めづらい項目を発注に使える形へ整理します。関連記事
参考：Kamil Nicieja, Writing Great Specifications（Manning）／Karl Wiegers, Joy Beatty, Software Requirements, Third Edition（Microsoft Press）