Claude Codeに任せる前に仕様を書く、機能単位の仕様駆動開発

AIコーディングエージェントに「75日間のフィットネスチャレンジ用の記録アプリを作って」と頼めば、おそらく数秒で動くアプリが手に入ります。ただし、その依頼に埋もれた数十もの決定、たとえば1日できなかったらどうなるのか、データをどこに保存するのかといった点には、口を挟む余地がありません。エージェントはそれらを黙って決め、こちらが知るのはコードができあがった後です。仕様駆動開発（SDD）はこの順序を逆にします。決めるべきことを短いファイルに書き出して承認し、それから初めてエージェントに作らせるのです。コードを書くのは引き続きAIで、変わるのは誰が、いつ決めるかです。ここでは、Claude Codeでこのループがどう回るのか、そして仕様を書くまでもないのはどんな場合かを紹介します。

1行のプロンプトが代わりに決めてしまうこと

あるテストでは、Claude DesktopアプリのClaude CodeをAuto mode（ツールの実行を承認待ちで止めずに進める権限設定）で動かし、空のフォルダでこのプロンプトだけを与えました。Claudeは一度も質問しませんでした。まず、作業の指示をひとまとめにしたfrontend-designスキルを読み込み、グラフィカルなインターフェースが必要だと事実上独断で決めました。続いてindex.htmlファイル1つだけのアプリを作り、曖昧な依頼を有名なフィットネスチャレンジの75 Hardと解釈して、1日2回のワークアウト、食事制限、1ガロンの水、10ページの読書、進捗写真をハードコードしました。

Claudeが前提を「Things to know」として挙げたのは最後になってからで、厳格モードやブラウザだけへのデータ保存などが含まれていました。その時点で、ルールはすでにコードになっています。実際に使っていると、こうした前提はずっと後になって表に出がちです。たとえば13日目に、連続記録が予告なくリセットされるといった形です。

バイブコーディングが行き詰まる5つのポイント

バイブコーディングとは、作りたいものを普段の言葉で伝え、残りはAIの推測に任せ、結果をチャットで直していくやり方です。手早い反面、開発者はAIがすでに下した選択に後から反応する立場になり、次の5つの問題が起きます。

5つに共通する根本原因は1つ、重要な要件や設計判断が一度も書き留められていないことです。プロンプトを長くしても解決しません。書き漏らした部分は、結局モデルが埋めてしまうからです。一方で、手早い概念実証、ボイラープレートの用意、試作、シンプルな個人サイトのように、リスクが低く使い捨てにできる作業なら、今でもバイブコーディングが向いています。こうした作業では、正式な仕様は手間を増やすだけです。

仕様は署名入りの作業指示書のようなもの

仕様（spec）はspecificationの略で、何を、なぜ作るのかについて開発者とAIが交わす書面の取り決めです。家を建てる前に施工業者が受け取る署名入りの作業指示書と同じで、指示書に書かれていないことは現場で決められます。作り手がAIの場合も同じです。役に立つ仕様には、利用者、中心となる目標、アプリの制約、そしてソフトウェアがやらないことを明記します。ファイル名やデータ構造といった「どう作るか」はAIに任せます。承認された仕様をもとにAIが番号付きの計画を作り、開発者はコードが書かれる前にそれを確認します。この段階なら間違ったルールは返信1回で直せますが、コードができた後に直すとなると、大がかりなリファクタリングが必要になります。

これはウォーターフォール開発ではありません。ウォーターフォール開発はプロジェクト全体を何か月もかけて事前に計画しますが、SDDは機能1つ分の短いループを回します。エージェントがまったく同じ動きを2回することはありませんが、引き締まった仕様は選択の幅を狭め、推測を大きく減らします。たとえ誤りがゼロにはならないとしてもです。

仕様ファイルの構成

すべては最上位のspecsフォルダにまとめます。基本となる3つのファイルは最初に1回だけ書き、その後は機能ごとに、featuresの下の番号付きフォルダにその機能専用の3つのファイルを置きます。

検証条件は、観察して確かめられるものでなければなりません。たとえば、空のフォームでStartを押し、何も保存されないことを確認するといった条件です。あとは作業がループになります。ロードマップの次の項目を選び、その仕様を書き、承認し、AIに作らせ、検証して、完了の印を付けます。同じループはCursorやCodexでも使えます。

▲ 基本ファイルと機能ごとの仕様フォルダ

インタビューで基本ファイルを固める

グリーンフィールドプロジェクトとは、コードもコミット履歴もない空のフォルダから始めるプロジェクトです。Claudeが空のフォルダにGitリポジトリを作った後、最初のプロンプトで明確なルールを課しました。まだコードは書かず、ビジョン、技術スタック、ロードマップについて開発者に1問ずつインタビューすること。ロードマップは最大6機能とし、それぞれ1回の作業でブラウザから試せるものにすること。ClaudeにAskUserQuestionツールを使うよう求めると、インタビューは推奨回答付きの選択式の質問になりました。

Claudeはロードマップの6枠のうち3枠を必須機能に充てました。今日のチェックイン、「75日中N日目」を示す日数カウンター、そして未達成の日のやり直し処理です。残りは進捗グリッド、完了画面、バックアップのエクスポートとインポートに割り当てました。データがすべてブラウザ内にとどまるため、バックアップは重要です。バイブコーディングで作ったアプリでは過去のどの日にもチェックを付けられましたが、この仕様で編集できるのは前日だけです。技術スタックは、フレームワークもビルド工程もないプレーンなHTML、CSS、JavaScriptに決まりました。いずれも、アプリのコードがまだ存在しない段階で決まったことです。この例では時間を節約するために推奨回答をそのまま採用しましたが、実際のプロジェクトでは1問ずつ慎重に検討すべきです。

機能ごとに回す2つのプロンプト

以降、各機能は同じ2つのプロンプトを順に通ります。計画用のプロンプトが作った仕様ファイルはレビューを経てコミットされ、実装用のプロンプトが新しいチャットでそのファイルをもとに機能を作ります。機能をマージするのは、テストと手動確認の両方に合格した後だけです。

計画：インタビューしてから3つのファイルを書く

計画用のプロンプトは、Claude Codeにroadmap.mdから未着手の次の機能を選ばせ、feature/1-todays-check-inのように命名規則に沿ったブランチを作らせたうえで、コードを書かずに開発者へインタビューさせます。最初の機能である今日のチェックインでは、チェックした項目はその場で薄く表示する、深夜0時を過ぎたら新しい日に切り替える、PlaywrightのテストはPixel 7とiPhone 15のモバイルプロファイルでChromiumとWebKitを使って実行する、といった細部がここで決まりました。

その結果、R1からR12までの要件と除外事項を記したrequirements.md、16の自動テストシナリオと8段階の手動確認手順を記したvalidation.md、そして構築の順序とリスクに関する注記を含むplan.mdができあがりました。注記の内容は、最初の機能はプロジェクトのセットアップも担うため、セッションが長引いたら、使えるチェックリストができるステップ4でいったん区切るべきだというものです。基本ファイルの抜けはこの3つのファイルすべてに波及するため、基本ファイルを先に見直します。

実装：チャットをクリアし、仕様から作る

仕様をコミットした後、開発者は/clearを実行して会話を消去しました。プロジェクトの状態はチャット履歴ではなく、Gitで管理されたMarkdownファイルに残っているため、新しいセッションでもチームの別のメンバーでも作業を引き継げます。実装用のプロンプトは、Claude Codeにplan.mdを1ステップずつ実行し、requirements.mdに書かれたものだけを作り、validation.mdのテストをすべて実行し、手動で確認すべき点を報告するよう求めます。

Playwrightのテスト38件はすべて合格しましたが、Claude Codeはロードマップの項目を未完了のまま残し、人による手動確認を待ちました。ローカルサーバー上で6つのタスクにチェックを付け、ヘッダーに「Day complete」と表示されたのを確かめてから、ようやくClaudeはコミットとマージを行い、機能を完了済みにしました。2つ目の機能も同じ2つのプロンプトを使い、118件のテストに合格しました。Playwrightは導入の手間が増えますが、手作業でクリックして確かめるだけの場合と比べれば、はるかに強力な安全網になります。それでも自動テストだけでは十分ではなく、完了とする前に人が画面を確認すべきです。

▲ 自動テスト後の人による確認

繰り返すプロンプトをスキルにする

機能ごとに長いプロンプトを貼り付ける手間を省くため、計画用のプロンプトをClaude Codeのスキルにしました。スキルとは、名前を付けてディスクに保存し、コマンドとして実行できる指示のセットです。.claude/skills/feature-spec/SKILL.mdに保存されたこのスキルは、ロードマップの次の項目を見つけ、ブランチを作り、インタビューを行い、アプリのコードには手を付けずに3つの仕様ファイルを書きます。デスクトップアプリを再起動した後は、/feature-specと入力するだけで次の機能に取りかかれます。スキルは、エージェントにプロジェクトのことを教える4つの方法の1つです。ほかの3つは、最初に読み込まれるCLAUDE.mdやAGENTS.mdの常設ルール、独自のコンテキストウィンドウを持つレビュー担当のエージェント、そして外部のコンテキストやツールを取り込むMCPサーバーです。

既存のコードベースに仕様を加える

実際の開発の大半は、仕様のない既存のコードベース、つまりブラウンフィールドのプロジェクトで行われ、基本ファイルはコードから作ることになります。ここでの例は、FastAPIのバックエンドと自動テストを備えた、75日間のフィットネス記録用のプログレッシブウェブアプリ（インストールして使えるウェブアプリ）です。

1. コードを変更せずにリポジトリとテストを調べ、わかったことから3つの基本ファイルを書くようClaude Codeに指示します。
2. 文書とコードが食い違う箇所を確認します。READMEには、バックエンドではすでに1つにまとめられていた4つの連続記録の指標が書かれていたうえ、存在しないデプロイ用ファイルや設定ファイルが記載されていました。拠り所にすべきは、文書ではなくコードです。
3. 基本ファイルとスキルをコミットし、/feature-specを実行します。新しい休息日の機能について、Claude Codeはfeature/07-pause-daysブランチを作り、75日間の1回の挑戦で休息日を何日認めるかを尋ね、5日を推奨しました。
4. 仕様を承認し、連続記録を途切れさせずに最大5日の休息日を前もって設定できる機能をClaude Codeに作らせます。テストに合格したら、スマートフォンで結果を手動で確認します。

Plan ModeからBMADまで、フレームワークの選び方

SDDのフレームワークは、同じループを独自のコマンド、ルール、エージェントのペルソナでパッケージ化したものです。2026年10月13日時点で、軽いものから重いものへ並べると次のようになります。

5つを直接比較したベンチマークはまだないため、この並びは品質ではなく重さを示しています。実践的なのは2段構えのやり方です。新規プロジェクトや大きな機能にはBMADのような重いフレームワークを、小さな作業にはPlan Modeを使います。1つのリポジトリで2つの仕様フレームワークを動かしてはいけません。食い違う文書が、信頼できる唯一の情報源を壊してしまうからです。ただしPlan Modeは例外で、ファイルを書かないため、1つのフレームワークと併用できます。

まとめ

決定を書き残さなければ、AIエージェントが技術スタックもルールも、スタイルまでも選んでしまいます。そうした判断は自分で下し、大きな機能は必ず計画、仕様化、実装の順に進めましょう。始め方は次のとおりです。

1. specsフォルダを作り、AIのインタビューを受けて3つの基本ファイルを書きます。既存のコードがある場合は、コードから導き出します。
2. 次の機能は、コードを書くことを禁じた計画用のプロンプトで始め、できた仕様ファイルをレビューしてコミットします。
3. チャットをクリアして仕様から作らせ、テストに合格し、自分でも結果を確認してからマージします。
4. 2回貼り付けたプロンプトは、スキルにします。
5. 短いチケットに収まる変更、3ファイル未満の変更、設計判断を伴わない変更、目で見て判断する見た目の調整には、仕様を書く必要はありません。