0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@akira_papa_AI(あきらパパ)

AIが書いたコード、動くけど「なんかズレてる」の正体 — Spec-Driven Development（仕様駆動開発）で、AIを“設計図どおり”に動かす実践ガイド

0
Posted at

はじめに：「動くけど、なんか違う」あの感じ

AIにコードを書かせるの、ほんまに速くなりましたよね。

「ログイン機能つけて」「この一覧、検索できるようにして」みたいにお願いするだけで、数十秒後にはそれっぽいコードが出てくる。最初は感動するんです。けど、しばらく使ってると、こういう瞬間に出会いませんか。

「動いてはいる。でも、なんか違う。」

  • 想定してた挙動と、微妙にズレてる
  • エラー処理が、自分のプロジェクトの作法と違う
  • 「そこはそうじゃなくて…」と説明し直すと、今度は別のところが崩れる
  • 3回やり取りして、結局それなら自分で書いたほうが早かった、みたいな

これ、AIが悪いわけじゃない気がするんです。よく考えたら、こっちが「何を作りたいか」をちゃんと渡せてなかっただけなんですよね。頭の中にある完成形を、ふわっとした一言だけ渡して、あとはAIにエスパーしてもらおうとしてた。そりゃズレます。

最近この「ふわっと投げて、ズレたら直す」スタイルに、ちゃんとした名前と対策が出てきました。スタイルのほうは Vibe Coding（バイブコーディング） 、対策のほうが、この記事のテーマである Spec-Driven Development（仕様駆動開発、以下SDD） です。

ひとことで言うと、SDDはこういう考え方です。

コードを書かせる前に「仕様（＝何を作るか）」を先に書く。そして、その仕様を“AIへの設計図”として渡す。

「仕様書なんて重いもの書きたくないわ…」って思った人、ちょっと待ってください。ここで言う仕様は、分厚いWord文書のことじゃないんです。むしろ AIに正確に動いてもらうための、構造化したメモ に近い。そしてこれが、2026年のAI開発で一番アツいテーマの一つになってます。

この記事では、

  • なぜ今、仕様を先に書くのか（Vibe Codingの限界）
  • SDDの全体像（むずかしい用語は全部かみ砕きます）
  • 実際に書く仕様のサンプル（そのままコピーして使えるやつ）
  • GitHub Spec Kit / Amazon Kiro という実在ツールの話
  • そして一番伝えたい「仕様を“実行可能”にする」という一歩

までを、AI開発にまだ慣れてない人でも置いていかれないように、順番に話していきます。明日から仕事で1つ試せるところまで持っていきましょう。

なぜ今、わざわざ「仕様を先に」書くのか

Vibe Codingが静かに生む、3つの失敗モード

Vibe Codingは悪者じゃないです。ちょっとした調べ物や、捨てる前提のプロトタイプなら、ノリで投げるのが一番速い。問題は、ちゃんと残すコードや、チームで触るコードにまでノリを持ち込んだときに起きます。代表的な失敗が3つあると思ってます。

失敗モード①：仕様がプロンプトに散らばって消える

「あ、そこは管理者だけ編集できるようにして」「金額は税込で」みたいな大事な決めごとを、チャットの途中でポロポロ伝えますよね。あれ、会話が流れた瞬間に消えるんです。3日後の自分も、隣のチームメンバーも、その決定を知らない。仕様がAIとの会話ログの海に沈んでる状態です。

失敗モード②：ドリフト（仕様とコードのズレ）

最初はちゃんと意図どおりだったのに、何度も追加・修正してるうちに、いつの間にか元の設計から少しずつズレていく。これを ドリフト（drift＝漂流） と言います。一個一個は小さなズレでも、積もると「動くけど、誰も全体像を説明できないコード」が出来上がる。Amazonがまさにこの問題を名指しで「構造なしでAIに作らせると、ローカルでは動くけどアーキテクチャからドリフトして、エッジケースを外し、本番で崩れる」と言ってます。

失敗モード③：レビューできない

レビューする側からすると、「で、これは結局なにを満たしてれば正解なの？」という基準（受け入れ条件）がどこにもない。だから「動いてるっぽいからOK」みたいな感想レビューになる。基準がないところに、まともなレビューは生まれないんですよね。

この3つ、根っこは同じです。「何を作るか」が、AIにも人間にも、ちゃんと残る形で書かれていない。 SDDは、ここに先に手を打とうという発想なんです。

2026年、ツールのほうが先に動き出した

おもしろいのが、これは個人のお気持ちの話じゃなくて、もう大手が本気でツールを出してきてるってことです。事実だけ並べます。

  • GitHub Spec Kit … GitHubが公開しているOSSのツールキット（github/spec-kit）。Constitution → Specify → Plan → Tasks → Implement という流れで、仕様駆動開発を支援する。Copilot / Claude / Gemini / Codex / Windsurf / Kiro など 30種類のAIエージェントと連携 でき、特定ツールへのロックインがないのが特徴。
  • Amazon Kiro … Amazonが2026年5月7日に国際展開を開始したエージェント型IDE（Code OSS＝VS Codeの土台の上に構築）。旧Amazon Q Developerの置き換えで、「仕様を先に書いてから実装する」を中核に据えている。

つまり、「AIに任せる時代だからこそ、設計の作法が大事になる」という方向に、業界全体が舵を切り始めてる。実装が速くなった分、ボトルネックが“何を作るかの設計と合意”に移った、ということなんやと思います。

ここで、あきらパパがずっと大事にしてる考え方とつながります。「何を作るか（What）」と「なぜ作るか（Why）」を考えるのが人間、「どう作るか（How）」をやるのがAI。 SDDは、この役割分担をそのまま開発フローに落とし込んだ方法論なんですよね。

Spec-Driven Developmentとは（むずかしい用語を“登場人物”にする）

そもそも「仕様」って何なん？

「仕様」って言葉が固いだけで、中身はシンプルです。料理にたとえると分かりやすい。

  • 行き当たりばったり料理（Vibe Coding）：冷蔵庫を開けて、その場のノリで作る。美味しい時もあるけど、同じ味は二度と作れないし、人に再現してもらえない。
  • レシピを書いてから作る（SDD）：材料・分量・手順・「こうなったら完成」を先に書く。誰が作っても同じ味になるし、改善もしやすい。

仕様とは、ようは 「完成したらこうなっている、という状態を、先に言葉にしたもの」 です。それだけです。SDDは、このレシピを先に書いて、調理（実装）をAIに任せる、という発想。

SDDに出てくる4人の登場人物

GitHub Spec Kitの流れに沿うと、SDDでは段階ごとに4種類のドキュメント（成果物）を作ります。これを擬人化すると、こんなチームです。

登場人物（ファイル） 役割 ひとことで言うと
憲法（constitution.md） プロジェクトの絶対ルール 「うちはこういう方針でやる」という全体の憲法。品質・テスト・設計の原則
仕様（spec.md） 何を・なぜ作るか ユーザーストーリーと受け入れ条件。Howは書かない（What/Whyだけ）
計画（plan.md） どう作るか 技術スタック・アーキテクチャ・設計判断
タスク（tasks.md） 手順の分解 実装できる粒度に割った、順番つきのToDoリスト

ポイントは、この4人が上から順番にバトンを渡していくこと。憲法が全体の前提を決め、仕様が「何を」を固め、計画が「どう」を決め、タスクが「手順」に割る。そして最後に 実装（Implement） で、AIがタスクを1つずつ片付けていく。

各段階の成果物が、次の段階の「AIに渡す構造化された文脈（コンテキスト）」になる。ここがSDDの肝です。ふわっとした一言じゃなくて、積み上がった設計図を渡すから、AIがズレにくい。

Prompt EngineeringからContext Engineeringへ

ちょっとだけ抽象的な話を。最近よく言われる Context Engineering（文脈設計） って言葉、SDDはまさにこれの実践版なんです。

  • Prompt Engineering … うまい一言（プロンプト）をひねり出す技術
  • Context Engineering … AIに渡す“文脈そのもの”を設計する技術

一発のうまいプロンプトでがんばるんじゃなくて、憲法・仕様・計画・タスクという積み上がった文脈を用意して、AIが正しく動く土俵を整える。 SDDは「いいプロンプトを書く」より一段上の、「いい文脈を組む」アプローチだと思ってもらえれば。

SDDの全体像：5フェーズの地図

実際の流れを、地図にするとこうなります。各フェーズで「人間が決めること」と「AIに任せること」をはっきり分けるのがコツです。

フェーズ やること 人間が決める AIに任せる
① Constitution プロジェクト憲法を作る 品質・テスト・設計の原則、譲れない方針 原則の文章化・抜け漏れ指摘
② Specify 仕様を書く 何を/なぜ、受け入れ条件、優先度 ユーザーストーリーの構造化、曖昧さの洗い出し
③ Plan 技術計画を立てる 技術選定の最終判断、トレードオフ 候補技術の比較、アーキ案の生成
④ Tasks タスクに分解 範囲・優先順位の確認 依存関係を考えた順番づけ、TDD順の分解
⑤ Implement 実装する 受け入れ条件を満たすかの判断、レビュー コード生成、テスト作成、リファクタ

大事なのは、人間がいなくなるわけじゃないってこと。むしろ人間は、より上流の「意図」「合意」「判断」に集中する。手を動かす量は減るけど、頭を使う場所が変わるんです。実装者から、設計者・評価者へ。

実際に書いてみる：仕様サンプル4点

ここからは手を動かすパートです。題材は、どのプロジェクトにもありそうな 「タスク管理アプリのタスク作成API」 にします。固有の情報は一切使わない、汎用のダミー題材です。そのままコピーして、自分の題材に差し替えて使ってください。

コード例①：憲法（constitution.md）

まずプロジェクトの「絶対ルール」。これは機能ごとじゃなく、プロジェクト全体で1回書くものです。

# プロジェクト憲法（constitution.md）

## 第1条：品質の原則
- すべての公開APIには、正常系・異常系の自動テストを必ず付ける
- 外部入力は信頼しない。バリデーションを通っていない値を処理しない

## 第2条：テストの原則
- 受け入れ条件は、必ず1つ以上のテストに対応づける（トレーサビリティ）
- テストのないバグ修正はマージしない（再発防止のため）

## 第3条：設計の原則
- 1つの関数は1つの責務。副作用は境界に寄せる
- 破壊的操作（削除・上書き・外部送信）は、デフォルトで拒否し明示的に許可する

## 第4条：意思決定の原則
- 仕様で迷ったら [NEEDS CLARIFICATION] を付けて止める。憶測で実装しない
- 重要な技術判断は plan.md に「なぜそれを選んだか」を1行残す

これがあると、AIに「うちの憲法に従って」と言うだけで、毎回テストやバリデーションの方針を説明し直さなくて済む。チームの暗黙知を、明示的なルールに変えるわけです。

コード例②：仕様（spec.md）— Howを書かないのがコツ

次に、機能ごとの仕様。ここでは 「どう実装するか（How）」は一切書きません。あくまで「何を・なぜ・どうなったら完成か」だけ。

# 仕様：タスク作成API（spec.md）

## 目的（Why）
ユーザーが自分のタスクを登録できるようにする。登録したタスクは
あとで一覧・検索の対象になる。

## ユーザーストーリー（What）
- ログイン済みユーザーとして、タイトルと期限を指定してタスクを作成したい
- 作成したタスクには、自動で作成日時と「未完了」状態が付いてほしい

## 受け入れ条件（Acceptance Criteria）
- AC-1: タイトルが1〜100文字なら、タスクを作成し 201 を返す
- AC-2: タイトルが空、または101文字以上なら、作成せず 400 を返す
- AC-3: 期限が「過去の日時」なら、作成せず 400 を返す
- AC-4: 未ログインなら、作成せず 401 を返す
- AC-5: 作成成功時、レスポンスに id / createdAt / status="todo" を含む

## スコープ外（Non-goals）
- タスクの編集・削除（別仕様で扱う）
- 通知・リマインダー機能

## 未確定（要確認）
- [NEEDS CLARIFICATION] 期限は必須か、任意か？（仮：任意とする）
- [NEEDS CLARIFICATION] 1ユーザーあたりの作成上限はあるか？

注目してほしいのが2つ。

1つめは 受け入れ条件にAC-1のような番号を振ってる こと。これが後で「テストとの対応づけ（トレーサビリティ）」で効いてきます。

2つめは [NEEDS CLARIFICATION] マーカー。仕様を書いてると、必ず「あれ、ここ決まってないな」が出てきます。それを憶測で埋めずに、「未確定」と明示して止める。これ、めっちゃ大事です。曖昧なまま実装に進むと、AIが勝手に都合よく解釈して、後で「そんなつもりじゃなかった」が起きる。曖昧さは、実装より前に潰す。

コード例③：計画（plan.md）— ここで初めてHowを書く

仕様がOKになって初めて、「どう作るか」を考えます。

# 計画：タスク作成API（plan.md）

## 技術スタック
- 言語/FW: TypeScript + Express
- DB: PostgreSQL（tasks テーブル）
- バリデーション: Zod

## アーキテクチャ方針
- レイヤ構成: route → handler → service → repository
- バリデーションは handler の入口で行い、service には検証済みの値だけ渡す

## 主要な設計判断（なぜそれを選んだか）
- Zodを採用：受け入れ条件（文字数・日時）をスキーマで宣言的に表現でき、
  そのままテストにも流用できるため
- status はDBのデフォルト値 'todo' で持つ：アプリ側の書き忘れを防ぐため

## データモデル
- tasks(id, user_id, title, due_at, status, created_at)

ここで [NEEDS CLARIFICATION] が残ってたら、本来は計画に進んじゃダメです。Spec Kitには、planの前に曖昧さを潰す /speckit.clarify という専用ステップがあるくらい、ここを大事にしてます。

コード例④：タスク（tasks.md）— 実装できる粒度に割る

最後に、計画を「順番つきの作業リスト」に分解します。AIが1つずつ片付けられる粒度にするのがコツ。

# タスク分解（tasks.md）

## 前提
- 各タスクは「テストを先に書く（TDD）」順で並べる
- AC-x は spec.md の受け入れ条件IDに対応する

## タスクリスト
- [ ] T1: tasks テーブルのマイグレーション作成
- [ ] T2: Zodスキーマ作成（title 1-100文字 / due_at 任意・未来日時） … AC-1, AC-2, AC-3
- [ ] T3: AC-1〜AC-5 に対応する失敗テストを先に書く（まだ実装しない）
- [ ] T4: handler 実装（バリデーション → 401チェック → service呼び出し）… AC-4
- [ ] T5: service/repository 実装（作成・createdAt・status付与）… AC-5
- [ ] T6: 全テストを通す → リファクタ
- [ ] T7: 憲法 第2条チェック（全ACがテストに対応しているか）

ここまで来ると、AIに渡すのが「ログイン機能つくって」じゃなくて、憲法＋仕様＋計画＋タスクという、積み上がった設計図になります。同じAIでも、出てくるコードの精度が全然変わるんですよね。

ツールに乗る：GitHub Spec Kit と Amazon Kiro

「手で全部書くの大変そう…」と思いますよね。安心してください。さっきの流れを 半自動でやってくれるツール が、もう実在します。

GitHub Spec Kit

OSSなので誰でも使えます。導入のイメージはこんな感じです（細部はバージョンで変わるので、必ず公式READMEを確認してください）。

# Spec Kit を使えるようにする（uvx 経由の例）
uvx --from git+https://github.com/github/spec-kit.git specify init my-project

導入すると、対応エージェント（Claude / Copilot / Gemini / Codex など）から、こういうスラッシュコマンドが使えるようになります。

コマンド 役割
/speckit.constitution プロジェクト憲法を作る
/speckit.specify 仕様（spec.md）を作る — 何を/なぜ
/speckit.clarify 仕様の曖昧さ（要確認点）を潰す
/speckit.plan 技術計画（plan.md）を作る
/speckit.tasks タスク（tasks.md）に分解する
/speckit.analyze 成果物どうしの整合性をチェックする
/speckit.implement タスクを実行して実装する

流れとしては、constitution で土台を作って、specify で機能の仕様を書いて、clarify で曖昧さを潰して、plan → tasks → implement と降りていく。各ステップでAIに丸投げじゃなく、人間が中身を確認して直すのが正しい使い方です。30種のエージェントに対応してて、ツールを乗り換えても同じ流れが使えるのが強み。

Amazon Kiro

もう一つの選択肢が、Amazonが2026年5月に国際展開を始めた Kiro。VS Codeベースのエージェント型IDEで、最初から「Spec（仕様）」「Steering（規約）」という概念が組み込まれてます。Steeringファイルにコーディング規約を書いておくと、エージェントが毎回それに従って動く。Spec Kitの「憲法」に近い発想ですね。

大事な注記：ツールがなくても始められる

ここ、勘違いしないでほしいんですけど、SDDの本質はツールじゃなくて“順番”です。「実装の前に、何を作るかを構造化して書く」。これさえ守れば、ツールを入れる前に、ただのMarkdownファイルを4枚（constitution / spec / plan / tasks）置くだけでも今日から始められます。 むしろ最初はそのほうが、何が起きてるか理解しやすい。ツールは、慣れてきて「これ毎回手で書くの面倒だな」と思ってから入れれば十分です。

【ここが核心】仕様を“ただの文書”で終わらせない — 実行可能仕様

さて、ここからが一番伝えたいところです。

SDDを「仕様書を先に書くだけ」で終わらせると、昔ながらの“書いて満足する仕様書”に逆戻りします。書いたきり誰も見ない、コードとズレても気づかない、あの仕様書です。それじゃ意味がない。

SDDが本当に効くのは、仕様を「実行可能（executable）」にしたときです。どういうことか。順番に。

ステップ1：受け入れ条件を、そのままテストにする

さっきの spec.md で、受け入れ条件にAC-1のような番号を振りましたよね。あれを テストコードに1対1で対応づけるんです。

// tasks.create.spec.test.ts
// spec.md の受け入れ条件(AC)とテストを 1対1 で対応づける
import { describe, it, expect } from "vitest";
import { createTask } from "../src/handlers/createTask";

describe("タスク作成API（spec.md AC対応）", () => {
  it("AC-1: タイトル1〜100文字なら 201 を返す", async () => {
    const res = await createTask({ user: { id: "u1" }, body: { title: "買い物" } });
    expect(res.status).toBe(201);
    expect(res.body).toMatchObject({ status: "todo" });
    expect(res.body.id).toBeDefined();
    expect(res.body.createdAt).toBeDefined(); // AC-5
  });

  it("AC-2: タイトルが空なら 400 を返す", async () => {
    const res = await createTask({ user: { id: "u1" }, body: { title: "" } });
    expect(res.status).toBe(400);
  });

  it("AC-3: 期限が過去日時なら 400 を返す", async () => {
    const res = await createTask({
      user: { id: "u1" },
      body: { title: "提出", dueAt: "2000-01-01T00:00:00Z" },
    });
    expect(res.status).toBe(400);
  });

  it("AC-4: 未ログインなら 401 を返す", async () => {
    const res = await createTask({ user: null, body: { title: "提出" } });
    expect(res.status).toBe(401);
  });
});

こうすると、「仕様を満たしているか」が、人間の感想じゃなくて、テストの成否で機械的に判定できるようになります。AC-1からAC-5まで、全部緑なら仕様を満たしてる。赤なら満たしてない。レビューが「動いてるっぽい」から「全ACがパスしている」に変わるんです。

ステップ2：仕様↔テストのトレーサビリティをCIで守る

ここでもう一歩。「受け入れ条件に書いたのに、テストが存在しない」を機械で検出します。憲法 第2条「受け入れ条件は必ず1つ以上のテストに対応づける」を、人の善意じゃなくて仕組みで守るわけです。

# scripts/check_traceability.py
# spec.md の AC-x が、テストファイル内で参照されているかを確認する
import re
import sys
from pathlib import Path

spec = Path("spec.md").read_text(encoding="utf-8")
tests = "\n".join(p.read_text(encoding="utf-8") for p in Path("tests").rglob("*.test.ts"))

# spec.md から AC-1, AC-2 ... を抽出
ac_ids = set(re.findall(r"AC-\d+", spec))
# テスト側で言及されている AC を抽出
covered = set(re.findall(r"AC-\d+", tests))

missing = sorted(ac_ids - covered)
if missing:
    print(f"❌ テスト未対応の受け入れ条件があります: {missing}")
    sys.exit(1)  # CIをここで落とす

print(f"✅ 全 {len(ac_ids)} 件の受け入れ条件にテストが対応しています")

そして、これをCI（GitHub Actions）に組み込んで、未対応の受け入れ条件があったらマージできないゲートにします。

# .github/workflows/spec-gate.yml
name: spec-gate
on: [pull_request]
jobs:
  traceability:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - name: 仕様とテストの対応をチェック
        run: python scripts/check_traceability.py
      - name: テスト実行
        run: npm test

これで何が起きるか。仕様に新しい受け入れ条件を足したのに、テストを書き忘れたら、CIが赤くなって教えてくれる。 仕様が「書いて終わり」じゃなく、コードと常に同期する“生きた仕様”になるんです。これが「実行可能仕様」です。

ステップ3：ドリフトを検知する

最後にドリフト対策。コードを直したのに仕様を更新し忘れる、逆に仕様だけ変えてコードが追いついてない、こういうズレを定期的にあぶり出します。完全自動化は難しいですが、AIに差分レビューさせるだけでもかなり効きます（プロンプトは次章で出します）。

トレーサビリティを表で持っておくと、ドリフトが一目で分かります。

受け入れ条件 テスト 実装 状態
AC-1 ✅ あり ✅ あり 同期
AC-2 ✅ あり ✅ あり 同期
AC-3 ✅ あり ⚠️ 仮実装 要確認
AC-4 ❌ なし ✅ あり ドリフト（テスト未作成）

「AC-4は実装したのにテストがない」が、表でも CI でも光る。ズレを“誰のせい”じゃなくて“観測できる事実”として扱う。ここ、あきらパパがいつも言ってる「責める軸じゃなくて、思いやりの軸」と同じなんですよね。人を責めずに、仕組みでズレを見つける。

落とし穴と、引き返すための基準

正直に言いましょう。SDDも万能じゃないです。むしろ やりすぎると逆に遅くなる。よくある落とし穴と、撤退の目安を表にしておきます。

落とし穴 症状 対処 撤退ライン
過剰仕様（overspec） 1文字直すのに仕様書を3枚更新 小さな変更はSDDを使わない 仕様を書く時間 > 実装する時間 が続くなら、その機能はSDD対象から外す
ドリフト放置 コードだけ直して仕様を更新しない CIゲート＋差分レビューを定例化 表が「ドリフト」だらけになったら、いったん実装を止めて仕様を現状に合わせる
曖昧さの温存 [NEEDS CLARIFICATION] を埋めずに実装へ clarifyを必須ステップにする 未確定が3つ以上残ったまま実装に進もうとしたら止める
全部SDD化 試作・調査にまで仕様を要求 捨てる前提のコードはVibe Codingで良い 「これは捨てるコード」と分かってるなら仕様は書かない
憲法の形骸化 憲法はあるけど誰も従ってない 憲法を“テスト可能なルール”に絞る 守られてない条文は、守れる粒度に書き直すか削除

いちばん多いのが 「過剰仕様」 だと思います。SDDが効くのは、残すコード・チームで触るコード・本番で動くコード。逆に、ちょっと試したいだけ、捨てる前提のプロトタイプなら、ノリで作る（Vibe Coding）ほうが速い。全部を仕様化しようとしない。これ、本当に大事です。

判断の合言葉はシンプルで、「これ、来週の自分か誰かがまた触る？」。触るなら仕様を書く。触らない（捨てる）なら書かない。それだけ。

人間とAI、どこで線を引くか

SDD全体を通して、人間とAIの役割分担を整理するとこうなります。これが、この記事で一番持って帰ってほしい表かもしれません。

工程 人間がやる（判断・意図） AIに任せる（生成・実行）
憲法 譲れない方針・品質基準を決める 文章化、抜け漏れの指摘
仕様 何を/なぜ、受け入れ条件、優先度 構造化、曖昧さ（要確認点）の洗い出し
計画 技術選定の最終判断、トレードオフ 候補比較、アーキ案の生成
タスク 範囲とゴールの確認 依存関係を考えた順番づけ
実装 受け入れ条件を満たすかの判断 コード生成、テスト作成、リファクタ
レビュー 通す/止める/差し戻すの最終決定 差分要約、ドリフト検出、リスク指摘

見てもらうと分かるんですが、人間が消えるどころか、上流の“判断”の重みが増してるんですよね。コードを打つ量は減るけど、「何を作るか」「どこまでが完成か」「これを通していいか」を決めるのは、ずっと人間の仕事。AIは、その判断を高速で実行してくれる、めちゃくちゃ優秀な実装パートナー。主導権は手放さない。けど、手は借りまくる。 これがちょうどいい距離感かなと思います。

そのまま使えるプロンプト3本

最後に、明日から使えるプロンプトを3本置いておきます。コピーして、{ } の中だけ差し替えてください。

プロンプト①：仕様の「曖昧さ」を洗い出す

仕様を書いたら、実装に進む前にこれを通す。憶測で実装される事故が激減します。

あなたは仕様レビューの専門家です。以下の仕様（spec.md）を読み、
「実装者やAIが憶測で埋めてしまいそうな曖昧な点」を洗い出してください。

# 出力ルール
- 曖昧な点ごとに [NEEDS CLARIFICATION] を付け、なぜ曖昧かを1行で説明する
- それぞれに「最も無難なデフォルト案」を1つ添える
- 受け入れ条件として書けるものは「AC-x: 〜なら〜を返す」の形に整形する
- 仕様に書いていない実装方法（How）は提案しない。あくまで What/Why の曖昧さだけ指摘する

# 対象の仕様
{ここに spec.md を貼る}

プロンプト②：受け入れ条件を、テストケースに変換する

仕様が固まったら、ACをテストの設計図に落とす。実行可能仕様の入口です。

以下の受け入れ条件（AC）を、自動テストのケース一覧に変換してください。

# 出力ルール
- 各テストに、対応する AC-x のIDを必ず明記する（トレーサビリティのため）
- 正常系だけでなく、境界値・異常系も網羅する（例: 0文字, 1文字, 100文字, 101文字）
- 各ケースは「前提 / 操作 / 期待結果」の3点で書く
- 実装コードは書かなくてよい。テストケースの一覧だけでよい

# 受け入れ条件
{ここに spec.md の受け入れ条件を貼る}

プロンプト③：コードと仕様の「ドリフト」を差分レビューする

定期的に、あるいはPR前に走らせる。仕様とコードのズレをAIに見つけさせます。

あなたは仕様とコードの整合性をチェックするレビュアーです。
以下の「仕様」と「実装コード」を突き合わせ、ズレ（ドリフト）を報告してください。

# 観点
1. 仕様の受け入れ条件で、コードに実装されていないものはどれか（AC-x で示す）
2. コードにあるが、仕様に書かれていない挙動はどれか
3. 仕様とコードで解釈が食い違っていそうな箇所はどこか

# 出力ルール
- 各指摘に「仕様側の根拠」と「コード側の該当箇所」を必ず併記する
- 確信が持てないものは「要確認」と明示し、勝手に断定しない
- 修正案は提案してよいが、最終判断は人間が行う前提で書く

# 仕様
{ここに spec.md を貼る}

# 実装コード
{ここに該当コードを貼る}

この3本、共通してるのは 「AIに勝手に断定させず、判断は人間に戻す」 形になってること。AIは曖昧さを見つけたり、変換したり、差分を出したりが得意。でも「これでいく」と決めるのは人間。役割分担、ここでもブレさせないのがコツです。

まとめ：明日からの最初の一歩

長くなったので、最後にぎゅっとまとめます。

  • AIで実装が速くなった分、ボトルネックは 「何を作るかの設計と合意」 に移った
  • Vibe Coding（ノリで投げる）は、仕様が会話に沈む・ドリフトする・レビューできない、の3つで静かに事故る
  • Spec-Driven Development は、コードの前に「憲法・仕様・計画・タスク」を構造化して書き、AIへの設計図にする方法論（GitHub Spec Kit / Amazon Kiro が実在ツール）
  • 仕様を “実行可能” にする（受け入れ条件→テスト→CIゲート→トレーサビリティ）と、書いて満足の仕様書から卒業できる
  • ただし 全部をSDD化しない。残すコードにだけ使う。捨てるコードはノリでOK

で、最初の一歩。いきなり全部やらなくていいです。今日やるのは、これだけ。

  1. 次に作る小さな機能を1つ選ぶ（API1本、画面1枚くらい）
  2. その機能の spec.md を1枚書く。受け入れ条件にAC-1, AC-2…と番号を振る（Howは書かない）
  3. プロンプト①を流して、曖昧な点を3つ潰す
  4. プロンプト②で 受け入れ条件をテストに変換 して、そこから実装に入る

これだけで、AIの出力が「なんかズレてる」から「だいたい合ってる」に変わるのを、たぶん体感できます。

最後に、ちょっとだけ個人的な話を。

仕様って、めんどくさい義務みたいに思われがちなんですけど、あきらパパは 「明日の自分への置き手紙」 やと思ってるんです。今日の自分が「何を作りたかったか」を、ちゃんと言葉にして残しておく。そうすると、明日の自分も、隣のチームメンバーも、そしてAIも、迷わず動ける。3日後に「あれ、これ何のために作ったんやっけ」って頭を抱える未来を、先回りで消しておく感覚。

それってつまり、明日の自分が「あの時、仕様書いといてくれてあざっす」って言ってくれる選択なんですよね。

そしてもう一つ。AI時代って、コードを打つ速さで差がつく時代じゃなくなってきてる。差がつくのは、「何を作るかを設計できる力」と、「それを残せる仕組みを持ってるか」。仕様という設計図は、書けば書くほど自分の資産になる。コードはAIが何度でも再生成できるけど、「何を作るべきか」を見抜いて言葉にする力は、AIには丸投げできない、あなたの価値そのものです。

実装者から、設計者へ。手を動かす人から、設計図を描く人へ。その第一歩が、たった1枚の spec.md から始められる。

明日の自分が「あざっす」って言ってくれる一歩、よかったら今日、踏んでみてください。

参考（2026年6月時点で確認した情報源）

  • GitHub Spec Kit（github/spec-kit）公式リポジトリ／ドキュメント
  • Microsoft for Developers ブログ「Diving Into Spec-Driven Development With GitHub Spec Kit」
  • Amazon Kiro 公式ドキュメント（Specs / Steering）

※ ツールのコマンド名・導入手順はバージョンで変わります。実際に使う際は、必ず各公式の最新ドキュメントを確認してください。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?