はじめに — 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に仕様書を添付するだけで、レビュアーの理解スピードもグッと上がります。