Zenn
🔥

spec-kit徹底解剖：AI時代の仕様駆動開発を実現するツールキットの内部構造

に公開
GitHub
LLM
tech

はじめに

GitHubが2025年9月にオープンソースとしてリリースした「Spec Kit」は、従来の「コード優先」から「仕様優先」への開発パラダイムシフトを実現するツールキットです。AIコーディングエージェントと連携し、曖昧なプロンプトから明確な仕様、実装計画、タスク分解、そして動作するコードまでを体系的に生成する革新的なアプローチを提供しています。

本記事では、spec-kitの内部構造から実装方法論まで、技術者が実践的に活用するための詳細な解説を行います。

spec-kitとは何か？

従来開発手法の課題

これまでのAIコーディングでは「vibe-coding」と呼ばれる手法が一般的でした。目標を説明してコードブロックを受け取るが、往々にして「見た目は正しいが実際には動作しない」という問題が頻発していました。

主な課題：

  • コンパイルエラーの頻発
  • 実際の意図とは異なるソリューションの生成
  • 期待しないスタックやアーキテクチャの選択
  • 既存コードベースとの整合性の欠如

Spec-Driven Development（SDD）の革新性

Spec-Driven Developmentは従来のソフトウェア開発の常識を覆します。何十年もの間、コードが王様で、仕様書は「実際の作業」であるコーディングが始まると廃棄される足場に過ぎませんでした。SDDでは、仕様が実行可能となり、単にガイドするのではなく、直接動作する実装を生成します。

核心的な変化：

  • 従来: コード → 仕様書（事後作成）
  • SDD: 仕様書 → プラン → タスク → コード（自動生成）

spec-kitの内部アーキテクチャ

プロジェクト構造解析

spec-kitで初期化されたプロジェクトは以下の構造を持ちます：

project-root/
├── .github/
│   └── prompts/
│       ├── specify.prompt.md
│       ├── plan.prompt.md
│       └── tasks.prompt.md
├── memory/
│   ├── constitution.md
│   └── constitution_update_checklist.md
├── scripts/
│   ├── check-task-prerequisites.sh
│   ├── common.sh
│   ├── create-new-feature.sh
│   ├── get-feature-paths.sh
│   ├── setup-plan.sh
│   └── update-claude-md.sh
├── specs/
│   └── [feature-number]-[feature-name]/
│       ├── spec.md
│       ├── plan.md
│       ├── data-model.md
│       ├── research.md
│       ├── quickstart.md
│       └── contracts/
│           ├── api-spec.json
│           └── signalr-spec.md
└── templates/
    ├── CLAUDE-template.md
    ├── plan-template.md
    ├── spec-template.md
    └── tasks-template.md

コアコンポーネントの詳細解析

1. CLIツール（specifyコマンド）

spec-kitのエントリーポイントとなるCLIツールは、uvxを通じてGitHubリポジトリから直接インストール可能です：

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

主要機能:

  • プロジェクトの初期化とテンプレート配置
  • AIエージェント選択（Claude Code、GitHub Copilot、Gemini CLI）
  • 必要な依存関係のチェックと設定

2. テンプレートシステム

spec-template.md
仕様書のテンプレートは構造化された形式でユーザーストーリーと機能要件を定義します：

# [Feature Name] Specification

## User Stories
[ユーザー視点での要求事項]

## Functional Requirements  
[システムが満たすべき機能的要件]

## Acceptance Criteria
[受け入れ基準のチェックリスト]

## [NEEDS CLARIFICATION] マーカー
[明確でない要件への対処]

plan-template.md
仕様分析、憲法遵守チェック、アーキテクチャ設計、技術スタック選択を含む包括的な実装計画テンプレートです。

3. プロンプトエンジニアリングシステム

.github/prompts/ ディレクトリには、各フェーズでAIエージェントを適切にガイドするための精密に設計されたプロンプトが格納されています。

メモリ・憲法システム

constitution.md - 開発原則の定義

プロジェクト憲法は、アーキテクチャ原則を強制する重要なコンポーネントです。例：

  • セクション7.3: 最小プロジェクト構造 - 初期実装で最大3プロジェクト
  • セクション8.1: フレームワーク信頼性 - ラッパーではなく、フレームワーク機能を直接使用
  • 現実世界テスト優先: モックより実際のデータベース、スタブより実際のサービスインスタンスを使用

4段階のワークフロー詳解

Phase 1: Specify - 仕様定義

技術スタックやアプリ設計ではなく、ユーザージャーニー、体験、成功とは何かを定義する段階です。

コマンド例:

/specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page.

生成される成果物:

  • ユーザーストーリー
  • 機能要件
  • 受け入れ基準
  • 曖昧さの明確化マーカー（[NEEDS CLARIFICATION]）

Phase 2: Plan - 技術計画

技術的な段階では、希望するスタック、アーキテクチャ、制約をAIエージェントに提供し、包括的な技術計画を生成させます。

コマンド例:

/plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.

生成される成果物:

  • アーキテクチャ設計
  • 技術スタック選択の理由
  • データモデル設計
  • API仕様
  • パフォーマンス要件

Phase 3: Tasks - タスク分解

仕様と計画を実際の作業に分解し、小さく、レビュー可能なチャンクに変換します。各タスクは独立して実装・テスト可能です。

タスク分解の例:

  • "認証機能を作る" → "メールフォーマットを検証するユーザー登録エンドポイントを作成"
  • "データベースを設計" → "ユーザーテーブルのマイグレーションスクリプトを作成"

Phase 4: Implement - 実装

AIエージェントが生成されたタスクリストに基づいて、一つずつ（または並行して）実装を進めます。

対応AIエージェントとの連携

Claude Code連携

プロジェクトフォルダでClaude Codeを実行すると、/specify、/plan、/tasksコマンドが利用可能になり、適切に設定されていることが確認できます。

ワークフロー:

  1. specify init <project_name> --ai claude
  2. Claude Codeでプロジェクトフォルダに移動
  3. /specifyでユーザー要求を記述
  4. AIが仕様書とブランチを自動生成
  5. /planで技術詳細を指定
  6. /tasksでタスク分解
  7. implementコマンドで実装開始

GitHub Copilot / Gemini CLI連携

同様のコマンド体系で、それぞれのAIエージェントの特性を活かした開発が可能です：

specify init <project_name> --ai copilot
specify init <project_name> --ai gemini

内部メカニズムの深掘り

スクリプトシステム解析

create-new-feature.sh
自動機能番号付け、セマンティックブランチ名生成、テンプレートベースの生成、適切なディレクトリ構造作成を行います：

  • 既存specsをスキャンして次の機能番号を決定（001, 002, 003...）
  • 説明からセマンティックブランチ名を生成し、自動作成
  • 機能仕様テンプレートを要件でカスタマイズ
  • specs/[branch-name]/構造の適切な作成

setup-plan.sh
実装計画生成のオーケストレーション：

  • 仕様分析と理解
  • 憲法遵守チェック
  • アーキテクチャ決定
  • 技術スタック統合

テンプレートエンジンの仕組み

抽象化レベルの強制

機能仕様テンプレートは明示的に指示します：「✅ ユーザーが何を必要とし、なぜ必要かに焦点を当てる」「❌ どのように実装するかは避ける（技術スタック、API、コード構造なし）」

この制約により、LLMが適切な抽象化レベルを維持し、仕様が実装技術の変化に対して安定性を保ちます。

曖昧さマーカーシステム

両方のテンプレートは[NEEDS CLARIFICATION]マーカーの使用を義務付けています。ユーザープロンプトから仕様を作成する際：1. すべての曖昧さをマークする 2. 推測しない：プロンプトで指定されていない場合はマークする

これにより、LLMがもっともらしいが潜在的に間違った仮定を作ることを防ぎます。

実装シナリオ別の活用法

1. グリーンフィールド開発（0→1）

新規プロジェクトでは、すぐにコーディングを始めたくなりますが、少量の事前作業で仕様とプランを作成することで、AIが一般的なパターンに基づく汎用ソリューションではなく、実際に意図したものを構築することを保証します。

実装例：

# プロジェクト初期化
specify init photo-organizer --ai claude

# 仕様定義
/specify Build a photo organization app with drag-and-drop albums, 
date-based grouping, and tile-preview interface

# 技術計画
/plan Use React with TypeScript, IndexedDB for local storage, 
and minimal external dependencies

2. 既存システムへの機能追加（N→N+1）

複雑な既存コードベースに機能を追加することは困難ですが、新機能の仕様を作成することで、既存システムとの相互作用方法が明確になります。プランがアーキテクチャ制約をエンコードし、新しいコードがボルトオン追加ではなく、プロジェクトネイティブに感じられることを保証します。

3. レガシーシステムの近代化

レガシーシステムを再構築する必要がある場合、元の意図は時間とともに失われることが多いです。spec-kitの仕様駆動開発プロセスにより、重要なビジネスロジックを現代的な仕様で捉え、新しいアーキテクチャを設計し、継承された技術的負債を持ち込むことなく、AIにシステムを一から再構築させることができます。

開発フェーズとゲート制御

フェーズ-1：実装前ゲート

実装計画テンプレートの「フェーズ-1ゲート」は憲法原則を直接強制します：

シンプリシティゲート（第VII条）

  • 3プロジェクト以下を使用？
  • 最小限の依存関係？
  • ラッパーではなく、直接的なフレームワーク使用？

現実性ゲート

  • 現実的な環境でのテスト使用？
  • モックより実際のデータベース優先？
  • 実装前の契約テスト義務？

チェックポイントシステム

各フェーズで明確な検証ポイントが設定されており、次のフェーズに進む前に現在のタスクが完全に検証される仕組みが構築されています。

実践的な使用方法

セットアップと初期化

  1. 環境要件

    • Linux/macOS（WindowsではWSL2）
    • Python 3.11+、Git、uv
    • AIエージェント（Claude Code推奨）

  2. プロジェクト作成

    # 基本初期化
uvx --from git+https://github.com/github/spec-kit.git specify init my-project

# AI指定での初期化
specify init my-project --ai claude

# 現在ディレクトリでの初期化
specify init --here --ai claude

# エージェントツールチェックを無視
specify init my-project --ai claude --ignore-agent-tools

開発プロセスの実践

1. 仕様作成フェーズ

/specify Develop Taskify, a team productivity platform. It should allow users to create projects, add team members, assign tasks, comment and move tasks between boards in Kanban style. In this initial phase, let's have multiple predefined users - one product manager and four engineers. Create three different sample projects with standard Kanban columns: "To Do," "In Progress," "In Review," and "Done."

生成される成果物:

  • specs/001-create-taskify/spec.md
  • 新しいブランチ 001-create-taskify
  • ユーザーストーリーと機能要件の詳細

2. プラン作成フェーズ

/plan We are going to generate this using .NET Aspire, using Postgres as the database. The frontend should use Blazor server with drag-and-drop task boards, real-time updates. There should be a REST API created with a projects API, tasks API, and a notifications API.

生成される構造:

specs/001-create-taskify/
├── spec.md
├── plan.md
├── data-model.md
├── research.md
├── quickstart.md
└── contracts/
    ├── api-spec.json
    └── signalr-spec.md

3. タスク分解フェーズ

/tasks

AIエージェントが仕様とプランを分析し、実装可能な具体的タスクリストを生成します。

4. 実装フェーズ

implement specs/001-create-taskify/plan.md

Claude Codeが行動を開始し、実装を作成します。重要な点として、Claude Codeは（dotnetのような）ローカルCLIコマンドを実行するため、マシンにそれらがインストールされていることを確認する必要があります。

高度な機能と最適化

並列実装探索

同じ仕様から複数の実装アプローチを生成し、パフォーマンス、保守性、ユーザー体験、コストなど、異なる最適化ターゲットを探索できます。

研究駆動コンテキスト

研究エージェントが仕様プロセス全体を通じて重要なコンテキストを収集し、技術オプション、パフォーマンス影響、組織的制約を調査します。

双方向フィードバック

本番現実が仕様進化を知らせます。メトリクス、インシデント、運用学習が仕様改善の入力となります。

troubleshooting と最適化

一般的な問題と解決策

Git認証問題（Linux）
Git Credential Managerをインストールして解決します：

wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
sudo dpkg -i gcm-linux_amd64.2.6.1.deb
git config --global credential.helper manager

ランタイムエラーの対処
アプリケーションは動作するがCLIログで直接利用できないランタイムエラー（ブラウザログでレンダリングされるエラーなど）がある場合、エラーをClaude Codeにコピー&ペーストして解決を試みます。

パフォーマンス最適化のベストプラクティス

  1. 仕様の精密性向上: [NEEDS CLARIFICATION]マーカーを積極的に活用
  2. 憲法の遵守: プロジェクト固有の制約を明確に定義
  3. 段階的検証: 各フェーズでの徹底的なレビュー
  4. 反復改善: フィードバックループの活用

まとめ

spec-kitは「コードが真実の源」から「意図が真実の源」への移行を具現化します。AIにより仕様が実行可能となり、何が構築されるかを決定するのです。

主要な価値提案:

  • 構造化されたAI連携: 曖昧なプロンプトから明確な実装への体系的変換
  • 反復可能性: 仕様変更時の迅速な再生成能力
  • 品質保証: 各フェーズでの検証ゲート
  • 組織統合: エンタープライズ制約と開発標準の統合

これは開発者を置き換えたり創造性を自動化することではありません。機械的翻訳を自動化して人間の能力を増幅することです。仕様、研究、コードが共に進化し、各反復がより深い理解と意図と実装の間のより良い整合をもたらすタイトなフィードバックループを作ることです。

spec-kitは単なるツールではなく、AI時代のソフトウェア開発における新しいパラダイムの具現化です。従来の開発プロセスに革命をもたらし、より効率的で品質の高いソフトウェア開発を可能にする画期的なアプローチといえるでしょう。

この記事は、GitHubの公式ブログ記事、リポジトリドキュメント、および関連技術文書に基づいて作成されました。spec-kitの最新情報や詳細なドキュメントは公式リポジトリをご参照ください。

Discussion