sdd

仕様駆動開発（SDD）スキル

仕様を実行可能にし、動作する実装を直接生成することで、従来のソフトウェア開発を一変させる手法である仕様駆動開発について、GitHub の Spec-Kit を使ってユーザーをガイドします。

中核となる理念

仕様駆動開発では、次の点を重視します。

• 意図駆動開発：「どのように」より先に「何を」を定義します
• 充実した仕様の作成：ガードレールと組織の原則を活用します
• 複数段階での改善：一度きりのコード生成ではありません
• AI ネイティブ：高度な AI 機能に大きく依存します

これはAI ネイティブな開発です。仕様は単なるドキュメントではなく、実装を直接推進する実行可能な成果物です。AI エージェントは仕様で定義された意図に沿った動作するコードを生成するために、仕様を使用します。

クイック判断ツリー

新しいプロジェクト（グリーンフィールド）ですか？

→ 完全な 6 ステップのプロセスについては、グリーンフィールドワークフローを参照してください

既存のコードベース（ブラウンフィールド）ですか？

→ リバースエンジニアリングと統合のガイダンスについては、ブラウンフィールドワークフローを参照してください

インストール方法が必要ですか？

→ セットアップとトラブルシューティングについては、インストールガイドを参照してください

インストールのクイックスタート

推奨（永続的）：

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

1 回限りの使用：

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

確認：

specify check

詳細なインストールオプション、トラブルシューティング、環境変数については、インストールガイドを参照してください。

対応 AI エージェント

以下で動作します。

• ✅ Claude Code
• ✅ GitHub Copilot
• ✅ Gemini CLI
• ✅ Cursor
• ✅ Qwen Code
• ✅ opencode
• ✅ Windsurf
• ✅ Kilo Code
• ✅ Auggie CLI
• ✅ CodeBuddy CLI
• ✅ Roo Code
• ✅ Codex CLI
• ✅ Amp
• ⚠️ Amazon Q Developer CLI（スラッシュコマンドのカスタム引数には対応していません）

成果物の要約とフィードバックループ

重要なワークフロー：SDD コマンドによって成果物が生成または変更された後は、ユーザーの関与を保つため、必ずこのフィードバックループを自動的に実行してください。

各コマンドの完了後

1. 成果物の変更を検出する

   • 作成または変更された成果物を特定します。
     • constitution.md（プロジェクトの原則）
     • spec.md（要件仕様）
     • plan.md（技術的な実装計画）
     • tasks.md（実行可能なタスクの内訳）
     • ブラウンフィールドワークフローの分析レポート

2. 読み取り、要約する

   • 関連する成果物を読み取ります
   • 重要な情報を抽出します。
     • constitution.md の場合：中核となる原則、コーディング規約、制約
     • spec.md の場合：主な要件、ユーザーストーリー、成功基準
     • plan.md の場合：技術スタックの選択、アーキテクチャ上の決定、マイルストーン
     • tasks.md の場合：タスク数、主なタスクのカテゴリ、依存関係
     • 分析レポートの場合：現在のパターン、技術的負債、統合ポイント

3. 構造化された要約を提示する（以下の 10 項目テンプレートを使用）

   • 何が生成されたのか、その理由を示します
   • 最も重要な決定とその根拠を強調します
   • 品質を示す指標と注意点を含めます
   • 要約は焦点を絞り、次の行動につながる内容にします
   • 各セクションに分かりやすい見出しを付けます

4. 機能のステータスを含める（ハイブリッド方式）

   • すべての要約に簡潔なステータス行を含めます
   • 詳細なステータスは /speckit.status で必要に応じて表示します
   • 下記の「機能ステータスの追跡」セクションを参照してください

5. フィードバックの選択肢を提示する

   • 選択肢 A：「問題ありません。次のステップに進んでください」
   • 選択肢 B：「[特定のセクション]を変更したいです」
   • 選択肢 C：「次の変更を加えて再生成してください：[ユーザーの入力]」
   • 選択肢 D：「[特定の決定]が行われた理由を説明してください」

10 項目の要約テンプレート

任意の SDD コマンドが完了した後は、次の構造化形式を使用します。

## ✅ [Command Name] Completed - Here's What Just Happened

### 🎯 Key Decisions Made (Top 3)
1. [Decision] - **Rationale:** [Why this was chosen]
2. [Decision] - **Rationale:** [Why this was chosen]
3. [Decision] - **Rationale:** [Why this was chosen]

### 📋 What Was Generated
- [Artifact 1]: [Brief description of content]
- [Artifact 2]: [Brief description of content]

### 🔍 Important Items to Review (Top 3)
1. [Critical item to check and why it matters]
2. [Important detail to verify and potential impact]
3. [Edge case to consider and how it affects the design]

### ⚠️ Watch Out For (Top 2)
- [Potential issue or gotcha] - **How to avoid:** [Guidance]
- [Common mistake] - **How to avoid:** [Guidance]

### 🔄 What This Enables Next (2 Options)
- **Option 1:** [Next step] - Best if: [Condition]
- **Option 2:** [Alternative step] - Best if: [Condition]

📊 **Feature Status:** [Current Feature Name] ([Stage]) → Next: [Next Feature]
   Progress: [●●●○○] [X]% | Completed: [N] of [Total] features | Dependencies: [Status]

**Your options:** [A] Proceed [B] Modify [C] Explain more [D] Show full status

例：`/speckit.specify`実行後の要約の拡充

```

✅ Specify が完了しました — 今回の処理内容

🎯 主な決定事項

1. 認証：JWT トークン - 理由：ステートレスなアーキテクチャ、水平方向のスケーリングが可能、業界標準
2. パスワード要件：12 文字以上で複雑さを確保 - 理由：セキュリティ（NIST のガイドライン）と使いやすさのバランス
3. セッションタイムアウト：24 時間 - 理由：ウェブアプリの標準であり、セキュリティとユーザーの利便性のバランスが取れています

📋 生成された内容

• `.speckit/features/user-auth/specify.md`：5 つのユーザーストーリー、8 つの成功基準、3 つのエッジケースを含む完全な要件

🔍 確認すべき重要事項

1. パスワードリセットのフロー - メール要件がインフラストラクチャ（SMTP サーバー、テンプレート）に合っていることを確認してください
2. 多要素認証 - 現時点では「今後の拡張」としてマークされていますが、MVP に含める必要があるかもしれません
3. レート制限 - 15 分あたり 5 回のログイン試行に設定されています。セキュリティポリシーに合っているか検討してください

⚠️ 注意事項

• メールサービスの依存関係が指定されていません - 回避方法：plan.md の依存関係にメールサービスを追加してください
• ユーザーデータの GDPR 準拠 - 回避方法：データ保持とユーザー削除の要件を確認してください

🔄 次にできること

• オプション 1： `/speckit.plan` を実行して技術的な実装を設計します - 最適な場合：要件に問題がない場合
• オプション 2： specify.md を変更します - 最適な場合：要件の調整や機能の追加が必要な場合

📊 機能のステータス： user-authentication（仕様作成済み）→ 次：profile-management 進捗：[●●○○○] 40% | 完了：5 つの機能のうち 1 つ | 依存関係：database-setup ✅

選択肢： [A] 計画に進む [B] 要件を変更する [C] JWT を選んだ理由を説明する [D] 全ステータスを表示する ```

要約を省略する場合

次の場合に限り、要約の手順を省略します。

• ユーザーが「要約を省略」または「すべての手順を自動実行」と明示的に依頼した場合
• 成果物を変更せずにコマンドを再実行する場合
• コマンドが失敗するかエラーが発生した場合（その場合はトラブルシューティングを行います）

このワークフローのメリット

• 「ブラックボックス」のような感覚を解消： 何が生成されたか、なぜ生成されたかを明確に説明します
• 早期のフィードバックが可能： 実装前に誤解に気づけます
• 俊敏性を維持： 長時間の承認プロセスではなく、構造化された形式で素早く確認できます
• 信頼を構築： AI の判断と、その理由をユーザーが確認できます
• コンテキストを提供： 機能のステータスにより、プロジェクト全体における現在の状況を把握できます

機能ステータスの追跡

ハイブリッド方式

各 SDD コマンドの実行後、要約に簡潔な機能ステータス行を含めます。詳細なステータスは、ユーザーの要求に応じて /speckit.status で表示します。

簡潔なステータス行の形式

各要約の末尾に、次の内容を含めます。

📊 **Feature Status:** [Current Feature Name] ([Stage]) → Next: [Next Feature Name]
   Progress: [●●●○○] [X]% | Completed: [N] of [Total] features | Dependencies: [Dep] ✅/⏸️

ステージの値：

• Specifying（20% 完了）
• Planning（40% 完了）
• Tasking（60% 完了）
• In Progress（80% 完了）
• Complete（100% 完了）

進捗インジケーター：

• 完了したステージには塗りつぶされた丸（●）を使用します
• 未完了のステージには空の丸（○）を使用します
• ステージに基づいてパーセンテージを計算します

詳細なステータスダッシュボード

ユーザーが全ステータス（オプション D）を要求するか、/speckit.status を実行した場合は、次を表示します。

📊 Project Feature Status Dashboard

🎯 CURRENT FEATURE
├─ [feature-name] ([Stage] - [X]% complete)
│  ├─ ✅ Requirements specified
│  ├─ 🔄 Implementation plan in progress
│  ├─ ⏸️  Tasks not started
│  └─ ⏸️  Implementation not started
│  Blockers: [None | Description]
│  Dependencies: [feature-name] ✅

✅ COMPLETED FEATURES ([N])
├─ [feature-1] (100% complete)
└─ [feature-2] (100% complete)

📋 UPCOMING FEATURES ([N])
├─ [feature-3] (depends on: [current-feature])
└─ [feature-4] (depends on: [feature-3])

⚠️  BLOCKED FEATURES ([N])
[List any features that are blocked with reasons]

自然言語による機能管理

Claude は、自然言語による機能管理のリクエストを自動的に検出して処理します。

ユーザーの発言: 「機能 XYZ を ABC より前に移動して」 Claude の動作:

1. .speckit/features/ から現在の機能リストを読み取ります
2. 現在の順序を番号付きで表示します
3. 新しい順序を提案します
4. 確認を求めます
5. 憲章または計画の機能の優先順位／順序を更新します
6. 更新後のステータスダッシュボードを表示します

ユーザーの発言: 「メール通知の新機能を追加して」 Claude の動作:

1. 新機能のリクエストを検出します
2. 確認の質問（優先順位、依存関係、説明）をします
3. 機能仕様の概要を生成します
4. 機能リストの適切な位置に追加します
5. 更新後のステータスダッシュボードを表示します

ユーザーの発言: 「まずは profile-management を進めましょう」 Claude の動作:

1. 現在の機能の順序を特定します
2. profile-management を最優先に移動することを提案します
3. 必要に応じて依存関係を調整します
4. 成果物を更新します
5. 更新後のステータスを表示します

検出パターン:

• 「[feature] を [other] の前／後に移動」 → 順序を変更
• 「[feature] を追加」 → 新機能
• 「まず [feature] を進めましょう」 → 最優先に移動
• 「[feature] はひとまずスキップ」 → 保留としてマーク
• 「[feature] が完成しました」 → ステータスを完了に更新
• 「[feature] に依存する機能は何ですか？」 → 依存関係ツリーを表示
• 「機能のステータスを表示」 → ダッシュボード全体を表示

機能のクイック操作

リクエストに応じて、次の操作をユーザーに案内します。

機能を追加:

User: "Add a feature for admin dashboard"
Claude:
1. What's the priority? (High/Medium/Low)
2. What features does this depend on? (user-auth, profile-management, etc.)
3. Brief description?
[Creates outline, shows updated status]

機能の順序を変更:

User: "Reorder features"
Claude:
Current order:
1. user-authentication
2. profile-management
3. admin-dashboard
4. email-notifications
5. reporting

How would you like to reorder? (provide new numbers or describe changes)
[Updates order, shows new status]

機能を削除:

User: "Remove the reporting feature"
Claude:
⚠️  Warning: This will remove 'reporting' feature.
Dependencies affected: None
Are you sure? (yes/no)
[If yes: removes, updates status]

進捗の計算

SDD ワークフローの完了状況に基づいて、進捗を自動的に計算します。

ステージ	進捗	指標
仕様策定済み	20%	specify.md が存在する
計画済み	40%	plan.md が存在する
タスク化済み	60%	tasks.md が存在する
進行中	80%	実装を開始している（コードファイルが変更されている）
完了	100%	実装が完了し、テストが合格している

依存関係の追跡

依存関係を追跡して可視化します。

依存関係を表示:

user-authentication
├─ Depends on: database-setup ✅
└─ Blocks: profile-management ⏸️, admin-dashboard ⏸️

着手可能か確認:

📊 Can we start profile-management?
   Checking dependencies...
   ✅ user-authentication (complete)
   ✅ database-setup (complete)

   All dependencies satisfied! Ready to proceed.

循環依存を検出:

⚠️  Warning: Circular dependency detected
   feature-A depends on feature-B
   feature-B depends on feature-C
   feature-C depends on feature-A

   Please resolve this before proceeding.

ワークフローとの統合

グリーンフィールドプロジェクトの場合:

• /speckit.specify の後に、複数の機能があるかどうかを尋ねます
• ある場合は、それらをリストアップし、各機能の進捗を追跡します
• 各コマンドの後にステータスを表示します

ブラウンフィールドプロジェクトの場合:

• /speckit.reverse-engineer の後に、発見された機能から機能リストを作成します
• 新機能を、既存の文書化済み機能とは別に追跡します
• ステータスに対する統合の影響を表示します

機能管理の詳細なガイダンスについては、機能管理ガイドを参照してください。

このスキルの使い方

ユーザーが SDD について尋ねたとき

1. 中核となる理念を説明します。実行可能な仕様、意図駆動型、AI ネイティブ
2. 前提条件を確認します。`uv`、Python 3.11 以降、Git、AI エージェント
3. プロジェクトの種類を判断します。新規（グリーンフィールド）か既存（ブラウンフィールド）か
4. 適切なワークフローを案内します。
   • グリーンフィールド → グリーンフィールドワークフロー
   • ブラウンフィールド → ブラウンフィールドワークフロー

ユーザーが新しいプロジェクトを始めたいとき

1. インストールを案内します → インストールガイド
2. プロジェクトを初期化します。 ```bash specify init my-project --ai claude ```
3. グリーンフィールドワークフローに沿って進めます → グリーンフィールドワークフロー
4. 各ステップの後：成果物を要約し、ユーザーからフィードバックを得ます

ユーザーが既存のコードベースを持っているとき

1. `.speckit/` ディレクトリがあるか確認します
2. ない場合 → ブラウンフィールドワークフローに沿って案内します。
   • 既存のコードを分析します
   • 既存のパターンから憲章を生成します
   • 成果物の生成戦略を選択します
   • SDD で新機能を追加します
3. ある場合 → 現在の進捗に基づいて次のステップを判断します
4. 各ステップの後：成果物を要約し、ユーザーからフィードバックを得ます

ユーザーが機能の追加を希望する場合

グリーンフィールドプロジェクトの場合：

1. グリーンフィールドワークフローに移動します
2. 手順 3〜6（仕様の定義 → 計画 → タスク → 実装）に従います
3. 次に進む前に、各成果物を要約します

ブラウンフィールド／既存プロジェクトの場合：

1. ブラウンフィールドワークフローに移動します
2. 手順 6〜7（仕様の定義 → 統合計画 → タスク → 実装）に従います
3. 次に進む前に、各成果物を要約します

ユーザーが問題に遭遇した場合

1. インストールの問題 → インストールガイドのトラブルシューティングセクション
2. ワークフローの問題 → 該当するワークフローガイドを確認します：
   • グリーンフィールドのトラブルシューティング
   • ブラウンフィールドのトラブルシューティング
3. 機能の検出 → `SPECIFY_FEATURE` 環境変数を設定します（インストールガイドを参照）

ワークフローの概要

グリーンフィールド（新規プロジェクト）

``` specify init → /speckit.constitution → [SUMMARIZE] → /speckit.specify → [SUMMARIZE] → /speckit.plan → [SUMMARIZE] → /speckit.tasks → [SUMMARIZE] → /speckit.implement ```

詳細： グリーンフィールドワークフロー

ブラウンフィールド（既存プロジェクト）

``` specify init --here → /speckit.brownfield → [SUMMARIZE] → /speckit.analyze-codebase → [SUMMARIZE] → /speckit.reverse-engineer → [SUMMARIZE] → /speckit.specify → [SUMMARIZE] → /speckit.integration-plan → [SUMMARIZE] → /speckit.tasks → [SUMMARIZE] → /speckit.implement ```

詳細： ブラウンフィールドワークフロー

対応する開発フェーズ

0 から 1 への開発（「グリーンフィールド」）

大まかな要件から始め、仕様をゼロから作成し、実装手順を計画して、本番環境に対応したアプリケーションを構築します。

→ グリーンフィールドワークフロー

反復的な機能強化（「ブラウンフィールド」）

既存のコードベースに機能を段階的に追加し、レガシーシステムをモダナイズし、変化する要件に合わせてプロセスを適応させ、既存のコードを SDD 形式にリバースエンジニアリングします。

→ ブラウンフィールドワークフロー

創造的な探索

多様なソリューションを並行して検討し、複数の技術スタックとアーキテクチャに対応し、UX パターンを試します。

→ グリーンフィールドワークフロー - マルチスタック探索セクション

主なコマンドのリファレンス

インストールとセットアップ

```bash specify init # 新規プロジェクト specify init --here --force # 既存プロジェクト specify check # インストールを確認 ```

グリーンフィールドワークフロー

``` /speckit.constitution # プロジェクトの原則 → SUMMARIZE /speckit.specify # 要件を定義 → SUMMARIZE /speckit.plan # 技術計画 → SUMMARIZE /speckit.tasks # タスクを分割 → SUMMARIZE /speckit.implement # 実行 ```

ブラウンフィールドワークフロー

``` /speckit.brownfield # 既存コードを分析 → SUMMARIZE /speckit.analyze-codebase # 詳細な分析と原則の定義 → SUMMARIZE /speckit.reverse-engineer # 既存の機能を文書化 → SUMMARIZE /speckit.integration-plan # 新機能の統合を計画 → SUMMARIZE ```

任意の機能強化コマンド

``` /speckit.clarify # 曖昧な要件を明確化 /speckit.analyze # 成果物間の整合性を確認 /speckit.checklist # 品質チェックリストを作成 ```

分析スクリプト

SDD スキルには、品質を詳細に検証し、進捗を追跡するための分析スクリプトが含まれています：

`scripts/phase_summary.sh`

tasks.md ファイル内のすべてのフェーズについて、包括的な進捗レポートを生成します。

• 各フェーズの完了率を表示します
• フェーズごとの未完了タスクを一覧表示します
• 簡略化または変更されたタスクを強調表示します
• 全体の進捗統計を提示します
• 任意の SDD 機能の tasks.md ファイルに対応します

使用方法： ```bash ~/.claude/skills/sdd/scripts/phase_summary.sh specs/003-keyboard-shortcuts/tasks.md ```

出力： フェーズごとにまとめられた、Markdown 形式の進捗レポートです。以下が含まれます。

• フェーズごとの完了率
• 未完了タスクの一覧（各フェーズにつき最大 5 件）
• 簡略化されたタスクに関する警告
• 機能全体の進捗概要

使用するタイミング：

• 任意の SDD 機能の進捗を確認するとき
• 完了済みと未完了の項目をすばやく把握するとき
• 対応が必要なフェーズを特定するとき
• 関係者向けの状況レポートを作成するとき

`scripts/analyze-requirements.py`

spec.md と tasks.md にわたる要件のカバレッジを分析します。

• 機能要件（FR-001、FR-002 など）を実装タスクに対応付けます
• カバーされていない要件（タスクのカバレッジの抜け）を特定します
• 測定可能な基準がない曖昧な要件にフラグを付けます
• カバレッジ率を算出します

使用方法： ```bash python3 ~/.claude/skills/sdd/scripts/analyze-requirements.py ```

出力： カバレッジ指標、未対応の要件、曖昧な要件を含む JSON

`scripts/analyze-success-criteria.py`

成功基準の検証カバレッジを分析します。

• 成功基準（SC-001、SC-002 など）を検証タスクに対応付けます
• 各基準が測定可能かどうかを検証します
• 検証タスクのない基準を特定します
• 指標の種類（パフォーマンス、アクセシビリティ、ユーザビリティ）ごとに分類します

使用方法： ```bash python3 ~/.claude/skills/sdd/scripts/analyze-success-criteria.py ```

出力： カバレッジの概要と検証タスクの対応付けを含む JSON

`scripts/analyze-edge-cases.py`

仕様全体にわたるエッジケースのカバレッジを分析します。

• エッジケースを明示的なタスクのカバレッジに対応付けます
• 暗黙的にカバーされるケース（一般的なロジックで処理されるケース）を特定します
• 対応が必要な未対応のエッジケースにフラグを付けます
• カバレッジの種類（EXPLICIT、IMPLICIT、UNCOVERED）ごとに分類します

使用方法： ```bash python3 ~/.claude/skills/sdd/scripts/analyze-edge-cases.py ```

出力： カバレッジの内訳と未対応のエッジケースの詳細を含む JSON

使用するタイミング： これらのスクリプトは、詳細な一貫性検証を行うため、`/speckit.analyze` の実行中に自動的に呼び出されます。以下の特定に役立ちます。

• タスクでカバーされていない要件
• 検証タスクのない成功基準
• テストカバレッジが必要なエッジケース
• 明確化が必要な曖昧な要件

検証コマンド（ブラウンフィールド）

``` /speckit.validate-reverse-engineering # 仕様の正確性を検証 /speckit.coverage-check # ドキュメントのカバレッジを確認 /speckit.validate-constitution # 憲章の一貫性を検証 /speckit.trace [feature] # 仕様をコードに対応付け ```

詳細なドキュメント

• インストールガイド：インストール方法、トラブルシューティング、環境変数
• グリーンフィールドのワークフロー：新規プロジェクト向けの全 6 ステップのワークフロー
• ブラウンフィールドのワークフロー：既存のコードベース向けの全 7 ステップのワークフロー

他のスキルとの連携

このスキルは以下と併用すると効果的です。

• project-memory：SDD の決定事項やパターンを記録します
• design-doc-mermaid：plan.md からアーキテクチャを可視化します
• github-workflows：SDD 成果物の検証を自動化します
• code-quality-reviewer：生成された実装をレビューします

リソース

• GitHub Spec-Kit リポジトリ：https://github.com/github/spec-kit
• 課題／サポート：https://github.com/github/spec-kit/issues
• ライセンス：MIT

メンテナー

• Den Delimarsky (@localden)
• John Lam (@jflam)