こんにちは、サイオステクノロジーの遠藤です。
最近はClaude Codeを使った開発にどっぷりハマっているのですが、「とりあえず作ってみて」でAIに丸投げすると、思ってたのと違うものができあがることってありませんか？
そんな課題を解決してくれるのが、GitHubがオープンソースで公開したSpec Kitです。今回は実際にTodoアプリの仕様をSpec Kitで生成してみたので、その体験をシェアします。
この記事の内容
| 項目 | 内容 |
|---|---|
| やったこと | GitHub Spec Kitを使ってTodoアプリの仕様書を生成 |
| 得られるもの | Spec Kitの導入方法と4フェーズワークフローの理解 |
| 対象読者 | AIコーディングエージェントでの開発精度を上げたい人 |
こんな人に読んでほしい
✅ Claude Code、GitHub Copilot、Cursor などのAIコーディングエージェントを使っている
✅ AIに「とりあえず作って」で丸投げして失敗したことがある
✅ 仕様書を書くのが面倒だけど、品質は上げたい
✅ チーム開発でAIの使い方を標準化したい
はじめに
AIコーディングエージェントの課題
AIコーディングエージェントは便利ですが、こんな経験ありませんか？
- 「ログイン機能作って」→ 想定と全然違う認証方式で実装された
- 「修正して」→ 関係ないところまで変えられた
- 「シンプルに」→ 必要な機能まで削られた
これらの問題の多くは、仕様が曖昧なまま実装を始めてしまうことが原因です。
Spec Kitとは
Spec Kit は、GitHubが2025年9月にオープンソースで公開した「仕様駆動開発（Spec-Driven Development）」のためのツールキットです。
特徴:
- 4フェーズワークフロー: Specify → Plan → Tasks → Implement
- ゲート付き進行: 各フェーズが完了するまで次に進めない
- マルチエージェント対応: Claude Code、GitHub Copilot、Cursor、Gemini CLIなど15以上のAIエージェントに対応
仕様書を先に作ることで、AIへの指示が明確になり、実装のブレを防げるという考え方ですね。
Spec Kitのインストール
前提条件
- Python 3.11以上
- Git
- uv（パッケージ管理）
- AIコーディングエージェント（Claude Code、GitHub Copilot、Cursorなど）
インストール手順
uvを使って永続的にインストールします：
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
インストール確認：
specify version
プロジェクトの初期化
specify init コマンド
新規プロジェクトを作成します。今回はClaude Codeを使うので --ai claude を指定：
mkdir todo-app-speckit
cd todo-app-speckit
specify init . --ai claude
出力：
╭──────────────────────────────────────────────────────────────────────────────╮
│ │
│ Specify Project Setup │
│ │
│ Project todo-app-speckit │
│ Working Path /path/to/todo-app-speckit │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
Selected AI assistant: claude
Selected script type: sh
Initialize Specify Project
├── ● Check required tools (ok)
├── ● Select AI assistant (claude)
├── ● Select script type (sh)
├── ● Fetch latest release (release v0.0.90)
├── ● Download template
├── ● Extract template
├── ● Initialize git repository
└── ● Finalize (project ready)
Project ready.
生成されるファイル構成
.claude/
└── commands/
├── speckit.constitution.md # プロジェクト原則
├── speckit.specify.md # 仕様作成
├── speckit.plan.md # 技術計画
├── speckit.tasks.md # タスク分解
├── speckit.implement.md # 実装実行
├── speckit.clarify.md # 曖昧性解消（オプション）
├── speckit.analyze.md # 一貫性分析（オプション）
└── speckit.checklist.md # 品質チェック（オプション）
.specify/
├── memory/
│ └── constitution.md # 憲法（プロジェクトルール）
├── scripts/
│ └── bash/
│ ├── create-new-feature.sh
│ └── ...
└── templates/
├── spec-template.md
├── plan-template.md
└── tasks-template.md
Claude Codeの .claude/commands/ にスラッシュコマンドが配置されます。
Spec Kitの4フェーズワークフロー
Spec Kitは4つのフェーズで構成されています：
Phase 1: Specify（仕様作成）
/speckit.specify コマンドで仕様書を生成します。
入力例:
/speckit.specify シンプルなTodoアプリ - タスクの作成・完了・削除ができるWebアプリケーション
生成される spec.md の構成:
# Feature Specification: Simple Todo Application
**Feature Branch**: `001-todo-app`
**Created**: 2025-12-07
**Status**: Draft
## User Scenarios & Testing *(mandatory)*
### User Story 1 - Create New Task (Priority: P1)
[ユーザーストーリーの詳細]
**Acceptance Scenarios**:
1. **Given** [初期状態], **When** [アクション], **Then** [期待結果]
### Edge Cases
[エッジケースの列挙]
## Requirements *(mandatory)*
### Functional Requirements
- **FR-001**: System MUST allow users to create a new task with a title
- **FR-002**: System MUST validate that task title is not empty
...
## Success Criteria *(mandatory)*
- **SC-001**: Users can create a new task in under 5 seconds
...
ポイント:
- ユーザーストーリーは優先度（P1, P2, P3…）付き
- 各ストーリーは独立してテスト可能（MVP単位でリリース可能）
- 技術スタックには言及しない（WHATとWHYに集中）
Phase 2: Plan（技術計画）
/speckit.plan コマンドで技術的な実装計画を作成します。
生成される plan.md の構成:
# Implementation Plan: Simple Todo Application
## Summary
[仕様から抽出した要件 + 技術的アプローチ]
## Technical Context
**Language/Version**: TypeScript 5.x
**Primary Dependencies**: React 18.x, Vite
**Storage**: LocalStorage
**Testing**: Vitest + React Testing Library
**Target Platform**: Modern Web Browsers
## Project Structure
### Source Code
todo-app/
├── src/
│ ├── components/
│ ├── hooks/
│ ├── types/
│ └── utils/
└── tests/
## Architecture Decisions
[データフロー、コンポーネント階層、エンティティ定義]
## Implementation Phases
[Phase 1: Core Data Model → Phase 2: UI → Phase 3: Styling → Phase 4: Testing]
このフェーズで初めて技術スタックが決まります。
Phase 3: Tasks（タスク分解）
/speckit.tasks コマンドでタスクリストを生成します。
生成される tasks.md の構成:
# Tasks: Simple Todo Application
## Format: `[ID] [P?] [Story] Description`
- **[P]**: 並列実行可能（ファイルが異なる、依存なし）
- **[Story]**: どのユーザーストーリーに属するか
## Phase 1: Setup
- [ ] T001 Create project structure with `npm create vite@latest`
- [ ] T002 Install dependencies
- [ ] T003 [P] Configure Vitest
## Phase 2: Foundational
- [ ] T005 Define Task type in `src/types/task.ts`
- [ ] T006 [P] Implement LocalStorage utilities
- [ ] T007 Create `useTasks` custom hook
## Phase 3: User Story 1 - Create New Task (P1)
- [ ] T010 [US1] Create TaskInput component
- [ ] T011 [US1] Add validation logic
- [ ] T012 [US1] Style TaskInput with error state
- [ ] T013 [P] [US1] Write TaskInput component tests
## Dependencies & Execution Order
[フェーズ間の依存関係、並列実行の機会]
ポイント:
- ユーザーストーリー単位でグループ化
[P]マークで並列実行可能なタスクを識別- MVPファーストの実装戦略
Phase 4: Implement（実装）
/speckit.implement コマンドでタスクを実行します。
実装フロー:
- タスクリストから1つずつ（または並列で）実装
- 各タスク完了後にテスト実行
- チェックポイントで動作確認
- 次のユーザーストーリーへ
実際に生成された仕様書を見てみる
今回、Todoアプリ用に生成した仕様書の一部を紹介します。
spec.md（仕様書）
## User Scenarios & Testing
### User Story 1 - Create New Task (Priority: P1)
ユーザーがやるべきことを思いついたとき、すぐにタスクとして記録したい。
タスクにはタイトルを入力して保存できる。
**Why this priority**: タスク作成はTodoアプリの最も基本的な機能であり、
これがなければアプリとして成立しない。
**Acceptance Scenarios**:
1. **Given** タスク入力画面が表示されている
**When** タスク名「買い物に行く」を入力して保存する
**Then** タスクリストに「買い物に行く」が追加される
2. **Given** タスク入力欄が空の状態
**When** 保存ボタンを押す
**Then** エラーメッセージが表示され、タスクは追加されない
### Edge Cases
- 非常に長いタスク名（1000文字以上）→ 最大255文字で制限
- 同じタスク名を複数回入力 → 許可（別タスクとして扱う）
- 特殊文字やHTMLタグ → エスケープして安全に表示
## Requirements
### Functional Requirements
- **FR-001**: System MUST allow users to create a new task with a title
- **FR-002**: System MUST validate that task title is not empty or whitespace-only
- **FR-003**: System MUST limit task title to maximum 255 characters
...
## Success Criteria
- **SC-001**: Users can create a new task in under 5 seconds
- **SC-002**: Users can mark a task as complete with a single click
- **SC-004**: Task data persists across browser sessions with 100% reliability
## Assumptions
- ユーザー認証は不要（ローカルストレージのみで動作）
- 複数デバイス間の同期は不要
- タスクの編集機能は初期スコープ外
tasks.md（タスクリスト）
## Phase 3: User Story 1 - Create New Task (Priority: P1)
**Goal**: Users can create new tasks with validation
### Implementation for User Story 1
- [ ] T010 [US1] Create TaskInput component in `src/components/TaskInput.tsx`
- [ ] T011 [US1] Add validation logic (empty check, max length 255)
- [ ] T012 [US1] Style TaskInput with error state
- [ ] T013 [P] [US1] Write TaskInput component tests
**Checkpoint**: Users can create tasks with proper validation
---
## Phase 5: User Story 2 - Complete Task (Priority: P1)
**Goal**: Users can mark tasks as complete/incomplete with visual feedback
### Implementation for User Story 2
- [ ] T018 [US2] Add completion toggle to TaskItem component
- [ ] T019 [US2] Style completed tasks with strikethrough
- [ ] T020 [US2] Write completion toggle tests
**Checkpoint**: Tasks can be toggled between complete/incomplete states
Spec Kitを使ってみた感想
良かった点
✅ 仕様が明確になる
- 「タスクを作成する」という曖昧な要件が、具体的なAcceptance Scenariosに落とし込まれる
- エッジケースを事前に洗い出せる
✅ AIへの指示が楽になる
- 「T010を実装して」で済む（仕様は参照すればいい）
- 実装の判断に迷ったときに仕様書に戻れる
✅ MVPファーストの開発
- ユーザーストーリー単位で優先度が明確
- P1だけ実装→テスト→リリースが可能
注意点
❌ 最初の仕様入力は人間が考える必要がある
- 「シンプルなTodoアプリ」だけでは曖昧すぎる
- ある程度の要件整理は事前に必要
❌ オーバーヘッドがある
- 小規模な修正には向かない
- ドキュメント生成に時間がかかる
❌ テンプレートがやや重厚
- 全セクションを埋めようとすると大変
- 必要に応じてカスタマイズ推奨
まとめ
今回はGitHub Spec Kitを使ってTodoアプリの仕様を生成してみました。
この記事で学んだこと
✅ Spec Kitは「仕様→計画→タスク→実装」の4フェーズワークフロー
✅ 各フェーズにゲートがあり、品質を担保しながら進める
✅ ユーザーストーリー単位でMVPファーストの開発が可能
✅ Claude Code、GitHub Copilot、Cursorなど15以上のAIエージェントに対応
AIコーディングエージェントで「思ってたのと違う」を減らしたい方、ぜひSpec Kitを試してみてください！
