なぜspec-kitを利用してBDDする？
まずspec-kitとBDDはそれぞれどのようなものなのかを見てみましょう
🌱spec-kitとは？
仕様駆動開発を支援するツールキットです。
spec-kitを利用すれば、仕様から実行できるコードを生成できます。
🥒BDDとは？
「ユーザーやビジネスの期待される“振る舞い（Behavior）”を起点にして開発を進める」手法です。
ビジネス側とエンジニアの両方が理解できる自然言語で実行できる仕様を書いて、開発を進める手法です。
補足：実行できる仕様とは、仕様と実装が一致していなければ自動テストが失敗するため、仕様が古くなったり、コードのバグを検知できるものを指します。
歴史が長く、実践方法、支えるツールが充実しています。
なぜBDDの実践でspec-kitを薦めたいのか？
spec-kitを利用すると、ビジネスゴールをAIに伝えるだけで、BDDのプロセスに沿って仕様作成から実装までを支援してくれるため、仕様とコードの一貫性を保ちながら効率的に開発を進められます。
実践方法
次に設定から使い方を紹介します。
spec-kitの設定
- spec-kitをインストールする
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
- initコマンドを実行する
今回はclaude codeを利用しますが、他のAIエージェントでも利用できます。
specify init --here --ai claude
claudeに利用したいframework, library🥒などを伝える
今回は🥒BDDを実践するので、backendはBehave、frontendはpickled_cucumberの利用を指示します。
claude init
/init このprojectはfastapi+Behave, flutter+felangel/bloc+pickled_cucumber, mysqlを利用する
開発ガイドラインを作成
AIエージェントと開発者が一貫した方針で開発を進めるように、コード品質、テスト、設計などの「原則・ガイドライン」を定義します。
/speckit.constitution
コード品質、テスト基準、ユーザーエクスペリエンスの一貫性、ビヘイビア駆動開発、テスト駆動開発に焦点を当てた原則を作成します。これらの原則が技術的な意思決定と実装の選択にどのように影響するかについてのガバナンスも含めます。全てのドキュメントは日本語で書くこと
機能開発に進む
signup機能を作りながらspec-kitの使い方を見ていきたいと思います。
仕様を生成するように指示
/speckit.specify sign up機能を作ります。
1.emailを入力して、進むと、認証コード入力画面へ遷移。認証コードをメールに送る。
2.認証コード入力画面で認証コードを入力して進むと、
認証コードが正しいときに、username,password設定画面へ遷移する
間違ってる場合、エラーを表示する。
templateのkeywordは英語のまま、埋め込みの部分だけを日本語で書いて
生成された仕様はspec.mdに保存されます。
commit
仕様をrefinement
speckit.specifyで書いた仕様で曖昧な部分、複数の案がある部分を明確にすることで、後工程でも手戻りを減らすことができます。
/speckit.clarify
例えば、AIからいろんな案を提案するので、どの案で進むかを選びます
開発者が仕様をレビューして、変更、改善したい点をAIに伝える
変更したい内容を直接AIに指示することも可能です
/speckit.clarify
password入力は不要にする(理由：password漏洩を防ぐ、今後はOTPを利用する)。usernameを入力して、正常で終わったら、ログインされる
技術的な計画(plan)を作成する
/speckit.plan
実装する為のタスクを作成する
/speckit.tasks
実装する
/speckit.implement
実装後に一部の仕様を変更したい場合
- clarifyする
/speckit.clarify #### User Story 3 - 認証コードの再送信のシナリオ:
15分に3回まで送信できる。レート制限エラーを表示するのエラーメッセージを改善する
- 変更点をplanする
/speckit.plan is running… @specs/001-email-verified-signup/plan.md の既存の内容をベースにgit commit 1b5d23f にあるspecの変更点だけをplanしてplan.mdを更新して
- taskを作成して、実装する
/speckit.tasks
/speckit.implement
生成されたspec-kitとBDD関連のファイル
├── specs/ # 機能仕様とドキュメント
│ ├── 001-email-verified-signup/ # サインアップ機能
│ │ ├── spec.md # 機能仕様書
│ │ ├── plan.md # 実装計画
│ │ ├── research.md # 技術調査
│ │ ├── data-model.md # データモデル
│ │ ├── tasks.md # タスク一覧
│ │ ├── .....
│
├── backend/ # FastAPI バックエンド
│ └── tests/features/ # gherkin文法で書いた仕様書
│ ├── signup_success.feature # サインアップ: 正常フロー
│ ├── ...
│
├── frontend/ # Flutter フロントエンド
│ └── integration_test/features/ # gherkin文法で書いた仕様書
│ ├── signup.feature # サインアップ: 正常フロー
│ ├── ...
signup.featureの中身
全文はsignup.featureを参考してください
Feature: Email-verified Signup
New user creates account with email, OTP, and username
Scenario: Enter email and request OTP
Given ユーザーがサインアップ画面を訪問している
When 有効なメールアドレス "test@example.com" を入力して進む
Then システムが認証コード入力画面を表示する
Scenario: Verify OTP and navigate to username setup
Given ユーザーが認証コード入力画面にいる
Given メールアドレス "test@example.com" のOTPコードが送信されている
When 正しい認証コードを入力して進む
Then システムがユーザー名設定画面を表示する
BDD自動テストの実行イメージ
fvm flutter test integration_test/signup_bdd_test.dart
各コマンドのの使い方のまとめ
- /speckit.specify — まず“何を・なぜ”を書く（技術詳細は書かない） 
- /speckit.clarify — 仕様の曖昧さを潰す（必要に応じて複数回）
- /speckit.plan — “どう作るか”の方針を作成(アーキテクチャ、技術選定)
- /speckit.tasks — 実行タスクに分解。 
- /speckit.implement — 実装
仕様変更したい場合
clarify~implementを反復する
補足：/speckit.specifyを利用すると別の仕様書（spec.md）を生成されるので、既存の仕様書（spec.md）を更新してから、開発を進めるにはspecify抜きでclarifyから使うのが良いと思います
まとめ
本記事では、spec-kitとBDDを組み合わせた開発手法の実践方法を紹介しました。
主なメリット
- 人間はビジネス価値に集中できる
- 仕様とコードの一致を保証
- 段階的な仕様の洗練
-
specify→clarify→plan→tasks→implementの明確なワークフロー
spec-kit + BDDの組み合わせは、AIと人間が協力して「正しいものを、早く作る」ための強力なアプローチです。ぜひ一度試してみてください。
Discussion