はじめに — AIに雑に頼むと「速く間違う」だけ
AIに「いい感じに作って」と言って、本当に「いい感じ」のものが返ってきたこと、ありますか...?
ちょっと考えてみましょう。こんなプロンプトを書いたことはないでしょうか。
ユーザー登録機能を作って
で、返ってくるコードは、たしかに「動く」。
でも、メールアドレスのバリデーションがない。パスワードの強度チェックもない。重複登録の処理もない。エラーメッセージが英語。確認画面もない。
動くけど、期待とは違う。
なんでこうなるかというと、理由はシンプルです。 人間の頭の中にある「こうあるべき」が、AIに伝わっていない だけなんです。
これ、AIが悪いんじゃないんですよね。情報が足りないんです。
料理に例えるとわかりやすい。「美味しいもの作って」と言われたシェフは困る。和食なのか洋食なのか、何人分なのか、アレルギーはあるのか、予算はいくらなのか。 レシピ（=仕様書）なしに、期待通りの料理は出てこない。 当たり前ですよね。
ところが開発の現場では、この「当たり前」を飛ばして、いきなりAIにコードを書かせている人がめちゃくちゃ多い。
2026年3月現在、AIコーディングツールはものすごく進化しています。Claude Code、Cursor、Gemini CLI...どれも本当にすごい。でも、 「速く正しいものを作る」のと「速く間違ったものを作る」のは、紙一重 なんです。
その差を分けるのが、今回紹介する Spec-Driven Development（SDD） という考え方です。
Spec-Driven Development（SDD）とは何か
SDD（Spec-Driven Development）を一言で言うと、こうです。
「コードを書く前に、仕様書を書く。その仕様書を Single Source of Truth（唯一の正解＝全てのベースになる1枚の設計図）として、コード・テスト・ドキュメントを全て生成する」
...と書くと難しそうに聞こえるかもしれないですが、やっていることはシンプルです。
さっきの料理の例を続けるなら、 レシピを先に書いて、そのレシピ通りにAIシェフに作ってもらう というだけの話。レシピがあれば、何度作っても同じ味になる。レシピがなければ、毎回「なんか違う」が起きる。
「AIへの設計図を先に作ってから、AIに作らせる」 ただそれだけ。
なぜ今SDDなのか
2026年のAI開発ツールには、ある矛盾があります。
- AIのコード生成速度は爆速になった（数秒で数百行のコードが出てくる）
- でも「何を作るか」の定義は、まだ人間がやるしかない
つまり、 AIがどれだけ速くなっても、指示が曖昧なら「速く間違う」だけ なんです。
SDDは、この問題を「仕様書」という中間成果物で解決します。
従来: 人間の頭の中 → (曖昧なプロンプト) → AIが実装 → 「なんか違う...」
SDD: 人間の頭の中 → 仕様書 → AIが実装 → 仕様書通りのものが出てくる
仕様書が間に入ることで、 人間の意図が構造化されて、AIが正確に理解できる形になる わけです。
「仕様書」と聞いてビビらなくていい
ここで「仕様書」と聞いて「うわ、めんどくさそう」と思った方。
大丈夫です。ここで言う仕様書は、 SIerが書くような100ページの設計書じゃない です。Markdownで書く、1〜2ページの「AIへの設計図」です。
しかも、この仕様書自体もAIに書かせることができる。自分で全部書く必要はないんです。
AI時代の仕様書テンプレート — 5つの必須要素
じゃあ、その「設計図」には何を書けばいいのか。
僕が実務で使っているテンプレートを共有します。仕様書に必要な要素は、 たった5つ です。
# 機能仕様書: {機能名}
## 1. 目的と背景（Why）
- なぜこの機能が必要なのか
- どんな課題を解決するのか
- 誰のための機能なのか
## 2. 機能要件（What）
- この機能は何をするのか（箇条書きで具体的に）
- 正常系の動作フロー
- 画面やAPIのエンドポイント
## 3. 非機能要件（How well）
- パフォーマンス要件（レスポンスタイム等）
- セキュリティ要件
- エラーハンドリング方針
## 4. 入出力の具体例（Examples）
- 正常な入力と期待される出力
- 異常な入力と期待されるエラー
- エッジケース
## 5. 制約条件・禁止事項（Constraints）
- 使用する技術スタック
- やってはいけないこと
- 既存コードとの整合性ルール
なぜこの5つなのか
1つずつ説明しましょう。
① 目的と背景（Why） — これがないと、AIは「なぜ」がわからないまま実装します。「ユーザー登録機能」と言われても、BtoBなのかBtoCなのか、セキュリティ重視なのかUX重視なのかで、設計が全然変わる。 Whyを伝えることで、AIの判断の方向性が定まる んです。
② 機能要件（What） — 何をするのかの具体的な記述。ここが曖昧だと「動くけど違う」が起きます。 箇条書きで、1つずつ具体的に 書くのがコツです。
③ 非機能要件（How well） — 「動けばいい」だけじゃなく、どのくらいの品質で動くべきかを定義します。これを書かないと、パフォーマンスやセキュリティが後回しになる。
④ 入出力の具体例（Examples） — これが実は 一番重要 かもしれない。AIは具体例があると、精度が劇的に上がります。「正常な入力→期待する出力」のペアを3つ書くだけで、AIの理解度が全然違う。
⑤ 制約条件・禁止事項（Constraints） — 「TypeScriptで書いて」「外部APIは使わないで」「既存のUserモデルを使って」みたいな制約。これがないとAIが自由に設計しすぎて、既存コードと噛み合わなくなる。
実例: ユーザー登録機能の仕様書
さっきの「ユーザー登録機能を作って」を、このテンプレで書くとこうなります。
# 機能仕様書: ユーザー登録機能
## 1. 目的と背景（Why）
- BtoC向けWebアプリケーションの新規ユーザー登録機能
- ユーザーが自分でアカウントを作成し、サービスを利用開始できるようにする
- 不正アカウント作成を防ぎつつ、登録のハードルは低く保つ
## 2. 機能要件（What）
- メールアドレスとパスワードでの登録
- メールアドレスの重複チェック
- パスワード強度の検証（8文字以上、英数字記号混在）
- メール認証フロー（確認メール送信→リンククリックで有効化）
- 登録完了後、ダッシュボードへリダイレクト
## 3. 非機能要件（How well）
- レスポンスタイム: 登録API 500ms以内
- パスワードはbcryptでハッシュ化（ソルトラウンド10）
- レート制限: 同一IPから5回/分
- エラーメッセージは日本語で返す
## 4. 入出力の具体例（Examples）
### 正常系
- 入力: { email: "test@example.com", password: "Passw0rd!" }
- 出力: { status: 201, message: "確認メールを送信しました" }
### 異常系（重複）
- 入力: { email: "existing@example.com", password: "Passw0rd!" }
- 出力: { status: 409, error: "このメールアドレスは既に登録されています" }
### 異常系（パスワード弱）
- 入力: { email: "test@example.com", password: "1234" }
- 出力: { status: 400, error: "パスワードは8文字以上で英数字記号を含めてください" }
## 5. 制約条件・禁止事項（Constraints）
- TypeScript + Next.js App Router
- データベース: MongoDB（Mongoose）
- 外部認証サービス（Auth0等）は使わない
- 既存の /lib/db.ts の接続を使用する
- テストは Jest + supertest で書く
どうでしょうか。最初の「ユーザー登録機能を作って」と比べて、AIに渡す情報量が全く違いますよね。
これが「設計図」の力 です。
AIに仕様書を書かせる3つのプロンプトパターン
「テンプレはわかった。でも、これを毎回手で書くのはめんどくさい」
めっちゃわかります。
なので、 仕様書自体もAIに書かせましょう 。ここでは3つのパターンを紹介します。
パターンA: ゼロからアイデアベースで仕様書を生成
まだ何も決まっていない段階で、アイデアから仕様書を生成するパターンです。
あなたは経験豊富なシニアエンジニアです。
以下のアイデアから、実装可能な機能仕様書を作成してください。
## アイデア
「ブログ記事の下書きを保存して、予約投稿できる機能がほしい」
## 仕様書テンプレート（この形式で出力してください）
1. 目的と背景（Why）
2. 機能要件（What）— 箇条書きで具体的に
3. 非機能要件（How well）— パフォーマンス、セキュリティ、エラーハンドリング
4. 入出力の具体例（Examples）— 正常系2つ、異常系2つ以上
5. 制約条件（Constraints）— 技術スタック: Next.js + TypeScript + MongoDB
## 注意
- 機能要件は「何ができるか」を箇条書きで10個以上
- 入出力の具体例はJSON形式で
- エッジケースも必ず含める
パターンB: 曖昧な会話を構造化する
チャットやミーティングで出た曖昧な要望を、仕様書に変換するパターン。
以下は、プロダクトオーナーとの会話メモです。
この内容から、エンジニアが実装可能なレベルの機能仕様書を作成してください。
## 会話メモ
- 「ユーザーがお気に入りの記事をブックマークできるようにしたい」
- 「あ、あとブックマークしたやつを一覧で見れるようにして」
- 「タグとかで分類できるといいかも」
- 「他の人のブックマークは見えないようにしてね」
## 出力形式
（上記テンプレートと同じ）
## 追加指示
- 会話メモに書かれていないが、実装上必要になる要件も推測して含める
- 推測した要件には「※推測」と注記する
- 曖昧な点は「要確認」としてリストアップする
このパターンのポイントは、 「推測した要件には注記する」 と指示していること。これで、AIが勝手に決めた部分を人間が確認できる。
パターンC: 既存コードから仕様書を逆生成する
すでに動いているコードから仕様書を作るパターン。リファクタリングや引き継ぎに使えます。
以下のコードから、機能仕様書をリバースエンジニアリングしてください。
## コード
（ここに既存コードを貼る）
## 出力形式
（上記テンプレートと同じ）
## 追加指示
- コードの実際の振る舞いを正確に記述する
- バグの可能性がある箇所は「※要検証」と注記する
- テストが不足している箇所を「テスト追加推奨」として指摘する
- 暗黙的なビジネスルール（コメントにない判断ロジック）を明示する
この3つのパターンを使い分ければ、 仕様書を書くこと自体にそれほど時間はかからない です。
重要なのは、 AIが出力した仕様書を人間が必ず確認すること 。AIに仕様書を書かせて、ノーチェックでAIに実装させると、間違いが増幅される。ここは手を抜いちゃダメなポイントです。
誤解しないでほしいのは、SDDは「これで完璧に正しいものが作れる」という銀の弾丸じゃない、ということ。ただし、 「雑に頼んで手直しを繰り返す」よりは、圧倒的にマシ です。「完璧」じゃなくて「大幅に改善する」という温度感で捉えてもらえると。
仕様書 → 実装 → テストの自動化フロー
仕様書ができたら、ここからが本番です。
仕様書1枚から、 コード、テスト、APIドキュメント の3つを生成できます。しかも、それぞれ別のプロンプトで独立して生成できるので、並列で進められる。
Step 1: 仕様書 → コード生成
以下の機能仕様書に基づいて、実装コードを生成してください。
## 仕様書
（ここに仕様書をそのまま貼る）
## 実装ルール
- TypeScript の strict モードで書く
- 関数には JSDoc コメントをつける
- エラーハンドリングは仕様書の「非機能要件」に従う
- ファイル構成: controller / service / model / validator に分離
- 各ファイルの冒頭に「この仕様書のどの要件を実装しているか」をコメントで記述
最後の行がポイントです。 「仕様書のどの要件を実装しているか」をコメントで書かせる ことで、後からトレーサビリティ（追跡可能性＝「この実装はどの仕様に基づいているか」を追跡できること）が確保できる。
Step 2: 仕様書 → テストケース生成
以下の機能仕様書に基づいて、テストコードを生成してください。
## 仕様書
（ここに仕様書をそのまま貼る）
## テストルール
- Jest + supertest を使用
- describe ブロックは仕様書の「機能要件」の各項目に対応させる
- 仕様書の「入出力の具体例」を全てテストケースに変換する
- 正常系、異常系に加えて、以下のエッジケースも追加:
- 空文字列の入力
- 極端に長い入力（1000文字以上）
- SQLインジェクション / XSS パターン
- 同時リクエスト（競合状態）
ここで注目してほしいのは、 仕様書の「入出力の具体例」がそのままテストケースになる こと。だから仕様書に具体例を厚く書いておくことが大事なんです。
Step 3: 仕様書 → APIドキュメント生成
以下の機能仕様書に基づいて、OpenAPI 3.0 形式の API 仕様を生成してください。
## 仕様書
（ここに仕様書をそのまま貼る）
## 出力ルール
- YAML形式で出力
- リクエスト/レスポンスの例（examples）を必ず含める
- エラーレスポンスも全パターン記述
- description には仕様書の「目的と背景」を反映
フロントエンドとバックエンドを別のチーム（あるいは別のAIセッション）で開発している場合、このAPIドキュメントが「共通言語」になります。
# 生成されるOpenAPI仕様の例
openapi: 3.0.0
info:
title: User Registration API
version: 1.0.0
description: BtoC向けWebアプリケーションの新規ユーザー登録API
paths:
/api/auth/register:
post:
summary: 新規ユーザー登録
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [email, password]
properties:
email:
type: string
format: email
example: "user@example.com"
password:
type: string
minLength: 8
example: "Passw0rd!"
responses:
'201':
description: 登録成功
content:
application/json:
example:
status: 201
message: "確認メールを送信しました"
'400':
description: バリデーションエラー
content:
application/json:
example:
status: 400
error: "パスワードは8文字以上で英数字記号を含めてください"
'409':
description: メールアドレス重複
content:
application/json:
example:
status: 409
error: "このメールアドレスは既に登録されています"
仕様書1枚から、コード・テスト・APIドキュメントの3点セットが生成される。 これがSDDの破壊力です。
「速く間違う」を防ぐ3つのバリデーションポイント
ここで1つ、大事な話をさせてください。
SDDは強力ですが、 仕様書が間違っていたら、全部間違います 。コードもテストもドキュメントも、全部「間違った仕様」に基づいて生成される。
だから、「仕様書を書いたらすぐ実装」じゃなく、 3つのチェックポイント を入れる必要があるんです。
① 仕様書自体のレビュー（AIにレビューさせる）
仕様書を書いたら（AIに書かせたら）、 別のプロンプトでレビューさせる 。
あなたはシニアエンジニア兼プロダクトマネージャーです。
以下の機能仕様書をレビューしてください。
## 仕様書
（ここに仕様書を貼る）
## レビュー観点
1. 機能要件に漏れはないか（ユーザーが期待する動作が全てカバーされているか）
2. 非機能要件は十分か（セキュリティ、パフォーマンス、エラーハンドリング）
3. 入出力の具体例にエッジケースは含まれているか
4. 制約条件に矛盾はないか
5. 曖昧な記述はないか（「適切に」「必要に応じて」等の曖昧表現）
6. 実装不可能な要件はないか
## 出力形式
- 問題がある箇所: [重要度: 高/中/低] + 指摘内容 + 修正案
- 問題がない箇所: 「OK」
ポイントは、 「曖昧な記述はないか」をチェック観点に入れること 。「適切に処理する」「必要に応じて」みたいな曖昧表現は、人間は読み飛ばしてもAIは困る。仕様書の曖昧さを潰すのが、品質を上げる一番のレバレッジです。
② 仕様 ↔ 実装の整合性チェック
コードが生成されたら、仕様書と突き合わせる。
以下の「仕様書」と「実装コード」を比較して、整合性をチェックしてください。
## 仕様書
（貼る）
## 実装コード
（貼る）
## チェック観点
1. 仕様書の機能要件が全て実装されているか（漏れチェック）
2. 仕様書にない機能が勝手に追加されていないか（過剰実装チェック）
3. 入出力の具体例と、コードの実際の振る舞いが一致するか
4. 非機能要件（バリデーション、エラーハンドリング等）が実装されているか
5. 制約条件が守られているか
## 出力形式
| 仕様書の要件 | 実装状況 | 備考 |
|------------|---------|------|
（テーブル形式で全件チェック）
③ テストによる自動検証
最後に、生成されたテストを実行して、仕様通りに動くか検証する。
# テストを実行
npx jest --verbose --coverage
# カバレッジが不足している場合、AIに追加テストを依頼
以下のテストカバレッジレポートを見て、
仕様書の要件でテストされていない箇所を特定し、
追加テストケースを生成してください。
## カバレッジレポート
（ここにカバレッジ結果を貼る）
## 仕様書
（ここに仕様書を貼る）
この3段階のバリデーションを入れると、 「AIが速く間違う」問題はかなり抑えられる 。完璧とは言わないけど、ノーチェックで進めるのとは雲泥の差です。
人間とAIの役割分担 — 「What/Why」で勝負する開発スタイル
最後に、SDDの本質的なところを話させてください。
SDDをやっていくと、気づくことがあります。
エンジニアの仕事が「コードを書くこと」から「何を作るかを決めること」に変わる。
| フェーズ | 人間がやること | AIがやること |
|---|---|---|
| 要件定義 | 課題の発見、優先順位の判断 | 要件の構造化、仕様書の生成 |
| 設計 | 仕様書のレビュー、最終判断 | 設計案の提示、トレードオフの整理 |
| 実装 | コードレビュー、アーキテクチャ判断 | コード生成、リファクタリング |
| テスト | テスト戦略の決定、結果の評価 | テストケース生成、実行、レポート |
| ドキュメント | 最終確認 | APIドキュメント、READMEの生成 |
この表を見ると、 人間の仕事は全て「判断」と「評価」 であることがわかります。実装の手を動かす部分は、ほぼAIに任せられる。
これは「エンジニアの仕事がなくなる」という話じゃないです。むしろ逆で、 「何を作るか」「なぜ作るか」を深く考える時間が増える んです。
仕様書を書くことは、つまり 「自分が何を作りたいのかを、自分自身に問いかけること」 でもある。
なんとなく「こんな機能ほしい」を、5つの要素に分解して書き出す過程で、「あれ、本当にこの機能いるんだっけ」「この要件、矛盾してないか」みたいな気づきが生まれる。
仕様書は、AIへの指示書であると同時に、自分の思考を整理するツール でもあるんです。
まとめ
この記事で伝えたかったことを整理すると、こうなります。
- AIに雑に頼むと「速く間違う」 — 問題はAIじゃなく、渡す情報の不足
- SDDは「仕様書ファースト」の開発スタイル — コードの前に設計図を書く
- 仕様書は5要素（Why / What / How well / Examples / Constraints） で書ける
- 仕様書自体もAIに書かせられる — 3つのプロンプトパターンで
- 仕様書1枚からコード・テスト・ドキュメントが生成できる — これがSDDの破壊力
- 3つのバリデーションポイント で「速く間違う」を防ぐ
- エンジニアの仕事は「What/Why」の設計者 — Howは手放していい
「AIにいい感じに作って」と言うのをやめて、「仕様書を1枚書く」。
たったこれだけの習慣が、AIとの共同作業の質を劇的に変えてくれます。
まずは、次に作る機能を1つだけ選んで、仕様書から始めてみてください。
いきなり全部やろうとしなくていいです。テンプレートをコピーして、5つの要素を埋めるだけ。それだけで「AIへの伝わり方」が変わるのを実感できるはず。
最初は面倒に感じるかもしれないですが、仕様書を書く5分が、「期待と違うコードを手直しする30分」を消してくれる...そう考えると、なかなか悪くない投資だと思いませんか。
チーム開発での運用ヒント
個人開発だけでなく、チームでSDDを導入する場合のコツも1つだけ。
仕様書のレビューをコードレビューより先にやる。
コードレビューで「そもそもこの設計じゃなくない?」ってなった経験、ありませんか。仕様書の段階でレビューを入れると、実装前にズレを修正できるので、コードレビューが「設計の是非」じゃなく「実装の品質」に集中できるようになる。PRに仕様書を添付するだけで、レビュアーの理解スピードもグッと上がります。