仕様駆動開発マスター講義 — 要件定義からDESIGN.mdまで

この講義では、AIコーディングエージェントに実装を任せる前に何を準備すべきかを、要件定義書からDESIGN.md（仕様書）、受け入れ基準、そして実装サイクルまで一通り扱います。全12週のカリキュラムの仕様駆動開発の週で扱う内容を、より体系立てて深掘りする位置づけです。

「いい感じに作って」で終わらせず、AIにも人にも伝わる文書をどう書くか。実際に手を動かすときにそのまま使える型を持ち帰っていただくことを目指します。

まず、なぜコードを書く前に文章を書く必要があるのか、その理由から確認します。

AIエージェントは前提を推測しない

人間だけでコードを書いていた頃は、頭の中の意図をその場で補完できました。しかしAIコーディングエージェントは、指示された内容をそのまま形にしようとするため、書かれていない前提を推測しません。指示があいまいなままだと、AIは間違っていなくても「本当に欲しかったもの」とは違う結果を出してしまいます。

仕様駆動開発とは、コードを書き始める前に「何を作るか」「どう動けば正しいか」を文章として先に定義し、それをもとに実装を進める考え方です。

例えば「ログイン機能を作って」とだけ伝えると、AIはメール認証か、SNS連携か、パスワードの再設定をどう扱うかといった判断を独自に補ってしまいます。こうした暗黙の前提を先に文章にしておくことが、仕様駆動開発の出発点です。

仕様書は自分自身の頭の整理でもある

仕様を先に書くことは、AIのための説明書であると同時に、自分自身の頭の中を整理する作業でもあります。頭の中にある曖昧なイメージを、完成したかどうかを誰でも確かめられる形に言い直す。仕様駆動開発が担っているのは、この翻訳の作業です。

個人開発の規模であれば、分厚い文書にする必要はありません。それぞれ数行〜数十行程度でも十分機能します。

書いている途中で「ここがまだ決まっていない」と気づくこと自体が、仕様書を書く価値のひとつです。曖昧さは、書き出して初めて可視化されます。

要件定義書・仕様書・受け入れ基準の違い

似ているようで役割が異なる3つの文書を整理します。

• 要件定義書：誰のために、何のために作るのかを言葉にしたもの
• 仕様書：具体的にどんな機能を、どう動かすかを詳細化したもの
• 受け入れ基準：何をもって完成とみなすかの判定リスト

大切なのは、書く順番——全体像から詳細、そして判定基準へ——を守ることです。

仕様書→実装の順序を徹底する

AIコーディングエージェントは指示された順に手を動かすため、仕様書を書く前にコードから着手すると手戻りが増えます。エージェントに依頼する際は、まず仕様書ファイルを読ませてから実装計画を立てさせ、計画に対して人間が確認してから着手させるという二段階の指示が有効です。

「仕様書に基づいて実装計画を提示してください。実装はまだしないでください」のように、計画提示と実装実行を明示的に分けて依頼すると、認識のズレを実装前に修正できます。

計画を先に確認するステップを省略すると、実装が進んでからの手戻りは仕様書を直すだけでは済まなくなり、書いたコードごと直す必要が出てきます。二段階の指示は、その手戻りを未然に防ぐための工夫です。

第1章のまとめ

仕様駆動開発は、AIに実装を任せる時代だからこそ効果を発揮する考え方です。次章からは、実際に要件定義書をどう書くかを見ていきます。

「何のために、誰のために作るのか」を言葉にする要件定義書の書き方を扱います。

要件定義書に書くべき4つの要素

要件定義書は、想定ユーザー・解決したい課題・実現したいことの全体像を書いたものです。初めて書く場合は、次の要素を埋めることから始めてみましょう。

• 目的：このアプリ・機能は何のために作るか（1〜2文）
• 想定ユーザー：誰が、どんな場面で使うか
• 主な機能：箇条書きで3〜5個程度
• 入力・出力：ユーザーが何を入力し、何が返ってくるか

これらの項目は、箇条書きで十分です。完璧な文章よりも、読み返したときに自分自身で意図を再現できるかどうかを基準に書いてみてください。

「やらないこと」を決める重要性

初心者が仕様を書くとき、最も抜け落ちやすいのが「やらないこと（スコープ外）」の明記です。たとえば掲示板を頼むときに一言で済ませると、AIは登録機能や通知、検索、管理画面までまとめて作り始めてしまうことがあります。手を広げすぎていつまでも完成しない、という形でつまずく人は少なくありません。

「今回は投稿と一覧表示だけ。会員登録や通知は次のステップ」のように、今回は作らない機能を先に書き出しておけば、AIも人も途中で寄り道せずに済みます。

個人開発で失敗しやすいスコープの広げすぎ

個人開発では欲張ったスコープが最大の失敗要因になります。仕様書には「今回作る範囲」と「今回は作らない範囲」を両方明記し、後者を意図的に残しておくことで判断のブレを防ぎます。

1週間で確認できる単位にマイルストーンを刻むなど、区切りの良い粒度に分けることで、AIエージェントの実装結果が仕様と一致しているかを都度検証でき、大きなズレに気づかないまま進む事態を避けられます。

要件定義書をAIへの最初の指示にする

この文書をAIコーディングエージェントへの最初の指示として渡すと、AIは前提を推測する必要が減り、意図に近い実装を返しやすくなります。出来上がりに不足があれば、直接の修正指示ではなく仕様書に書き足してから渡し直します。この行き来を繰り返すのが、仕様駆動開発の基本の回し方です。

第2章のまとめ

要件定義書は、目的・想定ユーザー・主な機能・やらないことを言葉にする最初の一歩です。次章では、これを実装可能な粒度に分解する仕様書（DESIGN.md）の書き方に進みます。

要件定義書をもとに、画面設計・データ設計まで踏み込んだDESIGN.mdの書き方を扱います。

仕様書に書く内容の粒度

仕様書は、要件定義書をもとに「具体的にどんな機能を、どう動かすか」を詳細化したものです。画面の項目、入力と出力、扱うデータの形などを書きます。DESIGN.mdという名前でリポジトリのルートに置いておくと、AIコーディングエージェントが実装の前に参照しやすくなります。

画面設計を言語化する

画面設計は、要素の配置だけでなく状態（初期表示・入力中・エラー・完了など）ごとの見え方を書き出します。図やワイヤーフレームがあれば添えますが、文章だけでも「この画面には何がどう表示され、どのデータを参照するか」が伝わることを基準にします。

• 画面ごとに状態一覧（初期・入力中・エラー・完了）を書く
• 画面間の遷移条件を明記する

特にエラー状態の見え方は見落とされがちです。「何を入力したときに」「どんなメッセージが」「どこに表示されるか」まで書いておくと、AIコーディングエージェントが作るエラー処理のブレを減らせます。

データ設計を言語化する

データ設計は、扱う情報の項目名・型・必須かどうか・初期値を一覧化します。曖昧な指示語（「いい感じに」「きれいに」）は避け、具体的な状態や条件で書きます。

データ項目は名前・型・必須有無を表形式で整理しておくと、AIコーディングエージェントに渡したときの解釈のブレを減らせます。

項目の必須・任意の判断に迷ったら、「その項目がなければ機能が成立しないか」を基準に考えると整理しやすくなります。初期値の有無も、画面の初回表示に直結するため忘れずに書き出しておきましょう。

DESIGN.mdの章立ての一例

個人開発でそのまま使える仕様書の章立ての一例として、目的・対象ユーザー・主要機能・画面一覧・データ構造の概要・各機能の受け入れ基準・今回のスコープ外事項・週次マイルストーン案、という構成が挙げられます。

すべての項目を最初から完璧に埋める必要はなく、実装を進めながら加筆・修正していく前提で運用して構いません。

第3章のまとめ

DESIGN.mdは、要件定義書を実装可能な粒度まで分解した設計図です。次章では、この仕様書に基づいて「完成」をどう判定するかという受け入れ基準を扱います。

「何をもって完成とみなすか」を明確にし、実装できる大きさにタスクを分解する方法を扱います。

受け入れ基準を観測可能な形で書く

仕様書に機能を書くだけでは「完成」の基準が曖昧なままです。各機能に対して、どの状態になれば完了と言えるかを受け入れ基準として書き添えます。例えば「ログインフォームを実装する」ではなく「メールアドレス未入力時にエラー文言が表示され、送信ボタンが無効化される」のように、観測可能な振る舞いで記述します。

「正しく動く」のような主観的な表現ではなく、誰が読んでも同じ判定ができる条件に落とし込むことがポイントです。判定に迷う受け入れ基準は、まだ具体性が足りていないサインだと考えてください。

受け入れ基準はテスト設計にも使える

受け入れ基準は、次の工程であるテスト設計にもそのまま使えるため、この段階で丁寧に書いておくほど後工程が楽になります。

• 入力条件と期待される出力・画面状態をセットで書く
• 数値や文言は具体的な例を添える
• 「エラー時にどう振る舞うか」も含める

後の週でテストコードを書く際、この受け入れ基準の文章をほぼそのままテストケースの説明文として使えることが多く、二度手間を避けられます。

仕様書から画面・機能単位のタスクへ分解する

仕様書はそのままでは実装依頼として大きすぎます。AIコーディングエージェントに一括で「全部作って」と依頼すると、意図しない実装や仕様との食い違いが起きやすくなります。仕様書を画面単位・機能単位の小さなタスクに分解し、1タスクが1回のレビューで確認できる大きさに保つことが重要です。

タスクの並べ方と依存関係

分解の際は「この画面に必要なコンポーネントは何か」「このコンポーネントが依存するデータは何か」を洗い出し、依存関係の順（データ定義→ロジック→UI、など）にタスクを並べます。この順序を意識するだけで、後戻りの少ない実装サイクルになります。

第4章のまとめ

受け入れ基準は完成の判定基準であり、テストの土台にもなります。仕様書をタスクに分解し、依存関係の順に並べることで、実装の手戻りを減らせます。次章はいよいよ、AIエージェントとの実装サイクルの実践です。

コンポーネント単位の実装依頼から、仕様と実装のズレを見つけて直すレビューの型までを扱います。

コンポーネント単位で依頼する

実装依頼はコンポーネント単位で出すと、AIコーディングエージェントの出力を検証しやすくなります。依頼文には、対象コンポーネントの役割・受け取るデータ・表示する状態・満たすべき受け入れ基準を含めます。

一度に複数コンポーネントを依頼すると、ズレが起きた際にどこに原因があるか特定しづらくなるため、まずは1コンポーネントを依頼して結果を確認し、問題なければ次に進む、という小刻みな進め方が安全です。

依頼の粒度に迷ったら、「レビューで一度に読める分量か」を目安にするとよいでしょう。読みきれない量の差分が返ってきたら、次回はもう一段階小さく依頼し直します。

仕様と実装のズレを検知する3つの観点

AIコーディングエージェントが出力したコードは、必ず仕様書と突き合わせて確認します。見るべき観点は主に三つです。

• 機能面で受け入れ基準を満たしているか
• データの扱いが設計と一致しているか（項目の過不足や型の食い違い）
• 画面の状態遷移が仕様通りか

三つの観点のうち、特にデータの扱いのズレは画面上の見た目だけでは気づきにくいため、実際の値を出力させたりログを確認したりする一手間が有効です。

ズレを見つけたら仕様書側を見直す

ズレを見つけたら、コードを直接書き換える前に、まず仕様書のどの記述が伝わっていなかったのかを確認し、依頼文を修正してから再依頼する習慣をつけると、同じズレを繰り返しにくくなります。修正はコードだけでなく、伝え方そのものに向けることが大切です。

仕様駆動開発は仕上げの精度も上げる

仕様書を用意すれば、AIの実装が自動的に正しくなるわけではありません。仕様書があっても確認の手間が消えるわけではありません。減るのは、依頼した内容と出来上がったものの食い違いです。実装が終わったら、受け入れ基準の項目を上から順に見ていき、満たせているかを1つずつ確かめます。

受け入れ基準との突き合わせを省略すると、見た目は動いているように見えても、細かな条件分岐の抜けに気づかないまま公開してしまうことがあります。

第5章のまとめ

コンポーネント単位の依頼、三つの観点でのズレ検知、そして仕様書へのフィードバックというサイクルを回すことで、仕様駆動開発は実践的な武器になります。

この講義では、仕様駆動開発の考え方から、要件定義書の書き方、DESIGN.mdの章立て、受け入れ基準の設計、そしてAIエージェントとの実装サイクルまでを、5つの章に分けて扱いました。共通しているのは「曖昧さを先に文章で潰しておく」という姿勢です。

最初から完璧な仕様書を書く必要はありません。書いて、渡して、ズレを見つけて直す——この往復を重ねることが、仕様駆動開発を身につける一番の近道です。

要件定義書の書き方は「要件定義書の書き方：AIに伝わる目的・スコープ・やらないこと」の記事で、DESIGN.mdの章立てとテンプレートは「DESIGN.mdテンプレート実例」の記事で、それぞれより詳しく解説しています。あわせてご覧ください。

実際に自分の企画で仕様書を書き、実装まで進める演習は、全12週のシラバスで扱います（無料で読めます。成果や収益をお約束するものではありません）。

講義で扱ったテーマを、公式ドキュメントや公的機関の資料で確かめたいときの入口です。

• Gherkin Reference（Cucumber）：受け入れ基準をGiven/When/Thenで書くときの記法
• spec-kit（GitHub）：仕様書を起点にAIエージェントと開発を進めるための公開ツールキット

この特別講義は無料で視聴できる総集編です。関連する内容を実際に手を動かしながら学びたい方は、全12週のシラバスで学習の全体像を確認できます（無料で読めます。成果や収益をお約束するものではありません）。先行案内はこちら。