SDD（仕様駆動開発）入門——Vibe Codingを卒業してAI開発の精度を上げる方法

はじめに

Claude CodeやCursorでAI開発をしていて、こんな経験はありませんか？

• AIが生成したコードが意図と微妙にずれている
• 「ここ直して」を繰り返すうちに、元の設計が崩壊した
• 動くものはできたが、後から見ると何をしたかったのかわからない

これらの問題の原因は、AIの性能ではなく 「仕様の曖昧さ」 にあります。

2026年に入り、SDD（Spec Driven Development / 仕様駆動開発） というアプローチが注目を集めています。GitHubが公式にSpec Kitをリリースし、はてなブックマークでも「SDDのスラッシュコマンドを自作して運用している」という記事が話題になりました。

本記事では、SDDの考え方を理解し、Claude Codeで仕様ファーストの開発フローを実践する方法をハンズオン形式で解説します。

この記事を読み終わったら、以下ができるようになります。

• Vibe CodingとSDDの違いを説明できる
• 仕様ファイル（Spec）の書き方を理解する
• Claude Codeのスラッシュコマンドで自分なりのSDDフローを構築できる

Vibe Coding vs SDD——何が違うのか

Vibe Codingの限界

「Vibe Coding」とは、AIに曖昧なプロンプトを投げて「いい感じに」コードを生成してもらうスタイルです。プロトタイプや個人開発では有効ですが、以下の問題が生じます。

問題は「修正ループ」が回るたびにコンテキストが膨れ上がり、AIが混乱しやすくなることです。3回目の修正あたりから、前に直した箇所が壊れ始めるのはよくあるパターンです。

SDDのアプローチ

SDDでは、コードを書く前に 仕様（Spec） を定義します。仕様が明確であれば、AIは推測する必要がなくなり、1回目の生成精度が大幅に向上します。

ポイント: SDDは「事前準備に時間がかかる」と思われがちですが、修正ループが激減するため、トータルでは速くなります。

SDDの6フェーズ

SDDは6つのフェーズで構成されます。GitHub Spec Kitなどのツールはこのフローに沿って設計されています。

ただし、すべてのフェーズを律儀に回す必要はありません。大事なのは 「実装前に仕様を明確にする」 という原則です。

ハンズオン 1: 仕様ファイルの書き方

ここから実践に入ります。架空のプロジェクト「KanriPro」（業務管理SaaS / Next.js + Firestore + TypeScript）を例に、仕様ファイルの書き方を見ていきましょう。

シナリオ: タスクのフィルタリング機能を追加する

要件は「タスク一覧画面にステータスと担当者でフィルタリングできる機能を追加する」です。

Vibe Codingの場合

こういうプロンプトを直接AIに投げてしまいがちです。

タスク一覧にフィルター機能を追加して。
ステータスと担当者でフィルターできるようにして。

これだと、AIは以下のような判断を「自分で」します。

• フィルターUIはドロップダウンかチェックボックスか？
• フィルタリングはクライアントサイドかサーバーサイドか？
• URLパラメータと連動させるか？
• 「全て」のオプションは必要か？
• 複数ステータスの同時選択は可能か？

SDD: 仕様ファイルを書く

代わりに、以下のような仕様ファイルを先に作ります。

# KP-015: タスクフィルタリング機能

## 概要
タスク一覧画面（/tasks）にステータスと担当者によるフィルタリング機能を追加する。

## ユーザーストーリー
- プロジェクトメンバーとして、ステータス別にタスクを絞り込みたい
- プロジェクトメンバーとして、特定の担当者のタスクだけを表示したい
- プロジェクトメンバーとして、フィルター条件をURLで共有したい

## 受け入れ基準
1. ステータスフィルター
   - 選択肢: 全て / 未着手 / 進行中 / レビュー中 / 完了
   - 単一選択（ドロップダウン）
   - デフォルト: 全て

2. 担当者フィルター
   - 選択肢: 全て / プロジェクトメンバー一覧
   - 単一選択（ドロップダウン）
   - デフォルト: 全て

3. URL連動
   - フィルター変更時にURLパラメータを更新（例: /tasks?status=in_progress&assignee=user123）
   - URLパラメータからフィルター状態を復元する
   - ブラウザの戻る/進むに対応する

4. パフォーマンス
   - フィルタリングはFirestoreクエリで実行（クライアントサイドフィルタリングは不可）
   - where句で複合クエリを使用

## 技術方針
- フィルターUIコンポーネント: src/components/TaskFilter.tsx（Client Component）
- URLパラメータ管理: next/navigation の useSearchParams
- Firestoreクエリ: src/lib/tasks.ts にフィルター付きクエリ関数を追加
- 複合インデックスの作成が必要（status + assignee）

## エッジケース
- メンバーが0人のプロジェクト → 担当者フィルターを非表示
- フィルター結果が0件 → 「条件に一致するタスクはありません」を表示
- 不正なURLパラメータ → デフォルト値にフォールバック

## テスト観点
- 各ステータスでフィルタリングが正しく動作する
- URLパラメータとフィルター状態が同期する
- 不正なパラメータでエラーにならない

この仕様ファイルがあれば、AIが推測すべきことはほぼゼロです。

ハンズオン 2: Claude Codeでスラッシュコマンドを作る

SDDのフローをClaude Codeに組み込むには、スラッシュコマンド（カスタムコマンド）が便利です。はてなブックマークで話題になったshibayu36さんの記事を参考に、自分のプロジェクトに合ったコマンドを作ってみましょう。

ディレクトリ構成

.claude/
├── commands/
│   ├── spec.md           # 仕様作成コマンド
│   ├── plan.md           # 技術設計コマンド
│   └── implement.md      # 仕様に基づく実装コマンド
└── skills/
    └── coding-standards/
        └── SKILL.md

コマンド1: /spec — 仕様作成

.claude/commands/spec.md を作成します。

---
description: 機能の仕様を作成する
---

以下の手順で機能の仕様ファイルを作成してください。

## 手順

1. ユーザーの要件を確認する（$ARGUMENTS に記述されているはず）
2. 以下のテンプレートに沿って仕様を作成する
3. 仕様ファイルを `specs/` ディレクトリに保存する

## テンプレート

```markdown
# [機能名]

## 概要
[1〜2文で機能の説明]

## ユーザーストーリー
- [ロール]として、[目的]したい

## 受け入れ基準
1. [具体的な条件と期待される動作]
2. [具体的な条件と期待される動作]

## 技術方針
- [使用するコンポーネント・ファイルパス]
- [データの流れ]

## エッジケース
- [想定されるエッジケースと対応方針]

## テスト観点
- [テストすべきケース]

重要なルール

• 実装はしない。仕様の作成だけを行う
• 曖昧な点があればユーザーに質問する
• 技術方針はプロジェクトのスタック（Next.js App Router + Firestore + TypeScript + Tailwind CSS）に合わせる

### コマンド2: `/plan` — 技術設計

`.claude/commands/plan.md` を作成します。

```markdown
---
description: 仕様ファイルを元に技術設計を作成する
---

以下の手順で技術設計を行ってください。

## 手順

1. `specs/` ディレクトリから該当する仕様ファイルを読み込む
2. 仕様の受け入れ基準を満たすための技術設計を作成する
3. 設計ファイルを `specs/` ディレクトリに保存する

## 設計ファイルのフォーマット

```markdown
# [機能名] - 技術設計

## 変更対象ファイル
| ファイル | 変更内容 | 新規/既存 |
|---------|---------|:---------:|
| src/... | 説明 | 新規 or 既存 |

## 実装タスク
1. [ ] タスク1（依存なし）
2. [ ] タスク2（タスク1に依存）
3. [ ] タスク3（依存なし）

## データモデル
[Firestoreのコレクション/フィールドの変更がある場合]

## 注意事項
[実装時の注意点]

重要なルール

• 実装はしない。設計だけを行う
• 仕様にない要件を勝手に追加しない
• タスクは依存関係を明示する

### コマンド3: `/implement` — 仕様ベースの実装

`.claude/commands/implement.md` を作成します。

```markdown
---
description: 仕様と設計に基づいて実装する
---

以下の手順で実装を行ってください。

## 手順

1. `specs/` ディレクトリから仕様ファイルと設計ファイルを読み込む
2. 設計の「実装タスク」を順番に実装する
3. 各タスク完了後、受け入れ基準を確認する

## 重要なルール

- **仕様にないことは実装しない**
- 仕様の受け入れ基準を1つずつ満たしていく
- エッジケースは仕様に記載されたものだけ対応する
- 実装中に仕様の不備を見つけたら、実装を止めてユーザーに報告する
- コーディング規約は .claude/skills/ を参照する

ハンズオン 3: 実際のフローを回してみる

「KanriPro」のタスクフィルタリング機能を、SDDフローで実装してみましょう。

Step 1: /spec タスクフィルタリング機能

Claude Codeで以下を実行します。

> /spec タスク一覧にステータスと担当者でフィルタリングできる機能を追加したい。URLパラメータと連動させて、フィルター条件を共有可能にしたい。

Claude Codeが仕様ファイルを生成し、不明点を質問してきます。

仕様を作成する前にいくつか確認させてください。

1. ステータスの選択肢は？（例: 未着手/進行中/完了）
2. 複数のステータスを同時に選択できるようにしますか？
3. タスク数はどの程度を想定していますか？（パフォーマンス方針に影響）

この「質問」がSDDの核心です。Vibe Codingでは質問されずにAIが勝手に判断しますが、SDDでは曖昧な点が明示的に解消されます。

Step 2: /plan

仕様が固まったら、技術設計を作成します。

> /plan タスクフィルタリング機能

設計ファイルに、変更対象ファイルと実装タスクが一覧で出力されます。ここで「変更範囲が大きすぎないか」「依存関係は正しいか」をレビューします。

Step 3: /implement

設計に問題がなければ、実装に進みます。

> /implement タスクフィルタリング機能

AIは仕様と設計を参照しながら、タスクを1つずつ実装していきます。仕様に書かれていないことは実装しないため、スコープが膨らむ心配がありません。

全体戦略: 大規模プロジェクトでSDDを回す

実務では1つの機能だけでなく、20〜30のチケットを並行して進めることがあります。SDDを大規模に適用するときのポイントを整理します。

specsディレクトリの運用

specs/
├── KP-010-dashboard-redesign/
│   ├── spec.md                    # 仕様
│   ├── design.md                  # 技術設計
│   └── status: completed          # ステータス（ファイル名で管理）
├── KP-015-task-filtering/
│   ├── spec.md
│   ├── design.md
│   └── status: in-progress
├── KP-016-notification-system/
│   ├── spec.md
│   └── status: spec-review        # 仕様レビュー中
└── KP-017-export-csv/
    └── status: drafting            # 仕様作成中

バッチ戦略

ポイント: 仕様作成とレビューをまとめて先に済ませておくと、実装フェーズではAIに仕様を渡すだけで並列実行できます。Agent TeamsやClaude Code の複数セッションと組み合わせると、3〜4件の実装を同時に進められます。

仕様のレビューは「diff 1000行のPR」と同じ

SDDの注意点は、仕様が膨大になるとレビューできなくなることです。cc-sddなどのツールが自動生成する仕様は詳細すぎて、人間が確認しきれないケースがあります。

おすすめは 自作スラッシュコマンドで「自分がレビューできる粒度」に仕様を調整するアプローチです。完璧な仕様書を目指す必要はありません。AIが推測しなくて済む程度の明確さがあれば十分です。

Tips・注意点

1. 小さく始める

いきなり全フェーズを導入する必要はありません。まずは /spec コマンドだけ作って、「実装前に仕様を書く」習慣をつけましょう。

2. 仕様は「完璧」でなくていい

SDDの目的は完璧な仕様書を書くことではなく、AIの推測を減らすことです。曖昧な点が3つあったプロンプトを、曖昧な点が0〜1つの仕様にできれば十分です。

3. AGENTS.md / CLAUDE.mdとの組み合わせ

仕様ファイルは個別機能の定義ですが、プロジェクト全体のルール（コーディング規約、ディレクトリ構成、技術スタック）は AGENTS.md や CLAUDE.md に書いておきます。仕様には「何を作るか」、AGENTS.md / CLAUDE.mdには「どう作るか」を分離するイメージです。

4. 仕様ファイルはGitで管理する

仕様ファイルをGitにコミットしておくと、「なぜこの実装にしたのか」が後から追跡できます。PRに仕様ファイルの変更を含めることで、コードレビューの質も向上します。

まとめ

SDD（仕様駆動開発）は、AI開発の精度を安定させるためのシンプルな原則です。「コードを書く前に仕様を書く」——それだけで、修正ループの削減、コードの一貫性向上、チーム共有の容易さを実現できます。

まずは .claude/commands/spec.md を1つ作って、次の機能開発で「先に仕様を書く」を試してみてください。修正ループが1回減るだけでも、体感できるほどの効率改善があるはずです。

---

参考リンク：

• SDD（仕様駆動開発）のスラッシュコマンドを自分で作って運用している — shibayu36
• Spec-driven development with AI — GitHub Blog
• GitHub Spec Kit
• Spec Driven Development