spec-driven-development

仕様駆動開発（SDD）

このスキルは、構造化された AI 支援ソフトウェア開発のために、GitHub の SpecKit 手法を実装します。SpecKit は、品質ゲートとマルチエージェント連携を組み込んだ体系的なフェーズベースのアプローチを通じて、仕様を実行可能な成果物へと変換します。

中核となる理念

「仕様は実行可能なものとなり、実装の指針となるだけでなく、動作する実装を直接生成します。」

このスキルを使用する場面

• 構造化された開発が必要な新しいプロジェクトを始めるとき
• 複雑な機能について複数の AI エージェントや開発者の連携を調整するとき
• 憲章に基づくガバナンスを通じて一貫した品質を確保するとき
• 複雑な機能を管理しやすい並行作業に分解するとき
• 明確な仕様が整う前の早すぎる実装を防ぐとき
• 厳格なガバナンス要件を持つエンタープライズプロジェクト
• 複数の機能をリアルタイムで可視化する必要があるチーム

7 フェーズのワークフロー

フェーズ 0：プロジェクトの初期化

目的： プロジェクト構造を作成し、開発環境を設定します

成果物：

• .specify/ ディレクトリ構造
• Git リポジトリ
• 自動化スクリプト
• テンプレート

主なアクション：

• ディレクトリ構造を設定する
• バージョン管理を初期化する
• AI エージェントの設定を行う
• スクリプトのバリエーションを生成する（bash/powershell）

フェーズ 1：憲章

目的： プロジェクトのガバナンスと開発原則を確立します

成果物： memory/constitution.md

中核となる原則：

1. ライブラリ優先の原則： すべての機能はスタンドアロンのライブラリとして始めます
2. CLI インターフェースの必須化： すべてのライブラリにテキストベースのインターフェースを設けます
3. テスト優先の必須化： 実装に先立ってテストを行います
4. シンプルさと抽象化の抑制： 複雑さを最小限に抑えます
5. 統合優先のテスト： 現実的なテスト環境を優先します

バージョン管理： セマンティックバージョニング（MAJOR.MINOR.PATCH）

• MAJOR：後方互換性のないガバナンス変更
• MINOR：新しい原則、または重要な拡張
• PATCH：軽微な明確化や改善

オーケストレーション： すべての成果物にわたって検証しながら、対話形式で原則を定義します

フェーズ 2：仕様策定

目的： HOW ではなく WHAT と WHY に焦点を当てた、詳細な機能仕様を作成します

成果物： specs/[feature]/spec.md

必須セクション：

• 機能ブランチ名（2～4 語）
• ユーザーシナリオ（P1、P2、P3 の優先順位付き）
• 受け入れシナリオ（Given/When/Then 形式）
• エッジケース
• 機能要件（FR-XXX）
• 主要なエンティティ
• 成功基準（測定可能で、技術に依存しないもの）

主な制約：

• 実装ではなく、ビジネス価値に焦点を当てます
• 開発者ではなく、ステークホルダー向けに記述します
• 重大な未知事項を示す確認マーカーは最大 3 つまでです
• 各ユーザーストーリーは個別にテスト可能である必要があります

品質ゲート：

• コンテンツ品質の検証
• 要件の網羅性チェック
• 機能の準備状況の評価
• 成功基準の測定可能性

フェーズ 3：明確化

目的： 仕様の曖昧さを体系的に特定し、解消します

成果物： specs/[feature]/spec.md を更新します

明確化の観点：

• 機能の範囲
• データモデル
• ユーザーエクスペリエンス（UX）
• 非機能属性（パフォーマンス、セキュリティなど）
• 統合ポイント

主な制約：

• 1 セッションにつき質問は最大 5 つまでです
• 選択式または短答式の形式を使用します
• 影響が大きく、実装に不可欠な不確実性に焦点を当てます
• 反復的に改善するため、質問は一度に 1 つずつ行います

オーケストレーション： 対話形式の質問ワークフローを使用し、各回答の後に仕様を段階的に更新します

フェーズ 4：計画

目的： 技術的な実装戦略を作成し、技術的な未知事項を解決します

サブフェーズ：

フェーズ 0 - 調査：

• 技術的な未知事項を特定して調査します
• 出力：すべての不確実事項を解決した research.md
• ゲート： 未解決の確認事項がある場合はエラー

フェーズ 1 - 設計：

• データモデルと API コントラクトを作成します
• 出力：data-model.md、コントラクトスキーマ、エージェント固有のコンテキスト

成果物：

• specs/[feature]/plan.md
• specs/[feature]/research.md
• specs/[feature]/data-model.md
• specs/[feature]/contracts/

計画のセクション：

• 機能の概要
• 技術的なコンテキスト（言語、依存関係、プラットフォーム）
• プロジェクト構成
• リポジトリのレイアウト
• 標準外のアプローチに関する複雑さの追跡

フェーズ 5：分析

目的： 実装前に成果物間の整合性を検証します

分析対象の成果物：

• specs/[feature]/spec.md
• specs/[feature]/plan.md
• specs/[feature]/tasks.md

検出パス：

1. 重複
2. 曖昧さ
3. 仕様が不十分な項目
4. 憲章との矛盾

出力： 重大度順にランク付けされた指摘事項を含む分析レポート（重要度の高い項目を最大 50 件）

主な制約：

• 読み取り専用の操作（ファイルを変更できません）
• タスクの分割後に実行する必要があります
• 憲章の原則を優先します

フェーズ 6：タスクの分割

目的： 計画から実行可能で依存関係順に並んだタスクリストを生成します

成果物： specs/[feature]/tasks.md

タスクの構成：

• 完了状況を追跡するチェックボックス
• 連番のタスク ID
• 任意の並列化マーカー（||）
• ストーリーラベル（該当する場合は P1、P2、P3）
• 正確なファイルパス
• 明確な説明

フェーズの構成：

1. フェーズ 1： プロジェクトのセットアップ
2. フェーズ 2： 基盤となる前提条件（ブロッキング — ユーザーストーリーの前に完了する必要があります）
3. フェーズ 3 以降： ユーザーストーリーの実装（優先順位順：P1 → P2 → P3）
4. 最終フェーズ： 仕上げと横断的な懸案事項

主な原則：

• 独立した実装ができるよう、タスクをユーザーストーリーごとにグループ化します
• 各ストーリーは個別にテストおよび提供できます
• 依存関係を明確に追跡します
• 並列化マーカーを明示します
• 基盤フェーズが完了するまで、ユーザーストーリーの作業は行いません

フェーズ 7：実装

目的： 組み込みの検証を行いながら、フェーズごとに実装を進めます

8 段階のプロセス：

1. 前提条件の確認： プロジェクトの準備状況を検証します
2. チェックリストの検証： 完了項目と未完了項目を数え、未完了項目がある場合は確認を求めます
3. コンテキスト分析： 必須の成果物（tasks.md、plan.md）と任意の成果物を読み込みます
4. プロジェクトのセットアップ： 検出された技術に応じた無視ファイルを作成または確認します
5. タスクの処理： タスクを解析し、フェーズ、依存関係、実行フローを抽出します
6. 段階的な実装： TDD に従ってフェーズごとにタスクを実行します
7. エラー処理： 進捗を報告し、失敗に対処して、デバッグに役立つコンテキストを提示します
8. 最終検証： 完了を確認し、実装を検証して、テストカバレッジを確認します

オーケストレーション： チェックと相互確認を組み込んだ体系的な多段階実行

オーケストレーションと並列実行

オーケストレーションの基本方針

依存関係が許す範囲で各フェーズ内の並列実行を行いながら、フェーズを順次進めます。

調整の仕組み

1. フェーズベースのゲート

• 次のフェーズを開始する前に、各フェーズを完了し、検証する必要があります
• エラーや未解決の問題がある場合、ゲートによって進行がブロックされます
• 実装：テンプレートの検証、チェックリストの要件、憲章との整合性チェック

2. 依存関係の追跡

• タスクには、実行前に解決が必要な依存関係を指定します
• 基盤フェーズが、すべてのユーザーストーリー作業をブロックします
• タスクには前提条件を明示的に記載します

3. 並列化マーカー

• 依存関係がない場合、タスクに並列実行のマークを明示的に付けます
• タスク形式では || マーカーを任意で使用できます
• タスクを同時に実行できることを示します

4. ユーザーストーリーのグループ化

• 独立した並行実装ができるよう、タスクをユーザーストーリーごとにグループ化します
• 各ユーザーストーリーは独立してテストおよび提供できます
• 複数のエージェント／開発者が同時に作業できるようになります

5. 憲章との一貫性

• 一貫したプラクティスを維持するため、すべてのフェーズで憲章を参照します
• すべてのコマンドで憲章を読み込み、検証します
• 並行する作業ストリーム間の整合性を確保します

並行実行パターン

パターン 1：ユーザーストーリーの並列化

基盤フェーズの完了後、ユーザーストーリー（P1、P2、P3）は異なるエージェントが並行して実装できます

メリット：

• 独立したテストが可能
• 段階的な提供
• ブロックの軽減
• チーム連携の拡張性

例：

Foundation: ✓ Project setup, database schema, auth framework

Parallel Work:
├─ Agent 1: P1 Story - User registration flow
├─ Agent 2: P1 Story - User login flow
└─ Agent 3: P2 Story - Profile management

パターン 2：タスクレベルの並列化

フェーズ内で、依存関係のないタスクを同時に実行できます

例：

Phase 3: P1 User Registration
├─ [ ] T3.1 || Create user model (tests/models/test_user.py)
├─ [ ] T3.2 || Create registration endpoint (tests/api/test_register.py)
└─ [ ] T3.3 || Create validation service (tests/services/test_validation.py)

パターン 3：マルチエージェント連携

異なる AI エージェントが、共通の成果物形式を使用して、それぞれ異なる側面に取り組めます

例：

Feature "User Authentication":
├─ Claude: Generated spec.md and plan.md (reasoning strength)
├─ Copilot: Implemented auth endpoints (code generation)
└─ Gemini: Wrote integration tests (test coverage)

同期ポイント

並行作業の同期が必要となる重要なポイント：

1. 憲章の策定後： 以降のすべての作業は原則に沿う必要があります
2. 仕様策定後： 計画を立てる前に、明確化が必要な事項を解決する必要があります
3. 計画に関する調査後： 設計の前に、すべての不明点を解決する必要があります
4. タスク策定後： 実装前に、分析による検証が必要です
5. 基盤タスクの完了後： ユーザーストーリーの作業を開始できます
6. 実装中： チェックリストの検証が完了するまで、実行はブロックされます

エージェント連携パターン

パターン 1：テンプレート主導の引き継ぎ

構造化された Markdown テンプレートにより、異なる AI エージェント間で一貫した成果物形式を保てます

メリット： エージェント間の相互運用性、一貫したドキュメント、曖昧さの軽減

パターン 2：憲章との整合性

憲章は、すべてのエージェントとフェーズで共有されるコンテキストとして機能します

メリット： 一貫した品質基準、予測可能な動作、チーム／エージェント間の整合性

パターン 3：段階的な進行

エージェント間の明確な引き継ぎポイントを設けた、直線的なフェーズ進行

メリット： 明確な責任分担、混乱の軽減、品質ゲート

パターン 4：段階的な改善

次のフェーズに進む前に、フェーズ内で反復的に改善します

メリット： より高品質な成果物、手戻りの軽減、早期のエラー検出

パターン 5：成果物主導のコンテキスト

会話ではなく、成果物への参照を通じてコンテキストを引き継ぎます

メリット： ステートレスな実行、コンテキストの復元、長期にわたるプロジェクトへの対応

ディレクトリ構造

.specify/
├── memory/
│   └── constitution.md          # Project governance and principles
├── scripts/
│   ├── *.sh                     # Bash automation scripts
│   └── *.ps1                    # PowerShell automation scripts
├── specs/
│   └── [feature-name]/
│       ├── spec.md              # Feature specification
│       ├── plan.md              # Technical implementation plan
│       ├── tasks.md             # Actionable task breakdown
│       ├── research.md          # Research findings (optional)
│       ├── data-model.md        # Data structure design (optional)
│       ├── quickstart.md        # Getting started (optional)
│       └── contracts/           # API/interface definitions (optional)
└── templates/                   # Command and artifact templates

ベストプラクティス

1. 以降のすべての判断の指針とするため、早い段階で憲章を策定します
2. 計画前に曖昧な点を解決するため、clarify コマンドを使用します
3. 問題を早期に発見するため、実装前にanalyze コマンドを実行します
4. 独立してテストできるよう、ユーザーストーリーを構成します
5. 並列化できるタスクには、|| を明示的に付けます
6. ユーザーストーリーの作業に入る前に、基盤フェーズを完全に完了します
7. すべてのフェーズを通じて、憲章との整合性を維持します
8. 仕様では、具体的で測定可能な成功基準を使用します
9. 仕様策定フェーズでは、実装の詳細を避けます
10. それぞれの強みを活かすため、複数の AI エージェントを活用します

避けるべき落とし穴

1. 明確化フェーズを省略すると、仕様が曖昧になります
2. 仕様に早まって実装の詳細を盛り込むと、柔軟性が損なわれます
3. 憲章を無視すると、プラクティスに一貫性がなくなります
4. 適切に依存関係を追跡せずに並行作業を行うと、競合が発生します
5. 基盤フェーズが未完了だと、すべてのユーザーストーリーの作業がブロックされます
6. 実装前に analyze を実行しないと、問題のある計画に労力を費やすことになります
7. 初期フェーズで仕様を細かく定めすぎると、AI エージェントの創造性が制限されます
8. 成功基準が不十分だと、検証が主観的になります
9. ユーザーストーリーのグループ化を使用しないと、並列化の可能性が制限されます

実装シナリオ

シナリオ 1：新しいプロジェクトの開始

憲章に基づくガバナンスを備えた、全 7 フェーズのワークフローを使用します。早い段階で原則を確立することに重点を置きます。

シナリオ 2：複数の開発者／エージェントがいるチーム

ユーザーストーリーの並列化とワークツリーによる分離を重視します。リアルタイムで状況を把握するためにダッシュボードを使用します。

シナリオ 3：ガバナンス要件のあるエンタープライズ

エンタープライズの制約を盛り込んだ包括的なコンスティテューションを用意します。実装の前に分析フェーズを必須にします。

シナリオ 4：迅速なプロトタイピング

ビジョンをすり合わせるために詳細な仕様を作成しつつ、計画は簡素にします。迅速に検証できるよう、小さなユーザーストーリーを作成します。

参考資料

GitHub SpecKit（spec-kit）の手法に基づいています。これは、Claude Code、GitHub Copilot、Gemini、Cursor など、15 以上の AI コーディングエージェントに対応した、仕様駆動開発のためのオープンソースツールキットです。