Spec Kitではじめる仕様書駆動開発(SDD)超入門

今日話すこと

  • 仕様駆動開発(SDD)とは

  • SDDのツール

  • Spec Kit入門

  • 実践例

  • Spec KitのTips

  • おまけ

仕様駆動開発(SDD)とは

バイブコーディングの課題

  • AIが書くコードの品質にばらつき

  • 余計な機能の追加や意図と異なる実装

  • 人間とAIでコンテキスト共有が不足

  • 人間の「期待値」との「答え合わせ」手段の不在

仕様駆動開発(SDD)とは

SDD(Spec-Driven Development)
= コードより先に仕様書を書く開発手法

  • 仕様書が唯一の情報源

  • コードは仕様の表現にすぎない

  • 仕様がコードに仕えるのでなく、コードが仕様に仕える

出典: spec-driven.md - GitHub spec-kit

従来の開発 vs SDD

従来の課題

SDD

人間自身も要件の曖昧さに気づかない

仕様を書く過程で曖昧な考えが明確化

仕様書を書いても実装中に乖離が発生

仕様書からコードを生成

コードが真実の源泉になりがち

仕様変更でコードも更新

レシピと料理で例えると

曖昧なレシピ

詳細なレシピ

AIも同じ

「塩少々」「適量」「いい感じに」

分量・手順・火加減がすべて明確

明確な仕様 → 期待通りの実装

→ 作る人によって味にばらつき

→ 誰が作っても同じ味を再現可能

曖昧な指示 → ガチャ結果

SDDの欠点と注意点

初期コスト

コンテキスト消費

仕様の品質

  • 仕様書作成に工数が必要

  • 小規模・試作には過剰

  • 仕様・計画・タスクでトークンを消費

  • エージェントの作業領域が圧迫される

  • 未熟な仕様で誤った実装を量産

  • レビューとイテレーションが必須

中〜大規模や複数人開発に適し、探索的プロトタイピングには不向き

参考: Understanding SDD - Birgitta Böckeler

SDDの基本フロー

flowchart TD A["Specify<br>何を作るか明確化"] -->|検証| B["Plan<br>どう作るか設計"] B -->|検証| C["Tasks<br>実装単位に分解"] C -->|検証| D["Implement<br>AIエージェントが実装"]

出典: Spec-driven development with AI - GitHub Blog

SDDのツール

SDDのツール

  • Spec Kit

  • Kiro

  • cc-sdd

Spec Kit

GitHubが提供するOSSのSDDツールキット

  • テンプレートとプロンプトで仕様管理

  • clarify/analyzeで仕様の品質検証

https://github.com/github/spec-kit

Kiro

AWS開発のエージェント型IDE

  • Hooksでファイル保存時に自動実行

  • 画像からの実装にも対応

https://kiro.dev/

cc-sdd

コミュニティ製のSDDツール

  • Kiro互換の仕様フォーマット

  • 13言語のプロンプトに対応

https://github.com/gotalab/cc-sdd

Spec Kit入門

対応エージェント

テンプレートとプロンプトで動作し、特定のIDEに依存しない

  • Claude Code / Copilot / Cursor など

Spec Kitのワークフロー

flowchart LR Z[Constitution] A[Specify] --> B[Clarify] B --> C[Plan] C --> D[Tasks] D --> E[Analyze] D -.->|optional| H[Checklist] E --> F[Implement] E -.->|optional| G[Tasks to Issues]

  • 各ステップでテンプレートとプロンプトを自動生成

  • 成果物単位でコンテキストを切り替え可能

Constitution

Constitution = プロジェクトの「憲章/憲法」

プロジェクトの不変の原則を定義する

  • すべての仕様・コードの判断基準

  • 例: セキュリティを何よりも優先する

/speckit.constitution セキュリティ第一で堅牢なシステムを構築する原則を定義して

Specify

自然言語で機能仕様を記述する

  • 漠然としたアイデアを自動的に明確化

  • ユーザーストーリーと受け入れ基準

  • 機能要件と主要エンティティ

  • 測定可能な成功基準

/speckit.specify GitHub issueに自動応答するボットを作って

spec.mdの構成

セクション

内容

User Scenarios & Testing

ユーザー視点の利用シナリオと受け入れ基準

Functional Requirements

システムが満たすべき機能要件

Key Entities

主要なデータ・概念の定義

Success Criteria

測定可能な成功基準

Clarify

仕様の曖昧な箇所を質問形式で洗い出す

  • 最大5つの質問を自動生成

  • 見落としがちな仕様の矛盾も検出

  • 回答を仕様書に反映

例: 「リトライする」という記述に対し → 「エクスポネンシャルバックオフ」などの選択肢を提供

/speckit.clarify

Plan

技術計画を策定する

  • データモデルとAPIコントラクトを設計

  • リサーチで技術的な不明点を解消

/speckit.plan

Tasks

計画を小さな実装タスクに分割する

  • Setup→実装→Polishのフェーズ構成

  • ユーザーストーリー単位で独立実行可能

/speckit.tasks

Analyze

仕様・計画・タスクの整合性をチェックする

  • 6カテゴリで矛盾や漏れを検出

  • 読み取り専用で修正提案のみ出力

/speckit.analyze

Checklist

仕様の品質を検証するチェックリストを生成

  • 要件の完全性・明確さ・一貫性を検査

  • 仕様書のユニットテストとして機能

/speckit.checklist セキュリティ要件の品質を検証して

Implement

タスクに基づきAIエージェントが実装する

  • テスト→実装の順序でコード生成

  • タスク完了ごとに仕様と照合

/speckit.implement

Tasks to Issues

タスクをGitHub Issueに変換する

  • tasks.mdから依存関係順にissueを作成

  • MCP serverなどで投稿

/speckit.taskstoissues

speckit-gates

各ステップに品質ゲートを自動追加するコミュニティ製スキル

  • 計画・実装・ドキュメントを自動検証

  • GREEN/YELLOW/REDで品質を可視化

npx skills add drillan/speckit-gates

https://github.com/drillan/speckit-gates

speckit-gatesのスキル

スキル

トリガー

内容

planning-validate

/speckit.plan後に自動

計画成果物の整合性を検証

implementation-verify

/speckit.implement後に自動

実装カバレッジを確認

docs-sync

/speckit.implement後に自動

ドキュメントの同期

progress-report

手動実行

進捗ダッシュボードを表示

release-check

手動実行

リリース前の総合チェック

実践例

hachimokuプロジェクト

マルチエージェントコードレビューツール

  • 6種のレビューエージェントを搭載

  • diff・PR・ファイル単位でレビュー実行

  • TOMLによるレビューエージェントのカスタマイズ

  • Spec Kitで仕様を管理し段階的に開発

https://github.com/drillan/hachimoku

紹介記事: hachimoku: TOMLで定義するマルチエージェントコードレビューCLI

hachimokuでセルフレビュー

このスライドも5種のカスタムエージェントで品質チェック

https://github.com/drillan/stapy120/blob/main/.hachimoku/agents/natural-text-reviewer.toml

レビュー結果

カスタマイズした5種類のエージェントが指摘を自動検出


### Critical (2)

#### 1. FR-008/FR-014違反: 実践例セクション（lines 300-352）でhachimokuの仕様書をインラインmarkdownコードブロックで表示しているが、仕様ではliteralincludeで抜粋表示することが要求されている。手動コピーの結果、原文との差異も発生している（例: Acceptance Scenario 1で「Markdown で出力される」→「出力される」に短縮、FR-004で「型検証し、不正な出力をエラーとして検出できなければならない」→「型検証できなければならない」に短縮）。

- **Agent**: content-accuracy-reviewer
- **Location**: `docs/index.md:300`
- **Category**: literalinclude
- **Suggestion**: 3つのコードブロック（User Story: lines 300-316、受け入れ基準: lines 324-335、機能要件: lines 343-352）をすべて literalinclude ディレクティブに置き換え、:lines: や :start-after:/:end-before: で該当箇所のみを抽出する。例:

https://github.com/drillan/stapy120/blob/main/docs/_static/slides-review-sample.md

仕様書の例: User Story

ユーザー視点の利用シナリオを優先度付きで記述


### User Story 1 - 基本的なコードレビュー実行 (Priority: P1)

開発者が自分の変更に対してマルチエージェントレビューを実行し、コード品質・バグ・セキュリティの問題を検出する。

開発者はターミナルからレビューコマンドを実行する。システムは変更されたファイルを自動検出し、適用可能なエージェントを選択して逐次実行する。各エージェントの結果は統一されたレポートとして出力される。

**Why this priority**: これがツールの根幹機能であり、この機能なしにはプロダクトとしての価値がない。最小限のMVPとしてこの機能単独で開発者にレビュー結果を提供できる。

**Independent Test**: ターミナルから `8moku` を実行し、変更差分に対するレビュー結果が Markdown 形式で stdout に表示されることで検証可能。

出典: hachimoku/specs/001-architecture-spec/spec.md

仕様書の例: 受け入れ基準

Given/When/Then形式でテスト可能な基準を定義


**Acceptance Scenarios**:

1. **Given** Git リポジトリ内にコミット済みの変更がある状態, **When** ユーザーがレビューコマンドを実行, **Then** 適用可能な全エージェントが逐次実行され、重大度別に分類されたレビューレポートが Markdown で出力される
2. **Given** 変更差分にエラーハンドリングコードが含まれる状態, **When** レビューを実行, **Then** silent-failure-hunter エージェントが自動的に適用対象として選択される

→ AIが「合格/不合格」を自動判定可能

出典: hachimoku/specs/001-architecture-spec/spec.md

仕様書の例: 機能要件

FR-XXX形式で機能要件を一意に識別

- **FR-002**: システムは複数の専門エージェントを逐次または並列に実行し、各エージェントの結果を統一されたレポートに集約できなければならない
- **FR-003**: システムはエージェント定義ファイルからエージェントを読み込み、動的にレビューエージェントを構築・実行できなければならない
- **FR-004**: システムは各エージェントの出力を事前定義されたスキーマで型検証し、不正な出力をエラーとして検出できなければならない
- **FR-005**: システムは変更ファイルのパターンや差分内容に基づいて、適用すべきエージェントを自動選択できなければならない

→ 番号付きで要件の追跡と相互参照が可能

出典: hachimoku/specs/001-architecture-spec/spec.md

Spec KitのTips

仕様作成前のブレインストーミング

/speckit.specify の前にアイデアを整理する

ツール

特徴

Feature Development

コードベース探索とアーキテクチャ設計

Superpowers

対話型のアイデア深掘りと設計文書化

Deep Trilogy

大規模アイデアのコンポーネント分解

仕様の分割

  • 大規模プロジェクトは仕様を分割してスコープを小さくする

  • 例: 機能ごとに仕様を分割

graph TD 002[002-domain-models] --> 003[003-agent-definition] 002 --> 004[004-configuration] 003 --> 005[005-review-engine] 004 --> 005 005 --> 006[006-cli-interface]

仕様書の文量が多い

/speckit.specify の直後にAIに質問する

  • わからないこと

  • 自分が気になるポイント

認証失敗時のエラーハンドリング要件を詳しく説明して

AIが説明し、不明確な点を明確化

Tasks to Issuesの注意

そのままだと大量のissueが作られる

  • 適切な粒度にまとめる

  • 関連ドキュメントもissueに含める

/speckit.taskstoissues 適切な粒度に分類し、関連するドキュメントのリファレンスを必ずつけてください

まとめ

まとめ

  • 仕様の明確化でAI出力と期待値のずれを抑制

  • 仕様→計画→実装を段階的にすり合わせ

  • Spec KitでSDDを手軽に実践

おまけ

このスライド自体もSpec Kitで作成

4つの仕様で構築

  • 001: ビルド基盤の構築

  • 002: CSSテーマの設計

  • 003: MyST記法ルールの策定

  • 004: スライド内容の作成

graph TD 001[001-slides-setup] --> 002[002-slide-css] 001 --> 003[003-myst-rules] 002 --> 004[004-slide-content] 003 --> 004

例: タイポグラフィ仕様

「スライドがフルHDで収まるようにして」という指示だけで
AIが具体的な値に落とし込む


- **FR-001**: スライドの本文フォントは `Zen Kaku Gothic New` を第一候補とし、`Hiragino Kaku Gothic ProN`・`Noto Sans JP` を次候補とすること
- **FR-002**: コード表示フォントは `Source Code Pro` を使用すること
- **FR-003**: 各要素のフォントサイズは以下のとおりとすること: h1（2.0em）、h2（1.6em）、h3（1.3em）、本文（36px）、コードブロック（0.5em）、インラインコード（0.85em）
- **FR-004**: 行間は以下のとおりとすること: 本文（1.6）、リスト（1.8）、コードブロック（1.4em）
- **FR-005**: 日本語テキストは `word-break: auto-phrase` で自然な位置で改行し、字間は本文 `0.04em`・見出し `0.06em` とすること

https://github.com/drillan/stapy120/blob/main/specs/002-slide-css-spec/spec.md

例: テーブル記法の仕様

禁止パターンの明示でAIの記法選択を統一


- **FR-005**: テーブルは `{list-table}` ディレクティブで記述しなければならない（パイプテーブル禁止）
- **FR-006**: `:header-rows:` オプションを必ず指定する
- **FR-007**: `:widths: auto` を基本とする
- **FR-008**: 太字見出し＋箇条書きの複数グループは `{list-table}` に変換する
- **FR-008a**: テーブルの列数は3列以内とする。4列以上になる場合はスライドを分割する
- **FR-008b**: セル内の文字数が多くテーブルでは視認性が悪い場合もスライドの分割を検討する
- **FR-008c**: 列を横断して1対1で対応する比較項目は、セル内箇条書きではなく独立したテーブル行として記述する

https://github.com/drillan/stapy120/blob/main/specs/003-myst-notation-rules/spec.md