仕様駆動開発のすすめ Spec-Kitの導入とモノレポでの課題

はじめに

こんにちは！
CI事業部ソリューション開発セクションの古賀です。

最近、AIコーディングツールの進化が目覚ましく、GitHub CopilotやCursor、Claude Codeなどを使って
コードを生成する場面が当たり前になってきました。
しかし、AIにコードを書かせるとき、「思っていたのと違うものができた」という経験はないでしょうか。

その原因の多くは、ソフトウェア開発に潜む「曖昧さ」にあります。
今回は、この曖昧さを仕様の力で解決する仕様駆動開発（Spec-Driven Development）という考え方と
それを実現するツールSpec-Kitを紹介します。
さらに、モノレポ構成でSpec-Kitを使う際に直面した課題と
その解決策となるBMAD-METHODについても触れていきます。

仕様駆動開発（Spec-Driven Development）とは

仕様駆動開発は、GitHubが2025年に提唱した開発手法です。
従来のAI開発では、プロンプト（指示文）からいきなりコードを生成する
いわゆる「バイブコーディング」が主流でした。
仕様駆動開発では、コードを書く前に仕様を明確に定義し
その仕様をもとにAIが実装を進めます。

ソフトウェア開発における「曖昧さ」のアプローチの違い

ソフトウェア開発では、要件の解釈や設計の判断に常に「曖昧さ」がつきまといます。
AIを活用した開発においても、この曖昧さをどう解決するかが品質を大きく左右します。

ここで、従来のAI開発と仕様駆動開発のアプローチの違いを整理してみます。

従来のアプローチでは、開発者自身がプロンプトエンジニアリングの技術を駆使して
AIに正確な指示を伝える必要があります。
プロンプトの書き方ひとつで出力の品質が変わるため、開発者の腕に依存する部分が大きいです。

一方、仕様駆動開発では、最初に仕様をしっかり固めることで
AIに渡す情報から曖昧さを排除します。
プロンプトのできに依存しないため、安定した品質を維持しやすいのが特徴です。

Spec-Kitとは

Spec-Kitは、GitHubが公開しているオープンソースの仕様駆動開発ツールキットです。
特定のAIコーディング環境に依存せず
GitHub Copilot、Claude Code、Cursor、Gemini CLIなどさまざまな環境で使用できます。

Spec-Kitは以下の4つのフェーズで開発を進めます。

1. Specify（仕様の定義）

ユーザー体験やゴールにフォーカスして、何を作るかを記述します。
技術スタックではなく、ユーザージャーニーや成功基準を定義するのがポイントです。

2. Plan（技術方針の策定）

使用する技術スタック、アーキテクチャ、制約条件を決めます。

3. Tasks（タスクの分割）

実装を小さく、レビュー可能でテスト可能な単位に分割します。
AIエージェントが検証できる粒度にすることが重要です。

4. Implement（実装）

分割されたタスクをAIコーディング環境で実装します。

基本的な使い方

Spec-KitにはSpecify CLIというコマンドラインツールが用意されています。
事前にuv（Python用パッケージマネージャ）とPython 3.11以上、Gitが必要です。

インストール（永続インストール）

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

プロジェクトの初期化

# 新規プロジェクトを作成する場合
specify init my-project --ai claude

# 既存ディレクトリに初期化する場合
specify init . --ai claude
# または
specify init --here --ai claude

--aiには使用するAIエージェント（claude, gemini, copilot, cursor-agent など）を指定します。

初期化後、プロジェクトディレクトリでAIアシスタント（Claude CodeやCursorなど）を起動すると、
/speckit.constitution、/speckit.specify、/speckit.plan、/speckit.tasks、/speckit.implement といったスラッシュコマンドが利用可能になります。
まず /speckit.constitution でプロジェクトの原則を定め、続けて /speckit.specify で仕様を記述し、/speckit.plan → /speckit.tasks → /speckit.implement の順に進めていきます。

初期化を実行すると、プロジェクトに以下のようなディレクトリが生成されます。

.specify/
├── memory/
│   └── constitution.md      # プロジェクトの原則（/speckit.constitutionで作成）
├── scripts/                  # 内部スクリプト
├── specs/                    # 機能ごとの仕様（例: 001-feature-name/spec.md）
│   └── 001-<feature-name>/
│       ├── spec.md
│       ├── plan.md
│       └── tasks.md
└── templates/                # 仕様・計画・タスクのテンプレート

テンプレートに沿って仕様を記述し、スラッシュコマンドでAIに渡すことで
一貫性のある実装を進めることができます。

なお、Spec-Kitは2025年8月に公開されたばかりのツールですが
2026年2月時点でGitHub上で約70,000スターを獲得しており、注目度の高さがうかがえます。

モノレポとSpec-Kitの組み合わせで直面する課題

Spec-Kitは単一プロジェクトでは非常にうまく機能しますが
モノレポ構成で使おうとすると、いくつかの課題が見えてきます。
実際に試してみた中で感じた3つのパターンを紹介します。

パターン1：ルートディレクトリのみでinitする

最もシンプルな構成ですが、コンテキストの過負荷に陥りやすいです。

仕様ファイルにフロントエンドとバックエンドの両方のルールを記述する必要があり
内容が肥大化してAIの推論精度が低下します。
また、Spec-Kitは「001-feature」のように連番でタスクを管理するため
複数の開発者が異なるサブプロジェクトを触ると番号の競合やマージコンフリクトが頻発します。

パターン2：ルートと各サブプロジェクトで個別にinitする

独立性を高めようとするこの方法は、コマンドの衝突を招きます。

IDE上でSpec-Kitのコマンドを実行した際に
ルートの設定なのかサブフォルダの設定なのかが判別できなくなります。
また、内部スクリプトがGitルートを基準にパスを解決していることが多く
サブフォルダから実行するとファイルの生成先がずれるケースもありました。

パターン3：サブプロジェクトのみでinitする

一見クリーンですが、API仕様の整合性の空白が生まれます。

フロントエンドとバックエンドのAIが完全に分断されるため
API仕様の変更時に「誰が両者の整合性を担保するか」という問題が
すべて人間の手作業に戻ってきます。
OpenAPI定義の更新や各AIへの反映など、人間がオーケストレーターとして
立ち回る必要があり、大きなオーバーヘッドになります。

コミュニティでも議論されている課題

実はこれらの課題はSpec-KitのGitHubリポジトリ上でも議論されています。

特にIssue #581のスレッドでは、多くのユーザーが同じ壁にぶつかっている様子が見えます。
根本的な原因は、Spec-Kitの内部スクリプト（common.sh）のget_repo_root関数が
git rev-parse --show-toplevelでGitリポジトリのルートを取得する設計になっている点です。
モノレポではGitルートとプロジェクトルートが一致しないため
仕様ファイルが意図しない場所に生成されてしまいます。

コミュニティではこの問題に対して、get_repo_rootを書き換えて
.specifyディレクトリの位置をプロジェクトルートとして優先する回避策が広く共有されています。
また、Discussion #769ではブランチ名を状態管理に使用している設計そのものが
モノレポとの相性の悪さの根本原因として挙げられており
Git依存を取り除いたspeckit-remixというフォークも生まれています。

2026年2月時点でこれらのissueはまだオープンの状態であり
公式のモノレポサポートは今後に期待という状況です。

BMAD-METHODでモノレポの課題を解決する

これらの課題に対し、BMAD-METHOD（以下BMM）は
エージェント・オーケストレーションという異なるアプローチで解決を図ります。

BMMは、AI駆動の開発フレームワークで
PM、アーキテクト、開発者、UXなど12以上の専門エージェントが
役割分担しながら協調して開発を進める仕組みです。

専門エージェントによるAPI整合性の自動統制

Spec-Kitでは人間がAPI仕様の整合性を管理する必要がありましたが
BMMではArchitect（アーキテクト）エージェントがその責務を担います。

実装前に/check-implementation-readinessを実行することで
アーキテクトがPRD（要件定義）とアーキテクチャ（API設計）に矛盾がないかを自動検証します。
これにより、フロントとバックで解釈がズレたまま開発が進むことを未然に防ぐことができます。

ドキュメント・シャーディングによる文脈の最小化

巨大なモノレポでもAIが混乱しない仕組みとして
ドキュメント・シャーディング（情報の細分化）があります。

巨大な仕様書を他に依存しない独立した「ストーリーファイル」に分割し
開発エージェントにはその瞬間の実装に必要な文脈だけを渡します。
これにより、数千行のコードベースでも高い推論精度を維持できます。

Spec-Kitのパターン1で発生した「コンテキストの過負荷」を
アーキテクチャレベルで解決しているのがポイントです。

モノレポ専用のオーケストラ構成

BMMは、中央のOrchestratorディレクトリが設計図（SSoT：Single Source of Truth）を保持し
各サブプロジェクトがそれを参照する構造をネイティブにサポートしています。

monorepo/
├── .bmad/                  # Orchestratorディレクトリ（SSoT）
│   ├── agents/             # 専門エージェント定義
│   ├── architecture/       # アーキテクチャ設計
│   └── stories/            # ストーリーファイル
├── apps/
│   ├── frontend/           # .bmadを参照
│   └── backend/            # .bmadを参照
└── packages/
    └── shared-types/       # 共有型定義

Turborepoを用いたモノレポ構築や、共有パッケージ（shared-types等）の設定を
AIが自律的に行うワークフローも用意されています。
インフラレベルから整合性を確保できるのは大きな強みです。

まとめ

今回は、仕様駆動開発とSpec-Kit、そしてモノレポでの課題を解決するBMAD-METHODを紹介しました。

Spec-Kitは、仕様を中心に据えた開発フローを手軽に導入できるツールです。
単一プロジェクトや個人開発では、AIに対する指示の曖昧さを大幅に減らすことができます。

一方で、モノレポ構成になると仕様の分散や整合性の問題が出てきます。
BMAD-METHODは、専門エージェントによるオーケストレーションでこの課題に対処しており
複数の技術スタックが混在するプロジェクトで威力を発揮します。

個人的には、まずSpec-Kitで仕様駆動開発の考え方に慣れてから
プロジェクト規模や構成に応じてSpec-KitとBMAD-METHODを使い分けるのが良いと感じました。