Initial commit
This commit is contained in:
Zhongwei Li
407
skills/sdd-docs/README.md
Normal file
407
skills/sdd-docs/README.md
Normal file
@@ -0,0 +1,407 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user