はじめに

こんにちは、コウです。
近年、AI技術の進歩により、仕様駆動開発においてもAIを活用する事例が増えてきました。
本記事では、私がAIを活用して仕様駆動開発をしてみた経験について共有します.

仕様駆動開発とは

仕様駆動開発とは、仕様を最初に明確・厳密に定義し、その仕様を基準に実装・テストを進める開発手法です。
仕様が明確であるため、開発プロセス全体の透明性が高まり、品質の向上やコミュニケーションの円滑化が期待できます。

特徴

• 実装よりも仕様書が主役
• 仕様が「契約（Contract）」の役割を持つ
• 実装者は仕様に従ってコードを書く
• テストは仕様を満たしているかを検証する

典型的な流れ

1. 要件定義
2. 仕様書作成（API仕様、状態遷移、入出力、制約など）
3. 仕様レビュー・合意
4. 実装
5. 仕様ベースでテスト（自動テスト含む）

従来の仕様駆動開発の課題

従来の仕様駆動開発では、仕様書の作成や更新に多くの時間と労力がかかることが課題でした。
また、仕様と実装の乖離が発生しやすく、開発プロセス全体の効率が低下することもありました。

AIによる仕様駆動開発のメリット

AIを活用することで、仕様書の自動生成や更新が可能となり、開発プロセスの効率化が図れます。
さらに、AIは大量のデータとコードを解析し、仕様と実装の整合性をチェックすることができます。

バイブコーディングとの違い

バイブコーディングは、AIと人間がリアルタイムで協力してコードを書く手法ですが、よくAIが人間の指示をわからないままにコードを書いてしまうことがあります。
仕様駆動開発では、まず仕様を明確に定義し、その後に実装を進めますので、AIが仕様に基づいてコードを生成するため、より正確な実装が期待できます。

開発体験記

今回、私はgithub spec-kitを活用して仕様駆動開発を試みました。

github spec-kitとは

github spec-kitはGitHub が提供している仕様駆動開発を支援するツールキットで、仕様書の管理、テストケースの自動生成、ドキュメントの生成などをサポートします。

開発内容

今回のプロジェクトでは、Excel ファイルを PDF に変換する REST API サービスを開発しました。

インストールと初期化

まずは以下のコマンドを実行し、github spec-kitをインストールします。

1uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

そして、使用するAIエージェントとスクリプトを選択し、インストール完了です。

すると、以下のようなディレクトリ構成が自動生成されます。

1└── 📁.github
2    └── 📁agents
3        ├── copilot-instructions.md
4        ├── speckit.analyze.agent.md
5        ├── speckit.checklist.agent.md
6        ├── speckit.clarify.agent.md
7        ├── speckit.constitution.agent.md
8        ├── speckit.implement.agent.md
9        ├── speckit.plan.agent.md
10        ├── speckit.specify.agent.md
11        ├── speckit.tasks.agent.md
12        ├── speckit.taskstoissues.agent.md
13    └── 📁prompts
14        ├── speckit.analyze.prompt.md
15        ├── speckit.checklist.prompt.md
16        ├── speckit.clarify.prompt.md
17        ├── speckit.constitution.prompt.md
18        ├── speckit.implement.prompt.md
19        ├── speckit.plan.prompt.md
20        ├── speckit.specify.prompt.md
21        ├── speckit.tasks.prompt.md
22        └── speckit.taskstoissues.prompt.md
23└── 📁.specify
24    └── 📁memory
25        ├── constitution.md
26    └── 📁scripts
27        └── 📁bash
28            ├── check-prerequisites.sh
29            ├── common.sh
30            ├── create-new-feature.sh
31            ├── setup-plan.sh
32            ├── update-agent-context.sh
33    └── 📁templates
34        ├── agent-file-template.md
35        ├── checklist-template.md
36        ├── plan-template.md
37        ├── spec-template.md
38        └── tasks-template.md

こちらは、github spec-kitのコマンドを解釈と実行する用のテンプレートやエージェントが格納されているディレクトリです、基本は触る必要はありません。

コマンド実行

github spec-kitでは、以下のコマンドを使用して仕様駆動開発を進めていきます。

開発ワークフロー

プロジェクトの基本方針を定義（Constitution）

以下​コマンドでプロジェクトの基本方針を定義します。

1/speckit.constitution  <指示：プロジェクトの原則とガイドラインの定義>

このコマンドを実行すると、開発における価値観、設計原則、制約、非機能要件（品質、セキュリティなど）が明文化されます。
結果は.specify/memory/constitution.mdに保存されます。

プロジェクトの原則とガイドラインの定義とは

• 価値観: 開発において重視する価値観（例: ユーザー中心設計、セキュリティ第一など）
• 設計原則: コード品質、モジュール化、再利用性などの設計に関する指針
• 制約: 使用する技術スタック、プラットフォーム、ライブラリの制約
• 非機能要件: パフォーマンス、スケーラビリティ、セキュリティ、可用性などの要件
• 開発プロセス: コードレビュー、テスト戦略、デプロイメント手順などの開発に関するルール

要件定義（Specify）

以下​コマンドで要件定義を行います。

1/speckit.specify  <指示：機能要件、ユーザーストーリー、API仕様>

このコマンドを実行すると、自動的にブランチを切って、ユーザーストーリー、機能要件、API仕様などが具体化されます。
結果はspecs/001-<機能名>/spec.mdに保存されます。

機能要件、ユーザーストーリー、API仕様の具体化とは

• ユーザーストーリー: ユーザーの視点から見た機能の説明（例: "ユーザーとして、Excel ファイルを PDF に変換したい"）
• 機能要件: システムが提供すべき機能の詳細な説明（例: "Excel ファイルのアップロード、PDF ファイルの生成、PDFファイルのダウンロード"）
• API仕様: エンドポイント、リクエスト/レスポンス形式、認証方法などの技術的な仕様

不明点の解消（Clarify）

以下​コマンドで不明点の解消を行います。

1/speckit.clarify <指示：不要でも良いです。>

このコマンドを実行すると、仕様書の曖昧・矛盾・不足している点を洗い出し、人間に質問を投げかけ、意思決定を明確化します。
結果はspecs/001-<機能名>/spec.mdに反映されます。

曖昧・矛盾・不足している点を洗い出し、意思決定を明確化とは

• 曖昧な要件の特定: 仕様書内の不明確な部分を特定し、具体的な質問を作成
• 矛盾の解消: 仕様書内で矛盾している部分を特定し、解決策を提案
• 不足している情報の補完: 仕様書に不足している情報を特定し、必要な情報を収集

実装計画の策定（Plan）

以下​コマンドで実装計画の策定を行います。

1/speckit.plan  <指示：技術選定、アーキテクチャ設計、実装手順や依存関係>

このコマンドを実行すると、技術選定、アーキテクチャ設計、実装手順や依存関係が整理されます。
結果はspecs/001-<機能名>/plan.mdに保存されます。

技術選定、アーキテクチャ設計、実装手順や依存関係の整理とは

• 技術選定: 使用するプログラミング言語、フレームワーク、ライブラリの選定
• アーキテクチャ設計: システムの構成要素、データフロー
• 実装手順: 開発のステップバイステップの手順、マイルストーン
• 依存関係の整理: 外部サービス、API、ライブラリなどの依存関係の管理

(＊)ここまでの段階でどんな指示を書けばよいか、正直かなり迷いました。
私はまずプロジェクトの全体像をできるだけ詳しくマークダウンで書き出し、それをAIに渡しました。
するとAIが、この段階に必要な内容をうまく抽出し、書いていない部分も補完してくれました。

作業分解（Tasks）

以下​コマンドで作業分解を行います。

1/speckit.tasks <指示：不要でも良いです。>

このコマンドを実行すると、実装可能な粒度までタスクを分解し、順序を整理します。
結果はspecs/001-<機能名>/tasks.mdに保存されます。

実装可能な粒度までタスクを分解し、順序を整理とは

• タスク分解: 大きな機能を小さなタスクに分解
• タスクの優先順位付け: 重要度や依存関係に基づいてタスクを整理
• タスクの順序付け: 開発の順序を決定

整合性チェック（Analyze）

以下​コマンドで整合性チェックを行います。

1/speckit.analyze  <指示：不要でも良いです。>

このコマンドを実行すると、仕様・計画・タスク間の矛盾や漏れを検証し、整合性レポートや修正案を生成します。

仕様・計画・タスク間の矛盾や漏れを検証とは

• 仕様と計画の整合性: 仕様書と実装計画の内容が一致しているかを確認
• 仕様とタスクの整合性: 仕様書とタスクリストの内容が一致しているかを確認
• 計画とタスクの整合性: 実装計画とタスクリストの内容が一致しているかを確認
• 憲章との整合性: 仕様、計画、タスクがプロジェクトの基本方針に沿っているかを確認

実装実行（Implement）

以下​コマンドで実装実行を行います。

1/speckit.implement  <指示：不要でも良いです。>

このコマンドを実行すると、タスクに基づいてコードや設定を作成し、機能を構築します。

タスクに基づいてコードや設定を作成し、機能を構築とは

• コード生成: タスクに基づいて必要なコードを生成
• 設定ファイルの作成: 必要な設定ファイルを生成
• 機能の統合: 生成されたコードや設定を統合し、機能を構築
• テストコードの生成: 機能を検証するためのテストコードを生成
• ドキュメントの更新: 実装内容に基づいてドキュメントを更新
• コードレビュー: 生成されたコードの品質を確認し、必要に応じて修正

まとめ

AI の力を借りることで、仕様書の作成や更新が効率化され、開発プロセス全体の透明性と品質が向上したと感じています。

仕様駆動開発は、特に複雑なシステムや高い品質が求められるプロジェクトにおいて、有効な手法だと感じました。

一方で、どれだけ詳細な仕様書を用意しても、AI が常にバグのないコードを生成できるわけではありません。
そのため、何度か修正を重ねながら進める必要があります。

それでも今回の取り組みを通して、多くの学びがあり、非常に良い経験になりました。

今回のプロジェクトはこちらのリポジトリで公開しています。
興味がある方はぜひご覧ください。