Claude Code で spec-driven 開発を 10 倍速にする具体手順

AI コーディングエージェントに指示を投げると、毎回出力が微妙にブレる。個人開発ではタスクを分解しきれず、途中で止まる。この 2 つを同時に解決する方法として、筆者が実運用しているのが 仕様書を先に書いて Claude Code の判断基準として使う spec-driven なワークフローです。本記事では、その最小構成を、コピペで始められるテンプレート付きで解説します。

※ タイトルの「10 倍」は筆者の体感値です。プロジェクト性質により差があります。

spec-driven とは何ではないか

よくある誤解は「仕様書を書く → ウォーターフォールに戻る」ですが、ここでの spec-driven はそれとは別物です。Claude Code に一貫した判断基準を与えるための、軽量なアラインメント層としての仕様書です。

仕様書は完成品ではなく、対話しながら書き換え続ける下書き
実装手順は書かず、受入基準だけ書く
AI が勝手に範囲を広げないよう、「非目的」を明記する

仕様書は 1 機能につき 200 行前後を上限にします。2 画面に収まらない時点で、その機能は小さく切り直すサインです。

全体像

┌── docs/SPEC.md ──┐   ┌── CLAUDE.md ──────┐
│  目的            │   │ プロジェクト憲法  │
│  非目的          │   │ 禁止事項 / 規約   │
│  制約            │   │ 参照ドキュメント  │
│  受入基準        │   │ 優先モデル        │
└────────┬─────────┘   └─────────┬─────────┘
         │                       │
         └───────────┬───────────┘
                     ▼
          ┌────────────────────┐
          │ /plan        仕様 → 計画(ドライラン)  │
          │ /implement   計画 → 実コード + テスト │
          │ /review      差分 → 仕様に反映        │
          └────────────────────┘

/plan → /implement → /review を 1 ループとして、仕様書を書き直しながら進めます。

Step 1: `docs/SPEC.md` を書く

最初に書く唯一の書類。4 ブロック固定で書き始めます。

# Feature: <name>

## 目的 (What / Why)
このフィーチャーで解決したい具体的な問題を 1〜3 行で。

## 非目的 (Out of scope)
- このフィーチャーでは扱わないこと
- 後続のフィーチャーに回すこと

## 制約 (Constraints)
- 技術的制約 (ランタイム、コスト、既存コードとの整合)
- UX 制約 (ターゲットデバイス、言語)

## 受入基準 (Acceptance)
- [ ] 観察可能な条件 1
- [ ] 観察可能な条件 2
- [ ] 観察可能な条件 3

ポイントは 「非目的」ブロック です。AI は文脈を広く読むため、非目的を書かないと勝手にリファクタや関連改善を始めます。明示するだけで範囲の暴走が止まります。「目的」より先に「非目的」を書き切るくらいの気持ちでちょうどいい。

Step 2: `CLAUDE.md` にプロジェクト憲法を置く

CLAUDE.md はリポジトリ直下に置くと Claude Code が自動読込するファイルです。ここには プロジェクト全体の不変条件 だけを書きます。

使用言語・ランタイム・フレームワーク
禁止事項 (例: 新規依存追加前に相談)
命名規則・ディレクトリ規約
参照すべきドキュメント群の場所
優先モデル (デフォルト / 調査 / 軽量タスク)

過去のバグ修正記録を全部残すと、毎セッションの context が膨張します。1〜2 画面で収まる運用不変条件 に限定するのがコツ。変更頻度の高い情報は docs/decisions/ 等の別ファイルに逃がし、そこを CLAUDE.md から参照するに留めます。

Step 3: slash commands で再現性のあるフローを作る

Claude Code の slash commands (.claude/commands/<name>.md) を使って、3 個のコマンドでフロー全体を閉じます。

※ 2026 年現在、.claude/commands/ は後方互換で動作しますが、新しい推奨フォーマットとして Skills (.claude/skills/<name>/SKILL.md) が導入されています。本記事のテンプレートは commands/ で書いていますが、Skills に移植しても同じフローがそのまま機能します。

/plan — 仕様書から実装計画を出す (コード変更しない)
/implement — 計画に従ってコードを変更する
/review — 差分を仕様と突き合わせ、仕様の更新提案を出す

/plan の中身はたとえば次のような書き出しで足ります。

---
description: 仕様書を実装計画に落とす (コード変更しない)
---

You are planning an implementation. DO NOT modify files yet.

1. Re-read `docs/SPEC.md`. Treat it as the single source of truth.
2. Identify the minimal set of files to touch.
3. For each file, describe the change in 1–3 lines. No code.
4. List any OPEN QUESTIONS that would block implementation.
5. Output the plan as a numbered list.

If SPEC.md is ambiguous, stop and ask instead of guessing.

毎回「これから何をするか」を説明する手間が消え、入力トークンも数百減ります。これが回数を重ねるほど効いてきます。

Step 4: サブエージェントと TaskCreate の使い分け

実運用では、状況ごとにツールを切り分けます。

サブエージェント (Agent ツール): コードベース全体の探索や長文読み込みなど、main session の context を汚したくない 場面
TaskCreate / TaskList: セッションをまたぐ進捗追跡、タスクの claim / unblock の管理
上記どちらも使わずに済むのが一番速い。1 タスクで終わる単純作業は直接実行

どれを使うかの判断を毎回悩まないよう、CLAUDE.md に「いつサブエージェントを使うか」を 2〜3 行書いておくと安定します。

落とし穴

仕様書を AI に生成させすぎる。SPEC.md は人間が書くか、最終版は必ず人間レビューを通します。AI 任せにすると、AI の好みに寄った抽象度に収束し、判断基準として機能しなくなる
CLAUDE.md に履歴を溜める。「前回これで詰まった」的な個別事例を全部残すと context が膨らみ、本来不要な制約まで効いてきます。個別事例は docs/decisions/<yyyy-mm-dd>-<topic>.md に分離
/clear と /compact を混同する。/clear は履歴を消す、/compact は要約して続ける。長セッション中に /clear すると直前の計画が飛ぶ。長いタスクでは /compact を優先
仕様書 → 実装が 1 ループで終わると思い込む。/review で受入基準を更新し、仕様書を最新化してから次の機能に進む。これを省略すると次のループの精度が落ちる

ワークフローで 10 倍になったポイント

筆者が体感で大きく効いたのは 4 つ。

「非目的」明記による手戻り削減 — これ単独で 2〜3 割減
サブエージェントでの context 保護 — セッションが 3〜5 倍長持ちする
slash commands による指示入力の省略 — 毎回 100 トークン前後を節約
TaskCreate による中断復旧 — 作業が細切れになる個人開発では地味に最大効果

最後が侮れません。家事・打ち合わせ・別プロジェクトへの割込みで作業が分断される個人開発では、「再開時にどこまで進んでいたか」が一目で分かるだけで気持ち 2〜3 倍は速く戻れます。

まとめ

spec-driven は「重い開発」ではなく「AI の揺れを抑えるアラインメント層」。2 つのファイル (SPEC.md / CLAUDE.md) と 3 つのスラッシュコマンドから始められます。テンプレート一式は記事末尾のリポジトリエクスプローラに置いたので、コピペしてご活用ください。

次回は Bun + Hono で始める個人開発の最小構成 を書く予定です。