はじめに — AIに「いい感じに作って」が通用しない理由
Claude Code、GitHub Copilot、Cursor——AIコーディングツールが急速に普及し、「自然言語でコードを書く時代」が到来しています。しかし、こんな経験はないでしょうか。
- 同じ指示を出しているのに、セッションごとに出力品質がバラバラ
- 「いい感じに作って」で動くものは出てくるが、保守できないコードになる
- 途中でセッションが切れると、AIが文脈を忘れてやり直しになる
これらは「Vibe Coding」——AIに自然言語で任せて試行錯誤し、動くものを早く出すスタイル——で起きがちな問題です。Vibe Codingは探索フェーズや小規模な作業には向いていますが、規模が大きくなると品質が安定しません。
GitClear社が2.11億行のAI生成コードを分析した調査では、ガードレールなしでAIにすべてを書かせると欠陥率が急上昇し、生産性向上が数ヶ月以内に消滅するという結果が報告されています。
この問題を解決するアプローチが**仕様駆動開発（SDD: Specification-Driven Development）**です。
仕様駆動開発（SDD）とは
SDDの基本的な考え方はシンプルです。AIにコードを書かせる前に、まず仕様を書く。 そして、その仕様をAIと人間が共有するコンテキストとして扱います。
具体的には、.spec/ フォルダに4つのMarkdownファイルを用意します。
| ファイル | 内容 | 作成者 |
|---|---|---|
PLAN.md |
やりたいことの自由なメモ・アイデア | 人間 |
SPEC.md |
AIが構造化した要件定義 | AI |
TODO.md |
分解されたタスク一覧 | AI |
KNOWLEDGE.md |
プロジェクト固有の学習記録 | AI |
この4ファイルの連携がSDD全体のフローを作ります。
なぜ「仕様を先に書く」だけで品質が変わるのか
理由1: 曖昧な指示は曖昧な出力を生む
AIは与えられた情報の範囲でしか判断できません。「ユーザー管理機能を作って」とだけ伝えると、AIは不足情報を「推測」で埋めます。この推測がセッションごとに異なるため、品質がバラつくのです。
SPEC.mdに「ユーザーの権限は管理者・編集者・閲覧者の3種類」「パスワードはbcryptでハッシュ化」「メールアドレスの重複は不可」と明記しておけば、AIの推測の余地が大幅に減ります。
理由2: セッションをまたいでも文脈が維持される
AIコーディングツールのセッションは有限です。コンテキストウィンドウがいっぱいになると、過去の会話は圧縮・削除されます。しかし、SPEC.mdとTODO.mdがファイルとして残っていれば、新しいセッションでもAIは「何を作っていて、どこまで終わっているか」を正確に把握できます。
理由3: 人間のレビューコストが下がる
SPEC.mdという「正解」があるため、AIの出力が仕様通りかどうかを機械的にチェックできます。「何となく良さそう」ではなく、「仕様のこの項目を満たしているか」という具体的な観点でレビューできるのです。
実践手順 — 今日から始める「プチSDD」
大がかりな導入は不要です。以下の3ステップで始められます。
Step 1: PLAN.mdに考えをダンプする
PLAN.mdにはテンプレートを設けません。これは意図的な設計です。「きれいに書かなければ」というプレッシャーを排除し、心理的ハードルを下げます。
<!-- .spec/PLAN.md -->
# やりたいこと
- ブログ記事の一覧ページを作りたい
- タグでフィルタリングできるようにしたい
- ページネーションは後でいい、まず10件表示
- デザインはシンプルに、Tailwind使う
- 記事データはMarkdownファイルから読み込む
箇条書きでも、散文でも、断片的なメモでも構いません。ポイントは情報量です。少ない情報でAIを動かすと、人間が思ってもいない方向に生成が進みます。
音声入力を活用すると、10分で数千文字分のコンテキストをPLAN.mdに入れられます。タイピングでは出せない情報量です。
Step 2: AIにSPEC.mdとTODO.mdを生成させる
PLAN.mdができたら、AIに構造化を依頼します。
PLAN.mdを読んで、SPEC.md（要件定義）とTODO.md（タスク一覧）を作成してください。
不明点があれば質問してください。
AIが生成したSPEC.mdの例：
<!-- .spec/SPEC.md -->
## 機能要件
### 記事一覧ページ
- Markdownファイルから記事メタデータ（title, tags, date）を取得
- 新しい順に最大10件を表示
- タグによるフィルタリング機能（複数選択可）
## 技術仕様
- フレームワーク: Next.js (App Router)
- スタイリング: Tailwind CSS v4
- 記事ソース: /content/*.md（frontmatter形式）
ここで重要なのが人間によるレビューです。SPEC.mdに書かれた内容がPLAN.mdの意図と合っているか確認し、齟齬があれば修正します。この「壁打ち」のプロセスが、AIとの認識齟齬をなくします。
Step 3: TODO.mdに従って実装を進める
TODO.mdのタスクを1つずつAIに依頼していきます。
<!-- .spec/TODO.md -->
- [x] Markdownパーサーのセットアップ（gray-matter）
- [x] 記事メタデータ取得関数の実装
- [ ] 記事一覧コンポーネントの作成
- [ ] タグフィルタリング機能の実装
セッションが切れても、TODO.mdを見れば進捗がわかります。新しいセッションで「SPEC.mdとTODO.mdを読んで、次の未完了タスクに取りかかってください」と指示するだけで作業を再開できます。
SDDを続けるためのコツ
SDDの最大の課題は継続です。Vibe Codingは「とりあえず動かす」までの摩擦が小さく、短期的な進捗が見えやすいため、SDDからVibe Codingへの「揺り戻し」が起きがちです。
継続のために意識したいポイントを紹介します。
- PLAN.mdのハードルを上げない: テンプレートや書式の制約を課さない。雑なメモでOK
- KNOWLEDGE.mdを活用する: 一度ハマった問題の原因と解決策を記録しておくと、同じ問題でAIが迷わなくなる
- 小さく始める: 全プロジェクトに一度に導入するのではなく、1つの機能追加から試す
-
CLAUDE.mdやAGENTS.mdと連携する: プロジェクトの恒久的なルールはCLAUDE.mdに、SDDの仕様ファイルは
.spec/に、と役割を分ける
まとめ
仕様駆動開発（SDD）は、大げさな開発方法論ではありません。4つのMarkdownファイルを用意するだけで始められる、実用的なプラクティスです。
| 課題 | Vibe Coding | SDD |
|---|---|---|
| 品質の安定性 | セッションごとにバラつく | SPEC.mdが基準になる |
| セッション継続 | コンテキスト消失で手戻り | TODO.mdで途中再開可能 |
| レビュー | 「何となく良さそう」判断 | 仕様ベースの明確なチェック |
| 学習の蓄積 | セッションごとにリセット | KNOWLEDGE.mdに蓄積 |
AIコーディングツールは「テキスト生成」の延長ではなく、「ソフトウェアエンジニアリング」のツールです。曖昧な指示は曖昧な出力を生みます。まずはPLAN.mdに10分だけ考えを書き出すところから始めてみてください。それだけで、AIの出力品質が目に見えて変わるはずです。