バイブコーディングから
仕様駆動開発へ書かれていない決まりを見つけ、仕様で AI に作らせ、仕様と照らして確かめる

図 1 の 1 つ目が、この講座の出発点です。GitHub は、AI コーディングエージェントを「文字どおりに受け取るペアプログラマー (literal-minded pair programmers)」と呼び、曖昧な指示は、書かれていない要件の推測を AI に強いると説明しています。「備品の貸出を管理するアプリ」とだけ頼めば、他の社員の予約が見えるか、誰が返却を記録するかは、AI がよくある作り方から選びます。選んだ作り方は、どれも筋が通っています。ただ、その職場の決まりと合っているかは、出来上がった画面を動かすまで分かりません。

推測を減らすには、決まりを言葉にして AI に渡します。ところが、渡した言葉も、図 1 の残りの 3 つの性質のせいで失われます。AI が一度に読める文章の量をコンテキストウィンドウ (context window) と呼び、会話の履歴・読んだファイル・コマンドの出力は、すべてこの中に入ります。Claude Code は、会話がコンテキストウィンドウを使い切りそうになると、それまでの会話を自動で要約して続けます。要約で細部が抜けるので、会話の最初に決めた細かい取り決めは、長い会話の後半で守られなくなることがあります。

会話を新しく始めると、前の会話で決めたことは AI に伝わっていません。昨日の会話で「社用車は延長できない」と決めても、今日の会話の AI は知りません。そのため各製品には、会話のたびに AI が自動で読むファイルがあります。Claude Code の CLAUDE.md、多くの製品が共通で読む AGENTS.md などです。続けて守らせたい決まりは、会話ではなくファイルに書きます。

ファイルに書いた決まりにも、守られる保証はありません。Claude Code の公式ドキュメントは、プロンプトや CLAUDE.md に文章で書いた指示は AI が読んでどうするかを決めるもので、見落としや誤った解釈が起こりうると説明しています。これに対して、権限の設定やフック (hook) のように Claude Code 自体が実行する仕組みは、AI の判断に関係なく毎回働きます。たまに外れても直せばよい決まりは文章で書き、1 回でも破られると取り返しがつかない決まりは設定で縛ります。

ソフトウェアは、作る前に「何を作るか（要求）」と「どう作るか（設計）」を決めてからコードを書きます。この 2 つの工程を飛ばしても、決めることは無くなりません。決めていない決まりは、コードを書く人がその場で決めます。AI にコードを書かせるとき、その場で決めるのは AI です。

Thoughtworks の Birgitta Böckeler は、仕様駆動開発を調べた記事で、仕様を「AI コーディングエージェントを導くために自然な言葉で書いた、ソフトウェアの振る舞いを決める構造化された文書」と定義しています。2025 年 7 月に AWS が開発環境の Kiro を、9 月に GitHub が Spec Kit を公開し、仕様駆動開発の手順を支援するツールが登場しました。ツールごとに呼び名は違いますが、工程は図 2 の 5 つにまとまります。

図 2 の最初の 2 つは、バイブコーディングで飛ばしていた工程です。決まりを見つけて書くのは人で、AI は質問を出し、下書きを書いて手伝います。書かれた仕様は、作らせる工程で AI に読ませる指示になり、確かめる工程で出来上がった物を測る物差しになります。運用中に変更が出たら、コードより先に仕様を直します。

Böckeler は、AI に読ませる文書を 2 種類に分けています（図 3）。仕様は、1 つの機能を作る・変える作業のための文書です。メモリーバンク (memory bank) は、どの作業でも AI に読ませる取り決めの文書で、使うコマンド、コードの書き方、全体の構成などを書きます。会話のたびに AI が自動で読む CLAUDE.md・AGENTS.md はメモリーバンクにあたり、Kiro ではステアリング (steering)、Spec Kit では constitution と呼びます。Spec Kit の説明は、constitution はプロジェクトに 1 回作り、残りの手順は機能ごとに繰り返すとしています。

仕様が AI の作業を縛る仕組み

仕様を書いても、AI がそれを読まなければ、また推測で作ります。仕様駆動開発は、次の 4 つの仕組みで、仕様を AI の作業に効かせます。

1 つ目は、番号のつながりです。要件の受け入れ基準に番号を付け、設計・タスク・テストの項目から、その番号で参照します。Spec Kit の仕様の雛形は、要件を FR-001 のような番号で書きます。Spec Kit の /speckit-analyze は、要件の番号ごとに対応するタスクがあるかを表にし、タスクが 1 つも無い要件を抜けとして報告します。番号がつながっていれば、図 4 のように、1 つの決まりがどこで作られ、どのテストで確かめられるかを、コードを読まずにたどれます。

番号のつながりがあると、2 つのことができます。1 つは抜けの発見です。設計やテストに番号が現れない受け入れ基準は、作られていないか、確かめられていません。もう 1 つは変更の追跡です。R4-1 を変えたら、R4-1 が付いた設計・タスク・テストだけを直せば済みます。

2 つ目は、工程ごとに人が確かめてから次に進むことです。Spec Kit の説明は、手順を 1 つずつ実行し、結果を確かめてから続けるよう求めています。Kiro も、要件を利用者が確かめた後に設計の文書を作ります。要件の誤りを要件のうちに直せば、設計とコードに誤りが広がりません。人が確かめずに次へ進めると、AI の推測が文書の形で残るだけになります。

3 つ目は、仕様を読ませてから作らせることです。作らせるときは、新しい会話で、メモリーバンクと仕様のファイルを読ませ、タスクを 1 つだけ頼みます。会話の中で決めたことは次の会話に引き継がれませんが、ファイルに書いた仕様は毎回同じ形で読ませられます。

4 つ目は、文章で守らせられない決まりを設定で縛ることです。仕様は文章なので、AI が従う保証はありません。テストのファイルを変えさせない、本番のデータベースに触らせない、のように、1 回でも破られると困る決まりは、権限の設定や環境の分離で縛ります。

Böckeler は、仕様駆動開発を、仕様を残す期間で 3 つの段階に分けています。

この講座は、spec-anchored の段階で進めます。使い始めたアプリには変更が続き、仕様を残しておかなければ、番号のつながりも、何を作ったかの説明も失われるからです。ツールごとの工程の名前は、次のとおりです。

この講座は、特定のツールに依存しない共通の工程で進め、仕様を Markdown（見出しや箇条書きを書けるテキスト形式）のファイルにまとめます。Kiro や Spec Kit を使う場合も、各工程で決めることは同じです。

要件には、次の 5 つを書きます。GitHub は Spec Kit の紹介で、要件の段階では利用者の行動と、何ができれば成功かを書き、使う技術は書かないよう勧めています。

受け入れ基準の書き方には、EARS 記法 (Easy Approach to Requirements Syntax) を使います。EARS は、英国の Rolls-Royce で Alistair Mavin らが 2009 年に発表した、要件を決まった文型で書く方法で、Kiro も受け入れ基準をこの文型で書きます。文型を決めておくと、条件・主語・結果が文から抜けにくくなります。

受け入れ基準の番号は、要件の見出しと連番で付けます（R1 予約する → R1-1、R1-2）。番号は、設計・タスク・テストの項目から参照する住所になるので、一度付けた番号は付け替えません。基準を消すときも、番号は欠番にして残します。

設計に書くこと

要件が固まったら、設計の文書にどう作るかを書きます。設計は AI に書かせ、人は次の 5 つを確かめて選びます。GitHub は、設計の段階で人が技術・構成・制約を与え、AI に案を作らせ、必要なら複数の案を出させて比べるよう勧めています。

データの設計では、アプリが持つ情報を、表（テーブル）と項目で書きます。データは画面より先に決めます。画面は後から足せますが、データの形を後から変えると、そのデータを使うすべての画面と処理を直すことになるからです。消してよいデータと残すデータも、ここで決めます。

状態の設計では、要件の状態の表を、データの項目と、状態を移す操作に置き換えます。どの操作がどの状態からどの状態へ移せるかを書いておくと、AI が「どの状態からでも取り消せる」作りを選ぶのを防げます。

権限の設計では、役割ごとに、見られるデータと変えられるデータを書きます。必ず書くのは、権限の確認を画面ではなくサーバー側で行うことです。画面のボタンを隠すだけの作りでは、URL を直接開けば権限の外の操作ができます。公開アプリの研究で最も多かったアクセス制御の不備は、この確認が無いことで起きます。

画面の設計では、画面の一覧と、どの役割がどの画面を使うかを書きます。技術の選定では、言語・データベース・置き場所・ログインの方法を決めます。AI に候補を 2〜3 つ、理由つきで出させ、保守を頼める人が扱えるか、費用はいくらかで、人が選びます。

設計を書かせたら、受け入れ基準の番号ごとに、設計のどこで満たすかを表にさせます。表に載らない番号があれば、設計に抜けがあります。

この講座の雛形と指示文を配布しています。要件の雛形は、観点の一覧を見出しにしたもので、自分のアプリの決まりを埋めて使います。例は、1 行の依頼から書き起こした「要確認」だらけの下書きと、質問に答えて詰めた後の要件の 2 つで、並べると、どの観点が質問で埋まったかが分かります。

AI は、自分で書いたコードを、自分で書いたテストで確かめます。テストの中身が弱ければ、テストが通っても受け入れ基準を満たしているとは限りません。Kiro のドキュメントも、確かめる内容が弱いテストや、誤った決まりを確かめるテストは、動きが誤っていても通ると注意しています。そこで、どんなテストを揃えるかは人が決め、作る前に固めます。テストは、受け入れ基準ごとに次の 4 種類を揃えます。

境目のテストを作らせると、仕様の抜けが見つかります。前の予約が 12:00 に終わるとき、12:00 に始まる予約は重なるのか。「重なる予約を受け付けない」という基準には答えがありません。答えが無い項目は、AI に決めさせず、担当者に確かめて要件に書き足します。

権限の外からの操作のテストは、受け入れ基準に書いていなくても、すべての機能に入れます。公開アプリの研究では、脆弱性の原因の 55.5% が、依頼に書かれていなかった安全の要件でした。業務の基準から作るテストだけでは、書かなかった安全の要件は確かめられません。どの機能にも当てはまる項目として、メモリーバンクにテストの決まりとして書いておきます。

テストの項目は、コードではなく、人が読める表で AI に出させます。1 行に、受け入れ基準の番号、操作、期待する結果を書かせます。読者は番号を 1 つずつ見て、4 種類が揃っているか、期待する結果が業務の事実と合っているかを確かめます。コードを読めなくても、この表は読めます。

テストは、作る前に書かせて固めます。Spec Kit は、タスクの雛形で、テストを先に書き、実装の前にそのテストが失敗することを確かめるよう定めています。constitution の例には、「テストを書く → 利用者が承認する → テストが失敗する → 実装する」という順が載っています。先に失敗を確かめるのは、何も作らなくても通ってしまう、確かめになっていないテストを見分けるためです。

承認したテストは、作る作業の中で AI に変えさせません。Claude Code では、テストのフォルダの編集を禁止する設定を置きます。

この禁止は、ファイルを編集するツールと、Claude Code が見分けられる一部のコマンドに効きます。コマンドの書き方によっては外れるため、仕様と照らすレビューでも、テストのファイルが変わっていないかを報告させます。テストを変える必要が出たら、作る作業を止め、理由を聞いてから、人が承認する別の作業として変えます。

完了の報告を受けたら、次の 3 つで確かめます。

3 つの確認で問題がなければ、変更を保存し、タスクに完了の印を付けて、次のタスクに進みます。

Kiro は、さらに進んだ確かめ方を備えています。EARS 記法の受け入れ基準から、いつでも成り立つ性質を取り出し、何百・何千の入力を自動で作って、その性質が破れないかを試します。この方法を property-based testing と呼びます。その Kiro も、テストが通ることは正しさの証拠であって証明ではない、と書いています。テストで確かめられるのは、書いた項目だけです。

仕様駆動開発の手順を、どんな作業にも同じ重さで当てはめると過剰になります。Böckeler は、小さな不具合の修正に Kiro を使ったところ、4 つのユーザーストーリーと 16 の受け入れ基準が作られ、「くるみを割るのに大槌を使うようだった」と書いています。そして、作る物の大きさと、何を作るかの明確さの 2 つの軸で進め方を選ぶ考え方を提案しています。これに、推測が外れたときの損害の軸を加えると、次の表になります。

何を作るかがまだ決まっていないときは、先に試作を作らせて触り、分かったことを要件に書いてから、試作を捨てて作り直します。試作は、決まりを見つけるための道具として使います。試作のコードをそのまま育てると、推測で決まったデータの形が残ります。

社外の顧客が使い、お金を受け取るサービスでは、観点が 3 つ増えます。知らない人が使うので、会員の登録とログイン、パスワードの再設定、そして顧客 A の利用者に顧客 B のデータが見えないことを、要件とテストに書きます。お金を受け取るので、料金、支払いが失敗したときに何日まで使わせるか、解約した後のデータをいつまで残すかを書きます。止まると顧客が困るので、同時に使う人数と画面の表示時間、稼働時間の目標、データを失ったときに戻せる時点を数で書きます。数が無いと、AI は 1 人で試して動けば完了とします。公開の前には、第三者のセキュリティ診断も受けます。