Claude Codeで実践する仕様(スペック)駆動開発入門

吉田真吾 (@yoshidashingo) です。

これだけは覚えて帰ってね💡

  • バイブコーディングの対極にある仕様駆動開発は、ソフトウェアエンジニアリングの基本原則をAI時代に再現するアプローチ
  • 仕様駆動開発は仕様で「開発ライフサイクルを」駆動するのではない。仕様を唯一の情報源 (Single Source of Truth) としつつ、プロセスはルールブックによって駆動される
  • Claude Codeでのステアリングには複数の方法があり、CLAUDE.md・スキル・AI-DLCのルールブックなど、目的に応じた使い分けと創意工夫の余地がある

実践Claude Code入門―現場で活用するためのAIコーディングの思考法 エンジニア選書

実践Claude Code入門―現場で活用するためのAIコーディングの思考法 エンジニア選書

Amazon

本日、デブサミで登壇してきました。

event.shoeisha.jp

Claude Codeで実践するスペック駆動開発入門 speakerdeck.com

『実践Claude Code入門』の第4章で触れているスペック駆動開発について、最近個人的にハマっている『AI-DLCワークフロー』まで含めて解説しました。

バイブコーディングの何が問題か

Andrej Karpathyが2025年2月に「Vibe Coding」を提唱したとき、彼は個人プロジェクトの文脈で語っていました。「Vibeに身を委ね、コードが存在することすら忘れる」── プロトタイプの探索やアイデアの検証には有効なアプローチです。しかし、プロダクションコードに同じアプローチを持ち込むと何が起こるでしょうか。

Werner Vogelsは、AWS re:Invent 2025のキーノートでこう断じました。

"We can't just pull a lever on your IDE and hope that something good comes out. That's not software engineering. That's gambling."

「IDEのレバーを引いて、いいものが出てくることを願う。それはソフトウェアエンジニアリングではない。ギャンブルだ」。

実務の現場で起きる問題は具体的です。

Verification Debt (検証負債) の蓄積。 AIがコードを生成する速度は、人間が理解・検証する速度をはるかに超えます。従来の技術的負債が「理解した上での妥協」であるのに対し、検証負債は「そもそも何が問題なのかわからないまま積み上がった構造」です。負債の存在すら認識できないという点で、従来の技術的負債よりも深刻です。

「動くけど何をしているか分からないコード」の増殖。 バイブコーディングでは、AIが生成したコードの内部構造を精査せずに「だいたいうまくいく」ことを確認して先に進みます。短期的にはプロジェクトは前に進みますが、コードベースの中に「誰も理解していない領域」が広がっていきます。

デバッグ不能な状態への到達。 問題が発生したとき、コードの意図を誰も理解していなければ、デバッグは困難です。AIに「直して」と頼んでも、文脈を理解していないAIが場当たり的な修正を重ねるだけで、根本原因にたどり着けません。

バイブコーディングを全否定するのは公平ではありません。問題は、プロトタイプで通用するアプローチをプロダクションコードにそのまま持ち込むことにあります。

仕様駆動開発とは何か

Thoughtworks Technology Radarでの位置づけ

仕様駆動開発 (Spec-driven Development) は、Thoughtworks Technology Radar Vol.32 (2025年4月) でTrial (試験運用) として採用された手法です。その核心は、仕様 (Spec) を先に定義し、その仕様に基づいてAIにコードを生成させることにあります。

これは新しい発明ではありません。ソフトウェアエンジニアリングが数十年にわたって実践してきた基本原則 ── 要件を定義し、設計し、実装し、テストする ── をAI時代に再適用したものです。AWS re:Invent 2025でVogelsが紹介したKiro IDEも、Requirements → Design → Tasks → Code Generationというフローでこの思想を体現しています (Kiro IDEのデモは、KiroチームのシニアプリンシパルデベロッパーClare Liguoriが担当しました) 。

仕様書とは何か

仕様駆動開発における「仕様 (Spec)」は、一種類の文書ではありません。開発のフェーズに応じて、さまざまな形をとります。

仕様の種類 役割 例
要求仕様 (Requirements Spec) 何を作るか、なぜ作るかを定義 ユーザーストーリー、EARS記法の要件文
設計書 (Design Doc) アーキテクチャと技術的設計を記述 コンポーネント図、API仕様、データモデル
ユビキタス言語 (Ubiquitous Language) ドメインの用語をチーム内で統一 用語集、ドメインモデル図
テスト仕様 (Test Spec) 期待する振る舞いを事前に定義 テストケース、受入基準
実行計画書 (Task Plan) 実装の順序と単位を規定 タスクリスト、スプリントバックログ

これらの仕様書群が「何を作るか」の情報源となり、AIはこれらを参照してコードを生成します。

仕様駆動 ≠ 仕様でプロセスを駆動する

ここで重要な区別があります。「仕様駆動」という名前から、仕様書が開発プロセス全体を駆動するかのように聞こえますが、実態は異なります。

仕様は「唯一の情報源 (Single Source of Truth)」であって、「プロセスの駆動源」ではありません。

何を作るかを定義するのは仕様の役割です。一方、どのような手順で・どのような品質基準で・どのような承認プロセスを経て作るかを決めるのは、仕様ではなくプロセスルール (ルールブック) の役割です。

なぜこの区別が重要なのか。仕様がプロセスを駆動すると考えると、「仕様書を書けばあとはAIが勝手にやってくれる」という誤解に陥ります。実際には、仕様の粒度をどう調整するか、どの段階で人間が承認するか、タスクの複雑さに応じてプロセスの深度をどう変えるか ── これらはすべてプロセスルール側の責務です。Kiro IDEのRequirements → Design → Tasks → Codeという順序制約も、仕様の「内容」ではなく「プロセス」のルールです。

『実践 Claude Code 入門』で体験する仕様駆動開発

仕様駆動開発の原則は理解できた。では、実際にClaude Codeでどう実践するのか。『実践 Claude Code 入門』(以下、本書) の第4章では、Claude Codeを使った仕様駆動開発を読者が一通り体験できるように構成されています。

第4章の概要

本書第4章では、CLAUDE.md をステアリングファイルとして活用し、以下のフローで仕様駆動開発を進めます。

  1. CLAUDE.md にプロジェクトの制約・規約・文脈を定義する
  2. .steering/ 配下に作業バッチフォルダを作成する
  3. 作業バッチごとに要件定義書・設計書・タスクリストを生成・保存する
  4. タスクリストに沿ってコードを生成し、テストする

Claude Codeの標準機能だけで完結するため、特別なフレームワークやプラグインは不要です。仕様駆動開発の「仕様を先に定義し、その仕様に基づいてコードを生成する」という原則を、最小構成で体験できます。

4章で作成する CLAUDE.md の例は以下で公開されています。

github.com

CLAUDE.md をステアリングにする功罪

4章でClaude Codeと壁打ちして開発ルールを CLAUDE.md に記載するアプローチは、仕様駆動開発の入門ハードルを下げていますが、プロジェクトの規模が大きくなるにつれて限界が見えてきます。

メモリファイルの肥大化。 開発ルールが増えるにつれて、CLAUDE.mdが膨れ上がります。Claude Codeのコンテキストウィンドウには上限があり、起動時に必ず読み込まれるメモリに今すぐ必要ではないかもしれないすべてのルールを読み込む意味はありません。開発ルール自体を工程や手法ごと、ドキュメント種別ごとに適切に構造化しておくことで、必要なタイミングで段階的開示されるように仕組み化しましょう。

ワークフローの適応性の低下。 本書で示した CLAUDE.md に制約を書き、.steering/に仕様を保存する方式では、「どのような順序で作業を進めるべきか」のプロセスルールまでは明示的に定義されていません。仕様書類に抜け漏れがないこと、観点漏れがないことなどは担保されておらず、生成された仕様書をチェックする人間のスキルに委ねられます。

本書は仕様駆動開発の入門部分を理解するために、プロセスの複雑さや構造的な構成を避けた結果です。チーム開発や監査要件が厳しい環境では、より構造化されたアプローチが必要になります。

AI-DLCのステアリング ― フレームワークレベルの規律

AI-DLCは、前セクションで挙げた限界に対して構造的な解決策を提供しています。

本書のアプローチとの対比

観点 本書のアプローチ AI-DLCワークフローのアプローチ
ステアリング CLAUDE.md (制約と文脈) CLAUDE.md + core-workflow.md + ルールブック
仕様の管理 .steering/ に作業バッチ単位で保存 aidlc-docs/ にステージ単位で保存
プロセスの駆動 CLAUDE.mdのプロンプトに依存 ルールブックがステージ順序を規定
状態管理 .steering/ 内のタスクリスト aidlc-state.md (専用ファイル)
監査証跡 タスクリストの完了状態 audit.md (全やり取りをタイムスタンプ付きで記録)

コアワークフローとルールブックによるプロセス駆動

AI-DLCワークフローでは、CLAUDE.md はプロジェクトの文脈 (技術スタック、ディレクトリ構造、コーディング規約) を伝える役割に留まります。プロセスの駆動は、core-workflow.md (ワークフロー定義) とルールブック (aws-aidlc-rule-details/) が担います。

これは、前セクションで述べた「仕様 ≠ プロセスの駆動源」という原則のアーキテクチャレベルの実装です。仕様書はaidlc-docs/に保存されますが、開発プロセスの順序・深度・承認タイミングは、ルールブックが規定します。

AI-DLCワークフローをClaude Codeで利用するガイダンスとして core-workflow.md を CLAUDE.md に上書きして使う記述も見られますが、適応型ワークフローの柔軟性を確保するという点からは推奨されません。

順序の強制。 Requirements Analysis → Workflow Planning → Functional Design → Code Generationという順序がフレームワークレベルで固定されています。「仕様を先に定義し、コード生成は後」という原則が、プロセスの構造に組み込まれています。

承認ゲートによるHuman-in-the-Loop。 14ステージ中13ステージに承認ゲートが設けられています。仕様書に「DO NOT PROCEED until user confirms」と明記されている通り、承認なしに次のステージへ進むことはできません。

Adaptive Depthによる深度調整。 同じステージでも、タスクの複雑さに応じて3段階 (Minimal / Standard / Comprehensive) で深度が自動調整されます。仕様駆動開発の「重さ」がタスクに合わせて伸縮します。

状態管理と監査証跡の分離

AI-DLCは、状態管理と監査証跡を専用ファイルに分離しています。aidlc-state.md が現在のフェーズ・完了したステージ・保留中のタスクなどの進捗状態を記録し、audit.md がすべてのユーザー入力とAI応答をタイムスタンプ付きで原文のまま記録します。

証跡の限界。 本書では作業バッチ単位のタスクリストを事実上の証跡として扱っています。しかし、タスクリストには「何をやったか」は記録されても、「なぜその判断をしたか」「ユーザーとAIの間でどのようなやり取りがあったか」は残りません。

本書のタスクリストが「何をやったか」の記録に留まるのに対し、audit.mdは「なぜその判断をしたか」までを含みます。規制対応やチーム間のナレッジ共有が求められるエンタープライズ環境では、この差は大きな意味を持ちます。

ルールブックの二層構造による組織カスタマイズ

AI-DLCのルールブックは、ベースレイヤーと拡張レイヤーの二層構造を採用しています。

aws-aidlc-rule-details/    ← ベースレイヤー (AI-DLC標準、変更不可)
ga-aidlc-rule-details/     ← 拡張レイヤー (組織固有のカスタマイズ)

ベースレイヤーがフレームワーク標準のルールを提供し、拡張レイヤーが組織固有の知見・品質基準・テンプレートで補完します。フレームワークの標準プロセスを壊さずに、業界固有の規制要件や社内の品質基準を追加できる設計です。

スキル化の功罪と適応型ワークフロー

スキルによる定型作業のコマンド化

Claude Codeのスキル (Skills) は、定型作業を手順化して再利用可能にする仕組みです。.claude/skills/にMarkdownファイルを配置すると、/スキル名で呼び出せるプロジェクト固有のスキルとして登録されます。

注: Claude Codeの初期バージョンでは.claude/commands/に配置する「カスタムスラッシュコマンド (Custom Slash Commands)」として提供されていた機能です。現在は.claude/skills/配下の「スキル (Skills)」に移行されています。

# .claude/skills/tdd-cycle.md の例
以下のTDDサイクルを実行してください:

1. $ARGUMENTS に基づいてテストファイルを作成する
2. テストを実行し、失敗することを確認する (Red)
3. テストを通す最小限の実装を書く (Green)
4. テストが通ることを確認する
5. コードをリファクタリングする (Refactor)
6. テストが引き続き通ることを確認する

このようなタスク単位のスキルは、スキルの中では手順に従い、スキルの外では自由に振る舞います。TDDサイクルを実行した後、次に何をするかはAIが状況に応じて判断できます。適応型ワークフローの中に事前定義型のサブワークフローを埋め込む手法であり、スキルの粒度が小さい限り、適応型ワークフローの柔軟性は保たれます。

aidlc-cc-plugin ― フルプロセスのスキル化が招く制約

しかし、スキル化の粒度を大きくすると話が変わります。AI-DLCの実行をフルプロセスでスキル化したaidlc-cc-plugin がその例です。このプラグインはClaude CodeにAI-DLCのワークフローをスキルとして組み込みます。

aidlc-cc-pluginでstartコマンドを実行すると、AI-DLCのフェーズに沿った実行が開始されます。しかし、フェーズに沿った実行が完了するとセッションが終了します。AI-DLCのワークフローを途中で離れて別の作業をしたり、フェーズの合間に自由な対話を挟んだりすることができません。AI-DLCのフェーズ実行に特化しているため、それ以外の用途には使えないのです。

プロンプトの精度 ― すべてのアプローチに共通する土台

どのアプローチを選んでも、最も基本的なステアリング手段はプロンプトの精度です。Vogelsはキーノートで「曖昧なプロンプトは曖昧なソフトウェアになる」と述べています。

  • 具体的なインプット例: 入力値の形式・バリデーションルール・エッジケースまで明示する
  • 期待するアウトプット: レスポンスの形式・ステータスコード・セッション管理の方法まで記述する
  • 制約条件: 「セキュアに実装する」ではなく、「bcryptでパスワードをハッシュ化し、JWTの有効期限は1時間とする」のように具体化する

CLAUDE.mdの制約も、スキルのテンプレートも、ルールブックの詳細ルールも、すべてプロンプトの精度を構造的に担保する仕組みです。ステアリングの設計とは、プロンプトの精度をどの粒度で・どの層で・どこまで事前に定義するかの設計に他なりません。

まとめ

  • バイブコーディングはプロトタイプには有効だが、プロダクションコードにはVerification Debt (検証負債) を蓄積するリスクがある
  • 仕様駆動開発は仕様で「開発ライフサイクルを」駆動するのではない。仕様を唯一の情報源としつつ、プロセスはルールブック (プロセスルール) によって駆動される
  • 『実践 Claude Code 入門』のCLAUDE.md + .steering/方式は入門に適しているが、メモリファイルの肥大化・ワークフローの適応性低下・証跡の限界がある
  • AI-DLCは、コアワークフロー + ルールブックによるステアリングと、専用の状態管理 (aidlc-state.md) ・監査証跡 (audit.md) で、これらの限界を構造的に解決している
  • スキル化はプロセスの再現性を高めるが、適応型ワークフローの柔軟性とトレードオフがある。ステアリングの設計とは、プロンプトの精度をどの層で・どの粒度で事前に定義するかの設計である