仕様(spec)駆動開発、仕様はどう書く？

1. SP 仕様(spec)駆動開発、仕様はどう書く？ ユーザーストーリー・受け入れ基準・GWT・EARSの整理
2. INTRODUCTION 今日の話 「specに何をどう書くか」には、実は定番の型がある spec = 仕様。spec駆動開発 = 仕様を先に書き、それを起点にAIと実装を進める開発スタイル Kiro / GitHub Spec Kit / Claude Codeのspec先行ワークフローなどで広まり、「仕様を先に書く」機会が増えた でも「仕様って具体的に何をどう書くの？」は意外と語られない 今日は仕様の構成要素と代表的な記法（GWT / EARSなど）を整理する 仕様(spec)駆動開発、仕様はどう書く？ 2 / 18
3. OVERVIEW specの全体像: 2層構造 仕様は「ユーザーストーリー（意図）+ 受け入れ基準（検証条件）」の2層で構成される ユーザーストーリー: 誰が・何を・なぜ = 意図・価値の記述 受け入れ基準: 満たされたと言える条件 = 検証可能な振る舞いの定義。GWTやEARSはこちらを書くためのフォーマット AI文脈のspecは requirements / design / tasks のMarkdown群を指すことが多い requirements（要件）: 何を作るか。上の2層（ストーリー + 受け入れ基準）はここに書く design（設計）: その機能をどう実現するか（機能単位の設計） tasks（タスク分解）: 実装を進める手順への分解 requirementsの例: 要件1: 再注文機能 ユーザーストーリー: 購入者として、注文履歴から再注文したい。なぜなら同じ商品を探す手間を省きたいから。 受け入れ基準: 1. When ユーザーが「再注文」を押した場合、システムは当該注文の全商品をカートに追加しなければならない 2. If 商品が販売終了してい る場合、… ※ 全体の方式設計（アーキテクチャ・技術選定）は機能ごとのspecとは別に、人とAIで決めてプロジェクト共通のドキュメントにまとめる ※ 3ファイルに分けるかはツール・規模次第。Claude Codeなどでは1つのspecにまとめ、機能単位の設計・タスク分解はAIに任せる運用も 仕様(spec)駆動開発、仕様はどう書く？ 3 / 18
4. USER STORY ユーザーストーリーの書き方: Connextra と ジョブストーリー 定番は「役割」起点のConnextra形式。「状況」を起点にしたいならジョブストーリー 定番 Connextra形式 代替 ジョブストーリー 「<役割> として、<実現したいこと> をしたい。なぜなら <価値> だから」 「<状況> のとき、<動機> したい。そうすれば <期待する結果> で きる」 例: ECサイトの購入者として、注文履歴から再注文したい。なぜな ら毎回同じ商品を探す手間を省きたいから 例: 会議の開始5分前に気づいたとき、ワンタップで参加したい。そ うすれば遅刻せずに済む アジャイルで20年以上使われてきた定番をそのまま利用。特に「なぜなら」 が重要 → 実装時に目的達成を判断でき、より良い代替案に気づける JTBD（Jobs to be Done）理論由来。役割ではなく状況（コンテキスト）を 起点にする。同じユーザーでも状況でニーズが変わるケースに強い 仕様(spec)駆動開発、仕様はどう書く？ 4 / 18
5. USER STORY ストーリーを支える2つの原則: 3C / INVEST ストーリーは意図を示す短い記述。詳細は受け入れ基準として書き残す 3C: Card / Conversation / Confirmation 元はアジャイルの原則。短く書く → 詳細は会話で詰める → 受け入れ基準で完成を確認 spec駆動開発では会話の相手にAIも加わり、決まったことは受け入れ基準に書き残すのが前提（詳しくは後半で） INVEST: 良いストーリーの6条件 Independent / Negotiable / Valuable / Estimable / Small / Testable Testable = 受け入れ基準が書けること → 2層構造につながる ※ 3C・INVESTの各項目の詳細は末尾の参考資料ページ 仕様(spec)駆動開発、仕様はどう書く？ 5 / 18
6. ACCEPTANCE CRITERIA 1 受け入れ基準の書き方(1) GWT（Given-When-Then） GWTは「満たされたと言える条件」を具体的なシナリオ（例）で書く BDD（振る舞い駆動開発）由来のフォーマット Given カートに商品Aが入っている When ログアウトして再ログインする Then カートに商品Aが残っている 前提（Given）が明示されるので「どういう状況の話か」が曖昧にならない Cucumber / Gherkin などのツールでそのまま自動テストにできるのが強み（実行可能な仕様） 仕様(spec)駆動開発、仕様はどう書く？ 6 / 18
7. ACCEPTANCE CRITERIA 2 受け入れ基準の書き方(2) EARS記法 EARSは決まったテンプレートに当てはめて、要件を曖昧さなく1文で書く 航空機エンジンなどの高信頼性分野の要求仕様のために作られた記法 基本形: 「<トリガー/条件> の場合、<システム名> は <応答> しなければならない」（When <trigger>, the <system> shall <response>） 型 キーワード 用途 Ubiquitous（遍在型） なし 常に成り立つ要件 Event-driven（イベント駆動型） When 何かが起きたときの応答 State-driven（状態駆動型） While ある状態にある間の振る舞い Optional feature（オプション機能型） Where 特定の機能・構成がある場合 Unwanted behavior（望ましくない挙動型） If ... then 異常系・エラー処理 ※ 複合型も可能（例: While オフラインモード中に、When 保存を押した場合〜）。各型の例文は末尾の参考資料ページ 仕様(spec)駆動開発、仕様はどう書く？ 7 / 18
8. CO M PA R I S O N GWT vs EARS: 「例」を書くか「ルール」を書くか GWTは具体例（テストケースに近い）、EARSはルール（仕様書の1文に近い） ルール EARSで書くと When ユーザーがログインに3回失敗した場合、システムはアカウ ントを15分間ロックしなければならない ルールそのものを1文で表現 例 GWTで書くと ・2回失敗 → 成功: ロックされない ・3回失敗: ロックされる ・ロック中に正しいパスワード: 拒否される… 個別シナリオを複数書いてルールを裏付ける EARSがAI文脈で人気の理由: 曖昧語（「適切に」「速やかに」等）が構文的に入りにくい / 5パターンの型で異常系の書き 忘れなど抜け漏れに気づける / Kiroが採用し知名度上昇 仕様(spec)駆動開発、仕様はどう書く？ 8 / 18
9. O T H E R F O R M ATS その他の書き方: 箇条書き / テーブル 実務最多派は箇条書き。入出力型の仕様にはテーブルが圧倒的に強い 箇条書きチェックリスト（ルール指向AC） 「〜できること」を自由に列挙。学習コストゼロで柔軟、短い機能ならこれで十分 ただしフォーマットの縛りがなく、品質が書き手のスキルに完全依存 入出力例・テーブル（デシジョンテーブル / GherkinのScenario Outline） 境界値・組み合わせの網羅を視覚的に確認できる（空欄 = 未定義がすぐわかる） 料金計算・割引ルール・バリデーション・権限マトリクスなど「入力 → 出力」型に強い （参考）状態遷移図・形式仕様: 状態やプロトコルの網羅性・厳密性は最強だが、日常の受け入れ基準には過剰なことが多 い 仕様(spec)駆動開発、仕様はどう書く？ 9 / 18
10. CO M PA R I S O N 強み・弱み比較一覧 万能な記法はない。それぞれ得意分野が違う 強み 弱み 向いている場面 GWT シナリオが具体的で認識ズレが起きにくい / そのま ま自動テスト化 網羅には記述量が膨らむ / ルール自体は 読み取りにくい 複雑な業務ロジック / BDDツールでの テスト自動化 EARS 1文で簡潔 / 型で抜け漏れに気づける / 曖昧語が入 りにくい そのままテストにならない / 複雑な条件 は読みにくい 要件定義 / 非機能要件 / AIに渡す requirements 箇条書き 学習コストゼロ / 粒度を気にせず書ける柔軟さ 曖昧・抜け漏れ・ばらつきが起きやす い / 書き手依存 シンプルな機能 / スピード重視 / まず 叩き台 テーブル 境界値・組み合わせの網羅を視覚的に確認 / パラメ タライズドテスト化 状態遷移・時間経過は表現しにくい / 意 図が読めない 料金計算 / バリデーション / 権限マト リクス 仕様(spec)駆動開発、仕様はどう書く？ 10 / 18
11. GUIDELINE 使い分けの指針 排他的に選ぶものではなく、混ぜるのが普通。判断軸は「ルールを書くか、例を書くか」 書きたいもの 記法 ルール（要件そのもの） EARS or 箇条書き 例（具体的なシナリオ） GWT or テーブル よくある組み合わせ: ユーザーストーリー（意図）+ EARSまたは箇条書き（ルール）+ GWT（重要シナリオの具体例） 目的別: 自動テストに直結させたい → GWT / テーブル、要件の抜け漏れ防止を重視 → EARS 仕様(spec)駆動開発、仕様はどう書く？ 11 / 18
12. AI ERA AI時代の変化: Conversationの前倒し AI相手では3Cの「Conversation」をドキュメントで前倒しに埋める アジャイル: ストーリーは会話のきっかけ。詳細は人間同士の対話で埋める AI相手: 会話が限定的 → 受け入れ基準側をアジャイル実務より厚めに書く傾向 だからこそEARSのような「曖昧さを排除する型」が再注目されている 仕様(spec)駆動開発、仕様はどう書く？ 12 / 18
13. REPLACE リプレイスの場合: コードから仕様を割り出す 既存コードがある場合は方向が逆。コードから仕様を復元し、それを新実装のspecにする ここまでの話は新規開発前提（仕様 → コード）。リプレイスでは既存コード・テスト・運用知識から現行の振る舞いを書 き起こす（AIにコードを読ませて要件ドラフトを生成させる方法も） 復元した仕様にも「ストーリー + 受け入れ基準」の2層構造とGWT/EARSの型がそのまま使える 現行踏襲がメインなら、復元先はよくある詳細設計書の形でもよい（= 仕様のベースライン） 変更点が少なければ「復元した設計書 + 仕様変更点メモ（人間が用意）」でも運用可能。変更点メモこそEARS/GWTの型で検証可能に書き、メ モが設計書に優先すると明示する 注意: コードから読み取れるのは「現在の実装」であって「意図（Why）」ではない → なぜそうなっているかは人が補う 仕様(spec)駆動開発、仕様はどう書く？ 13 / 18
14. SUMMARY まとめ 仕様 = ストーリー（なぜ）+ 受け入れ基準（何を満たすか）。記法は目的で選ぶ 仕様は「ユーザーストーリー（意図）+ 受け入れ基準（検証条件）」の2層構造で考える 書き方の型（Connextra / GWT / EARS / テーブル…）を知っていれば、specの品質はぐっと安定する まずは「ルールを書きたいのか、例を書きたいのか」を意識するところから 仕様(spec)駆動開発、仕様はどう書く？ 14 / 18
15. SP まとめ 仕様 = ストーリー（なぜ）+ 受け入れ基準（何を満たすか） 記法は「ルールか、例か」で選ぶ ご清聴ありがとうございました
16. APPENDIX （参考資料）3C: ストーリーの運用原則 ストーリーは「書いて終わり」ではなく、会話と確認で完成させていくもの Card: カードに書ける短い記述（詳細を書き込みすぎない） Conversation: 詳細は関係者との会話で詰める Confirmation: 受け入れ基準で「完成した」と確認できるようにする → ストーリー自体は完全な仕様ではなく「会話のきっかけ」 仕様(spec)駆動開発、仕様はどう書く？ 16 / 18
17. APPENDIX （参考資料）INVEST: 良いストーリーの6条件 良いストーリーかどうかは6つの観点でチェックできる Independent: 他と独立して着手できる / Negotiable: 詳細は交渉・調整の余地がある Valuable: ユーザーにとって価値がある / Estimable: 見積もれる程度に明確 Small: 1スプリントに収まる程度に小さい 仕様(spec)駆動開発、仕様はどう書く？ / Testable: 完成を検証できる（= 受け入れ基準が書ける） 17 / 18
18. APPENDIX （参考資料）EARS記法: 書き方のルールと例 要件文を決まったテンプレートに当てはめて書く。型は5つ + 複合型 基本形: 「<トリガー/条件> の場合、<システム名> は <応答> しなければならない」（When <trigger>, the <system> shall <response>） 型 キーワード 例 Ubiquitous（遍在型） なし システムはログを暗号化して保存しなければならない Event-driven（イベント駆動型） When When ユーザーがログインに3回失敗した場合、システムはアカウントを15分間ロックしなければならない State-driven（状態駆動型） While While メンテナンスモード中は、システムは一般ユーザーのアクセスを拒否しなければならない Optional feature（オプション機能型） Where Where 二要素認証が有効な場合、システムはログイン時に確認コードを要求しなければならない Unwanted behavior（望ましくない挙 動型） If ... then If 決済APIが応答しない場合、システムは注文を保留状態にしてユーザーに通知しなければならない ※ 複合型の例: 「While オフラインモード中に、When ユーザーが保存を押した場合、システムはローカルに一時保存しなければならない」 仕様(spec)駆動開発、仕様はどう書く？ 18 / 18