Spec-Kit: 憲法ベースの仕様駆動開発

機能開発のための7段階の憲法駆動ワークフローを提供する公式GitHub Spec-Kit統合。

クイックスタート

このスキルはGitHub Spec-Kit CLIと連携して、体系化された機能開発をガイドします：

1. Constitution → 統治原則の確立
2. Specify → 機能要件の定義
3. Clarify → 曖昧な点の解決
4. Plan → 技術戦略の作成
5. Tasks → 実行可能な分割の生成
6. Analyze → 一貫性の検証
7. Implement → 実装の実行

保存場所: .specify/specs/NNN-feature-name/ ディレクトリに番号付きの機能ファイルを作成します

いつ使うか

• プロジェクトで spec-kit をセットアップする場合
• 憲法ベースの機能仕様を作成する場合
• .specify/ ディレクトリで作業する場合
• GitHub spec-kit ワークフローに従う場合
• 憲法駆動開発を行う場合

---

前提条件とセットアップ

CLI インストールの確認

まず、spec-kit CLI がインストールされているか確認します：

command -v specify || echo "Not installed"

インストール

インストールされていない場合：

# 永続的なインストール（推奨）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# ワンタイム使用
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

必要条件:

• Python 3.11+
• Git
• uv パッケージマネージャー（uv のインストール）

プロジェクト初期化

CLI がインストールされているが、プロジェクトがまだ初期化されていない場合：

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

# 新しいプロジェクトを初期化
specify init <project-name> --ai claude

# オプション:
# --force: 空でないディレクトリを上書き
# --script ps: PowerShell スクリプトを生成（Windows）
# --no-git: Git 初期化をスキップ

---

<details> <summary>🔍 フェーズ検出ロジック</summary>

プロジェクト状態の検出

進める前に、常に現在の状態を検出します：

1. CLI がインストールされているか?

if command -v specify &> /dev/null || [ -x "$HOME/.local/bin/specify" ]; then
  echo "CLI installed"
else
  echo "CLI not installed - guide user through installation"
fi

2. プロジェクトが初期化されているか?

if [ -d ".specify" ] && [ -f ".specify/memory/constitution.md" ]; then
  echo "Project initialized"
else
  echo "Project not initialized - guide user through 'specify init'"
fi

3. 現在の機能

# 最新の機能ディレクトリを取得
LATEST=$(ls -d .specify/specs/[0-9]* 2>/dev/null | sort -V | tail -1)
echo "Latest feature: $LATEST"

4. 現在のフェーズ

最新の機能でファイルの存在をチェックしてフェーズを検出：

FEATURE_DIR=".specify/specs/001-feature-name"

if [ ! -f ".specify/memory/constitution.md" ]; then
  echo "Phase: constitution"
elif [ ! -d "$FEATURE_DIR" ]; then
  echo "Phase: specify"
elif [ -f "$FEATURE_DIR/spec.md" ] && ! grep -q "## Clarifications" "$FEATURE_DIR/spec.md"; then
  echo "Phase: clarify"
elif [ ! -f "$FEATURE_DIR/plan.md" ]; then
  echo "Phase: plan"
elif [ ! -f "$FEATURE_DIR/tasks.md" ]; then
  echo "Phase: tasks"
elif [ -f "$FEATURE_DIR/tasks.md" ] && grep -q "\\- \\[ \\]" "$FEATURE_DIR/tasks.md"; then
  echo "Phase: implement"
else
  echo "Phase: complete"
fi

</details> <details> <summary>📜 フェーズ 1: Constitution</summary>

Constitution フェーズ

すべての開発決定を統制する基本原則を確立します。

目的

以下を含む .specify/memory/constitution.md を作成：

• プロジェクトの価値観と原則
• 技術標準
• 意思決定フレームワーク
• コード品質の期待値
• アーキテクチャガイドライン

プロセス

1. コンテキストの収集

   • プロジェクトドメインの理解
   • 主要なステークホルダーの特定
   • 既存の標準のレビュー（ある場合）

2. 憲法案の作成

   • コア価値観と原則
   • 技術標準
   • 品質期待値
   • 意思決定基準

3. 構造

# プロジェクト憲法

## コア価値観

1. **[価値観名]**: [説明と影響]
2. **[価値観名]**: [説明と影響]

## 技術原則

### アーキテクチャ
- [根拠付き原則]

### コード品質
- [標準と期待値]

### パフォーマンス
- [パフォーマンス基準]

## 意思決定フレームワーク

技術的な決定を行う際は、以下を考慮：
1. [優先度付き基準]
2. [優先度付き基準]

4. バージョニング
   • 憲法は発展可能
   • 統治のための変更の追跡
   • 定期的なレビュー

コンテンツ例

# プロジェクト憲法

## コア価値観

1. **シンプルさは賢さより優先**: 賢い最適化よりも、理解しやすく保守しやすいシンプルなソリューションを優先する。

2. **ユーザーエクスペリエンス優先**: すべての技術的決定がユーザーエクスペリエンスを改善または維持する必要がある。

## 技術原則

### アーキテクチャ
- 継承よりもコンポジションを優先
- コンポーネントは疎結合に設計
- テスト可能性を考慮して設計

### コード品質
- すべての変更にコードレビューが必須
- ユニットテストカバレッジ > 80%
- 公開 API のドキュメント化

### パフォーマンス
- ページロード < 3 秒
- API レスポンス < 200ms
- 低速接続に対するプログレッシブエンハンスメント

## 意思決定フレームワーク

アプローチを選択する際：
1. コア価値観と一致しているか?
2. チームで保守可能か?
3. 成長に対応できるか?
4. 長期的なコストは?

</details> <details> <summary>📝 フェーズ 2: Specify</summary>

Specify フェーズ

技術固有の詳細を避けながら、何を構築する必要があるか、そしてなぜ構築するのかを定義します。

スクリプト使用

# 新しい機能を作成
.specify/scripts/bash/create-new-feature.sh --json "feature-name"

# 予想される JSON 出力:
# {"BRANCH_NAME": "001-feature-name", "SPEC_FILE": "/path/to/.specify/specs/001-feature-name/spec.md"}

JSON を解析: BRANCH_NAME と SPEC_FILE を抽出して、後続の操作に使用します。

テンプレート構造

.specify/templates/spec-template.md を読み込んで必要なセクションを理解し、その後 SPEC_FILE の場所で仕様を作成します。

仕様コンテンツ

機能要件に焦点を当てます：

# 機能仕様: [機能名]

## 問題ステートメント

[どんな問題を解決しているか?]

## ユーザーストーリー

### ストーリー 1: [タイトル]

As a [ロール]
I want [機能]
So that [利益]

**受け入れ基準:**
- [ ] [具体的でテスト可能な基準]
- [ ] [具体的でテスト可能な基準]

### ストーリー 2: [タイトル]

[続行...]

## 非機能要件

- パフォーマンス: [具体的なメトリクス]
- セキュリティ: [要件]
- アクセシビリティ: [標準]
- スケーラビリティ: [期待値]

## 成功メトリクス

- [測定可能な成果]
- [測定可能な成果]

## スコープ外

[含まれていないものを明確に述べる]

主要な原則

• 技術に依存しない: 「React を使用する」または「MySQL」を指定しない
• 成果に焦点: ユーザーが達成することを説明し、どのようにではなく
• テスト可能: 受け入れ基準は検証可能である必要がある
• 完全: エッジケースとエラーシナリオに対応する

Git 統合

スクリプトは自動的に：

• 新しい機能ブランチを作成（例：001-feature-name）
• ブランチをチェックアウト
• 仕様ファイルを初期化

</details> <details> <summary>❓ フェーズ 3: Clarify</summary>

Clarify フェーズ

ターゲット化された質問を通じて、不十分に指定された領域を解決します。

目的

実装計画の前に、仕様が完全で曖昧でないことを確認します。

プロセス

1. 仕様を分析

   • spec.md を徹底的に読む
   • 曖昧さ、ギャップ、前提を特定
   • 複数の有効な解釈がある領域に注意

2. 質問を生成（最大 5 個）

   • 高影響領域を優先
   • アーキテクチャに影響を与える決定に焦点を当てる
   • エッジケースとエラーハンドリングについて尋ねる

3. 質問フォーマット

## 明確化

### Q1: [明確で具体的な質問]

**コンテキスト**: [これが重要な理由]
**オプション**: [複数のアプローチが存在する場合]

### Q2: [明確で具体的な質問]

**コンテキスト**: [これが重要な理由]
**影響**: [この決定に依存するもの]

4. 仕様を更新
   • spec.md に「## 明確化」セクションを追加
   • 質問と回答を文書化
   • 回答に基づいて関連セクションを更新
   • すべての重要な質問に答えられるまで反復

ガイドライン

• 1 回につき最大 5 つの質問
• 具体的で一般的でない: 「同じドキュメントを同時に編集する 2 人のユーザーに対してどう対応すべきか?」ではなく「それはどのように機能すべきか?」ではなく
• 決定焦点: 技術的な選択に情報を与える質問
• 段階的: 複数の明確化ラウンドを実行できます

質問例

## 明確化

### Q1: 2 人のユーザーが同じドキュメントを同時に編集する場合、システムはコンフリクトをどのように処理する必要がありますか?

**コンテキスト**: これはデータモデル設計とユーザーエクスペリエンスに影響します。
**オプション**:
- Last-write-wins（シンプル、データ喪失の可能性）
- Operational transforms（複雑、すべての編集を保持）
- ロック編集（シンプル、コラボレーションを制限）

**回答**: [ユーザーが回答を提供]

### Q2: 同時に対応する必要がある最大ユーザー数は何人ですか?

**コンテキスト**: インフラストラクチャ計画とアーキテクチャの決定に影響します。
**影響**: キャッシング戦略、データベース選択、スケーリングアプローチを決定します。

**回答**: [ユーザーが回答を提供]

</details> <details> <summary>🏗️ フェーズ 4: Plan</summary>

Plan フェーズ

明確化された仕様に基づいた技術実装戦略を作成します。

スクリプト使用

# プラン フェーズをセットアップ
.specify/scripts/bash/setup-plan.sh --json

# 予想される JSON 出力:
# {"FEATURE_SPEC": "/path/spec.md", "IMPL_PLAN": "/path/plan.md", "SPECS_DIR": "/path/specs", "BRANCH": "001-feature"}

作成するドキュメント

1. メインプラン（plan.md）

# 実装計画: [機能名]

## テクノロジースタック

### フロントエンド
- フレームワーク: [根拠付き選択]
- 状態管理: [根拠付き選択]
- スタイリング: [根拠付き選択]

### バックエンド
- 言語/フレームワーク: [根拠付き選択]
- データベース: [根拠付き選択]
- API スタイル: [REST/GraphQL/etc 根拠付き]

## アーキテクチャ

### システム概要

```mermaid
graph TD
    A[Client] --> B[API Gateway]
    B --> C[Service Layer]
    C --> D[Data Layer]

コンポーネント設計

コンポーネント 1: [名前]

• 責任: [何をするか]
• インターフェース: [公開する API]
• 依存: [必要なもの]

[すべてのコンポーネントについて続行...]

デザインパターン

セキュリティに関する考慮事項

• 認証: [アプローチ]
• 認可: [アプローチ]
• データ保護: [アプローチ]

パフォーマンス戦略

• キャッシング: [戦略]
• 最適化: [主要領域]

エラーハンドリング

• エラータイプとハンドリング戦略
• ロギングとモニタリングアプローチ

#### 2. データモデル（`data-model.md`）

```markdown
# データモデル

## エンティティ関連図

```mermaid
erDiagram
    USER ||--o{ DOCUMENT : creates
    USER {
        string id
        string email
        string role
    }
    DOCUMENT {
        string id
        string title
        string content
    }

スキーマ

User

interface User {
  id: string;
  email: string;
  role: 'admin' | 'editor' | 'viewer';
  createdAt: Date;
}

[すべてのエンティティについて続行...]

#### 3. API コントラクト（`contracts/`）

API 仕様を作成：
- `api-spec.json` (OpenAPI/Swagger)
- `signalr-spec.md` (SignalR を使用する場合)
- その他のコントラクト定義

#### 4. リサーチ（`research.md`）- オプション

技術調査を文書化：

```markdown
# リサーチ: [トピック]

## 評価されたオプション

### オプション 1: [テクノロジー]
**利点**: [メリット]
**欠点**: [デメリット]
**適合**: [ニーズへの適合度]

### オプション 2: [テクノロジー]
[同じ構造...]

## 推奨

[選択されたオプションと根拠]

## 参考資料

- [出典 1]
- [出典 2]

5. クイックスタート（quickstart.md）- オプション

開発者向けのセットアップ手順。

アラインメントチェック

最終化する前に：

• ✅ プランはすべての要件に対応しているか?
• ✅ 憲法原則に従っているか?
• ✅ 技術的選択は正当化されているか?
• ✅ 依存は特定されているか?
• ✅ 実装可能か?

</details> <details> <summary>✅ フェーズ 5: Tasks</summary>

Tasks フェーズ

依存関係の順序を考慮した実行可能な実装タスクを生成します。

前提条件スクリプト

# 前提条件をチェック
.specify/scripts/bash/check-prerequisites.sh --json [--require-tasks] [--include-tasks]

# 出力: {"FEATURE_DIR": "/path", "AVAILABLE_DOCS": ["spec.md", "plan.md", ...]}

タスク生成

.specify/specs/NNN-feature/tasks.md を作成：

# 実装タスク: [機能名]

## フェーズ 1: 基礎

- [ ] 1.1 プロジェクト構造をセットアップ
  - アーキテクチャドックに従ってディレクトリレイアウトを作成
  - ビルドツールを設定
  - テストフレームワークを初期化
  - **依存**: なし
  - **要件**: R1.1

- [ ] 1.2 [P] 開発環境を設定
  - リンターとフォーマッターをセットアップ
  - CI/CD パイプラインの基本を設定
  - **依存**: 1.1
  - **要件**: R1.2

## フェーズ 2: コア実装

- [ ] 2.1 User モデルと永続化を実装
  - バリデーション付き User エンティティを作成
  - リポジトリパターンを実装
  - ユニットテストを作成
  - **依存**: 1.1
  - **要件**: R2.1, R2.3

- [ ] 2.2 [P] Document モデルを実装
  - Document エンティティを作成
  - User との関連性を定義
  - ユニットテストを作成
  - **依存**: 1.1
  - **要件**: R2.2

- [ ] 2.3 API エンドポイントを実装
  - REST コントローラーを作成
  - リクエスト/レスポンスバリデーションを追加
  - 統合テストを作成
  - **依存**: 2.1, 2.2
  - **要件**: R3.1, R3.2

[すべてのフェーズで続行...]

## フェーズ N: 統合とテスト

- [ ] N.1 エンドツーエンドテスト
  - E2E テストシナリオを作成
  - 重要なユーザーパスをテスト
  - **依存**: [すべての前のもの]
  - **要件**: すべて

## 注記

- `[P]` は並列化可能なタスクを示します
- 開始する前に必ず依存をチェック
- 要件の受け入れ基準を参照してください

タスクの特性

各タスクは:

• 具体的で実行可能
• 要件を参照（R1.1, R2.3 など）
• 依存を列挙
• 1～4 時間で完了可能
• 明確な受け入れ基準を持つ

タスク型:

• 実装タスク（コードを書く）
• テストタスク（テストを書く）
• 設定タスク（ツールをセットアップ）
• 統合タスク（コンポーネントを接続）

除外:

• デプロイメントタスク
• ユーザー訓練
• マーケティング活動
• 非コーディング作業

依存マーカー

• None: すぐに開始可能
• 1.1: まず タスク 1.1 を完了する必要があります
• 1.1, 2.2: 両方を最初に完了する必要があります
• [P]: 兄弟タスクと並列で実行可能

</details> <details> <summary>🔍 フェーズ 6: Analyze</summary>

Analyze フェーズ

アーティファクト間の一貫性と品質検証（読み取り専用）。

目的

実装前に以下を確認：

• 要件がすべてカバーされているか
• 計画が憲法と一致しているか
• ドキュメント間にコンフリクトがないか
• 不足している依存がないか

分析プロセス

1. すべてのドキュメントを読む

   • 憲法
   • 仕様
   • 計画
   • データモデル
   • タスク

2. カバレッジチェック

# 要件を抽出
grep -E "R[0-9]+\.[0-9]+" spec.md | sort -u > requirements.txt

# タスクで参照された要件を抽出
grep -E "Requirement.*R[0-9]+" tasks.md | sort -u > covered.txt

# 比較
comm -23 requirements.txt covered.txt

3. 一貫性チェック

憲法アラインメント:

• 計画は記載された原則に従っているか?
• アーキテクチャ選択は憲法に従って正当化されているか?

要件カバレッジ:

• すべての要件がタスクで対応されているか?
• 受け入れ基準はテスト可能か?

技術的一貫性:

• データモデルは仕様のニーズと一致しているか?
• API コントラクトは計画と一致しているか?
• 依存は現実的か?

タスク依存:

• すべての依存は有効か?
• クリティカルパスは特定されているか?
• 循環依存はないか?

4. 結果をレポート

# 分析レポート

## ✅ 合格チェック

- すべての要件がカバーされている
- 憲法アラインメントが検証されている
- 循環依存がない

## ⚠️ 警告

- 要件 R3.4 に対応するタスクがない
- タスク 5.2 は定義されていない依存を参照している

## 🔴 重大な問題

見つかりません

## 推奨事項

1. 要件 R3.4 のタスクを追加
2. タスク 5.2 の依存を明確にする
3. タスク 6.1 をより小さいタスクに分割することを検討（推定 8 時間）

ガイドライン

• 読み取り専用: ドキュメントを変更しない
• 客観的: 意見ではなく事実をレポート
• 実行可能: 具体的な推奨を提供
• 優先順位付け: 重大な問題から優先

</details> <details> <summary>⚙️ フェーズ 7: Implement</summary>

Implement フェーズ

依存と テスト駆動開発を尊重しながら、タスクを体系的に実行します。

実装戦略

1. フェーズごとの実行

   • フェーズ 2 の前にすべてのフェーズ 1 タスクを完了
   • タスク依存を尊重
   • 並列マーカー [P] を活用

2. タスク実行パターン

# 各タスクについて：
# 1. コンテキストを読む
cat .specify/specs/001-feature/spec.md
cat .specify/specs/001-feature/plan.md
cat .specify/specs/001-feature/data-model.md

# 2. 依存を確認
# 依存するすべてのタスクが完了していることを確認

# 3. 実装
# タスク説明に従ってコードを書く

# 4. テスト
# テストを作成して実行

# 5. 検証
# 要件に対して確認

# 6. マークを完了
# tasks.md を更新: - [x] task completed

3. テスト駆動アプローチ

各タスクについて：

• テストを最初に書く（適用可能な場合）
• テストに合格するために実装
• テストが緑のまま リファクタリング
• コンポーネントを接続するときに統合テスト

4. 品質チェック

タスクを完了とマークする前に：

• コードは計画アーキテクチャに従っているか
• テストが作成され、パスしているか
• 受け入れ基準を満たしているか
• 明白なバグがないか
• 前の作業と統合されているか

エラーハンドリング

実装が問題を明かにした場合：

1. 設計の問題: 計画フェーズに戻り、計画を更新
2. 要件ギャップ: 指定/明確化に戻り、仕様を更新
3. 技術的ブロッカー: 文書化し、ユーザーにエスカレート

進捗追跡

進めながら tasks.md を更新：

- [x] 1.1 プロジェクト構造をセットアップ ✓ 完了
- [x] 1.2 [P] 開発環境を設定 ✓ 完了
- [ ] 2.1 User モデルを実装 ← 現在ここ
- [ ] 2.2 [P] Document モデルを実装

完了基準

機能は以下の場合に完了：

• すべてのタスクを完了とマーク
• すべてのテストがパス
• すべての要件が検証されている
• コードレビュー完了（適用可能な場合）
• ドキュメントが更新されている

</details>

---

ファイル構造

.specify/
├── memory/
│   └── constitution.md              # フェーズ 1
├── specs/
│   └── 001-feature-name/            # 番号付き機能
│       ├── spec.md                  # フェーズ 2
│       ├── plan.md                  # フェーズ 4
│       ├── data-model.md            # フェーズ 4
│       ├── contracts/               # フェーズ 4
│       │   ├── api-spec.json
│       │   └── signalr-spec.md
│       ├── research.md              # フェーズ 4（オプション）
│       ├── quickstart.md            # フェーズ 4（オプション）
│       └── tasks.md                 # フェーズ 5
├── scripts/
│   └── bash/
│       ├── check-prerequisites.sh
│       ├── create-new-feature.sh
│       ├── setup-plan.sh
│       └── common.sh
└── templates/
    ├── spec-template.md
    ├── plan-template.md
    └── tasks-template.md

ワークフロールール

1. 順序付きフェーズ: フェーズを順番に完了する必要があります
2. Constitution を最初に: 機能の前に常に憲法を確立
3. 機能ごとのブランチ: 各機能は独自の Git ブランチを取得
4. 番号付き機能: 順序番号を使用（001、002、003）
5. スクリプト統合: 一貫性のために提供されている bash スクリプトを使用
6. 原則駆動: すべての決定は憲法と一致

まとめ

Spec-Kit は機能開発への厳密な憲法ベースのアプローチを提供し、明確なフェーズ、明示的な依存、およびすべてのステップでの包括的なドキュメント作成を特徴としています。ワークフローは原則から実装まですべての段階でアラインメントを確保します。

サポートファイル

高度な検出ロジックと自動化スクリプトについては、以下を参照：

• Detection Logic - 包括的な状態検出アルゴリズム