GitHub Spec Kitで仕様駆動開発を自動化してみた結果と注意点
[GitHub Spec Kit](https://github.com/github/spec-kit)は、GitHub公式が提供する仕様駆動開発ツールです。コマンド実行だけで、AIが仕様書作成から技術選定、実装計画、コード生成までを自動実行します。ブロック崩しゲーム開発で検証した結果、工数は削減されましたが、人間による仕様チェックの重要性も明らかになりました。

## この記事のまとめ

**Spec Kitで自動化される作業**
- プロジェクトの初期セットアップ
- プロジェクト原則の策定
- 詳細な仕様書の自動生成
- 技術選定と実装計画の立案
- タスクリストへの分解
- 実装の実行

**実際に得られた効果**
- 従来ステップバイステップで指示していた作業が簡略化
- 要件定義と品質チェックに集中できた
- 仕様や実装計画がマークダウンファイルとして出力され、チーム共有しやすい

**注意すべき課題**
- 予期しない機能の混入リスク（各ステップでの人間によるフィードバックが重要）
- オーバーエンジニアリング傾向（各ステップでの人間によるフィードバックが重要）
- テンプレートが英語のため、事前に翻訳しておくと便利

## 仕様駆動開発とは？

仕様駆動開発（Spec-Driven Development, SDD）は、ソフトウェア開発の初期段階で「仕様（Spec）」を明確に記述し、その仕様を軸に設計・実装・テスト・ドキュメント化までを一貫して行う手法です。

従来の「とりあえずコードを書いて後から仕様を調整する」アプローチとは逆に、仕様を中心とした開発プロセスを採用します。仕様書が唯一の真実の源泉（Single Source of Truth）となり、プログラム実装やテストケースはすべて仕様に従います。

### Vibeコーディングとの違い

AI時代の開発手法として、「Vibeコーディング」と「仕様駆動開発」という2つのアプローチがあります。

**Vibeコーディング**は、開発者がAIと会話のように指示しながらコードを生成する手法です。プロトタイプ作成には便利ですが、複雑なアプリケーション開発では要件を満たさないコードが生成される可能性があります。

**仕様駆動開発**は、詳細な仕様書を起点とする構造化されたプロセスです。仕様書が「唯一の真実の源泉」となり、コード生成の根拠となるドキュメントを持ちます。

GitHub公式によると、両者の違いは以下のように説明されています。

> 私たちはコーディングエージェントを検索エンジンのように扱っていますが、本来は文字通りの指示に従うペアプログラマーのように扱うべきです。

出典：[Spec-driven development with AI](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)

| 項目 | Vibeコーディング | 仕様駆動開発 |
|------|------------------|-------------|
| **開発の起点** | 曖昧なプロンプトから開始 | 詳細な仕様書から開始 |
| **AIの役割** | パターン認識でコード生成 | 仕様を解釈して実装 |
| **開発プロセス** | 行き当たりばったり | 段階的（Specify→Plan→Tasks→Implement） |
| **コード品質** | 「それっぽい」コードが生成される可能性 | 要件に沿ったコードが生成される |
| **検証方法** | 実装後に手動確認 | 各段階で検証ポイントあり |
| **向いている用途** | 簡単なプロトタイプ | 複雑なアプリケーション |
| **ドキュメント** | 実装後に作成（または作成されない） | 開発の起点として最初に作成 |

**具体例**

Vibeコーディングでは、「ログイン機能を作って」という指示だけでAIがコードを生成します。しかし、セキュリティ要件やエラーハンドリングが不足する可能性があります。

仕様駆動開発では、まず「パスワードは8文字以上、ログイン失敗3回でアカウントロック、セッション有効期限は24時間」といった詳細な仕様を定義してから実装します。

### 仕様駆動開発のメリットと注意点

**要件の明確化と手戻り削減**
- 事前に仕様を書くことで、開発者間の認識のズレを早期に発見
- 実装段階での手戻りが削減され、開発効率が向上

**チームコミュニケーションの改善**
- 仕様書が共通認識の基盤となる
- 属人化を防ぎ、新メンバーのオンボーディングが円滑に

**ドキュメント品質と保守性の向上**
- 仕様が常に最新の状態で維持される
- 将来的な引き継ぎや改修が容易に

**予測性の向上**
- 推測作業が減り、予期せぬ事態が少なくなる
- より高品質なコードが実現

### 注意すべき点

**初期コストの増加**
- 仕様作成に時間が必要
- 開発初期の投入時間が増える

**仕様更新の手間**
- 要件変更時に仕様書の更新が必要
- 仕様とコードの同期を保つ運用が求められる

### AI時代の仕様駆動開発

AIツールと組み合わせることで、仕様書から実装まで一気通貫で自動化できるため、最近注目を集めています。GitHubの「Spec Kit」やAWSの「Kiro」などのツールが登場し、実践を支援しています。

仕様を「実行可能」にすることで、開発意図自体をソフトウェア開発の中核に据えることを目指します。

## GitHub Spec Kitとは？

GitHub Spec Kitは、GitHub公式が提供する仕様駆動開発（Spec-Driven Development）用ツールキットです。

GitHub公式によると、Spec Kitは「仕様を実行可能にすることで、ソフトウェア開発を変革する」ことを目指しており、**「『何を』作るかを『どのように』作るかよりも先に定義する、意図駆動の開発」**を実現します。

### 基本コンセプト

GitHub公式によると、Spec Kitの開発プロセスは以下の特徴を持ちます。

- **リッチな仕様作成**: 詳細で構造化された仕様書を作成
- **段階的な洗練**: 複数ステップで仕様を詰めていく
- **AI活用**: 高度なAIモデルの能力を活用して仕様を解釈・実装

### 提供されるコマンド

Spec Kitは、開発プロセスを構造化するためのスラッシュコマンドを提供します。

| コマンド | 役割 |
|---------|------|
| `/constitution` | プロジェクトの原則とガイドラインを策定 |
| `/specify` | プロジェクト要件とユーザーストーリーを定義 |
| `/clarify` | 不明確な箇所を計画前に明確化 |
| `/plan` | 技術的な実装計画を作成 |
| `/tasks` | 実行可能なタスクリストを生成 |
| `/analyze` | 成果物間の一貫性をチェック |
| `/implement` | すべてのタスクを実行して機能を構築 |

### 対応するAIアシスタント

GitHub公式によると、2025年10月3日現在、Spec Kitは以下のAIアシスタントに対応しています。

- Claude Code
- GitHub Copilot
- Gemini CLI
- Cursor
- Qwen Code
- Opencode
- Windsurf
- Kilo Code
- Auggie CLI
- Roo Code
- Amazon Q Developer CLI（一部制限あり）
- Codex CLI（一部制限あり）

### 対応する開発フェーズ

GitHub公式によると、Spec Kitは以下の3つの開発フェーズをサポートします。

**0-to-1開発（グリーンフィールド）**
- ゼロから新規プロジェクトを生成
- 高レベルの要件から開始
- 実装ステップを計画

**クリエイティブ探索**
- 多様なソリューションを探索
- 複数の技術スタックをサポート
- UXパターンを実験

**反復的改善（ブラウンフィールド）**
- 既存機能に反復的に機能を追加
- レガシーシステムのモダナイゼーション
- プロセスの適応

### 実験的な目標

GitHub公式によると、Spec Kitは以下の目標を掲げています。

- 技術非依存性の実現
- エンタープライズ制約のサポート
- ユーザー中心の開発の実現
- クリエイティブで反復的なプロセスの実現

仕様と実装を一体化し、整合性・効率・保守性を高めることで、組織が繰り返しコードを書くことではなく、プロダクトシナリオに集中できるようにすることを目指しています。

## やってみた

実験としてブロック崩しゲームを作ってみました。

大体の開発の流れは、

1. プロジェクトのセットアップ
2. プロジェクトの原則を設定する
3. 要件を伝えて仕様書を作る
4. 実装計画を立てる
5. TODOリストを作る
6. 順に実装する

というものになります。

### プロジェクトセットアップ

まずは以下のコマンドでSpec Kitをインストールします。

```
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
```

そして、以下のコマンドでプロジェクトを作成します。

```
specify init <PROJECT_NAME>
```

これを実行するとAIアシスタントを選択する画面が表示されるので、任意のものを選びます。

![スクリーンショット 2025-10-03 17.16.46.png](https://image.docbase.io/uploads/e5701edd-e29a-48f9-be45-6b7ec64f6b22.png =612x387)

今回はClaudeを選択しました。
選択後、`<PROJECT_NAME>` の名前でプロジェクトがセットアップされ、以下のように完了のお知らせが表示されます。

![スクリーンショット 2025-10-03 17.17.15.png](https://image.docbase.io/uploads/9002d242-a99b-4512-bbba-2ae8629b47bc.png =WxH)

作業ディレクトリに移動してClaude Codeを実行します。

### プロジェクト原則の策定

`/constitution`コマンドでプロジェクトの原則とガイドラインを定義します。

このコマンドを実行すると、AIがプロジェクトの開発方針を策定してくれます。ここで定義される内容は、以下のようなものです。

- コード品質基準
- テスト標準
- ユーザー体験の一貫性
- パフォーマンス要件
- セキュリティ方針

これらの原則は、後続の仕様書作成や技術選定、実装計画の際にAIの意思決定の指針として機能します。

例えば、「シンプルさを優先」「必要最小限の依存関係」といった方針をここで明記しておけば、AIがオーバーエンジニアリングな提案をすることを防げます。

生成されたプロジェクト原則は`constitution.md`として保存されます。

今回は、以下の画像のように、公式ドキュメントを和訳したそのまま指定してみます。ついでに、出力されるドキュメントは日本語がいいのでそのように指定しておきました。

![スクリーンショット 2025-10-03 17.19.50.png](https://image.docbase.io/uploads/f134f2fe-de46-4b04-92d1-c70e0aa82e85.png =WxH)

すると、以下のようなルールを作ってくれました。

![スクリーンショット 2025-10-03 18.44.15.png](https://image.docbase.io/uploads/35aba84a-fb53-4307-8d8d-ba2e6e91a86e.png =WxH)

### 仕様書の生成

では、続いて仕様書を生成します。

仕様書の生成には `/specify` コマンドを実行します。

公式ドキュメントにも書いてある通り、**できるだけ詳細に「何を」、「なぜ」開発したいか？**とともに指示します。ただし、この段階では技術スタックを指定しません。

今回は、次のように指示しました。

![スクリーンショット 2025-10-03 17.27.53.png](https://image.docbase.io/uploads/33652cd5-976b-4772-baa4-a61d9c196d7c.png =WxH)

すると、以下のような仕様書を作ってくれました。

![スクリーンショット 2025-10-03 18.49.20.png](https://image.docbase.io/uploads/1beed863-962a-4ea7-ac09-49cd49677d80.png =WxH)

※ ご覧の通り、生成されるドキュメントは基本的に英語で出力されます。執筆時点(2025/10/03)で多言語対応はされていません。各ドキュメントはプロジェクトセットアップ時に生成される `.specify/templates` ディレクトリにあるテンプレートを元に生成されているようなので、**各コマンドを実行する前にこれらのテンプレートを翻訳しておくと良さそう**です。

この仕様書の中には、 `[NEEDS CLARIFICATION]`とマークされている箇所があります。
その箇所は人間によって仕様を明確にしてほしいところ。まだ仕様が未決定なところです。

それらの仕様決めを会話形式で進めてくれるのが `/clarify` コマンドです。
`/clarify` コマンドを実行すると、以下のように未決定の仕様について1つずつ確認をとってくれるので面倒くさがらずに答えていきます。
![スクリーンショット 2025-10-03 17.32.50.png](https://image.docbase.io/uploads/9c8b1515-42ca-4dd4-8252-6022521dd469.png =WxH)

これら全てに答えると仕様が明確化され、次の計画段階に進めます。

![スクリーンショット 2025-10-03 17.35.29.png](https://image.docbase.io/uploads/71202a5c-cde4-4220-a72c-a57717bc4cb6.png =WxH)

### 実装計画の生成

続いて、`/plan` コマンドを実行して実装計画を立ててもらいます。
計画段階では、指示された技術スタックなどの希望を伝えます。

![スクリーンショット 2025-10-03 17.38.52.png](https://image.docbase.io/uploads/37231f5a-a4fe-46d7-a519-683854c9e45e.png =WxH)

ユーザーからの指示を元に、必要な技術スタックの調査・選定や実装計画を立ててくれます。また、特に何も指定しなくてもテスト駆動開発のような計画を作ってくれます。

技術スタックの調査報告書は以下です。

![スクリーンショット 2025-10-14 10.13.28.png](https://image.docbase.io/uploads/818c6107-2495-42cc-a997-26e71ef924b0.png =WxH)

実装計画は以下です。

![スクリーンショット 2025-10-14 10.14.13.png](https://image.docbase.io/uploads/9159cde9-6b7c-4d35-9ccc-8afbaea00a36.png =WxH)


### TODOリストの生成

`/tasks` を実行して、計画を元にTODOリストを作ります。
このTODOリストに従ってClaudeが実装を進めていくことになります。

![スクリーンショット 2025-10-14 10.15.05.png](https://image.docbase.io/uploads/05f63fe5-24c1-4bf5-86c1-9550727ea9b6.png =WxH)

### 実装開始

`/implement` コマンドを実行して実装を指示します。
`/implement` コマンドを実行すると、先ほど生成したTODOリストに従って実装を開始してくれます。

今回はこんな成果物になりました。

[![mp4](/images/file_icons/movie.svg) block-breaker.mp4](https://docbase.io/file_attachments/78d692f8-6b10-4ee2-b3de-01dcac1317a8.mp4)


## 使ってみての感想

冒頭にも書きましたが、Spec Kitを使ってみていくつか教訓が得られました。

今回感じたSpec Kitの良い点は、

- **コマンドを実行するだけで、AIが詳細な仕様書作成や実装計画立案、技術選定、実装までしてくれる**
- **仕様や実装計画、技術選定などをそれぞれファイルとして出力してくれる**
- **勝手にテスト駆動開発してくれる**
- **Claude Codeに自然と統合できる**

という点です。

AIに作業を指示するとき、抽象的な指示だけだとAIが何を作りたいのかを理解できず、意図した成果物にならないことがあります。
かといって仕様書作成や計画立案などを1つ1つ指示するのは面倒なので、**Spec Kitによって、AIに自動で仕様書駆動開発してもらえるのは便利**です。

また、**仕様や実装計画、技術選定などをそれぞれマークダウンファイルとして出力してくれる**ため、いつでも読み返せるし修正しやすい。
それに、それらのファイルを**DocBaseなどの情報共有サービスに投稿できるのでチームメンバーと協働作業しやすそう**です。

それに、今回はClaude Codeと統合してみましたが、**追加されたスラッシュコマンドを順番に実行するだけでいいので利用のハードルが低い**のもポイントでした。

反面、特に何も指示しない場合は

- オーバーエンジニアリングになってしまう（これはモデルのクセかも）
- 想定外の仕様が加えられている

こともあるため、**各ステップで人間が適切にフィードバックするのが重要そう**です。

## 今後の活用
開発中に考えた、どのように活用すれば良さそうか？のアイディアもシェアします。

- チームで開発する場合、AIが生成した仕様書や技術選定レポートはメンバーに共有して議論が必要になりそう。その場合、Claude CodeやGemini CLIとDocBaseを[MCPサーバーで連携](https://help.docbase.io/posts/3902361)しておき、AIが生成したドキュメントをDocBaseに投稿することで議論の対象にできそう
    - 議論が完了したら、Claude CodeやGemini CLIで「DocBaseから仕様書を取得して spec.md に反映して」でOK
- Spec Kitのテンプレートは英語なので、日本語版をDocBaseにチーム共有でメンテナンスしておけば、プロジェクト間で流用できそう

## まとめ

GitHub Spec Kitは、以下の特徴を持つ仕様駆動開発ツールです。

**自動化される作業**
- プロジェクトセットアップから実装まで7つのコマンドで完結
- 仕様書、実装計画、技術選定レポートをマークダウンで出力
- テスト駆動開発を自動適用

**注意が必要な点**
- 人間による仕様書レビューが必須（致命的バグの混入リスク）
- オーバーエンジニアリング傾向（各ステップでのフィードバックが重要）
- テンプレートが英語（事前翻訳を推奨）

現時点では、新規プロジェクト開発での活用が確認されています。

## Q&A

この記事を読んで多くの方が抱くであろう疑問について、Q&A形式でお答えします。

### 個人開発者が今すぐ試す価値はありますか？

はい、特に「仕様を詰めるのが苦手」「テストを書く習慣がない」開発者には効果的です。

ただし、生成された仕様書は必ず人間がレビューしてください。AIが自動生成する仕様には、要件の解釈ミスや過剰な設計が含まれる可能性があります。

### 既存プロジェクトにも導入できますか？

はい、可能です。

公式ドキュメントによると、`specify init . --here` コマンドで現在のディレクトリに初期化できます。既存ファイルを上書きする必要がある場合は `--force` フラグを使用します。

ただし、今回は新規プロジェクトでのみ検証したため、既存プロジェクトでの実際の挙動は未確認です。

### 英語が苦手でも使えますか？

工夫が必要です。

`templates/` ディレクトリのテンプレートファイルを事前に日本語翻訳しておくことで、日本語での仕様書生成が可能になります。

また、公式ドキュメントによると、`/constitution` コマンドを使ってプロジェクト原則を定義する際に、コード品質基準、テスト標準、ユーザー体験の一貫性、パフォーマンス要件などを日本語で記述しておけば、それらがAIの技術的意思決定の指針として機能します。

### チーム開発での活用方法は？

AIが生成した仕様書や技術選定レポートを、DocBaseなどの情報共有ツールに投稿してレビューフローに組み込むのが有効です。

Claude CodeやGemini CLIとDocBaseを[MCPサーバーで連携](https://help.docbase.io/posts/3902361)しておけば、AIが生成したドキュメントを直接DocBaseに投稿できます。チームでレビューが完了したら、「DocBaseから仕様書を取得して spec.md に反映して」と指示するだけで同期できます。

### 各コマンドを使う際のコツは？

公式ドキュメントでは、各コマンドで以下のポイントを意識することを推奨しています。

**`/constitution`コマンド**
- プロジェクトの原則を最初に定義する
- 「シンプルさを優先」「必要最小限の依存関係」などの方針を明記
- これにより、後続の全ステップでAIの意思決定に一貫性が生まれる

**`/specify`コマンド**
- 「**何を**」「**なぜ**」に集中し、技術スタックは書かない
- ユーザーインタラクション、機能の期待値、コア機能を明確に記述
- エッジケースや制約条件も含めると、より正確な仕様書が生成される

**`/clarify`コマンド**
- `/plan`を実行する前に、曖昧な箇所を明確化
- 仕様書に`[NEEDS CLARIFICATION]`マーカーが残っている場合は、必ず対応してから次のステップへ

**`/plan`コマンド**
- この段階で初めて技術スタックを指定
- `/constitution`で定義したプロジェクト原則を見直し、技術選定の方向性を確認

**全体のコツ**
- 各ステップの実行後、必ず生成されたドキュメントを確認
- 不要な複雑性があれば即座にフィードバック

### オーバーエンジニアリングを防ぐコツは？

各ステップの実行後、必ず生成されたドキュメントを確認し、不要な複雑性があれば即座にフィードバックしてください。

AIは「しっかりした設計」を優先する傾向があるため、シンプルなプロジェクトでも状態管理ライブラリやテストフレームワークなど、過剰な技術スタックを提案することがあります。

公式ドキュメントでは、`/constitution` コマンドでプロジェクト原則を事前に定義することを推奨しています。ここで「シンプルさを優先」「必要最小限の依存関係」といった方針を明記しておけば、AIの提案がプロジェクトの性格に沿ったものになります。

## 参考リンク
- [GitHub SpecKit 公式リポジトリ](https://github.com/github/spec-kit)
- [Claude Code公式ドキュメント](https://docs.anthropic.com/ja/docs/claude-code/overview)
- [ClaudeにDocBaseのリモートMCPサーバーを接続する](https://help.docbase.io/posts/3902361)

## 著者について

2019年よりDocBaseの開発にフロントエンド／バックエンドエンジニアとして参加。  
新エディターや検索機能、[公式リモートMCPサーバー](https://help.docbase.io/posts/3919854)の開発などに携わる。  
日々、ChatgGPTやClaude、NotebookLMなどのAIエージェントを活用。

主なスキルは以下の通り。
- フロントエンド: React, TypeScript  
- バックエンド: Ruby, Ruby on Rails
- インフラ: Terraform