注目
SpecKit Specification Workflow Architecture
SpecKit: Claude Code による仕様駆動開発
仕様駆動開発のための SpecKit をマスターしましょう。まず仕様を書き、その後 Claude に完全なトレーサビリティを持って体系的に実装させる方法を学びます。
2026年1月10日 • 24 分で読める • 著者：ClaudeWorld
⚠️ コミュニティパターンに関する注意: SpecKit はコミュニティが開発したワークフローパターンであり、Claude Code の公式機能ではありません。ここで説明されているコマンドと概念は、Claude Code をカスタムスキルとワークフローで拡張するコミュニティプロジェクトである Claude Bootstrap Kit に基づいています。公式の Claude Code 機能は docs.anthropic.com でドキュメント化されています。
SpecKit は、Claude Code のカスタムスキルシステム上に構築された仕様駆動開発フレームワークです。コードに直接飛び込むのではなく、まず仕様を書き、その後 Claude が完全なトレーサビリティを持って体系的に実装します。
このアプローチは、明確性を確保し、手戻りを減らし、コードと同期し続けるドキュメントを作成します。
なぜ仕様駆動開発なのか？
コードファーストの問題点
Developer: "Implement user registration"
Claude: [Implements registration]
Developer: "Actually, I needed email verification"
Claude: [Adds email verification]
Developer: "And it should support SSO"
Claude: [Refactors for SSO]
Developer: "Wait, what about rate limiting?"結果: 複数のイテレーション、不明確な要件、ドキュメントなし。
SpecKit アプローチ
Developer: /speckit-specify User Registration Feature
→ Writes specification with all requirements
→ Clarifies ambiguities
→ Gets approval
Developer: /speckit-plan
→ Technical plan created
→ Architecture decisions documented
Developer: /speckit-implement
→ Claude implements from spec
→ Full traceability
→ Documentation auto-generated結果: 1回のイテレーション、明確な要件、完全なドキュメント。
SpecKit ワークフロー
┌────────────────────────────────────────────────────────────────┐
│ SPECKIT WORKFLOW │
│ │
│ ┌──────────────┐ │
│ │ SPECIFY │ Write pure product specification │
│ │ │ No technical details yet │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ CLARIFY │ Resolve [NEEDS CLARIFICATION] markers │
│ │ │ Make product decisions │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ PLAN │ Technical implementation plan │
│ │ │ Architecture decisions │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ TASKS │ Break plan into executable tasks │
│ │ │ Create implementation roadmap │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ IMPLEMENT │ Execute tasks with full traceability │
│ │ │ Link code to specifications │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ VALIDATE │ Verify implementation matches spec │
│ │ │ Cross-document consistency │
│ └──────────────┘ │
│ │
└────────────────────────────────────────────────────────────────┘SpecKit コマンド
| コマンド | 目的 |
|---|---|
/speckit-init | プロジェクトで SpecKit を初期化 |
/speckit-specify | 機能仕様を作成 |
/speckit-clarify | 曖昧さを解決 |
/speckit-plan | 技術計画を作成 |
/speckit-tasks | 実装タスクに分割 |
/speckit-implement | 実装を実行 |
/speckit-validate | 実装を検証 |
/speckit | 完全なワークフローを実行 |
はじめに
SpecKit の初期化
/speckit-init作成されるもの:
.speckit/
├── constitution.md # Project principles (9 rules)
├── specifications/ # Feature specifications
├── plans/ # Technical plans
├── tasks/ # Implementation tasks
└── README.md # SpecKit documentationConstitution（憲法）
SpecKit は9つの不変の原則を強制します:
# .speckit/constitution.md
## The 9 Principles
### 1. Library-First
All reusable logic lives in libraries, not in CLI or UI code.
### 2. CLI Interface
Features are accessible via CLI before any other interface.
### 3. Test-First
Tests are written before implementation.
### 4. Research-Driven
Decisions are backed by research, not assumptions.
### 5. Specification Consistency
Implementation matches specification exactly.
### 6. Simplicity
Choose the simplest solution that works.
### 7. Anti-Abstraction
Don't abstract until you have 3+ concrete cases.
### 8. Minimal Scope
Implement exactly what's specified, nothing more.
### 9. Integration-First
Integration tests are prioritized over unit tests.フェーズ 1: SPECIFY
仕様の作成
/speckit-specify User Registration FeatureClaude がガイドします:
# Specification: User Registration
## Overview
[One paragraph describing the feature]
## User Stories
As a [user type], I want to [action] so that [benefit].
## Acceptance Criteria
- [ ] User can register with email and password
- [ ] Email is validated for format
- [ ] Password meets security requirements
- [ ] Confirmation email is sent
- [ ] User cannot register with existing email
## User Flow
1. User enters email and password
2. System validates input
3. System creates account
4. System sends confirmation email
5. User is redirected to confirmation page
## Edge Cases
- Invalid email format → Show error message
- Weak password → Show requirements
- Existing email → Show "account exists" message
- Email delivery fails → Show retry option
## Out of Scope
- Social login (future feature)
- Two-factor authentication (future feature)
- Password reset (separate spec)
## [NEEDS CLARIFICATION]
- Maximum password length?
- Email template content?
- Redirect destination after registration?仕様テンプレート
---
id: SPEC-001
title: Feature Name
status: draft | review | approved | implemented
author: Developer Name
created: 2026-01-10
updated: 2026-01-10
---
# Feature Name
## Overview
[What and why]
## User Stories
[Who, what, why]
## Acceptance Criteria
[Testable requirements]
## User Flow
[Step-by-step flow]
## Edge Cases
[Error handling]
## Out of Scope
[What this doesn't include]
## [NEEDS CLARIFICATION]
[Unresolved questions]
## Dependencies
[Other features/specs needed]
## Metrics
[How to measure success]フェーズ 2: CLARIFY
曖昧さの解決
/speckit-clarify SPEC-001Claude がすべての [NEEDS CLARIFICATION] マーカーを特定します:
Found 3 items needing clarification:
1. Maximum password length?
Context: Security requirements for password validation
Options:
a) 128 characters (industry standard)
b) 256 characters (extra safety)
c) Unlimited (trust the user)
Recommendation: 128 characters (balances security and usability)
2. Email template content?
Context: Confirmation email sent to new users
Decision needed: Marketing wants branded template
3. Redirect destination after registration?
Context: Where to send user after successful registration
Options:
a) Dashboard
b) Profile setup
c) Welcome page決定を下す
User: "Use 128 char limit, simple text email for now,
redirect to profile setup."
Claude:
→ Updates specification with decisions
→ Removes [NEEDS CLARIFICATION] markers
→ Adds decision rationale更新された仕様:
## Decisions Made
### Password Length
- **Decision:** 128 character maximum
- **Rationale:** Industry standard, balances security and usability
- **Date:** 2026-01-10
### Email Template
- **Decision:** Simple text email
- **Rationale:** MVP approach, branded template in future phase
- **Date:** 2026-01-10
### Post-Registration Redirect
- **Decision:** Redirect to profile setup
- **Rationale:** Encourages profile completion, improves user experience
- **Date:** 2026-01-10フェーズ 3: PLAN
技術計画の作成
/speckit-plan SPEC-001Claude が技術計画を作成します:
# Technical Plan: User Registration
## Architecture Overview
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Frontend │ —> │ API │ —> │ Database │ │ (React) │ │ (Express) │ │ (Postgres) │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ Email │ │ │ │ (Resend) │ │ │ └─────────────┘ │ │ │ └──────────────────────────────────────►│
## Database Schema
```sql
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
email_verified BOOLEAN DEFAULT FALSE,
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE TABLE email_verifications (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID REFERENCES users(id),
token VARCHAR(255) UNIQUE NOT NULL,
expires_at TIMESTAMPTZ NOT NULL,
used_at TIMESTAMPTZ
);API Design
POST /api/auth/register
// Request
{
email: string; // Valid email format
password: string; // 8-128 chars, complexity requirements
}
// Response (201)
{
message: "Registration successful. Please check your email.";
userId: string;
}
// Error (400)
{
error: "validation_error";
details: { field: string; message: string }[];
}
// Error (409)
{
error: "email_exists";
message: "An account with this email already exists.";
}Security Considerations
- Password Hashing: bcrypt with cost factor 12
- Rate Limiting: 5 attempts per email per hour
- Token Security: 256-bit random token, 24h expiry
- Input Validation: Zod schemas on server
Dependencies
bcrypt- Password hashingresend- Email deliveryzod- Input validationprisma- Database ORM
Risks and Mitigations
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Email delivery fails | Medium | High | Retry queue, fallback provider |
| Password breach | Low | Critical | bcrypt, no plaintext storage |
| Rate limit bypass | Low | Medium | IP-based limiting backup |
## フェーズ 4: TASKS
### タスクへの分割
/speckit-tasks SPEC-001
Claude が実行可能なタスクを作成します:
```markdown
# Implementation Tasks: User Registration
## Task Overview
| ID | Task | Priority | Estimate | Dependencies |
|----|------|----------|----------|--------------|
| T1 | Database migration | High | 30 min | None |
| T2 | Validation schemas | High | 30 min | None |
| T3 | Registration API | High | 1 hour | T1, T2 |
| T4 | Email service | High | 45 min | None |
| T5 | Email integration | High | 30 min | T3, T4 |
| T6 | Registration form | Medium | 1 hour | T3 |
| T7 | Integration tests | High | 1 hour | T3, T5 |
| T8 | E2E tests | Medium | 45 min | T6 |
## Task Details
### T1: Database Migration
**Files:** `prisma/migrations/XXXX_add_users.sql`
**Spec Reference:** SPEC-001 > Database Schema
Create migration for:
- users table
- email_verifications table
Acceptance:
- [ ] Migration runs successfully
- [ ] Rollback works
### T2: Validation Schemas
**Files:** `src/lib/validation/auth.ts`
**Spec Reference:** SPEC-001 > API Design
Create Zod schemas for:
- Email validation
- Password validation (8-128 chars, complexity)
Acceptance:
- [ ] Email schema rejects invalid formats
- [ ] Password schema enforces requirements
### T3: Registration API
**Files:** `src/api/auth/register.ts`
**Spec Reference:** SPEC-001 > API Design
Implement POST /api/auth/register:
- Input validation
- Duplicate email check
- Password hashing
- User creation
- Response formatting
Acceptance:
- [ ] Returns 201 on success
- [ ] Returns 400 on validation error
- [ ] Returns 409 on duplicate email
[Continue for T4-T8...]フェーズ 5: IMPLEMENT
タスクの実行
/speckit-implement SPEC-001Claude がトレーサビリティを持って実装します:
/**
* Registration API Handler
*
* @spec SPEC-001
* @task T3
* @acceptance
* - Returns 201 on success
* - Returns 400 on validation error
* - Returns 409 on duplicate email
*/
export async function registerUser(req: Request, res: Response) {
// Validate input per SPEC-001 > API Design
const validation = RegistrationSchema.safeParse(req.body);
if (!validation.success) {
return res.status(400).json({
error: 'validation_error',
details: validation.error.flatten().fieldErrors
});
}
const { email, password } = validation.data;
// Check for existing user per SPEC-001 > Edge Cases
const existingUser = await db.user.findUnique({
where: { email }
});
if (existingUser) {
return res.status(409).json({
error: 'email_exists',
message: 'An account with this email already exists.'
});
}
// Hash password per Technical Plan > Security
const passwordHash = await bcrypt.hash(password, 12);
// Create user per SPEC-001 > Database Schema
const user = await db.user.create({
data: { email, passwordHash }
});
// Send verification email per SPEC-001 > User Flow
await sendVerificationEmail(user.id, email);
// Return success per SPEC-001 > API Design
return res.status(201).json({
message: 'Registration successful. Please check your email.',
userId: user.id
});
}トレーサビリティコメント
すべての実装が仕様にリンクバックします:
// @spec SPEC-001
// @task T3
// @acceptance Returns 201 on successこれにより以下が可能になります:
- 仕様カバレッジ: どの仕様が実装されているか？
- 変更影響: 仕様が変更されたときにどのコードが変わるか？
- 監査証跡: なぜこのコードが書かれたのか？
フェーズ 6: VALIDATE
検証
/speckit-validate SPEC-001Claude が検証します:
# Validation Report: SPEC-001
## Specification Coverage
| Acceptance Criteria | Status | Evidence |
|---------------------|--------|----------|
| User can register with email and password | ✅ | T3 implementation |
| Email is validated for format | ✅ | T2 schema |
| Password meets security requirements | ✅ | T2 schema |
| Confirmation email is sent | ✅ | T5 integration |
| User cannot register with existing email | ✅ | T3 duplicate check |
## Test Coverage
| Task | Tests | Passing |
|------|-------|---------|
| T3 Registration API | 8 | 8 ✅ |
| T6 Registration Form | 5 | 5 ✅ |
| T7 Integration Tests | 12 | 12 ✅ |
| T8 E2E Tests | 6 | 6 ✅ |
## Constitution Compliance
| Principle | Status |
|-----------|--------|
| Library-First | ✅ Validation in lib/ |
| Test-First | ✅ Tests written before impl |
| Specification Consistency | ✅ All criteria met |
| Simplicity | ✅ No over-engineering |
| Minimal Scope | ✅ Only specified features |
## Documentation Status
- [x] API documentation generated
- [x] Code comments with spec references
- [x] README updated
## Result: ✅ VALIDATED完全なワークフロー例
# Initialize SpecKit
/speckit-init
# Write specification
/speckit-specify Payment Processing Feature
# Clarify ambiguities
/speckit-clarify SPEC-002
# Create technical plan
/speckit-plan SPEC-002
# Break into tasks
/speckit-tasks SPEC-002
# Implement
/speckit-implement SPEC-002
# Validate
/speckit-validate SPEC-002または統合コマンドを使用:
/speckit Payment Processing Featureこれですべてのフェーズがインタラクティブに実行されます。
他のツールとの統合
SpecKit + Memory
# Save decisions to memory
/memory-save
Claude:
→ Saves SPEC-001 decisions to knowledge graph
→ Available in future sessions
→ Searchable for similar featuresSpecKit + GitHub
# Create PR with spec reference
/commit-push-pr
Claude:
→ Creates PR with SPEC-001 reference
→ Links to specification document
→ Includes acceptance criteria checklistベストプラクティス
1. コードを書く前に仕様を書く
Good:
/speckit-specify User Authentication
[Write complete spec]
[Get approval]
[Then implement]
Avoid:
[Start coding]
[Realize requirements unclear]
[Refactor repeatedly]2. 仕様はアトミックに保つ
Good:
- SPEC-001: User Registration
- SPEC-002: User Login
- SPEC-003: Password Reset
Avoid:
- SPEC-001: Complete Authentication System3. すべての曖昧さをマークする
Good:
## [NEEDS CLARIFICATION]
- What happens on third failed login?
- Should we lock the account?
- For how long?
Avoid:
[Assuming you know the answer]
[Making product decisions in code]4. コードで仕様を参照する
/**
* @spec SPEC-001
* @task T3
* @acceptance Returns 201 on success
*/5. マージ前に検証する
/speckit-validate SPEC-001
# Only merge if validatedSpecKit ディレクトリ構造
.speckit/
├── constitution.md # Project principles
├── specifications/
│ ├── SPEC-001-registration.md
│ ├── SPEC-002-login.md
│ └── SPEC-003-password-reset.md
├── plans/
│ ├── PLAN-001-registration.md
│ ├── PLAN-002-login.md
│ └── PLAN-003-password-reset.md
├── tasks/
│ ├── TASKS-001-registration.md
│ ├── TASKS-002-login.md
│ └── TASKS-003-password-reset.md
└── validation/
├── VALID-001-registration.md
└── ...メリット
開発者にとって
- コーディング前の明確な要件
- 手戻りの削減
- より良い見積もり
- 組み込みのドキュメント
チームにとって
- 共有された理解
- 一貫した品質
- 容易なオンボーディング
- 知識の保存
プロジェクトにとって
- 完全なトレーサビリティ
- 監査コンプライアンス
- 変更影響分析
- 生きたドキュメント
はじめ方
今日:
- プロジェクトで
/speckit-initを実行 - 1つの仕様を書く
- 実装まで follow through する
今週:
- 一般的な機能の仕様テンプレートを開発
- レビュープロセスと統合
- チームに SpecKit ワークフローをトレーニング
今月:
- 新機能の完全採用
- 既存機能の遡及的な仕様
- 手戻り削減を測定
SpecKit はソフトウェア構築の方法を変革します—混沌としたイテレーションから意図的な構築へ。書き留め、合意し、仕様通りに正確に構築します。
注: SpecKit は、Claude Code のカスタムスキルシステムを使用して構築されたコミュニティ開発のワークフローパターンです。Anthropic の公式製品ではありません。基盤となる概念は、Task ツール、エージェント、マークダウンベースのスキル定義などの公式 Claude Code 機能を活用しています。
参考資料:
- Claude Code 公式ドキュメント - 公式 Claude Code 機能
- Claude Code スキルシステム - カスタムスキルの作成方法
- コミュニティプロジェクト: Claude Bootstrap Kit