Claude Codeで始めるスペック駆動開発：ガイド付きチュートリアル

スペック駆動開発とは？

スペック駆動開発は、3つの文書をこの順に積み上げるワークフローです。変更が何をするべきかを述べる文書、それを手順に分解した計画、そして各段階の間に人間のレビューを挟みながら、その計画に沿って書かれるコードです。

スペック駆動開発で、機能が通過する3つのレビュー・ポイント。

スペックは、コードを書く前に平易な言葉でまとめる短い文書で、その変更が何をすべきかを示します。例えば「ユーザーが自分のデータをエクスポートできるようにする」といった機能なら、エージェントが推測しがちな点をスペックで確定させます。たとえば以下を挙げます。

• 対応するファイル形式
• 配布（受け渡し）の方法
• エクスポートが半端な状態のときの挙動
• 意図的に対象外とする機能の範囲

以下は、Telegramベースのアカウンタビリティアプリで、私が行ったworkout-shape-verification変更に対してClaude Codeが書いたスペックの冒頭です。この変更は、脆弱な心拍数の閾値判定を、時間に沿った心拍曲線の「形」に基づくチェックに置き換えるものです。

# Workout Shape-Based Verification — Design Spec
 
**Created:** 2026-05-05
**Status:** Draft
**Supersedes (partially):** [2026-03-17-calisthenics-verification-design.md]
  — replaces the absolute-HR thresholds for the Workout activity type.
  Run / Ride / Walk verification is unchanged.
 
## Problem
 
The current Workout verifier accepts an activity only if absolute heart-rate
levels clear fixed cutoffs: avg ≥ 120, max ≥ 140, range ≥ 30, suffer_score ≥ 3.
Two failures in production:
 
1. **False-negative risk.** As cardiovascular fitness improved
   (resting HR ~80), real calisthenics sessions with disciplined rest now
   average 115–125 bpm. Recent sessions have come within 4 bpm of the 120 floor.
 
<!-- ... continues for hundreds of lines through Solution, Risks,
 	Out of scope, and What is removed / added / changed / unchanged -->

計画は次の文書です。上のスペックを、エージェントが1つずつ進められる番号付きタスクに分解します。各タスクには、対象ファイル、変更内容、順序、テストが記されます。スペックが「何を」に答えるなら、計画は「どの手順で」に答えます。

コードは最後に来ます。計画に沿って、タスクごとに書かれます。

文書は3つ。各段階の間に人間のレビューが入ります。スペックが計画になる前にレビューし、計画がコードになる前にレビューし、最終的にマージ前のコードをレビューします。

プランモードとの違い

Claude Codeのビルトインのプランモード（Shift+Tabを2回で入る）を使ったことがあり、「何が違うのか」と思うかもしれません。プランモードは、1回のチャット内で計画を生成します。計画はメモリ上にのみ存在し、スペックは永続化されず、フェーズ間のレビューもありません。

スペック駆動開発では、スペックと計画をファイルとしてディスクに永続化します。各文書は次のフェーズに進む前に人間のレビューを通り、成果物はセッションをまたいで残ります。プランモードは2つの開発フェーズを1回のチャットに圧縮します。小さな作業なら機能しますが、コードベースが大きくなり実ユーザーに提供し始めると途端に破綻します。

バイブ・コーディングが壁に当たる理由

バイブ・コーディングは、プロトタイプ、単一ファイル、使い捨てスクリプトでは機能します。実ユーザーのいる本番アプリや既存の大規模コードベースでは悪化します。線引きの目安はおよそ4ファイルです。そこに触れる変更はスペックが必要ですし、明確な終着像を持つリファクタや、「正確には何をすべきか」が難所となる作業も同様です。

失敗の原因は明快です。「アプリに写真共有を追加して」のような曖昧なプロンプトは、モデルに数千の暗黙要件を推測させます。

その要件のひとつだけを取り上げてみましょう：通知設定。プロダクトマネージャーはチャネル単位のトグルを想定。バックエンドはオン/オフのスイッチを実装。フロントエンドはOSレベル統合を前提にする。3語に対する4つのもっともらしい解釈、そして4つの別製品が出来上がります。

スペック駆動開発の各レビュー段階は、コストが膨らむ前に異なる種類のミスを捕まえます。スペックレビューはスコープ肥大や誤った原因仮説を、計画レビューは未完の実装や矛盾するパターンを、コードレビューは読み上では良さそうでも最初の失敗テストで崩れる計画を捕捉します。

見返りは確かに得られますが、ゆっくり積み上がります。スペック段階は、コードが動く前に数時間の執筆コストがかかり、最初の数機能はバイブ・コーディングより遅く感じるでしょう。私の場合、損益分岐点は4〜5個目の機能でした。その頃には、スペックが、出荷して1週間後に書き直す羽目になる設計ミスを先に拾ってくれていました。

次の3節では、Claude Code内でこのワークフローを回す3つのオープンソース手法を順に見ていきます。課す構造の軽いものから重いものの順です。

Superpowers

Superpowersは3つの中で最も軽量です。私が日々使っている方法でもあり、最も詳しく扱います。

Superpowersとは？

SuperpowersはJesse VincentによるClaude Code用プラグイン（obra/superpowers、MITライセンス）で、GitHubでおよそ19.4万スターを集めています。

いくつかのスキルを同梱しています。Claudeのスキルは、Claude Codeで、特定のワークフローに従うために必要に応じて読み込まれる、名前付きの指示ファイルです。Superpowersは、コードに直行させず、スペック駆動のループに従わせるスキルを提供します。

SuperpowersのGitHubプロジェクトページ。

Superpowersのインストール方法

Claude Codeの公式プラグインマーケットプレイスからインストールします：

/plugin install superpowers@claude-plugins-official

SessionStartフックがusing-superpowersスキルを自動読み込みするため、入力を始めた瞬間からワークフローが有効になります（Claude code hooksは、特定のライフサイクルイベントでエージェントが実行するスクリプトです）。プロジェクトごとの配線は不要です。

Superpowersのワークフロー

以後は、4つのスキルが日々の作業を支えます。

サブエージェントとは、親が必要に応じて呼び出す、独自のコンテキストウィンドウで集中的に作業する別のClaude Codeインスタンスです。上の表のレビュアーはサブエージェントとして動くため、親の前提を持たず“冷めた目”でコードを読みます。

Superpowersの使い方

4つのスキルは、やりたいことを平易な言葉で伝えると起動します。brainstormingは「新機能について議論しよう」と言えば自動的にスペック作成の会話を始めます。他のスキルも同様にトリガーされます。

4つのSuperpowersスキルの順序。brainstormingとwriting-plansの間に2つの人間レビューがある。

以下の手順では、前述のスペック抜粋と同じworkout-shape-verification機能を用います。

ステージ1：ブレストからスペックへ

Claude Codeを開いて、次のように入力します。

Let's discuss a new feature. The Workout verifier in make-me-work uses absolute heart-rate cutoffs and is now misfiring as my resting HR drops. I want to replace the absolute cutoffs with a check on the shape of the HR curve over the session.

brainstormingスキルが引き継ぎ、次のような質問を10個前後返してきます。

• 正しい「形」とは何か
• どのデータストリームを組み合わせるか
• 形は良いが旧来の閾値に落ちるセッションをどう扱うか
• 変更をRunやRideにも適用するか

ここに人間のレビューが2つ入ります。1つ目は設計レビューで、こちらの回答が狙いどおりかを確認します。2つ目はスペックレビューで、Claudeが書いたファイルを読み、計画作業が始まる前に承認します。

ステージ2：スペックから計画へ

writing-plansスキルを実行します。承認済みのスペックを読み、計画ファイルを4部構成で作成します：

• Doneの定義
• 触れるファイルのファイルマップ
• デモ経路のユーザージャーニー
• 番号付きタスクリスト（チェックボックスの小タスク）

計画をレビューし、順序が不自然・粒度が荒いタスクに差し戻し、承認します。

ステージ3：計画からコードへ

subagent-driven-developmentを実行します。ここからはループが自動で回ります。各タスクについて、このスキルは：

1. 失敗するテストを書く
2. それを通すコードを書く
3. リファクタする
4. 差分を“冷読”するコードレビュー用サブエージェントを起動

レビュアーが問題を指摘したら、次のタスクに進む前に修正します。このステージの内側には人間レビューはありません。この段階に効くレビューは、直前の2つです。

ステージ4：フル差分レビュー

計画が完了したらrequesting-code-reviewを実行します。新しいサブエージェントが、スペックと計画に照らして全差分を読み、レビューを投稿します。マージ前に提案を取り込みます。

計画中のタスクでスペックとの矛盾が露わになった場合、ループは停止して質問します。スペックを編集（Claudeに任せても可）して、該当タスクを再生成できます。もう1つの選択肢は、そのタスク内での一度限りの修正です。Superpowersはスペックの誤りを黙って迂回しません。

ディスク上の実ファイルとしてのスペックと計画

以下は、workout-shape-verification機能のスペックをエディタで開いた様子です。

brainstormingスキルが書き出した直後の、ディスク上のスペックファイル。

ヘッダーにはCreated、Status、Supersedesフィールドが並びます。これはbrainstormingスキルのデフォルト出力です。続いてProblemセクションが来ます。いずれもコードではありません。スクリーンショット以降には、提案する解決策や、変更が触れる範囲・触れない範囲の制約が続きます。

対応する計画ファイルは、User Journeyから始まります。

承認済みスペックからwriting-plansスキルが生成した計画ファイル。

ジャーニーはデモ経路を5ステップ単位で歩き、各ステップごとに正確なコマンド、ファイル、引数を示します。続く番号付きタスクは、各ステップをsubagent-driven-developmentスキルが順に処理できるチェックボックスの小タスクへと翻訳します。

2つの文書の対応は次のとおりです。

スペックと計画を並べて。スペックは「何を・なぜ」に、計画は「どの手順で」に答えます。

より大きなスペックや計画では、公式ループにない工程を1つ足すことがあります。いわゆるレッドチームの読みです。承認前に、複数のOpusサブエージェントにスペックを“冷読”させ、各方面から穴を探させます。これは私の個人的な習慣で、Superpowersの機能ではありませんが、思い込みの誤りを十分に拾ってくれるので続けています。

Superpowersが不向きな場面

Superpowersは単一リポジトリでのソロ作業に合います。コードベース全体が1つのClaude Codeセッションに収まり、2ページ程度のスペックを実際に読むつもりがある場合に最適です。詳細な比較は後述のどれを選ぶべきかにあります。短く言えば、Superpowersはマルチリポジトリの機能や、役割分担を明確にすべき作業では苦戦します。

ある開発者は、プラグインへの公開の苦情で4つ目の失敗モードを指摘しました。「どんな小さなタスクでも果てしなく時間がかかる。Claudeがサブエージェントを立ち上げ、過剰な計画を書き始める。CSSを少し変えるだけでも延々と時間がかかる。」

対処は、極小の変更ではSuperpowersを使わないことです。スキルはブレストのトリガーでのみ起動します。1行のCSS修正なら、スペックループを一度も呼ばずにClaude Codeで済ませられます。ここでの真の失敗は、このワークフローをスペック不要の作業にまで過剰適用してしまうことです。

GitHub Spec Kit

Spec Kitは、スペックが単一のClaude Codeセッションを超えて残る必要がある場合の選択肢です。Claude Codeを開かない人がスペックを読む必要がある場合にも適しています。

GitHub spec-kitとは？

Spec KitはGitHubのプロジェクト（github/spec-kit、MITライセンス、10万スター超）で、CLIと、主要なAIコーディングエージェントで同じように回るワークフローを提供します。Claude Code、Cursor、Aider、Cline、Roo Codeがサポートされています。エージェント非依存の設計により、スペックをClaude Codeの外側に置けます。

Spec KitのGitHubプロジェクトページ。

GitHub spec-kitのインストール方法

現時点で公式のPyPIパッケージはないため、uvでGitタグからCLIをインストールします：

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

vX.Y.Zは最新のリリースタグに置き換えてください。パッケージ名はspecify-cli、登録されるコマンドはspecifyです。

GitHub spec-kitのワークフロー

このワークフローは、CLIがエージェントのスラッシュコマンドに追加する9つのコマンドで回ります。6つがループの中核、3つが補助で、コアがカバーしないケースに使います。

コマンド群と動詞の区切りはコロンではなくドットです：/speckit.specify（/speckit:specifyではない）。

Spec Kitの9つのスラッシュコマンド：パイプライン上にコア6つ、ぶら下がる形でオプション3つ。

これらのコマンドが生成する成果物は、Superpowersの節で見たスペックと計画と同じく、ディスクに書かれGitで追跡されます。違いは可搬性です。Spec Kitの成果物はClaude Codeに限らず任意のAIコーディングエージェントで使えるよう設計され、ワークフローも、単一ツールの副産物ではなく、GitHubのプルリクエストを通じた関係者レビューに向いています。

GitHub spec-kitを使うべきとき

ソロプロジェクトなら、たぶんSpec Kitは不要です。以下の場合に手に取ってください：

• プロジェクトが1人を超えて大きくなった
• Claude Codeを開かない人がスペックをレビューする必要がある
• 一部の作業をClaude Code以外のエージェントで回している
• 特定ツールの外側にあり、数カ月後でも読みやすいスペック形式が欲しい

BMADメソッド

Spec Kitが成果物を整理するのに対し、BMADは人を整理します。スペックからコードまでの流れを4つのフェーズに分け、それぞれを名前のあるロールエージェントが担当します。

BMADとは？

BMAD-METHOD（bmad-code-org/BMAD-METHOD、MITライセンス、約4.7万スター）はv6です。プロジェクトのドキュメントでは、頭字語は「Breakthrough Method for Agile AI-Driven Development」を意味します。Claude Codeほかのエージェント上で動作し、モジュール群としてインストールします。デフォルトのインストールで、6つのロールエージェント、4つのワークフローフェーズ、34以上の名付けられたワークフローを含むコアモジュールが提供されます。

BMAD-METHODのGitHubプロジェクトページ。

BMADのインストール方法

NodeでBMADをインストールします：

npx bmad-method install

6つのロールエージェントは、ユーザーがエージェントホスト内で名前を指定して有効化するプロンプト・ペルソナです。Claude Codeでは、BMADがインストールする有効化コマンドを入力します。リリースによって文法が変わるため、正確な構文はREADMEを参照してください。

BMADの同僚エージェントと成果物

有効化すると、その役割の指示・声・出力を、ペルソナを切り替えるまで引き継ぎます。6名は次のとおりです。

• Mary（アナリスト）
• Paige（テクニカルライター）
• John（プロダクトマネージャー）
• Sally（UXデザイナー）
• Winston（アーキテクト）
• Amelia（デベロッパー）

v6で想定されそうで不在のロールが2つあります：Scrum Masterエージェントと独立したQAエージェントはありません。スプリント計画とストーリー準備はデベロッパーが担い、QAテスト生成はデベロッパーが起動するワークフローです。

成果物は単一のスペックより重厚です。以下が得られます：

• プロダクトブリーフ
• PRD（プロダクト要件文書）
• UXスペック
• アーキテクチャ文書
• エピック（出荷後にユーザーができることを表すユーザーストーリーに分解）

PRDとアーキテクチャ文書が、Superpowersにおけるスペックと同じ役割を果たします。2つに分けることで、担当ロールが分かれ、より形式的な体裁になります。成果物群全体でソフトウェア開発のライフサイクルをカバーし、各機能は上位レイヤーの文脈を継承します。

BMADのワークフロー

v6のワークフローは4つのフェーズで動きます。

4つのBMADフェーズと担当ロールエージェント。小規模作業向けに、最初の3フェーズを飛ばすQuick Flowもある。

フェーズ1：分析は任意です。Mary（アナリスト）とPaige（テクニカルライター）がリサーチを行い、プロダクトブリーフを作成します。作るものが明確ならスキップします。

フェーズ2：計画は必須です。John（PM）がPRDを書き、UIを伴う機能であればSally（UXデザイナー）がUXスペックを加えます。

フェーズ3：ソリューショニングはWinstonの担当です。アーキテクトがまずアーキテクチャを起草し、次にJohnが要件をエピックとストーリーに分割します。ストーリーをアーキテクチャの後に置くのはv6の選択で、実装上の境界に合わせて適切に見積もれます。最後にWinstonが実装準備チェックを行い、PASS、CONCERNS、FAILの判定を出します。

フェーズ4：実装では、Amelia（デベロッパー）がストーリーごとに作業します：ストーリーの作成、実装、コードレビュー。エピック全体が完了したら、エピック全体を対象にQAテスト生成ワークフローを起動します。Claude Codeが実際にコーディングするのは、このAmeliaとして動くこのフェーズです。

小規模で範囲が明確な作業のために、BMADは「Quick Flow」を提供します。Ameliaを直接有効化して最初の3フェーズをスキップします。有効化コマンドはBMADのREADMEにあります（リリースで構文が変わることがあります）。Quick FlowはPRDもアーキテクチャ文書も作らず、短いストーリーと、それを満たすコードだけを生みます。「ボタン変更には大げさすぎる」という異議への回答です。

実装途中でスペックが誤りと判明した場合、BMADはWinstonのフェーズ3判定に戻ります。FAILならフェーズ2に戻ってPRDを書き直し、CONCERNSならWinstonの注記したリスクをストーリーに付けたまま進みます。大きな不整合では停止し、小さな不整合では前進できるように分岐しています。

複雑さが報われるとき

BMADは、実ユーザーに応える長期運用のプロジェクトで効果を発揮します。複数開発者のチームにも適しており、人の間で作業を受け渡せます。フェーズとロールの分離によるコストを、節約時間が上回ることが条件です。

一人のサイドプロジェクトには不向きです。ソロ作業では、4フェーズ・6エージェントの分割は多くがオーバーヘッドで、役割分担の意義も薄いからです。

フレームワークの選び方

選定は3つのルールで決まります。

• スペックをClaude Codeを開かない人も読む必要がある、あるいはGitに長期成果物として残す必要があるならSpec Kit。
• 複数人が明確に役割分担して作業する、あるいはPM的なステークホルダーが実際に関与するならBMAD。
• それ以外はSuperpowers。

プロジェクトに関する3つの質問。その先にある4つのフレームワーク。

意思決定ツリーが示す第4の選択肢は、Spec KitとSuperpowersの併用です。スペック段階はSpec Kitで進め、Gitに成果物を残してチーム横断レビューを可能にします。次に、Superpowersのsubagent-driven-developmentスキルを、1行の設定でSpec Kitの計画ファイルに向けます。Spec Kitの堅牢なスペックと、Superpowersの引き締まった実装ループを両立できます。

結論

スペック駆動開発は、順序だてた3つの文書です。スペックは作るものを、計画は手順を、コードは計画に従います。各段階の間には必ず人間のレビューが入ります。

上の意思決定ツリーでフレームワークを選んでください。多くの読者にはSuperpowersが合うはずです。インストールし、普段ならバイブ・コーディングで済ませていた、3〜5ファイルに触れる機能を1つ選びます。ブレスト、スペック、計画、実行までエンドツーエンドで回してください。実際に1回やってみるのが、どんな説明よりも身につきます。

Claude Codeの基礎を先に復習したい場合は、DataCampに実践的なClaude Codeチュートリアル、プランモード、CLAUDE.md、TDDを扱うベストプラクティスガイド、プランモード自体の詳細解説があります。