408 lines
15 KiB
Markdown
408 lines
15 KiB
Markdown
# SDD-Docs - ソフトウェア設計ドキュメント管理スキル
|
||
|
||
Claude Codeのための構造化されたソフトウェア設計ドキュメント（SDD）作成・管理スキルです。EARS記法を用いた要件定義、技術設計、タスク管理の3つのドキュメントを一貫したプロセスで作成・維持します。
|
||
|
||
---
|
||
|
||
## 目次
|
||
|
||
- [特徴](#特徴)
|
||
- [クイックスタート](#クイックスタート)
|
||
- [EARS記法について](#ears記法について)
|
||
- [ドキュメント構成](#ドキュメント構成)
|
||
- [使い方](#使い方)
|
||
- [ワークフロー](#ワークフロー)
|
||
- [ベストプラクティス](#ベストプラクティス)
|
||
- [FAQ](#faq)
|
||
- [トラブルシューティング](#トラブルシューティング)
|
||
- [リファレンス](#リファレンス)
|
||
|
||
---
|
||
|
||
## 特徴
|
||
|
||
### 解決する課題
|
||
|
||
- 曖昧で測定不可能な要件定義
|
||
- 技術的決定事項の記録不足
|
||
- タスク分解と進捗管理の困難さ
|
||
- ドキュメントの一貫性の欠如
|
||
|
||
### 提供する価値
|
||
|
||
- **明確性**: EARS記法による曖昧さのない要件定義
|
||
- **追跡可能性**: 要件→設計→タスクの明確な紐付け
|
||
- **テスト可能性**: すべての要件が検証可能
|
||
- **一貫性**: 統一されたドキュメント構造
|
||
|
||
---
|
||
|
||
## クイックスタート
|
||
|
||
### 1. スキルを有効化
|
||
|
||
Claude Codeでこのスキルが自動的に提案されます。
|
||
|
||
### 2. プロジェクトでドキュメントを初期化
|
||
|
||
```
|
||
docsディレクトリを初期化してください
|
||
```
|
||
|
||
### 3. 生成されるドキュメント
|
||
|
||
```
|
||
your-project/
|
||
└── docs/
|
||
├── requirements.md # 要件定義書（EARS記法）
|
||
├── design.md # 設計書
|
||
└── tasks.md # タスク管理書
|
||
```
|
||
|
||
### 4. 使用例
|
||
|
||
**要件を追加:**
|
||
```
|
||
ユーザー認証機能の要件を追加してください
|
||
```
|
||
|
||
**設計を文書化:**
|
||
```
|
||
認証システムのアーキテクチャを設計書に追加してください
|
||
```
|
||
|
||
**タスクに分解:**
|
||
```
|
||
認証機能を実装可能なタスクに分解してください
|
||
```
|
||
|
||
---
|
||
|
||
## EARS記法について
|
||
|
||
EARS（Easy Approach to Requirements Syntax）は、明確で曖昧さのない要件を記述するための構造化された記法です。
|
||
|
||
### 5つの基本パターン
|
||
|
||
| パターン | 形式 | 使用場面 | 例 |
|
||
|---------|------|----------|-----|
|
||
| **基本** | システムは〜しなければならない | 常時適用される要件 | システムはパスワードをbcryptで暗号化しなければならない |
|
||
| **イベント** | 〜の時、システムは〜しなければならない | イベント駆動要件 | ユーザーがログインボタンをクリックした時、システムは認証処理を開始しなければならない |
|
||
| **条件** | もし〜ならば、システムは〜しなければならない | 状態依存要件 | もし認証が失敗した場合、システムはエラーメッセージを表示しなければならない |
|
||
| **継続** | 〜の間、システムは〜しなければならない | 継続的要件 | ファイルアップロード中、システムは進捗バーを表示しなければならない |
|
||
| **場所** | 〜において、システムは〜しなければならない | コンテキスト固有要件 | EU地域において、システムはGDPR同意バナーを表示しなければならない |
|
||
|
||
### EARS記法の利点
|
||
|
||
- **一貫性**: すべての要件が同じ構造に従う
|
||
- **明確性**: 曖昧な表現を排除
|
||
- **テスト可能性**: 各要件が検証可能
|
||
- **完全性**: トリガー、条件、動作が明確
|
||
|
||
詳細: [EARS記法リファレンス](references/ears_notation_ja.md)
|
||
|
||
---
|
||
|
||
## ドキュメント構成
|
||
|
||
### 3つの必須ドキュメント
|
||
|
||
```mermaid
|
||
graph LR
|
||
A[requirements.md<br/>何を作るか] --> B[design.md<br/>どう作るか]
|
||
B --> C[tasks.md<br/>どう実装するか]
|
||
C --> D[実装]
|
||
D --> A
|
||
```
|
||
|
||
#### 1. requirements.md - 要件定義書
|
||
|
||
**目的**: 何を作るかを定義
|
||
|
||
**含まれる内容**:
|
||
- ユーザーストーリー（私は〜として、〜したい、なぜなら〜）
|
||
- EARS記法による受入基準（REQ-001, REQ-002...）
|
||
- 非機能要件（NFR-001, NFR-002...）
|
||
|
||
**例**:
|
||
```markdown
|
||
### ストーリー1: ユーザーログイン
|
||
**私は** 登録済みユーザーとして
|
||
**ログインしたい**
|
||
**なぜなら** 個人データにアクセスできるから
|
||
|
||
#### 受入基準
|
||
- REQ-001: ユーザーがログインボタンをクリックした時、システムは2秒以内に認証を完了しなければならない
|
||
- REQ-002: もしパスワードが誤っている場合、システムはエラーメッセージを表示しなければならない
|
||
```
|
||
|
||
#### 2. design.md - 設計書
|
||
|
||
**目的**: どのように作るかを文書化
|
||
|
||
**含まれる内容**:
|
||
- アーキテクチャ図（Mermaid形式）
|
||
- コンポーネント設計（目的、責務、インターフェース）
|
||
- データモデル・スキーマ
|
||
- 技術的決定事項と根拠
|
||
|
||
**例**:
|
||
```markdown
|
||
### コンポーネント: 認証サービス
|
||
**目的**: ユーザー認証とセッション管理
|
||
**責務**:
|
||
- JWT トークンの生成・検証
|
||
- パスワードのハッシュ化（bcrypt）
|
||
- セッションの管理
|
||
|
||
**インターフェース**:
|
||
- POST /auth/login - ログイン
|
||
- POST /auth/logout - ログアウト
|
||
```
|
||
|
||
#### 3. tasks.md - タスク管理書
|
||
|
||
**目的**: どのように実装するかを計画
|
||
|
||
**含まれる内容**:
|
||
- フェーズごとのタスク分解
|
||
- 各タスクの受入基準
|
||
- 依存関係と見積もり時間
|
||
- ステータス管理（TODO/IN_PROGRESS/BLOCKED/REVIEW/DONE）
|
||
|
||
**例**:
|
||
```markdown
|
||
#### タスク1.1: ログインエンドポイント実装
|
||
**説明**: POST /auth/loginエンドポイントの実装
|
||
**受入基準**:
|
||
- [ ] メール/パスワード検証
|
||
- [ ] JWTトークン生成
|
||
- [ ] エラーハンドリング
|
||
**依存関係**: なし
|
||
**推定工数**: 4時間
|
||
**ステータス**: `TODO`
|
||
```
|
||
|
||
---
|
||
|
||
## 使い方
|
||
|
||
### 基本的な使用フロー
|
||
|
||
1. **要件定義から開始**
|
||
```
|
||
ユーザー認証機能の要件を定義してください
|
||
```
|
||
→ `docs/requirements.md`にEARS記法で要件が追加される
|
||
|
||
2. **設計を文書化**
|
||
```
|
||
認証機能のアーキテクチャを設計してください
|
||
```
|
||
→ `docs/design.md`にコンポーネント設計が追加される
|
||
|
||
3. **タスクに分解**
|
||
```
|
||
認証機能の実装タスクを作成してください
|
||
```
|
||
→ `docs/tasks.md`に実装可能なタスクが追加される
|
||
|
||
4. **実装とレビュー**
|
||
```
|
||
タスク1.1を実装してください
|
||
```
|
||
→ コードが実装され、タスクステータスが更新される
|
||
|
||
5. **ドキュメントの検証**
|
||
```
|
||
ドキュメントをレビューしてください
|
||
```
|
||
→ チェックリストに基づいてレビューが実行される
|
||
|
||
### 高度な使用例
|
||
|
||
**既存プロジェクトのドキュメント化:**
|
||
```
|
||
このプロジェクトの既存コードから要件と設計を抽出してください
|
||
```
|
||
|
||
**要件の検証:**
|
||
```
|
||
requirements.mdの要件がEARS記法に従っているか確認してください
|
||
```
|
||
|
||
**タスクの進捗確認:**
|
||
```
|
||
完了したタスクと残りのタスクをリストアップしてください
|
||
```
|
||
|
||
---
|
||
|
||
## ワークフロー
|
||
|
||
### 標準的な開発フロー
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 1. 要件定義（requirements.md） │
|
||
│ ↓ ユーザーストーリーとEARS記法で「何を作るか」を定義 │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 2. 設計（design.md） │
|
||
│ ↓ アーキテクチャとコンポーネントで「どう作るか」記述 │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 3. タスク計画（tasks.md） │
|
||
│ ↓ 実装可能な粒度に分解して「どう実装するか」計画 │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 4. 実装 │
|
||
│ ↓ タスクを実行し、ステータスを更新 │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 5. レビュー │
|
||
│ ↓ ドキュメントとコードの整合性を確認 │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 6. 反復 │
|
||
│ ↓ 新しい要件や変更に応じてドキュメントを更新 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### ドキュメント検証チェックリスト
|
||
|
||
**requirements.mdの確認項目:**
|
||
- [ ] すべての要件がEARS記法に従っている
|
||
- [ ] 要件IDが一意である（REQ-XXX、NFR-XXX）
|
||
- [ ] 各要件がテスト可能である
|
||
- [ ] 非機能要件が含まれている
|
||
- [ ] 具体的な数値が使用されている
|
||
|
||
**design.mdの確認項目:**
|
||
- [ ] アーキテクチャ概要がある
|
||
- [ ] 主要コンポーネントが定義されている
|
||
- [ ] インターフェースが明確である
|
||
- [ ] 技術的決定事項と根拠が記載されている
|
||
- [ ] 図表が含まれている（Mermaid推奨）
|
||
|
||
**tasks.mdの確認項目:**
|
||
- [ ] タスクが適切な粒度に分解されている（半日〜2日程度）
|
||
- [ ] 各タスクに受入基準がある
|
||
- [ ] 依存関係が明確である
|
||
- [ ] 見積もり時間が記載されている
|
||
- [ ] ステータスが有効な値である
|
||
|
||
---
|
||
|
||
## ベストプラクティス
|
||
|
||
### 1. 具体的で測定可能な値を使用
|
||
|
||
**悪い例**: システムは速くなければならない
|
||
**良い例**: システムはユーザークエリに200ミリ秒以内に応答しなければならない
|
||
|
||
### 2. 1要件1文の原則
|
||
|
||
**悪い例**: システムはデータを検証し、保存し、メールを送信しなければならない
|
||
**良い例**:
|
||
- REQ-001: システムはデータを検証しなければならない
|
||
- REQ-002: データが有効な場合、システムは保存しなければならない
|
||
- REQ-003: データ保存後、システムは確認メールを送信しなければならない
|
||
|
||
### 3. 曖昧な用語を避ける
|
||
|
||
**避けるべき**: すべきである、できる、かもしれない、おそらく、一般的に
|
||
**使用する**: しなければならない
|
||
|
||
### 4. 依存関係を明確にする
|
||
|
||
タスク間の依存関係を明記して、実装順序を明確にします。
|
||
|
||
### 5. 図表を積極的に活用
|
||
|
||
Mermaid記法でアーキテクチャ図、シーケンス図、ER図を作成します。
|
||
|
||
### 6. 継続的な同期を維持
|
||
|
||
プロジェクトの進展に応じて、ドキュメントを常に最新の状態に保ちます。
|
||
|
||
---
|
||
|
||
## FAQ
|
||
|
||
**Q: EARS記法は必須ですか？**
|
||
A: 推奨されますが、プロジェクトに応じて調整可能です。ただし、EARS記法を使用することで要件の明確性が大幅に向上します。
|
||
|
||
**Q: 既存プロジェクトにも適用できますか？**
|
||
A: はい。既存のコードベースから要件と設計を抽出して、ドキュメント化することができます。
|
||
|
||
**Q: 英語版はありますか？**
|
||
A: 現在は日本語版のみですが、将来的に英語版テンプレートの追加を検討しています。
|
||
|
||
**Q: タスクのステータス管理はどうすればいいですか？**
|
||
A: マークダウンファイル内で直接更新します。Claude Codeを使用すると自動的に更新されます。
|
||
|
||
**Q: 他のツール（Jira、GitHub Issues）との連携は？**
|
||
A: 将来的な拡張機能として検討中です。現在はマークダウンベースでの管理のみです。
|
||
|
||
---
|
||
|
||
## トラブルシューティング
|
||
|
||
### 問題: スキルが認識されない
|
||
|
||
**原因**: スキルファイルのパスが正しくない
|
||
**解決策**:
|
||
1. `.claude-plugin/marketplace.json`のパスを確認
|
||
2. `sdd-docs/SKILL.md`が存在するか確認
|
||
|
||
### 問題: テンプレートが見つからない
|
||
|
||
**原因**: テンプレートファイルのパスが間違っている
|
||
**解決策**:
|
||
```bash
|
||
ls -la assets/templates/
|
||
```
|
||
で3つのテンプレートファイルが存在するか確認
|
||
|
||
### 問題: EARS記法が正しく適用されない
|
||
|
||
**原因**: パターンの理解不足
|
||
**解決策**: [EARS記法リファレンス](references/ears_notation_ja.md)を参照し、5つの基本パターンを確認
|
||
|
||
---
|
||
|
||
## リファレンス
|
||
|
||
### 詳細ドキュメント
|
||
|
||
- **EARS記法の完全ガイド**: [ears_notation_ja.md](references/ears_notation_ja.md)
|
||
- **実装例集**: [examples_ja.md](references/examples_ja.md)
|
||
- ECショッピングカート（requirements.md例）
|
||
- タスク管理API（design.md例）
|
||
- ユーザー認証機能（tasks.md例）
|
||
|
||
### テンプレート
|
||
|
||
- [requirements_template_ja.md](assets/templates/requirements_template_ja.md)
|
||
- [design_template_ja.md](assets/templates/design_template_ja.md)
|
||
- [tasks_template_ja.md](assets/templates/tasks_template_ja.md)
|
||
|
||
### ディレクトリ構造
|
||
|
||
```
|
||
sdd-docs/
|
||
├── SKILL.md # スキル定義ファイル
|
||
├── README.md # このファイル
|
||
├── assets/
|
||
│ └── templates/ # ドキュメントテンプレート
|
||
│ ├── requirements_template_ja.md
|
||
│ ├── design_template_ja.md
|
||
│ └── tasks_template_ja.md
|
||
└── references/ # リファレンス資料
|
||
├── ears_notation_ja.md # EARS記法詳細ガイド
|
||
└── examples_ja.md # 実装例集
|
||
```
|
||
|
||
---
|
||
|
||
## 謝辞
|
||
|
||
- **EARS記法**: Alistair Mavin et al.による"EARS - The Easy Approach to Requirements Syntax"
|
||
- **標準規格**: IEEE 830-1998, ISO/IEC/IEEE 29148:2018
|