はじめに
近年では「とりあえずプロンプトで書かせる（= vibe coding）」が流行ってきており、私も公私で活用させていただいています。
しかしvibe codingを実際使ってみると、コーディングは速い反面、設計のブレや再現性の低さ、コード品質の低さが目立ちました。
この課題を解決すべく仕様書駆動開発が生まれました。これらは“仕様を中心”に据えてAI実装を制御することで、予測可能なアウトカムとガバナンスを確保する狙いがあると思います。
今回は仕様書駆動開発のツールのうち、Spec Kitを実際に試してみたいと思います。
仕様書駆動開発とは
仕様書駆動開発（Spec-Driven Developmentは、まず仕様書（Spec を作り、そこから実装計画（Plan） → タスクリスト（Tasks） → 実装（Impl へと進めていく開発手法です。
- 先に「何を作るか／どう動くべきか」を言語化することで、
- 要件の抜け漏れや手戻りを減らす
- 実装時の意思決定を早くする
- テスト観点を最初から明確にする
といった効果が得られます。
このプロセスを人手でやると重いのが悩みですが、ここをAIエージェントのSpec Kitが自動化・半自動化してくれます。
SpecKitとは
Spec Kitは、仕様作成から実装・デバッグまでをCLIで支援するAIエージェントです。コマンドを叩くと、現状のリポジトリや指示内容をもとに、仕様や計画、テスト、コード、実行コマンドまで生成・実行します。
利用できるLLM（概要）
環境設定に応じて、一般的に以下のようなLLMを切り替えて利用できます（プロジェクト設定やプラグインに依存）:
- OpenAI 系（GPT）
- Google 系（Gemini）
- Anthropic 系（Claude）
- ほか、ローカル/社内モデルを指定する構成も可能
今回の構築では、Gemini CLI を利用して Spec Kit を動かしています。
よく使うコマンド（初心者向け早見表）
| コマンド | 使うタイミング | 何が起きるか |
|---|---|---|
speckit spec |
アイデアが固まったら | ヒアリングから仕様書（spec.mdを生成） |
speckit plan |
仕様ができたら | 技術計画書（plan.md）を生成（構成・設計方針） |
speckit tasks |
計画に合意したら | タスクリスト（tasks.md）を生成（実装手順） |
speckit impl |
実装を始めたい | タスクに沿ってコード実装＆テスト実行＆デバッグ |
speckit clarify |
不明点があるとき | Spec Kitから質問が飛んでくる（要件の明確化） |
speckit analyze |
現状を把握したい | コードベース分析と改善提案を出力 |
ワークフローの全体像
利用時の手順（RAG Q&Aを例に）
ここからは、初心者が最短で体験できる実践ステップです。コマンドや成果物は実際に使った流れに基づいています。
1. 仕様を作る（spec）
今回RAGの勉強も兼ねて、RAGのQ&Aシステムを開発するのにSpecKitを利用しようと思います。そのため、以下のように作りたいものの概要を伝えて実行します。（実際はもっと詳細伝えています。）
「RAGのQ&Aシステムを作りたい。UIはStreamlit、APIはFastAPI、ベクトルDBはQdrant、inputのデータはyoutubeの書き起こしがtxtファイルで存在しベクトルDBにも埋め込む。UIはチャット形式にして」
speckit spec
- 出力：
spec.md（機能/非機能要件、APIスキーマ、評価観点など）
参考：「ざっくり『RAGのQ&Aシステムを作りたい。UIはStreamlit、APIはFastAPI、ベクトルDBはQdrantで』と伝えて実行しています。
2. 計画を作る（plan）
仕様をもとに、技術方針やファイル構成を作ってもらいます。
speckit plan
- 出力：
plan.md（構成、依存関係、クラス設計など）
3. タスクを作る（tasks）
実行手順が明文化されます。
speckit tasks
- 出力：
tasks.md（実装手順のチェックリスト）
4. 実装を進める（impl）
いよいよ自律実装。依存追加、Docker構築、データ投入スクリプト生成・実行、テスト作成・実行、失敗時の自己デバッグまで回してくれます。
speckit impl
ポイント：SpecKitの
implはTDD（テスト駆動開発）を内包しています。実装完了より前にテストケースを先に作り、そのテストがパスするまで継続的に開発します。つまり、各タスクを「テスト → 実装 → テスト」のループで前進させるイメージです。
参考：テスト自動実行の裏側（要点）
Spec Kitは自身の開発サイクルの中に「テスト実行」を組み込んでいます。
① テスト生成 → ②（失敗するのを前提に）実行 → ③結果を読んで修正 → ④再テスト、を繰り返して前進します。
人間が行うTDDのループを、エージェントが裏側で高速に回しているイメージです。
生成される代表的なテスト（例）
テストは単体／結合／RAG評価の3層で作られました。
backend/tests/
├── unit/test_rag.py # チャンク分割などの純粋ロジック
├── integration/test_api.py # /ask APIの疎通と契約
└── rag_eval/test_retrieval.py# Qdrant検索の健全性
| タスクID | タスク内容（要約） | テスト例 |
|---|---|---|
| T010 | チャンク分割の単体テスト | unit/test_rag.py |
| T011 |
/askの結合テスト |
integration/test_api.py |
| T012 | RAG検索の評価テスト | rag_eval/test_retrieval.py |
補足：
impl中に失敗したテストがあれば、Spec Kitがログを読み、原因を推定し、コードや設定を自動修正して再実行します（何度も助けられました）。
（補足）5. 運用・保守での使い分け
手順の本質からは外れるため補足として記載します。
- 小さな修正（ホットフィックス）：そのまま自然言語で依頼
例）「/askのログにリクエストIDを追加して」「UIタイトルを変更して」 - 大きな変更（新機能・構造変更）：仕様→計画→タスク→実装を再実行
例）認証追加、データスキーマ刷新などはspec → plan → tasks → implを回すのが安全
実際に利用して感じたこと
良かった点
- スピードが段違い定型作業（雛形、設定、コマンド）を任せられ、人間は要件と設計の本質に集中できる。
- 自律デバッグが強力：
docker-compose logsやpytestの失敗を自分で読み、修正して再実行。環境依存のハマり所に強い。 - 一貫したドキュメント同期：
spec → plan → tasksと成果物が連鎖し、なぜその実装になったかが追いやすい。
難しかった点／コツ
- 指示は具体的に：曖昧な「いい感じに」ではなく、ログ提示や目的の明確化が大切。例：「このテストの失敗理由を特定して」。
- 思考の可視性：修正の意図が読みにくい場面も。コミットメッセージや変更点サマリの強化が今後の期待。
- レビューと品質担保の線引きが難しい：
仕様書からテストまで自動で走るため、人間がどこまでレビューするべきかの判断が課題。特に「要求の妥当性（正しい仕様か）」「セキュリティ/パフォーマンス要件」「運用上のSLO/SLA」「観測可能性（ログ/メトリクス/トレース」は、人が意識的にレビュー/ゲート化すべきポイント。プロダクション開発では、- 変更要求テンプレ＋受け入れ基準
- 静的解析/脆弱性スキャン
- パフォーマンステスト閾値
- セキュリティレビュー/権限境界レビュー
- 本番前の手動チェックリスト（運用 runbook/rollback手順を含む）
などを人間の責務として定義しておくと品質を保ちやすいと感じました。
まとめ
- テストが常に回る前提を作ると、Spec Kitの価値が最大化されます。
- 構造変更や大規模追加は、仕様書駆動モードに切り替えると安全に進められます。
- 実務では、人間側のレビュー境界（要求妥当性・非機能・セキュリティ・運用要件）を明確にし、品質ゲートを設計しておくと安心です。