Claude Codeで実現する仕様駆動開発(SDD)

こんにちは、LuupのUser Product Group Backend Teamのバックエンドエンジニア、Jang(チャン)です。

この記事はLuup Developers Blog Advent Calendar 2025 17日目の記事です。

AIエージェントと一緒に開発していて、「3時間前に立てた計画、何だっけ？」とチャット履歴をスクロールしたり、会話が長くなって重要な計画がコンテキストに埋もれてしまった経験はありませんか？私はこの問題を解決するために仕様駆動開発(Spec-Driven Development, SDD)を導入し、実際に活用しています。この記事では、その経験と知見を共有したいと思います。

TL;DR

課題： AIコーディングでは計画が会話に埋もれてしまいます（Vibe Codingの方向性喪失 + Plan Modeのコンテキスト汚染）。

解決策： SDDはPRDをファイルとして保存し、「1 Todo = 1 Commit = 1 Spec Update」の原則で同期します。

効果： 開発時間27-43%短縮、バグ71-83%削減、コードレビュー63-71%短縮。

差別化要素： Claude CodeのConfiguration as Codeで全設定をMarkdownで管理できます。

AI コーディングの根本的な問題

私は普段、AIエージェントを活用して開発しています。当初は特別な方法論なしに始めましたが、どちらのアプローチにも明確な限界があることに気づきました。

Vibe Coding: 「とりあえず実装して考えよう」

Vibe Codingは、CursorやWindsurfなどのAIエージェントで最も自然に始まる方式です。計画を最小限にして、すぐに実装に入ります。

// ユーザーの指示
// 「ユーザー認証機能を作って」

// 計画なしですぐに実装開始
export function login(email: string, password: string) {
  if (email && password) {
    return { token: "abc123" };
  }
}

最初は簡単に見えましたが、開発を進めるうちに要件が次々と出てきます。30分後には「パスワードハッシュも必要だ」、1時間後には「OAuthもサポートすべきでは」、2時間後には「JWT refresh tokenも…」、3時間後には「これ、DBトランザクション処理は…？」。この辺りで「最初から作り直した方がいい」と思うようになります。

問題は3つあります。

1. 方向性の喪失：全体像なしに始めたため、新しい要件が出るたびに混乱する。

2. 終わりのないリファクタリング：最初10行で始めたコードが、30分後50行、1時間後150行、2時間後300行と膨らみ、構造を何度も変更する。

3. 隠れた要件の発見：4時間開発した後に「これ、rate limitingが必要だけど…」という話が出ると、全体アーキテクチャに影響する。最初に計画していれば30分で済んだものを、4時間かけたコードのほとんどを修正することになる。

実際に時間を測定したところ、Vibe Codingでは実装2時間、リファクタリング1回目1時間、リファクタリング2回目1.5時間、バグ修正1時間で合計5.5時間かかりました。一方、SDDでは仕様作成30分、実装2時間、検証30分で合計3時間でした。

Plan Mode: 「計画は立てるけど...」

Plan ModeはVibe Codingよりは体系的です。AIがまず計画を立て、ユーザー承認後に実装を始めます。

User: 「ユーザー認証機能を実装して」

AI (Plan Mode):
1. データベーススキーマ設計
2. JWTトークン生成ロジック実装
3. ログインAPIエンドポイント作成
4. ミドルウェアで認証検証追加
5. テスト作成

この計画で進めますか？

しかし、依然として根本的な限界があります。最大の問題は、会話が長くなるとAIが初期計画を「忘れてしまう」ことです。

Day 1 午前9時に「OAuth認証機能を追加して」と依頼し、AIが計画を立てます。しかしDay 1 午後3時、200メッセージをやり取りした後、「元の計画は何だったっけ？」と聞くと、AIは「チャット履歴を見ると…provider設定まで完了したようです」と答えますが、実際には初期計画の詳細を覚えていません。Day 2に新しいセッションを開始すると、「どこまでやったっけ？」という質問に「前のセッションの内容は見えません。コードを見て推測します」と答えます。

Auto-Compactの構造的問題

ここでさらに深刻な問題があります。ほとんどのAIエージェント(Claude、Cursor、Windsurf)は、会話が長くなると以前の内容を自動的に圧縮します。まるで議事録を要約するかのように。

一度圧縮されると元に戻せません。 元の会話が500トークンだったとしても、「OAuthにGoogleも追加する？」「セキュリティー上、state検証が必要です。PKCEフロー推奨です。Client Secretは環境変数で管理して…」「PKCEは複雑すぎる。とりあえずstandard flowで」といった会話が、Auto-Compact後には50トークンで「OAuthにGoogle追加。Standard flow使用。Rate limiting含む」に圧縮されます。「なぜPKCEを使わなかったのか」「セキュリティーのtrade-off」「Redis使用理由」がすべて消えます。

これが最大の問題です。一度要約されると、元の会話は永遠に失われます。

コンテキストの意味が歪曲され、時間的文脈が失われ、情報が断片化されます。重要な決定が時系列で散らばり、特定のトピック（例：OAuth設定）のすべての議論を一目で見ることができません。

SDD: ファイルベースの仕様管理で問題解決

核心原則：「1 Todo = 1 Commit = 1 Spec Update」

SDDを一文で説明すると、「AIと一緒に開発する際、計画をファイルとして保存し、小さな作業単位でコード・コミット・ドキュメントを同時に更新する方法論」です。

実装完了 → git commit → 仕様更新 → コードレビュー
    ↓           ↓              ↓              ↓
  1 Todo    1 Commit    CHANGELOG.md      /code-review
                       tasks/XX.md
                       status.json

なぜこうするのでしょうか？AIと会話しながら開発すると、最初に立てた計画が会話に埋もれてしまう経験、皆さんあるでしょう。SDDはこの問題を3つの方法で解決します。

1. コード作成前にPRDドキュメント作成：「何を作るか」をまずファイルに残す
2. 小さな単位で同時更新：Todo 1つ終えるたびに、コード、コミット、ドキュメントを一度に更新する
3. 自動検証：人が忘れてもシステムが「ドキュメント更新してない？」と教える

PRD.md 永久保存 vs AI メモリーの揮発性

Plan ModeのAuto-Compact問題をSDDがどう解決するか、具体的に見てみましょう。

不可逆的圧縮 → 永久保存

# Compact: 情報損失
AI メモリ: "OAuth 追加予定" (50トークン)
           (詳細はauto-compactで損失)

# SDD: 完全な記録
~/.claude/specs/oauth-integration/PRD.md
  Section 3: 要件 (なぜ必要か)
  Section 4: 技術仕様 (どう実装するか)
  Section 6: 設計決定 (なぜこうしたか)

  + CHANGELOG.md (いつ何が変更されたか)
  + Git 履歴 (すべてのバージョン追跡)

主観的圧縮 → 明示的ドキュメント化

AIが「重要でない」と判断したものを削除するCompactとは異なり、SDDはすべての決定根拠を明示します。PRDには選択したオプション、検討した代替案、選択理由、Trade-off、補完策がすべて記録されます。

時間的コンテキスト → 変更履歴

Compactが最終状態だけを残すのとは異なり、SDDはCHANGELOG.mdですべての変更を追跡します。いつ変更されたか、なぜ変更されたか、誰が承認したか、影響範囲はどこかが明確に記録されます。

バージョン管理不在 → Git 履歴

Compactは元に戻せませんが、SDDはGitですべてのバージョンを管理します。必要なら以前のバージョンを確認・復元でき、どの部分が変更されたか正確に比較できます。

Claude Codeで実装するSDD

なぜClaude Codeか: Configuration as Code

KiroやBolt.newのようなSDD専用IDE（GUIベースの仕様駆動開発ツール）も存在します。それでもClaude Codeを選んだ理由は、Configuration as Codeと拡張性です。

Kiroは、PRDテンプレートをGUIで選択し、提供されたオプション内でのみ設定可能です。一方、Claude Codeはすべての設定をMarkdownファイルで管理します。

~/.claude/
├── commands/
│   ├── create-spec.md      # スラッシュコマンド（修正可能）
│   ├── code-review.md
│   └── update-spec.md
├── templates/
│   ├── prd-template.md     # PRDテンプレート（カスタマイズ）
│   └── task-template.md
└── skills/
    ├── spec-validator/     # 検証ロジック（プログラミング可能）
    ├── spec-tracker/
    └── spec-suggester/

この方式の利点は3つです。

1. Gitでバージョン管理が可能：設定の変更履歴を追跡できる
2. プロジェクト別カスタマイズが可能：バックエンド用、フロントエンド用など、プロジェクトに応じたテンプレートを作成できる
3. 設定の再利用が可能：一度作成した設定を他のプロジェクトにコピーして使える

CLAUDE.md 自動パースも強力な機能です。プロジェクトのルールをファイルで定義すると、/create-spec実行時に自動抽出されます。

# CLAUDE.md (プロジェクトルート)

## Development Guidelines

### Architecture

- DDD (Domain-Driven Design) パターン遵守
- Controllerにビジネスロジック禁止
- Domain Layerは外部依存性なし

### Code Style

- ESLint + Prettier 使用
- 関数は最大50行
- 複雑度(Cyclomatic Complexity) 10以下

/create-spec user-authentication 実行時にPRD.mdが自動生成され、Section 2に「Repository Best Practices」がCLAUDE.mdから自動抽出されます。そしてspec-validatorがリアルタイムでCLAUDE.mdルールを検証します。

スラッシュコマンドシステム

すべてのコマンドはMarkdownファイルで定義されます。実行の流れは次のようになります。

/create-spec oauth-integrationを実行すると：

1. CLAUDE.md 読み取り → プロジェクトルール抽出
2. 既存コード分析 → パターン学習
3. PRD生成（50KB、Section 1-8含む）
4. CHANGELOG.md、status.json、README.md生成
5. tasks/フォルダーに3つのタスクファイル生成
6. 各タスク用スラッシュコマンド自動生成（/oauth-integration-task-01、/oauth-integration-task-02、/oauth-integration-task-03）

スキルシステム: Claude CodeのSkills機能を活用した検証と追跡

Claude CodeのSkills機能を使うことで、仕様の検証と進捗追跡を実現できます。Skillsはカスタムロジックをマークダウンで定義し、特定の条件で自動的に起動させることができる強力な機能です。

通常のコードレビューとの違いは何でしょうか？通常のコードレビューは「完成したコードを事後的にチェック」しますが、SkillsはClaude Codeの実行プロセスに組み込まれるため、「コード作成中にリアルタイムで検証」できます。例えば、spec-validatorは以下のタイミングで自動起動します：

• ユーザーがコードを書いた直後（Write/Edit tool使用後）、即座に仕様との整合性をチェック
• 実装開始時にPRDを参照して実装方針を確認
• 定期的な同期チェック（30分ごと）で仕様との乖離を早期発見

さらに、Skillsはプロジェクト固有のルール（CLAUDE.md）を理解し、コンテキストを保持したまま検証します。単純な静的解析ツールではなく、「なぜこの実装になったのか」というPRDの意図まで理解して検証できる点が大きな優位性です。

spec-validatorは関連仕様を検索し、修正されたファイルパスから機能を推論します。そしてリアルタイムで仕様→コード検証（APIエンドポイント一致、データモデルスキーマ一致）とコード→仕様drift検証（文書化されていない機能、仕様と異なる実装）を実行します。

実行例：

// ユーザーがコード作成
// src/api/auth.ts
export const loginEndpoint = "/api/auth/signin";

// spec-validator 自動アクティブ化
⚠️ 仕様準拠の問題を検出

ファイル: src/api/auth.ts
仕様: ~/.claude/specs/user-authentication/PRD.md

問題:
1. エンドポイント名の不一致
   - PRDの期待値: POST /api/v1/auth/login
   - 現在: POST /api/auth/signin

オプション:
1. 仕様に合わせてコードを修正
2. 仕様を更新 (/update-spec)
3. 意図的な差異として文書化

spec-tracker（進捗追跡）を呼びだす例：

• git commit後
• ユーザーが進捗を問い合わせ時（/spec-status）
• タスク完了後

このSkillは、コミットにコード変更と仕様更新（tasks/*.md、CHANGELOG.md）の両方が含まれているか検証し、仕様更新が漏れていれば警告します。status.jsonを更新して、完了したタスク、全体進捗率%、最後の活動時間を追跡し、依存性と優先度に基づいて次のタスクを推奨します。

コンテキスト管理戦略: メモリー効率的な動作

AIはトークン数の制限により、すべてのPRDをメモリーに保持できません。そのため、必要な部分だけを選択的にロードします。

例えば、/oauth-integration-task-02を実行すると：

1. status.json 読み取り → Task 02 の位置を確認
2. tasks/02-token-exchange.md 読み取り（このタスクのみ）
3. PRD.md Section 4.4 読み取り（関連セクションのみ）
4. CHANGELOG.md 最後の5項目のみ読み取り

→ 全体PRD 50KBのうち5KBのみロード
→ トークン節約しながら必要なコンテキストを確保

スマートローディングの例：

ユーザー: "OAuth state検証をどう実装する?"

AI の動作:
1. "state" キーワードでPRDを検索
2. Section 4.6 "Security - State Validation" を発見
3. 該当セクションのみロード
4. 回答生成

→ 50KB PRD全体ではなく、関連する2KBのみロード

このアプローチにより、Claude Codeは大規模なプロジェクトでも効率的に仕様を管理できます。ファイル構造も階層化されており（PRD.md、tasks/、CHANGELOG.md、status.json）、必要な部分だけを選択的にロードすることで、トークン節約と高速レスポンスを両立しています。

実戦ワークフローと効果

実測データ

実際のプロジェクトで測定したSDDの効果です。

開発時間短縮 - OAuth認証機能実装比較（3日想定）:

方式	総時間	実装	リファクタリング	バグ修正	ドキュメント化
Vibe Coding	28時間	12h	8h	6h	2h
Plan Mode	22時間	10h	5h	4h	3h
SDD	16時間	10h	1h	2h	3h（自動）

時間節約： vs Vibe Coding 43%短縮（12時間節約）、vs Plan Mode 27%短縮（6時間節約）

主な削減要因は、リファクタリング時間80%削減（事前アーキテクチャ設計）、バグ修正時間67%削減（spec-validator リアルタイム検証）、ドキュメント化時間自動化（CHANGELOG.md、status.json 自動更新）です。

バグ削減率 - 仕様不一致によるバグ：

Vibe Coding: 平均12件/機能
  - APIエンドポイント不一致: 4件
  - データモデル不一致: 3件
  - 漏れた要件: 5件

Plan Mode: 平均7件/機能
  - APIエンドポイント不一致: 2件
  - データモデル不一致: 2件
  - 漏れた要件: 3件

SDD: 平均2件/機能
  - spec-validatorが事前ブロック: 5件
  - 自動検証で早期発見: 3件
  - 実際のプロダクションバグ: 2件

バグ削減率： vs Vibe Coding 83%削減、vs Plan Mode 71%削減

コードレビュー時間削減：

段階	Vibe Coding	Plan Mode	SDD
コンテキスト把握	30分	20分	5分（PRD読む）
要件確認	20分	15分	0分（PRD参照）
アーキテクチャ検証	25分	20分	5分（自動検証済み）
コード品質レビュー	30分	25分	20分
合計時間	105分	80分	30分

レビュー時間削減： vs Vibe Coding 71%短縮、vs Plan Mode 63%短縮

削減理由は、PRD.mdにすべてのコンテキストが文書化されており、spec-validatorがアーキテクチャ遵守を既に検証しており、/code-reviewコマンドを使ってcursor-agent経由で事前レビューしているためです。

いつSDDを使い、いつ避けるべきか

SDDがオーバーヘッドになる場合：

1. 小さなバグ修正 -「ログインボタンのテキスト誤字修正」「CSS余白2px調整」のような場合、仕様作成時間が実際の修正時間より長いため、仕様なしで直接修正または簡単なmini-spec（5分）を作成
2. 探索的コーディング（POC）-「このライブラリーが正しく動作するか素早くテスト」「アルゴリズム性能比較実験」のような場合、実験失敗の可能性を考えると仕様作成時間は無駄になる。Phase 1ではPlan Modeによる素早い実験（1-2時間）を行い、成功確認後にPhase 2でSDDへ転換
3. 緊急Hotfix -「プロダクション障害！今すぐ修正必要」のような場合、速度が最優先。即座に修正・デプロイ後、事後文書化

いつSDDを避けるべきか？

状況	推奨方式	理由
1時間未満の作業	Vibe Coding	仕様作成オーバーヘッド > 実際の作業
実験/POC	Plan Mode	失敗可能性高い、迅速なiteration必要
緊急Hotfix	Vibe Coding	速度が最優先、事後文書化
UIプロトタイプ	Plan Mode	複数バージョンを素早く試行
プロダクション機能	SDD	品質、保守性重要
1日以上の作業	SDD	コンテキスト保存必要
チーム協業	SDD	明確な文書化必要
アーキテクチャ遵守重要	SDD	自動検証必要

核心基準： 仕様作成時間 < 削減される時間 → SDD使用、仕様作成時間 > 削減される時間 → Vibe/Plan Mode

SDDへの懐疑的視点

SDDが万能の解決策ではないことも認識しておく必要があります。業界では複数の懸念と批判が提起されています。

まず、現在のツール実装に対する懸念です。「SDDツールは過度に複雑で、改善しようとして逆に悪化させる可能性がある」という指摘があります。特にワークフローの柔軟性不足、レビュー複雑度の増加、AI生成に対する実質的な制御権の問題が挙げられています。

技術的な側面でも限界があります。「Spec driftとhallucinationは本質的に避けられない」という指摘です^[1]。AIの生成するコードは非決定的（non-deterministic）であり、仕様とコード間の不一致を発生させる可能性があります。これは依然として厳格なCI/CD実践を必要とする理由です。さらに、2025年末現在も「良い仕様とは何か」についての業界合意はありません。プロンプトエンジニアリングのevalのように仕様を体系的に評価する方法もまだ確立されていません。

実践的な課題もあります。経験豊富な開発者にとって、過度に形式化された仕様は変更とフィードバックサイクルを遅らせる可能性があり、waterfallの初期段階で遭遇したような問題を引き起こす恐れがあります^[1:1]。また、SpecとCodeのどちらが最終成果物であるべきかという根本的な問いも未解決で、この選択によってまったく異なるワークフローと開発実践につながります。

より根本的な批判もあります。一部では、SDDが技術的課題の解決というより、AI企業の高いバリュエーション（ARRの25-70倍）を正当化するための手段である可能性を指摘しています^[2]。「70%自動化」といった主張は、実際のコーディングの複雑性を反映していないという意見です。実際に週末実験の結果、Plan Modeがgreenfield プロジェクト、プロトタイプ、1人開発においてSDDより優れていたという報告もあります^[3]。SDDは大規模レガシーコードベースやチームプロジェクトでより価値があるかもしれません。

これらの批判はすべて妥当です。SDDは2025年末時点でもemerging practiceであり、完璧な解決策ではありません。しかし私の経験上、1日以上のプロダクション機能開発では、Vibe CodingやPlan Modeより明確に優れていました。重要なのは、プロジェクトの特性に応じて選択することです。

おわりに

SDDが解決するAIコーディングの根本的問題

Vibe Codingの問題（方向性喪失、終わりのないリファクタリング、隠れた要件）は、PRDに全要件を明記しアーキテクチャを事前設計することで解決されます。また仕様作成段階で問題を発見できます。

Plan Modeの問題（コンテキスト汚染、トークン数制限、Auto-compact、変更追跡不在）は、PRD.mdの永久保存、ファイルベースの無制限保存、圧縮なしの完全保存、CHANGELOG.mdの自動記録、Git履歴で解決されます。

Claude Codeの技術的差別化要素

Configuration as Codeですべての設定をMarkdownで管理し、CLAUDE.md自動パースでプロジェクトルールを自動反映し、プログラミング可能な検証でスキルをMarkdownで拡張し、既存ツールチェーンを活用してVSCode、Git、CI/CDをそのまま使用できます。

AIコラボレーションの未来

SDDを通じて、AIエージェントは単純なコード生成器ではなく、真の開発パートナーになります。計画は会話に埋もれることなくPRDファイルとして永久保存され、Auto-compactによる情報損失もGitがすべてのバージョンを管理します。「なぜこう実装したっけ？」と悩む必要はなく、PRDとCHANGELOGがすべての意思決定理由を説明します。

SDDは完璧な解決策ではありませんが、AIとのコラボレーションにおける「計画の喪失」という根本的な課題に対する1つの有効なアプローチです。何より重要なのは、「3時間前に立てた計画、何だったっけ？」とチャット履歴をスクロールする必要がなくなることです。すべての計画、決定、理由がファイルとして残り、Gitで追跡可能で、AIがいつでも正確に参照できます。

核心原則：「1 Todo = 1 Commit = 1 Spec Update」

この原則1つを守れば、コードとドキュメントが自動的に同期し、AIとのコラボレーションがより生産的になります。SDDで皆さんのAIコーディング体験を一段階アップグレードしていただければ幸いです。

最後までお読みいただきありがとうございました。

明日18日目の記事もお楽しみに！

参考文献

• Spec-Driven Development with Claude Code - Arsturn Blog
• Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl - Martin Fowler
• Spec-driven development: Unpacking one of 2025's key new AI-assisted engineering practices - Thoughtworks
• AI Dev: Plan Mode vs SDD - A Weekend Experiment - Maxim Saplin
• Is AI a Bubble? I Didn't Think So—Until I Started Working On This Analysis - Hyperdev by Matsuoka

---

We are hiring

Luupでは、組織と個人の技術面での成長をどちらも大事にしながら、未来のモビリティインフラを一緒に創っていけるソフトウェアエンジニアを積極的に募集しています。

CTOや各開発チームのリーダーともカジュアル面談で直接話せる応募フォームも掲載しておりますので、ぜひお気軽にお声掛けください！
Luup採用情報

また技術発信も多くしているので、ぜひ興味ある方はそちらも覗いてみてください！
Luup Developers(Zenn)

脚注

1. Spec-driven development: Unpacking one of 2025's key new AI-assisted engineering practices - Thoughtworks

2. Is AI a Bubble? I Didn't Think So—Until I Started Working On This Analysis - Hyperdev by Matsuoka

3. AI Dev: Plan Mode vs SDD - A Weekend Experiment - Maxim Saplin