spec-kit-skill

プロジェクトの状態の検出

続行する前に、必ず現在の状態を検出してください。

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. 現在の機能

# Get latest feature directory
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

憲章フェーズ

すべての開発上の判断を統べる基盤となる原則を定めます。

目的

以下の内容を含む.specify/memory/constitution.mdを作成します。

• プロジェクトの価値観と原則
• 技術標準
• 意思決定の枠組み
• コード品質に関する期待事項
• アーキテクチャのガイドライン

手順

1. 背景情報を収集

   • プロジェクトの領域を理解する
   • 主要なステークホルダーを特定する
   • 既存の標準を確認する（あれば）

2. 憲章を起草

   • 中核となる価値観と原則
   • 技術標準
   • 品質に関する期待事項
   • 判断基準

3. 構成

# Project Constitution

## Core Values

1. **[Value Name]**: [Description and implications]
2. **[Value Name]**: [Description and implications]

## Technical Principles

### Architecture
- [Principle with rationale]

### Code Quality
- [Standards and expectations]

### Performance
- [Performance criteria]

## Decision Framework

When making technical decisions, consider:
1. [Criterion with priority]
2. [Criterion with priority]

4. バージョン管理
   • 憲章は進化する可能性があります
   • ガバナンスのために変更を追跡します
   • 定期的に見直します

内容の例

# Project Constitution

## Core Values

1. **Simplicity Over Cleverness**: Favor straightforward solutions that are easy to understand and maintain over clever optimizations.

2. **User Experience First**: Every technical decision should improve or maintain user experience.

## Technical Principles

### Architecture
- Prefer composition over inheritance
- Keep components loosely coupled
- Design for testability

### Code Quality
- Code reviews required for all changes
- Unit test coverage > 80%
- Documentation for public APIs

### Performance
- Page load < 3 seconds
- API response < 200ms
- Progressive enhancement for slower connections

## Decision Framework

When choosing between approaches:
1. Does it align with our core values?
2. Is it maintainable by the team?
3. Does it scale with our growth?
4. What's the long-term cost?

仕様策定フェーズ

技術の詳細には踏み込まず、何を構築する必要があるのか、そしてその理由を定義します。

スクリプトの使用方法

# Create new feature
.specify/scripts/bash/create-new-feature.sh --json "feature-name"

# Expected JSON output:
# {"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の場所に仕様を作成します。

仕様の内容

機能要件に重点を置きます。

# Feature Specification: [Feature Name]

## Problem Statement

[What problem are we solving?]

## User Stories

### Story 1: [Title]

As a [role]
I want [capability]
So that [benefit]

**Acceptance Criteria:**
- [ ] [Specific, testable criterion]
- [ ] [Specific, testable criterion]

### Story 2: [Title]

[Continue...]

## Non-Functional Requirements

- Performance: [Specific metrics]
- Security: [Requirements]
- Accessibility: [Standards]
- Scalability: [Expectations]

## Success Metrics

- [Measurable outcome]
- [Measurable outcome]

## Out of Scope

[Explicitly state what's NOT included]

主な原則

• 技術に依存しない：「React を使う」や「MySQL を使う」と指定しない
• 成果を重視する：方法ではなく、ユーザーが何を達成するのかを記述する
• テスト可能である：受け入れ基準を検証可能にする
• 網羅的である：エッジケースとエラーシナリオに対処する

Git との連携

スクリプトは自動的に以下を実行します。

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

明確化フェーズ

対象を絞った質問を通じて、仕様が不十分な領域を解消します。

目的

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

1. 仕様を分析する

   • spec.md を隅々まで読む
   • 曖昧な点、抜けている点、前提条件を特定する
   • 複数の妥当な解釈がある箇所を記録する

2. 質問を作成する（最大5件）

   • 影響の大きい項目を優先する
   • アーキテクチャに影響する判断に焦点を当てる
   • エッジケースとエラー処理について質問する

3. 質問の形式

## Clarifications

### Q1: [Clear, specific question]

**Context**: [Why this matters]
**Options**: [If multiple approaches exist]

### Q2: [Clear, specific question]

**Context**: [Why this matters]
**Impact**: [What decisions depend on this]

4. 仕様を更新する
   • spec.md に「## Clarifications」セクションを追加する
   • 質問と回答を記録する
   • 回答に基づいて関連するセクションを更新する
   • 重要な質問への回答がすべて得られるまで繰り返す

ガイドライン

• 各ラウンドの質問は最大5件
• 具体的にする：「同時編集をどのように処理しますか？」のように質問し、「どのように動作すべきですか？」のような質問は避ける
• 判断に結び付く内容にする：技術的な選択に役立つ質問にする
• 段階的に進める：明確化のラウンドを複数回実行できる

質問例

## Clarifications

### Q1: How should the system handle conflicts when two users edit the same document simultaneously?

**Context**: This affects data model design and user experience.
**Options**:
- Last-write-wins (simple, may lose data)
- Operational transforms (complex, preserves all edits)
- Locked editing (simple, limits collaboration)

**Answer**: [User provides answer]

### Q2: What's the maximum number of concurrent users we need to support?

**Context**: Affects infrastructure planning and architecture decisions.
**Impact**: Determines caching strategy, database choices, and scaling approach.

**Answer**: [User provides answer]

計画フェーズ

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

スクリプトの使用方法

# Setup plan phase
.specify/scripts/bash/setup-plan.sh --json

# Expected JSON output:
# {"FEATURE_SPEC": "/path/spec.md", "IMPL_PLAN": "/path/plan.md", "SPECS_DIR": "/path/specs", "BRANCH": "001-feature"}

作成するドキュメント

1. メイン計画（plan.md）

# Implementation Plan: [Feature Name]

## Technology Stack

### Frontend
- Framework: [Choice with rationale]
- State Management: [Choice with rationale]
- Styling: [Choice with rationale]

### Backend
- Language/Framework: [Choice with rationale]
- Database: [Choice with rationale]
- API Style: [REST/GraphQL/etc with rationale]

## Architecture

### System Overview

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

コンポーネント設計

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

• 責務：[実行する内容]
• インターフェース：[公開するAPI]
• 依存関係：[必要なもの]

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

デザインパターン

• [パターン]：[使用箇所と理由]

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

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

パフォーマンス戦略

• キャッシュ：[戦略]
• 最適化：[主な対象領域]

エラー処理

• エラーの種類と処理戦略
• ロギングとモニタリングのアプローチ

#### 2. Data Model (`data-model.md`)

```markdown
# Data Model

## Entity Relationship

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

スキーマ

ユーザー

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

[すべてのエンティティについて続けて記述...]

#### 3. API Contracts (`contracts/`)

Create API specifications:
- `api-spec.json` (OpenAPI/Swagger)
- `signalr-spec.md` (if using SignalR)
- Other contract definitions

#### 4. Research (`research.md`) - Optional

Document technology investigations:

```markdown
# Research: [Topic]

## Options Evaluated

### Option 1: [Technology]
**Pros**: [Benefits]
**Cons**: [Drawbacks]
**Fit**: [How well it matches our needs]

### Option 2: [Technology]
[Same structure...]

## Recommendation

[Chosen option with rationale]

## References

- [Source 1]
- [Source 2]

5. クイックスタート（quickstart.md）- 任意

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

整合性の確認

最終決定する前に、以下を確認します。

• ✅ 計画はすべての要件に対応していますか？
• ✅ 憲章の原則に従っていますか？
• ✅ 技術的な選択には根拠がありますか？
• ✅ 依存関係を特定していますか？
• ✅ 実装可能ですか？

タスクフェーズ

依存関係の順に並んだ、実行可能な実装タスクを生成します。

前提条件スクリプト

# Check prerequisites
.specify/scripts/bash/check-prerequisites.sh --json [--require-tasks] [--include-tasks]

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

タスクの生成

.specify/specs/NNN-feature/tasks.md を作成します。

# Implementation Tasks: [Feature Name]

## Phase 1: Foundation

- [ ] 1.1 Set up project structure
  - Create directory layout per architecture doc
  - Configure build tools
  - Initialize testing framework
  - **Depends on**: None
  - **Requirement**: R1.1

- [ ] 1.2 [P] Configure development environment
  - Set up linters and formatters
  - Configure CI/CD pipeline basics
  - **Depends on**: 1.1
  - **Requirement**: R1.2

## Phase 2: Core Implementation

- [ ] 2.1 Implement User model and persistence
  - Create User entity with validation
  - Implement repository pattern
  - Write unit tests
  - **Depends on**: 1.1
  - **Requirement**: R2.1, R2.3

- [ ] 2.2 [P] Implement Document model
  - Create Document entity
  - Define relationships with User
  - Write unit tests
  - **Depends on**: 1.1
  - **Requirement**: R2.2

- [ ] 2.3 Implement API endpoints
  - Create REST controllers
  - Add request/response validation
  - Write integration tests
  - **Depends on**: 2.1, 2.2
  - **Requirement**: R3.1, R3.2

[Continue with all phases...]

## Phase N: Integration & Testing

- [ ] N.1 End-to-end testing
  - Write E2E test scenarios
  - Test critical user paths
  - **Depends on**: [all previous]
  - **Requirement**: All

## Notes

- `[P]` indicates tasks that can be parallelized
- Always check dependencies before starting
- Reference requirements for acceptance criteria

タスクの特徴

各タスクは次の条件を満たす必要があります：

• 具体的で実行可能である
• 要件（R1.1、R2.3 など）を参照している
• 依存関係を列挙している
• 1～4時間で完了できる
• 明確な受け入れ基準がある

タスクの種類：

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

対象外：

• デプロイタスク
• ユーザートレーニング
• マーケティング活動
• コーディング以外の作業

依存関係マーカー

• なし：すぐに開始できる
• 1.1：先にタスク1.1を完了する必要がある
• 1.1、2.2：両方を先に完了する必要がある
• [P]：同じ階層のタスクと並行して実行できる

分析フェーズ

成果物間の一貫性と品質を検証します（読み取り専用）。

目的

実装前に、以下を確認します。

• すべての要件がタスクで網羅されている
• 計画が憲章に沿っている
• ドキュメント間に矛盾がない
• 依存関係に漏れがない

分析プロセス

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

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

2. 網羅性の確認

# Extract requirements
grep -E "R[0-9]+\.[0-9]+" spec.md | sort -u > requirements.txt

# Extract referenced requirements in tasks
grep -E "Requirement.*R[0-9]+" tasks.md | sort -u > covered.txt

# Compare
comm -23 requirements.txt covered.txt

3. 整合性の確認

憲章との整合性：

• 計画は明示された原則に従っていますか？
• アーキテクチャの選択は憲章に基づいて正当化されていますか？

要件の網羅性：

• すべての要件がタスクで扱われていますか？
• 受け入れ基準はテスト可能ですか？

技術的な整合性：

• データモデルは仕様のニーズに合っていますか？
• API コントラクトは計画と整合していますか？
• 依存関係は現実的ですか？

タスクの依存関係：

• すべての依存関係は有効ですか？
• クリティカルパスは特定されていますか？
• 循環依存はありませんか？

4. 調査結果を報告する

# Analysis Report

## ✅ Passing Checks

- All requirements covered
- Constitution alignment verified
- No circular dependencies

## ⚠️ Warnings

- Requirement R3.4 has no corresponding task
- Task 5.2 references undefined dependency

## 🔴 Critical Issues

None found

## Recommendations

1. Add task for Requirement R3.4
2. Clarify dependency for task 5.2
3. Consider breaking task 6.1 into smaller tasks (estimated 8 hours)

実装フェーズ

依存関係を尊重し、テスト駆動開発に従ってタスクを体系的に実行します。

実装戦略

1. フェーズごとの実行

   • フェーズ 1 のすべてのタスクを完了してから、フェーズ 2 に進みます
   • タスクの依存関係を尊重します
   • 並列マーカー [P] を活用します

2. タスク実行パターン

# For each task:
# 1. Read context
cat .specify/specs/001-feature/spec.md
cat .specify/specs/001-feature/plan.md
cat .specify/specs/001-feature/data-model.md

# 2. Check dependencies
# Verify all depends-on tasks are complete

# 3. Implement
# Write code per task description

# 4. Test
# Write and run tests

# 5. Validate
# Check against requirements

# 6. Mark complete
# Update tasks.md: - [x] task completed

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

各タスクについて：

• （該当する場合）まずテストを作成します
• テストに合格するよう実装します
• テストが成功した状態を維持しながらリファクタリングします
• コンポーネントを接続するときは統合テストを行います

4. 品質チェック

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

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

エラーへの対処

実装中に問題が判明した場合：

1. 設計上の問題：計画フェーズに戻り、計画を更新します
2. 要件の不足：仕様の作成／明確化に戻り、仕様を更新します
3. 技術的な阻害要因：記録し、ユーザーにエスカレーションします

進捗の追跡

作業を進めながら tasks.md を更新します：

- [x] 1.1 Set up project structure ✓ Complete
- [x] 1.2 [P] Configure development environment ✓ Complete
- [ ] 2.1 Implement User model ← Currently here
- [ ] 2.2 [P] Implement Document model

完了条件

次の条件を満たすと、機能は完了です：

• すべてのタスクが完了としてマークされている
• すべてのテストに合格している
• すべての要件が検証済みである
• コードレビューが行われている（該当する場合）
• ドキュメントが更新されている