はじめに
AI駆動開発とは ≒ 仕様駆動開発だと考えています。
AIによって開発を爆速化するために、仕様駆動開発（Specification-Driven Development） の仕組みを Claude Code のカスタムコマンドとして実装しました。本記事では、その実装内容を紹介します。
この記事のゴール
この記事を読むことで、以下が実現できます：
- Claude Code のカスタムコマンド機能を理解し、自社リポジトリに適用できる
- 仕様駆動開発の仕組みを具体的なコード例で理解できる
- 設計書テンプレートと実装フローをそのまま使える
概要（TL;DR）
- Claude Code のカスタムコマンドで仕様駆動開発システムを実装
- 対話形式で設計書を生成し、AIとの協働を最適化
- 設計時間を大幅に短縮（30分 → 5分）
- Next.js/React 向けに最適化された Phase 別実装フロー
- 全コード例・テンプレート掲載 - すぐに使える
背景
AI開発時代の仕様駆動開発ツールとしていくつか利用しました。
Kiro
- AI向けの仕様書生成・管理ツール
- 高機能だが、金額的に高コスト
- 小規模プロジェクトには導入ハードルが高い
SpecKit
- オープンソースの仕様駆動開発ツール
- 手軽に詳細な設計書が作成される
- 設計書作成に時間がかかる印象
0→1案件であればむしろSpecKitの方が適していると思いますが以下を実現するために独自実装を行いました。
- よりスピーディーな設計書作成: 対話形式で5分で完成
- リポジトリへの最適化: Next.js/React の規約に特化
- 運用しやすさ: カレント設計書管理、進捗追跡の自動化
全体のディレクトリ構造
まず、完成形の全体像を示します：
プロジェクトルート/
├── .claude/
│ ├── commands/ # カスタムコマンド定義
│ │ ├── design-docs:plan.md # 対話形式設計書生成
│ │ ├── design-docs:quick.md # クイック設計
│ │ ├── design-docs:start.md # 実装開始
│ │ ├── design-docs:track.md # 進捗管理
│ │ └── design-docs:switch.md # 設計書切り替え
│ └── .current-design-doc # カレント設計書パス
│
├── docs/
│ └── design_docs/
│ ├── README.md # システム説明書
│ ├── templates/ # 設計書テンプレート
│ │ ├── requirements_template.md
│ │ ├── design_template.md
│ │ └── tasks_template.md
│ └── YYYYMMDD-feature-name/ # 個別設計書（自動生成）
│ ├── requirements.md
│ ├── design.md
│ └── tasks.md
│
└── src/ # 実装コード
├── app/
├── components/
└── lib/
この構造により、設計書とコードが同じリポジトリで一元管理されます。
システムの特徴
5つのスラッシュコマンド
# 設計書作成
/design-docs:plan # 対話形式で詳細設計（推奨）
/design-docs:quick # 2分でクイック設計
# 実装・進捗管理
/design-docs:start # 設計書から実装開始
/design-docs:track # タスク進捗管理
/design-docs:switch # 設計書の切り替え
カレント設計書管理
-
.claude/.current-design-docで作業中の設計書を自動管理 -
/design-docs:startと/design-docs:trackは引数不要 - 設計書は
docs/design_docs/に保存
開発フロー
1. /design-docs:plan
↓
2. 設計書生成（requirements.md / design.md / tasks.md）
↓
3. .claude/.current-design-doc に保存（自動で更新）
↓
4. /design-docs:start（実装プロンプト生成）
↓
5. 実装作業(AI)
↓
6. /design-docs:track（進捗管理）
↓
7. 完了？
No → 5. に戻る
Yes → リリース
使用方法
パターン1: 詳細設計（推奨）
大規模機能や複数人での協働開発に最適
# ステップ1: 設計書作成
/design-docs:plan
# 対話形式で以下を入力:
# - What（何を作るか）
# - Why（なぜ必要か）
# - 機能要件
# - 非機能要件
# - 成功基準
# - アーキテクチャレイヤー
# - APIエンドポイント
# - ページ/コンポーネント構成
# - 権限制御
# ステップ2: 実装開始
/design-docs:start
# ステップ3: 進捗管理
/design-docs:track
生成される設計書:
docs/design_docs/YYYYMMDD-feature-name/
├── requirements.md # 要件定義
├── design.md # 詳細設計
└── tasks.md # タスク管理
所要時間: 約5分（質問に答えるだけ）
パターン2: クイック設計
小規模機能や緊急対応に最適
# ステップ1: クイック設計（2分）
/design-docs:quick
# 以下を一括入力:
# - Plan（一行要約）
# - What（概要）
# - Why（理由）
# - How（実装方法）
# - Tests（テスト）
# ステップ2: 実装開始
/design-docs:start
# ステップ3: 実装完了後、コミット更新
git add .
git commit --amend -m "feat: [機能名]
[実装結果のサマリー]
"
記録形式: gitの空コミットとして記録
Next.js特化のPhase設計
Phase 1: Types & Interfaces // TypeScript型定義
Phase 2: API Service Layer // API呼び出しロジック
Phase 3: Custom Hooks // カスタムフック（必要時）
Phase 4: UI Components // UIコンポーネント
Phase 5: Permission Control // 権限制御（必須）
Phase 6: Testing // テスト実装
Phase 7: Documentation & Review // ドキュメント・レビュー
この順序により、依存関係が明確化され、手戻りが最小化されます。
テンプレート実装
requirements_template.md
# Requirements: [Feature Name]
**Status**: Draft
**Created**: YYYY-MM-DD
**Developer**: [Developer Name]
## What（何を作るか）
[実装する機能の概要を3-5行で記述]
## Why（なぜ必要か）
[現在の問題点や背景を1-3行で記述]
## Requirements（要件）
### Functional Requirements（機能要件）
- [ ] [要件1]
- [ ] [要件2]
- [ ] [要件3]
### Non-Functional Requirements（非機能要件）
- [ ] レスポンス時間: [目標値]
- [ ] テストカバレッジ: [目標値]
- [ ] アクセシビリティ: WCAG 2.1 Level AA準拠
## Success Criteria（成功基準）
- [ ] [基準1]
- [ ] [基準2]
- [ ] [基準3]
- [ ] すべてのテストが通過する
- [ ] コードレビューで承認される
design_template.md
# Design: [Feature Name]
**Status**: Draft
**Created**: YYYY-MM-DD
**Developer**: [Developer Name]
## Architecture（アーキテクチャ）
どのレイヤーを変更するか:
UI Layer (Components) → Logic Layer (Hooks/Utils) → API Layer (Services) → Type Layer (Interfaces)
[ ] Components [ ] Hooks/Utils [ ] API Services [ ] Types/Interfaces
## Implementation（実装詳細）
### 1. Type Layer（必要な場合）
**Interface Definition**:
\`\`\`typescript
export interface [FeatureName] {
id: number;
// フィールド定義
}
export interface [FeatureName]FormData {
// フォームデータ定義
}
\`\`\`
### 2. API Service Layer
**Service Interface**:
\`\`\`typescript
class [FeatureName]Service {
async get[FeatureName]s(params: [FeatureName]ListParams): Promise<PaginatedResponse<[FeatureName]>> {
// API呼び出し
}
}
\`\`\`
### 3. Custom Hooks（必要な場合）
**Custom Hooks**:
\`\`\`typescript
export function use[FeatureName]List() {
// リスト取得ロジック
}
\`\`\`
### 4. Component Layer
**Page Component**:
\`\`\`typescript
// src/app/[route]/page.tsx
export default function [FeatureName]Page() {
// ページコンポーネント実装
}
\`\`\`
## Permission Control（必須）
### Permission Constants
\`\`\`typescript
// src/lib/permissions.ts
export const PERMISSIONS = {
[FEATURE]: {
VIEW: 'admin:[feature]:view',
CREATE: 'admin:[feature]:create',
EDIT: 'admin:[feature]:edit',
DELETE: 'admin:[feature]:delete',
},
}
\`\`\`
### Implementation Points
- [ ] PermissionGuard on page level
- [ ] hasPermission() checks for UI elements
- [ ] Sidebar menu with requiredPermissions
- [ ] Permission-based button visibility
## API Specification
### Endpoint
\`\`\`
GET /api/v7/admin/[resource]
Query Parameters:
- page: number (optional)
- per_page: number (optional)
- search: string (optional)
Response 200:
{
"data": [...],
"meta": {
"current_page": 1,
"last_page": 10,
"per_page": 20,
"total": 200
}
}
\`\`\`
## Testing Strategy
### Unit Tests
- [ ] API Service: モック応答でのCRUD操作テスト
- [ ] Custom Hooks: データ取得・更新ロジックテスト
- [ ] UI Components: レンダリング・ユーザーイベントテスト
### Test Coverage Target
- **Overall**: 85%以上
- **Critical paths**: 100%
## Error Handling
### Validation Errors
- Field-level error display with `<ValidationError />` component
- Clear errors on user interaction
- Never use toast for validation errors
## Performance Considerations
- **Target**: Initial page load < 2s
- **API Response**: < 500ms (p95)
- **Image Optimization**: Use Next.js Image component
tasks_template.md
# Tasks: [Feature Name]
**Status**: Not Started
**Created**: YYYY-MM-DD
**Progress**: 0/X tasks completed
## Task Breakdown
### Phase 1: Types & Interfaces
- [ ] Define TypeScript interfaces in \`src/lib/types.ts\`
- [ ] Define API request/response types
- [ ] Define form data types
### Phase 2: API Service Layer
- [ ] Create service class in \`src/lib/[feature]-service.ts\`
- [ ] Implement GET list endpoint
- [ ] Implement GET detail endpoint
- [ ] Implement POST create endpoint
- [ ] Implement PUT/PATCH update endpoint
- [ ] Implement DELETE endpoint
- [ ] Add error handling
### Phase 3: Custom Hooks（必要な場合）
- [ ] Create custom hooks in \`src/hooks/use[Feature].ts\`
- [ ] Implement data fetching logic
- [ ] Implement form management logic
- [ ] Add loading/error states
### Phase 4: UI Components
- [ ] Create page component \`src/app/[route]/page.tsx\`
- [ ] Implement list view with DataTable
- [ ] Implement search and filter
- [ ] Implement pagination
- [ ] Create form components
- [ ] Add validation error display
- [ ] Implement modals (if needed)
### Phase 5: Permission Control（必須）
- [ ] Add permission constants to \`src/lib/permissions.ts\`
- [ ] Add sidebar menu item with permissions
- [ ] Implement PermissionGuard on page
- [ ] Add permission checks for UI elements
- [ ] Test with different permission levels
### Phase 6: Testing
- [ ] Write API service tests
- [ ] Write custom hooks tests (if applicable)
- [ ] Write component tests
- [ ] Write permission tests
- [ ] Achieve 85%+ test coverage
- [ ] Run feature-specific tests: \`npm test -- [feature-name]\`
### Phase 7: Documentation & Review
- [ ] Update CLAUDE.md if new patterns introduced
- [ ] Update docs/sitemap.md
- [ ] Code review and cleanup
- [ ] Verify responsive design (1200px minimum)
- [ ] Verify dark mode support
## Progress Tracking
**Overall**: 0% (0/X tasks)
- Phase 1 (Types & Interfaces): 0% (0/X)
- Phase 2 (API Service): 0% (0/X)
- Phase 3 (Custom Hooks): 0% (0/X)
- Phase 4 (UI Components): 0% (0/X)
- Phase 5 (Permission Control): 0% (0/X)
- Phase 6 (Testing): 0% (0/X)
- Phase 7 (Documentation): 0% (0/X)
## Development Log
### Session 1: YYYY-MM-DD HH:MM-HH:MM
**Goal**: Phase 1の実装（Types & Interfaces）
**AI Tool**: Claude Code
**Tasks Completed**:
- [ ] TypeScript interfaces定義
**Next Session**:
- [ ] API Service実装
---
## Blockers
### Active Blockers
None currently
### Resolved Blockers
（なし）
## Notes
### Key Decisions
[設計の重要な決定事項]
### Lessons Learned
（実装後に記録）
### AI Time Savings
[AIによって節約できた時間の記録]
コマンド実装
長いので design-docs:plan.md だけopen。あとはcloseにしてあるので気になるかたはクリックしてマークダウンの詳細をご確認ください。
design-docs:plan.md
.claude/commands/design-docs:plan.md
# AI駆動開発: 対話形式設計書生成 (Next.js Frontend)
あなたはAI駆動開発アシスタントです。ユーザーと対話しながらNext.js/React機能の設計書を生成します。
## ステップ1: 基本情報の収集（1つずつ質問）
### ステップ1-1: What（何を作るか）
**メッセージ表示**:
\`\`\`
AI駆動開発アシスタントです。対話形式で設計書を作成します。
まず、実装する機能について教えてください：
**What（何を作るか）**（3-5行）:
実装する機能の概要を説明してください
例:
- ユーザー管理ページの作成
- 記事一覧ページのフィルター機能追加
- お知らせモーダルコンポーネントの実装
\`\`\`
ユーザーの回答を待ち、回答内容を変数に格納します。
---
### ステップ1-2: Why（なぜ必要か）
**メッセージ表示**:
\`\`\`
ありがとうございます。次に背景を教えてください：
**Why（なぜ必要か）**（1-3行）:
現在の問題点や背景を説明してください
例:
- 管理画面リニューアルプロジェクトの一環
- ユーザビリティ改善のため
- 新規要件対応
\`\`\`
ユーザーの回答を待ち、回答内容を格納します。
---
### ステップ1-3: 機能名の自動生成
**機能名は「What」の内容から自動生成します。ユーザーに質問しません。**
**自動生成ロジック**:
1. Whatの内容から主要なキーワードを抽出
2. 英語キーワードのみを使用（日本語は無視）
3. ケバブケース形式に変換（URLフレンドリー）
4. 最大3単語まで（長すぎる場合は短縮）
**生成例**:
- "ユーザー管理ページの作成" → \`user-management\`
- "記事一覧ページのフィルター機能追加" → \`article-list-filter\`
- "お知らせモーダルコンポーネントの実装" → \`announcement-modal\`
**重複チェック**:
\`docs/design_docs/\` ディレクトリ内の既存ディレクトリと被らないように、必要に応じて \`-v2\`, \`-v3\` などのサフィックスを追加。
**確認メッセージ**:
生成した機能名をユーザーに表示して確認:
\`\`\`
機能名を自動生成しました: \`{feature_name}\`
この名前で問題なければ「はい」、変更したい場合は新しい機能名を入力してください:
\`\`\`
ユーザーが「はい」「ok」「問題ない」などと回答した場合は生成した名前を使用。
別の名前を入力した場合はその名前を使用（英数字とハイフンのみ検証）。
## ステップ2: 要件の収集（1つずつ質問）
### ステップ2-1: 機能要件
**メッセージ表示**:
\`\`\`
次に要件を教えてください。
**機能要件**（3-5個リストアップ）:
実装する機能の具体的な要件をリストアップしてください
例:
- 一覧ページに検索・フィルター機能を実装
- ページネーション対応（20件/ページ）
- CRUD操作の権限制御
または:
- モーダルでのプレビュー表示
- フォームバリデーション
- ダークモード対応
\`\`\`
ユーザーの回答を待ち、回答内容を変数に格納します。
---
### ステップ2-2: 非機能要件
**メッセージ表示**:
\`\`\`
**非機能要件**（2-3個）:
パフォーマンス、品質などの非機能要件を教えてください
例:
- 初期表示: 2秒以内
- テストカバレッジ: 85%以上
- レスポンシブ対応（最小1200px）
※「任せる」と回答された場合は、適切な非機能要件を自動生成します
\`\`\`
ユーザーの回答を待ち、回答内容を格納します。
「任せる」や「おまかせ」と回答された場合は、機能に応じた適切な内容を自動生成します。
---
### ステップ2-3: 成功基準
**メッセージ表示**:
\`\`\`
**成功基準**（3-4個）:
実装完了の判断基準を教えてください
例:
- 全機能が正常に動作する
- テストがすべて通過する（85%以上のカバレッジ）
- デザインシステムに準拠している
※「任せる」と回答された場合は、適切な成功基準を自動生成します
\`\`\`
ユーザーの回答を待ち、回答内容を格納します。
「任せる」や「おまかせ」と回答された場合は、機能に応じた適切な内容を自動生成します。
## ステップ3: 設計情報の収集（1つずつ質問）
ユーザーに1つずつ順番に質問します。各質問の後、ユーザーの回答を待ちます。
### ステップ3-1: アーキテクチャレイヤー
**メッセージ表示**:
\`\`\`
設計の詳細を教えてください。
1. **アーキテクチャレイヤー**: どの層を変更しますか？
- Components / Hooks / API Services / Types（複数可）
- 「任せる」でも可（適切な層を自動判断）
\`\`\`
ユーザーの回答を待ち、回答内容を格納します。
「任せる」の場合は機能要件から適切な層を自動判断します。
---
### ステップ3-2: APIエンドポイント
**メッセージ表示**:
\`\`\`
2. **APIエンドポイント**: 必要ですか？
必要な場合:
- Method: GET/POST/PUT/DELETE
- Path: /api/v7/admin/xxx
- Query/Path parameters
- Request/Response形式
不要な場合: 「なし」「不要」と入力
任せる場合: 「任せる」と入力
\`\`\`
ユーザーの回答を待ち、回答内容を格納します。
「任せる」の場合は機能要件から適切なAPIを自動設計します。
「なし」「不要」の場合はAPIエンドポイントなしとして処理します。
---
### ステップ3-3: ページ/コンポーネント構成
**メッセージ表示**:
\`\`\`
3. **ページ/コンポーネント構成**: どのような構成にしますか？
例:
- ページ: src/app/[route]/page.tsx
- コンポーネント: src/components/[feature]/[Component].tsx
- フォーム: src/components/[feature]/[Feature]Form.tsx
「任せる」と入力で自動判断
\`\`\`
ユーザーの回答を待ち、回答内容を格納します。
「任せる」の場合は機能要件から適切な構成を自動生成します。
---
### ステップ3-4: 権限制御
**メッセージ表示**:
\`\`\`
4. **権限制御**: 必要ですか？（必須確認）
必要な場合:
- VIEW / CREATE / EDIT / DELETE のどれが必要か
- 権限コード: admin:[feature]:view など
CLAUDE.mdの規定により、新しいページ/機能には権限制御が必須です。
「任せる」と入力で標準的な権限を自動生成します。
\`\`\`
ユーザーの回答を待ち、回答内容を格納します。
「任せる」の場合は標準的な権限セット（VIEW/CREATE/EDIT/DELETE）を自動生成します。
---
### ステップ3-5: その他の実装詳細（任意）
**メッセージ表示**:
\`\`\`
5. **その他の実装詳細**（任意）:
- 特記事項があれば記述
- なければ「なし」と入力
\`\`\`
ユーザーの回答を待ち、回答内容を格納します。
特記事項がない場合はスキップします。
---
全ての回答を収集後、ステップ4に進みます。
## ステップ4: requirements.md 生成
\`docs/design_docs/templates/requirements_template.md\` に準拠して生成:
今日の日付を \`date +%Y%m%d\` で取得し、\`YYYYMMDD-[feature-name]\` 形式でディレクトリを作成。
requirements.mdの内容:
\`\`\`markdown
# Requirements: [Feature Name]
**Status**: Draft
**Created**: [今日の日付 YYYY-MM-DD]
**Developer**: [Git user.name を git config user.name で取得]
## What（何を作るか）
[ステップ1で収集した内容]
## Why（なぜ必要か）
[ステップ1で収集した内容]
## Requirements（要件）
### Functional Requirements（機能要件）
[ステップ2で収集した内容をチェックボックス形式で]
- [ ] [要件1]
- [ ] [要件2]
### Non-Functional Requirements（非機能要件）
[ステップ2で収集した内容]
- [ ] [要件1]
- [ ] [要件2]
## Success Criteria（成功基準）
[ステップ2で収集した内容]
- [ ] [基準1]
- [ ] [基準2]
\`\`\`
## ステップ5: design.md 生成
\`docs/design_docs/templates/design_template.md\` に準拠して生成:
design.mdの内容を、ステップ3で収集した情報に基づいて自動生成します。
## ステップ6: tasks.md 生成
\`docs/design_docs/templates/tasks_template.md\` に準拠して生成:
tasks.mdの内容を、ステップ3で収集した情報に基づいてタスク化します。
**タスク順序（CRITICAL - Next.js特化）**:
1. Phase 1: Types & Interfaces
2. Phase 2: API Service Layer
3. Phase 3: Custom Hooks（必要な場合）
4. Phase 4: UI Components
5. Phase 5: Permission Control（必須）
6. Phase 6: Testing
7. Phase 7: Documentation & Review
## ステップ7: ディレクトリ作成と確認
1. ディレクトリ作成: \`docs/design_docs/YYYYMMDD-feature-name/\`
2. 3ファイルを書き込み（Write toolを使用）
3. 生成された設計書のパスを表示
## ステップ8: カレント設計書として保存
1. \`.claude/.current-design-doc\` ファイルに設計書パスを保存:
\`\`\`
docs/design_docs/YYYYMMDD-feature-name/
\`\`\`
2. \`.claude/\` ディレクトリが存在しない場合は作成
3. Write toolを使用してファイルに書き込み
## ステップ9: 次のアクション提案
生成した設計書のパスを表示し、次のアクションを提案:
\`\`\`
設計書を生成しました！
docs/design_docs/YYYYMMDD-feature-name/
├── requirements.md
├── design.md
└── tasks.md
カレント設計書として保存しました
(.claude/.current-design-doc)
次のステップ:
- \`/design-docs:start\` で実装開始（引数不要）
- \`/design-docs:track\` でタスク管理（引数不要）
- \`/design-docs:switch\` で別の設計書に切り替え
または、直接実装を開始する場合:
「設計書に従って実装してください」
\`\`\`
## 重要な注意事項
1. **テンプレート準拠**: 必ず \`docs/design_docs/templates/\` の構造に従う
2. **タスク順序（CRITICAL）**: tasks.mdは必ず上記の順序で生成すること
3. **権限制御必須**: CLAUDE.mdの規定により、新機能には必ず権限制御を実装
4. **対話の効率化**: 小規模機能の場合は質問数を減らす
5. **エラーハンドリング**: ディレクトリ重複チェック、不正な機能名の検証
6. **日付取得**: \`date +%Y%m%d\` コマンドで今日の日付を取得
7. **Git user name**: \`git config user.name\` でユーザー名を取得
8. **ケバブケース**: ディレクトリ名とファイル名はケバブケース（例: \`user-management\`）
design-docs:quick.md
.claude/commands/design-docs:quick.md
# AI駆動開発: クイック設計（gitコミット方式）
2分で設計書を作成し、即座に実装を開始するための簡易設計コマンドです。
gitコミットメッセージ形式で設計を記録します。
## 使用シーン
- 小規模な機能追加・修正
- 緊急のバグ修正
- 実験的な機能実装
- プロトタイピング
## ステップ1: 設計情報の収集（一括質問）
AskUserQuestion toolで以下を一度に質問:
\`\`\`
クイック設計を作成します。以下の情報を教えてください：
1. **Plan（一行要約）**: 実装する機能を一行で
例: "記事一覧ページにソート機能を追加"
2. **What（何を作るか）**: 2-3行で概要説明
例: "記事一覧ページにソート機能を追加する。タイトル、作成日、更新日でソート可能にする。"
3. **Why（なぜ必要か）**: 1-2行で理由説明
例: "ユーザーが記事を見つけやすくするため"
4. **How（実装方法）**: 箇条書きで3-5個
例:
- ソート用のstateを追加
- ソートボタンUIを実装
- API呼び出し時にソートパラメータを追加
5. **Tests（テスト）**: 箇条書きで2-3個
例:
- ソートボタンクリックでAPIが正しいパラメータで呼ばれる
- ソート状態がUIに反映される
\`\`\`
## ステップ2: gitコミットメッセージ形式で設計書を生成
収集した情報をgitコミットメッセージ形式に変換:
\`\`\`
feat: [Plan]
What:
[What内容]
Why:
[Why内容]
How:
- [How 項目1]
- [How 項目2]
- [How 項目3]
Tests:
- [ ] [Test 項目1]
- [ ] [Test 項目2]
- [ ] [Test 項目3]
\`\`\`
## ステップ3: 空コミットとして記録
Bash toolを使用してgit空コミットを作成:
\`\`\`bash
git commit --allow-empty -m "設計書メッセージ内容"
\`\`\`
コミットハッシュを取得:
\`\`\`bash
git rev-parse HEAD
\`\`\`
## ステップ4: カレント設計書として保存
\`.claude/.current-design-doc\` ファイルに以下形式で保存:
\`\`\`
git:[commit-hash]
\`\`\`
## ステップ5: 確認メッセージと次のアクション
\`\`\`
クイック設計を作成しました！
git:[hash]
設計内容:
[Plan]
次のステップ:
- \`/design-docs:start\` で実装開始（引数不要）
- 実装完了後は以下のコマンドでコミット:
git add .
git commit --amend -m "feat: [Plan]
[実装結果のサマリー]
What:
[What内容]
Why:
[Why内容]
How:
- [完了した実装項目]
Tests:
- [x] [完了したテスト]"
または、直接実装を開始する場合:
「設計書に従って実装してください」
\`\`\`
## クイック設計の制限事項
1. **タスク管理なし**: \`/design-docs:track\` は使用不可
2. **詳細設計なし**: アーキテクチャ詳細やAPI仕様は記録されない
3. **進捗追跡なし**: Phase別の進捗管理は不可
4. **小規模限定**: 大規模機能の場合は \`/design-docs:plan\` を推奨
## 通常設計への変換（オプション）
クイック設計で開始したが、詳細な管理が必要になった場合:
\`\`\`
このクイック設計を通常の3ファイル設計に変換しますか？
変換すると:
- requirements.md / design.md / tasks.md を生成
- タスク管理と進捗追跡が可能になる
- \`/design-docs:track\` が使用可能になる
\`\`\`
ユーザーが「はい」と回答した場合:
1. gitコミットメッセージから情報を抽出
2. \`/design-docs:plan\` の簡易版を実行
3. 3ファイルを生成してカレント設計書を更新
## 重要な注意事項
1. **空コミット**: 実装前に設計のみをコミットするため \`--allow-empty\` 必須
2. **コミットハッシュ**: 短縮ハッシュではなく完全ハッシュを保存
3. **amend推奨**: 実装完了後は \`--amend\` でコミットメッセージを更新
4. **テストチェックリスト**: 実装完了時にチェックボックスを埋める
5. **小規模機能向け**: 大規模機能は \`/design-docs:plan\` を使用すべき
6. **権限制御**: 新ページの場合でも権限制御実装を忘れない
design-docs:start.md
.claude/commands/design-docs:start.md
# AI駆動開発: 実装指示生成 (Next.js Frontend)
設計書から実装プロンプトを自動生成し、AIに実装指示を出します。
## ステップ1: カレント設計書の読み込み
\`.claude/.current-design-doc\` ファイルを確認（Read tool使用）:
1. **ファイルが存在しない場合**: エラーメッセージを表示して終了
\`\`\`
カレント設計書が設定されていません
以下のいずれかを実行してください:
- \`/design-docs:plan\` で新規設計書を作成
- \`/design-docs:quick\` でクイック設計を作成
- \`/design-docs:switch\` で既存の設計書を選択
\`\`\`
2. **gitコミット方式の場合** (\`git:[hash]\` 形式):
- \`git show [hash]\` でコミットメッセージを読み込み（Bash tool使用）
- Plan/What/Why/How/Tests を抽出
- 簡易的な実装プロンプトを生成（ステップ4-簡易版へ）
3. **3ファイル方式の場合** (ディレクトリパス):
- 指定されたディレクトリから3ファイルを読み込み（ステップ2へ）
## ステップ2: 設計書の読み込み（3ファイル方式）
カレント設計書ディレクトリから以下を読み込み（Read tool使用）:
1. \`requirements.md\` - 機能要件と成功基準
2. \`design.md\` - アーキテクチャと実装詳細
3. \`tasks.md\` - タスク一覧と進捗
ファイルが存在しない場合はエラーメッセージを表示して終了:
\`\`\`
エラー: 設計書ファイルが見つかりません
[ディレクトリパス] に以下のファイルが必要です:
- requirements.md
- design.md
- tasks.md
\`\`\`
## ステップ3: コンテキスト抽出
各ファイルから必要な情報を抽出:
**requirements.mdから:**
- What（何を作るか）
- Why（なぜ必要か）
- Functional Requirements（機能要件）
- Non-Functional Requirements（非機能要件）
- Success Criteria（成功基準）
**design.mdから:**
- Architecture（どの層を変更するか）
- Implementation詳細（各層の型定義・インターフェース）
- API Specification（エンドポイント仕様）
- Permission Control（権限制御）
- UI/UX Design（デザイン要件）
- Testing Strategy（テスト戦略）
- Error Handling（エラーハンドリング）
- Performance Considerations（パフォーマンス要件）
**tasks.mdから:**
- Task Breakdown（Phase別タスク一覧）
- 現在の進捗状況
## ステップ4: 実装プロンプト生成
抽出した情報をもとに、Next.js/Reactアーキテクチャに準拠した実装指示を生成:
\`\`\`
以下の設計書に従って実装してください。
# 機能概要
## What（何を作るか）
[requirements.mdのWhatセクション]
## Why（なぜ必要か）
[requirements.mdのWhyセクション]
# アーキテクチャ
[design.mdのArchitectureセクションを引用]
実装する層:
[✓がついている層をリストアップ]
# 実装タスク（Phase別）
[tasks.mdのTask Breakdownを引用し、優先順位順に整理]
## Phase 1: Types & Interfaces
[Type層のタスクをリストアップ]
実装ファイル: \`src/lib/types.ts\`
[design.mdのInterface定義を含める]
## Phase 2: API Service Layer
[API Service層のタスクをリストアップ]
実装ファイル: \`src/lib/[feature]-service.ts\`
[design.mdのService Interface定義を含める]
## Phase 3: Custom Hooks
[Hook層のタスクをリストアップ - 必要な場合]
実装ファイル: \`src/hooks/use[Feature].ts\`
## Phase 4: UI Components
[Component層のタスクをリストアップ]
実装ファイル:
- Page: \`src/app/[route]/page.tsx\`
- Components: \`src/components/[feature]/\`
デザインシステム準拠:
- CLAUDE.mdの「標準UIパターン」に従う
- AuthGuard + NavigationSection + PageHeader レイアウト
- 検索・フィルター・テーブル・ページネーション
- ValidationError表示（フォームの場合）
- ダークモード対応
## Phase 5: Permission Control（必須）
[権限制御のタスクをリストアップ]
実装ステップ:
1. \`src/lib/permissions.ts\` に権限定数追加
2. \`src/components/ui/Sidebar.tsx\` にメニュー項目追加
3. ページに \`PermissionGuard\` 実装
4. UI要素に権限チェック実装
5. 権限別テスト実装
## Phase 6: Testing
[テストのタスクをリストアップ]
テスト実装:
- API Service tests: \`src/lib/__tests__/[feature]-service.test.ts\`
- Component tests: \`src/app/[route]/__tests__/page.test.tsx\`
- Permission tests: 異なる権限レベルでのテスト
実行コマンド: \`npm test -- [feature-name]\`
## Phase 7: Documentation & Review
[ドキュメント・レビューのタスクをリストアップ]
# API仕様
[design.mdのAPI Specificationセクションを完全引用]
# 権限制御
[design.mdのPermission Controlセクションを引用]
実装必須項目:
- 権限定数定義
- Sidebarメニュー権限
- ページレベルガード
- UI要素の権限制御
- 権限テスト
# UI/UX要件
[design.mdのUI/UX Designセクションを引用]
CLAUDE.md準拠:
- カラーパレット統一
- タイポグラフィ統一
- レスポンシブ対応（最小1200px）
- ダークモード完全対応
# テスト戦略
[design.mdのTesting Strategyセクションを引用]
## テストケース
- Unit tests: [具体的なテストケース]
- Integration tests: [具体的なシナリオ]
- Permission tests: [権限別シナリオ]
カバレッジ目標: 85%以上
# エラーハンドリング
[design.mdのError Handlingセクションを引用]
重要: バリデーションエラーは必ずフィールド下に表示（toast禁止）
# 成功基準
[requirements.mdのSuccess Criteriaを引用]
# 制約事項
- Next.js 14 App Router準拠
- CLAUDE.mdのコーディング規約に従う
- テストカバレッジ85%以上
- パフォーマンス要件: [design.mdから抽出]
- 権限制御必須実装
- レスポンシブ対応（最小1200px）
- ダークモード完全対応
# 実装の進め方
1. TodoWrite toolを使用してタスク管理開始
2. Phase順に実装（Types → API → Hooks → Components → Permissions → Testing）
3. 各Phase完了後、TodoWriteでタスクをcompletedに更新
4. 実装完了後、\`npm test -- [feature-name]\` を実行
5. \`/design-docs:track\` で進捗を記録
それでは実装を開始してください。
\`\`\`
**gitコミット方式の簡易版プロンプト:**
\`\`\`
以下の設計に従って実装してください。
# 機能: [Plan]
## What（何を作るか）
[What]
## Why（なぜ必要か）
[Why]
## 実装方法（How）
[Howの箇条書き]
## テストケース
[Testsのチェックリスト]
# 制約事項
- Next.js 14 App Router準拠
- CLAUDE.mdのコーディング規約に従う
- テストカバレッジ85%以上
- 権限制御必須実装（新ページの場合）
それでは実装を開始してください。
\`\`\`
## ステップ5: 実装開始確認
生成したプロンプトを表示し、実装を開始:
**3ファイル方式の場合:**
\`\`\`
設計書を読み込みました！
[設計書ディレクトリパス]
├── requirements.md ✓
├── design.md ✓
└── tasks.md ✓
実装プロンプトを生成しました。
上記の指示に従って実装を開始します。
進捗管理:
- TodoWrite toolでタスクを管理します
- 実装完了後は \`/design-docs:track\` で進捗を記録してください
\`\`\`
**gitコミット方式の場合:**
\`\`\`
設計コミットを読み込みました！
git:[hash]
実装プロンプトを生成しました。
上記の指示に従って実装を開始します。
実装完了後:
git add .
git commit --amend -m "feat: [機能名]
[実装結果のサマリー]
"
\`\`\`
その後、ステップ4で生成したプロンプトに従って実装を開始。
## 重要な注意事項
1. **設計書の完全性**: 3ファイルすべてが存在することを確認
2. **TodoWrite tool連携**: 実装中のタスク管理を自動化
3. **CLAUDE.md準拠**: 必ず既存のデザインシステムに従う
4. **権限制御必須**: 新しいページ/機能には必ず権限制御を実装
5. **テスト駆動**: テストを書いてから実装
6. **進捗記録**: 各Phase完了後に \`/design-docs:track\` で記録
7. **gitコミット方式対応**: \`git:\` プレフィックスで判別し、git show コマンドで読み込み
8. **フィーチャー特化テスト**: \`npm test -- [feature-name]\` で特定機能のみテスト実行
design-docs:track.md
.claude/commands/design-docs:track.md
# AI駆動開発: タスク進捗管理 (Next.js Frontend)
設計書のタスク管理と進捗追跡をアシストします。
\`docs/design_docs/templates/tasks_template.md\` に準拠して更新します。
## ステップ1: カレント設計書の確認
\`.claude/.current-design-doc\` ファイルを確認（Read tool使用）:
1. **ファイルが存在しない場合**: エラーメッセージを表示して終了
\`\`\`
カレント設計書が設定されていません
以下のいずれかを実行してください:
- \`/design-docs:plan\` で新規設計書を作成
- \`/design-docs:quick\` でクイック設計を作成
- \`/design-docs:switch\` で既存の設計書を選択
\`\`\`
2. **gitコミット方式の場合** (\`git:[hash]\` 形式):
- エラーメッセージを表示して終了
\`\`\`
gitコミット方式ではタスク管理は使用できません
タスク管理が必要な場合:
- \`/design-docs:plan\` で3ファイル形式の設計書を作成してください
\`\`\`
3. **3ファイル方式の場合** (ディレクトリパス):
- 指定されたディレクトリから \`tasks.md\` を読み込み（ステップ2へ）
## ステップ2: tasks.mdの読み込み
カレント設計書ディレクトリから \`tasks.md\` を読み込む（Read tool使用）。
ファイルが存在しない場合はエラーメッセージを表示して終了:
\`\`\`
エラー: tasks.md が見つかりません
[ディレクトリパス]/tasks.md が必要です。
\`\`\`
## ステップ3: 現在の進捗分析
tasks.mdの内容を解析して表示:
1. **チェックボックスをカウント**:
- \`- [ ]\` = 未完了
- \`- [x]\` = 完了
2. **Phase別に集計**:
- 各Phaseのタスク数と完了数
3. **進捗表示**:
\`\`\`
進捗状況
全体: X% (Y/Z tasks completed)
Phase別:
- Phase 1: Types & Interfaces - X% (Y/Z)
- Phase 2: API Service - X% (Y/Z)
- Phase 3: Custom Hooks - X% (Y/Z)
- Phase 4: UI Components - X% (Y/Z)
- Phase 5: Permission Control - X% (Y/Z)
- Phase 6: Testing - X% (Y/Z)
- Phase 7: Documentation - X% (Y/Z)
未完了タスク:
1. [ ] [Phase名] [タスク内容]
2. [ ] [Phase名] [タスク内容]
...
現在進行中:
（進行中タスクがあれば表示）
\`\`\`
## ステップ4: アクション選択
AskUserQuestion toolで以下を質問:
1. **実行するアクション**:
- 「タスクを開始する」
- 「タスクを完了にする」
- 「新しいタスクを追加する」
- 「開発ログを記録する」
- 「進捗確認のみ（更新なし）」
**選択に応じた処理:**
### アクション1: タスクを開始する
1. 未完了タスクリストを表示
2. AskUserQuestion toolで開始するタスクを選択
3. Edit toolを使用して tasks.mdの該当タスクを \`- [x]\` に更新（進行中マーク）
4. 「次にやるべきこと」を提案:
- 関連する実装ファイルのパス
- 実装すべき内容の要約
- 参考にすべきコード
### アクション2: タスクを完了にする
1. 進行中・未完了タスクリストを表示
2. AskUserQuestion toolで完了したタスクを選択（複数選択可）
3. Edit toolを使用して tasks.mdの該当タスクを \`- [x]\` に更新
4. Progress Trackingセクションの進捗率を再計算してEdit toolで更新
5. 次の推奨タスクを提案
### アクション3: 新しいタスクを追加する
1. AskUserQuestion toolで以下を質問:
- 追加するPhase
- タスク内容
2. Edit toolを使用して tasks.mdの該当Phaseに \`- [ ]\` 形式で追加
3. Progress Trackingの総タスク数を更新
### アクション4: 開発ログを記録する
1. AskUserQuestion toolで以下を質問:
- セッションの目標（Goal）
- 完了したタスク（Tasks Completed）
- 遭遇した問題（Issues Encountered） - オプション
- 次のセッションの予定（Next Session）
- 所要時間（Time）
- AIで節約できた時間（Time Saved with AI） - オプション
2. Edit toolを使用して Development Logセクションに以下形式で追記:
\`\`\`markdown
### Session X: YYYY-MM-DD HH:MM-HH:MM
**Goal**: [ユーザー入力]
**AI Tool**: Claude Code
**Tasks Completed**:
- [x] [タスク1]
- [x] [タスク2]
**Issues Encountered**:
- [問題と解決方法]
**Next Session**:
- [ ] [次のタスク]
**Time**: [X] minutes
**Time Saved with AI**: [Y] minutes
---
\`\`\`
### アクション5: 進捗確認のみ
ステップ3の進捗表示のみ実行し、tasks.mdは更新しない。
## ステップ5: 更新後の確認
tasks.mdを更新した場合:
\`\`\`
tasks.md を更新しました！
更新内容:
- [更新されたタスク一覧]
- 進捗率: X% → Y%
現在の状態:
- 完了: X tasks
- 進行中: Y tasks
- 未着手: Z tasks
次のステップ:
[次に取り組むべきタスクの提案]
推奨:
- Phase完了時は \`npm test -- [feature-name]\` を実行
- 権限制御実装後は権限別テストを実行
- 全Phase完了後は \`npm run lint && npm run build\` を実行
\`\`\`
## ステップ6: 継続的な進捗管理
実装中は定期的に \`/design-docs:track\` を実行することを推奨:
- Phase完了時
- 問題に遭遇した時
- 開発セッション終了時
- テスト実行後
## 重要な注意事項
1. **テンプレート準拠**: \`docs/design_docs/templates/tasks_template.md\` の構造を維持
2. **進捗率の正確性**: チェックボックスの数を正確にカウント
3. **開発ログの記録**: AIとの協働を可視化するため詳細に記録
4. **Blockers管理**: 問題が発生した場合はBlockersセクションに記録
5. **Key Decisions**: 重要な設計判断はNotesセクションに記録
6. **Edit toolの使用**: tasks.md更新時は必ずEdit toolを使用（Read → Edit）
7. **日時取得**: 開発ログ記録時は \`date +"%Y-%m-%d %H:%M"\` で現在時刻を取得
8. **テスト実行**: 各Phase完了時に \`npm test -- [feature-name]\` を実行推奨
9. **AI時間節約**: AIによって節約できた時間を記録し、生産性を可視化
design-docs:switch.md
.claude/commands/design-docs:switch.md
# AI駆動開発: 設計書切り替え
複数の設計書がある場合に、作業対象を切り替えます。
## ステップ1: 既存設計書の一覧表示
\`docs/design_docs/\` ディレクトリ内の設計書ディレクトリを検索（Bash tool使用）:
\`\`\`bash
ls -1d docs/design_docs/20*/ 2>/dev/null || echo "設計書が見つかりません"
\`\`\`
設計書が見つからない場合:
\`\`\`
設計書が見つかりません
以下のいずれかを実行してください:
- \`/design-docs:plan\` で新規設計書を作成
- \`/design-docs:quick\` でクイック設計を作成
\`\`\`
## ステップ2: 設計書の詳細情報表示
各設計書ディレクトリの \`requirements.md\` を読み込み、以下を抽出:
- 機能名（Feature Name）
- Status
- Created日付
- What（概要）
一覧形式で表示:
\`\`\`
利用可能な設計書:
1. 20251202-user-management/ (Draft)
Created: 2025-12-02
What: ユーザー管理ページの作成
2. 20251201-article-filter/ (In Progress)
Created: 2025-12-01
What: 記事一覧ページのフィルター機能追加
3. 20251130-announcement-modal/ (Completed)
Created: 2025-11-30
What: お知らせモーダルコンポーネントの実装
現在のカレント設計書: 20251201-article-filter/
\`\`\`
## ステップ3: 設計書の選択
AskUserQuestion toolで選択を促す:
\`\`\`
切り替える設計書を選択してください:
選択肢:
1. 20251202-user-management/
2. 20251201-article-filter/
3. 20251130-announcement-modal/
\`\`\`
ユーザーが選択した設計書のパスを取得。
## ステップ4: カレント設計書の更新
1. \`.claude/.current-design-doc\` ファイルを更新（Write tool使用）:
\`\`\`
docs/design_docs/YYYYMMDD-feature-name/
\`\`\`
2. 更新確認メッセージを表示:
\`\`\`
カレント設計書を切り替えました！
docs/design_docs/YYYYMMDD-feature-name/
├── requirements.md
├── design.md
└── tasks.md
次のステップ:
- \`/design-docs:start\` で実装開始
- \`/design-docs:track\` で進捗確認
\`\`\`
## ステップ5: 進捗状況の簡易表示（オプション）
切り替え後の設計書の \`tasks.md\` を読み込み、進捗状況を簡易表示:
\`\`\`
進捗状況: X% (Y/Z tasks completed)
Status: [Draft/In Progress/Completed]
\`\`\`
## 重要な注意事項
1. **ディレクトリ検索**: \`docs/design_docs/20*/\` パターンで日付プレフィックス付きのみ検索
2. **requirements.md必須**: 各ディレクトリに requirements.md が存在することを確認
3. **カレント設計書管理**: \`.claude/.current-design-doc\` を常に最新に保つ
4. **エラーハンドリング**: 不完全な設計書（ファイル欠損）は警告表示
5. **日付ソート**: 新しい設計書から順に表示（降順）
README.md
docs/design_docs/README.md
# AI駆動開発: 設計書管理システム
**仕様駆動開発による高品質・高速な機能実装を実現**
## 概要
このシステムは、AI（Claude Code）と協働しながら、仕様駆動で機能開発を進めるためのフレームワークです。
設計書を事前に作成することで、実装の方向性を明確化し、AIとの協働をスムーズにします。
### 主な特徴
- **対話形式の設計書生成**: 質問に答えるだけで詳細設計が完成
- **クイック設計モード**: 2分で設計を完了し、即実装開始
- **進捗管理**: タスク単位で実装状況を可視化
- **AI最適化**: Claude Codeが理解しやすい形式で設計を記録
- **設計書切り替え**: 複数の機能を並行開発可能
## 5つのスラッシュコマンド
\`\`\`bash
# 設計書作成
/design-docs:plan # 対話形式で詳細設計（requirements/design/tasks）
/design-docs:quick # gitコミット形式の2分設計
# 実装・進捗管理
/design-docs:start # カレント設計書から実装開始
/design-docs:track # タスク進捗管理・Development Log記録
/design-docs:switch # 設計書の切り替え
\`\`\`
## カレント設計書管理
- \`.claude/.current-design-doc\` で作業中の設計書を自動管理
- \`/design-docs:start\` と \`/design-docs:track\` は引数不要
- 設計書は \`docs/design_docs/\` に保存
## 使用方法
### パターン1: 詳細設計（推奨）
大規模機能や複数人での協働開発に最適
\`\`\`bash
# ステップ1: 設計書作成
/design-docs:plan
# 対話形式で以下を入力:
# - What（何を作るか）
# - Why（なぜ必要か）
# - 機能要件
# - 非機能要件
# - 成功基準
# - アーキテクチャレイヤー
# - APIエンドポイント
# - ページ/コンポーネント構成
# - 権限制御
# ステップ2: 実装開始
/design-docs:start
# ステップ3: 進捗管理
/design-docs:track
\`\`\`
**生成される設計書:**
\`\`\`
docs/design_docs/YYYYMMDD-feature-name/
├── requirements.md # 要件定義
├── design.md # 詳細設計
└── tasks.md # タスク管理
\`\`\`
### パターン2: クイック設計
小規模機能や緊急対応に最適
\`\`\`bash
# ステップ1: クイック設計（2分）
/design-docs:quick
# 以下を一括入力:
# - Plan（一行要約）
# - What（概要）
# - Why（理由）
# - How（実装方法）
# - Tests（テスト）
# ステップ2: 実装開始
/design-docs:start
# ステップ3: 実装完了後、コミット更新
git add .
git commit --amend -m "feat: [機能名]
[実装結果のサマリー]
"
\`\`\`
**記録形式:**
- gitの空コミットとして記録
- \`.claude/.current-design-doc\` に \`git:[hash]\` 形式で保存
### パターン3: 設計書の切り替え
複数の機能を並行開発する場合
\`\`\`bash
/design-docs:switch
# 利用可能な設計書一覧から選択
\`\`\`
## 設計書の構成
### requirements.md（要件定義）
- What（何を作るか）
- Why（なぜ必要か）
- Functional Requirements（機能要件）
- Non-Functional Requirements（非機能要件）
- Success Criteria（成功基準）
### design.md（詳細設計）
- Architecture（アーキテクチャレイヤー）
- Implementation（実装詳細）
- Type Layer（TypeScript型定義）
- API Service Layer（API呼び出し）
- Hook Layer（カスタムフック）
- Component Layer（UIコンポーネント）
- API Specification（API仕様）
- Permission Control（権限制御 - 必須）
- UI/UX Design（デザイン要件）
- Testing Strategy（テスト戦略）
- Error Handling（エラーハンドリング）
- Performance Considerations（パフォーマンス要件）
### tasks.md（タスク管理）
- Task Breakdown（Phase別タスク一覧）
- Phase 1: Types & Interfaces
- Phase 2: API Service Layer
- Phase 3: Custom Hooks
- Phase 4: UI Components
- Phase 5: Permission Control（必須）
- Phase 6: Testing
- Phase 7: Documentation & Review
- Progress Tracking（進捗率）
- Development Log（開発ログ）
- Blockers（ブロッカー管理）
- Notes（メモ・決定事項）
## Next.js特化の実装フロー
### Phase別実装順序（CRITICAL）
1. **Phase 1: Types & Interfaces**
- \`src/lib/types.ts\` に型定義
- API request/response型
- フォームデータ型
2. **Phase 2: API Service Layer**
- \`src/lib/[feature]-service.ts\` にサービスクラス
- CRUD操作の実装
- エラーハンドリング
3. **Phase 3: Custom Hooks（必要な場合）**
- \`src/hooks/use[Feature].ts\` にカスタムフック
- データ取得ロジック
- フォーム管理ロジック
4. **Phase 4: UI Components**
- \`src/app/[route]/page.tsx\` にページコンポーネント
- 一覧・詳細・フォーム画面
- CLAUDE.mdのデザインシステム準拠
5. **Phase 5: Permission Control（必須）**
- \`src/lib/permissions.ts\` に権限定数追加
- Sidebarメニュー項目追加
- PermissionGuard実装
- UI要素の権限制御
6. **Phase 6: Testing**
- API Service tests
- Component tests
- Permission tests
- カバレッジ85%以上
7. **Phase 7: Documentation & Review**
- CLAUDE.md更新（必要に応じて）
- docs/sitemap.md更新
- コードレビュー
### 必須実装項目
#### 権限制御（MANDATORY）
CLAUDE.mdの規定により、すべての新機能には権限制御が必須:
\`\`\`typescript
// 1. 権限定数定義
export const PERMISSIONS = {
FEATURE: {
VIEW: 'admin:feature:view',
CREATE: 'admin:feature:create',
EDIT: 'admin:feature:edit',
DELETE: 'admin:feature:delete',
},
}
// 2. Sidebarメニュー
{
icon: <Icon className="w-5 h-5" />,
label: "機能名",
path: "/feature",
requiredPermissions: [PERMISSIONS.FEATURE.VIEW],
}
// 3. ページレベルガード
<PermissionGuard requiredPermissions={[PERMISSIONS.FEATURE.VIEW]}>
{/* コンテンツ */}
</PermissionGuard>
// 4. UI要素の権限制御
const canCreate = hasPermission(PERMISSIONS.FEATURE.CREATE);
{canCreate && <Button>新規作成</Button>}
\`\`\`
#### デザインシステム準拠
CLAUDE.mdの「標準UIパターン」に従う:
- AuthGuard + NavigationSection + PageHeader レイアウト
- SearchAndFilter + DataTable + Pagination
- ValidationError表示（フォームの場合）
- ダークモード対応
- レスポンシブ対応（最小1200px）
#### テストカバレッジ
- Overall: 85%以上
- Critical paths: 100%
- Feature-specific tests: \`npm test -- [feature-name]\`
## まとめ
このシステムにより:
- **設計と実装の分離** - 設計フェーズで方向性を確定
- **AIとの協働最適化** - AIが理解しやすい形式で設計を記録
- **進捗の可視化** - Phase別タスク管理で進捗を明確化
- **品質の担保** - 権限制御・テスト・レビューの標準化
- **知識の蓄積** - 開発ログで経験を記録・共有
**次のステップ:**
1. \`/design-docs:plan\` で設計書を作成
2. \`/design-docs:start\` で実装開始
3. \`/design-docs:track\` で進捗管理
開発体験
- 学習コスト低: 対話形式で誰でも使える
- 属人化解消: 設計書が標準化
- AIとの協働: Claude Codeが設計を理解して実装
現状の課題
1. 複数人開発時のコンフリクトリスク
設計書ファイルは通常のソースコードと同様に Git で管理されるため、複数人が同じ設計書を編集する場合はコンフリクトが発生する可能性があります。
2. マスター仕様の管理
現状の仕組みは、マイグレーションファイルのように仕様書が追加されていくフローです。記事やアカウントなど、機能ごとのマスター仕様（常に最新の状態を保つドキュメント）は別途管理が必要です。
コマンドカスタマイズ例
BE系のプロジェクトで design-docs:plan.md で以下のようなカスタマイズを行なっています。
### ステップ3-1: Clean Architectureの層
**メッセージ表示**:
\`\`\`
設計の詳細を教えてください。
1. **Clean Architectureの層**: どの層を変更しますか？
- Domain / Service / Handler / Repository（複数可）
- 「任せる」でも可（適切な層を自動判断）
\`\`\`
ユーザーの回答を待ち、回答内容を格納します。
「任せる」の場合は機能要件から適切な層を自動判断します。
---
### ステップ3-2: APIエンドポイント
**メッセージ表示**:
\`\`\`
2. **APIエンドポイント**: 必要ですか？
必要な場合:
- Method: GET/POST/PUT/DELETE
- Path: /v8/xxx
- Query/Path parameters
不要な場合: 「なし」「不要」と入力
任せる場合: 「任せる」と入力
\`\`\`
ユーザーの回答を待ち、回答内容を格納します。
「任せる」の場合は機能要件から適切なAPIを自動設計します。
「なし」「不要」の場合はAPIエンドポイントなしとして処理します。
---
### ステップ3-3: データベース変更
**メッセージ表示**:
\`\`\`
3. **データベース変更**: 必要ですか？
必要な場合:
- テーブル名、カラム情報を記述
不要な場合: 「なし」「不要」と入力
任せる場合: 「任せる」と入力（機能に応じて自動設計）
\`\`\`
ユーザーの回答を待ち、回答内容を格納します。
「任せる」の場合は機能要件から必要なテーブル構造を自動生成します。
「なし」「不要」の場合はDB変更なしとして処理します。d
まとめ
実装したシステムの特徴
- 対話形式の設計書生成: 質問に答えるだけで完成
- AI最適化された設計フォーマット: Claude Codeが理解しやすい
- Phase別タスク管理: 進捗を可視化
- 権限制御の必須化: セキュリティを担保
- 開発ログによる知識蓄積: AIとの協働を記録
おわりに
仕様駆動開発は、AI時代においてこそ重要性を増しています。
Claude Codeのカスタムコマンド機能を活用することで、組織固有の開発プロセスをAIに最適化できます。
皆さんもぜひ、自社のリポジトリに合わせた仕様駆動開発システムを構築してみてください。
参考リンク:
最後に運動通信社について
運動通信社は「日本を世界が憧れるスポーツ大国にする」というビジョンを達成するべく、一緒に働く仲間を募集しています！
PMやアプリエンジニア、Webエンジニアなど色んな職種を募集しておりカジュアル面談大歓迎なので是非採用フォームよりご連絡ください！
ぜひ一緒に、自分たちも世の中もワクワクするサービスを作りましょう！