15 KiB
SDD-Docs - ソフトウェア設計ドキュメント管理スキル
Claude Codeのための構造化されたソフトウェア設計ドキュメント（SDD）作成・管理スキルです。EARS記法を用いた要件定義、技術設計、タスク管理の3つのドキュメントを一貫したプロセスで作成・維持します。
目次
特徴
解決する課題
- 曖昧で測定不可能な要件定義
- 技術的決定事項の記録不足
- タスク分解と進捗管理の困難さ
- ドキュメントの一貫性の欠如
提供する価値
- 明確性: 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記法リファレンス
ドキュメント構成
3つの必須ドキュメント
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...）
例:
### ストーリー1: ユーザーログイン
**私は** 登録済みユーザーとして
**ログインしたい**
**なぜなら** 個人データにアクセスできるから
#### 受入基準
- REQ-001: ユーザーがログインボタンをクリックした時、システムは2秒以内に認証を完了しなければならない
- REQ-002: もしパスワードが誤っている場合、システムはエラーメッセージを表示しなければならない
2. design.md - 設計書
目的: どのように作るかを文書化
含まれる内容:
- アーキテクチャ図（Mermaid形式）
- コンポーネント設計（目的、責務、インターフェース）
- データモデル・スキーマ
- 技術的決定事項と根拠
例:
### コンポーネント: 認証サービス
**目的**: ユーザー認証とセッション管理
**責務**:
- JWT トークンの生成・検証
- パスワードのハッシュ化（bcrypt）
- セッションの管理
**インターフェース**:
- POST /auth/login - ログイン
- POST /auth/logout - ログアウト
3. tasks.md - タスク管理書
目的: どのように実装するかを計画
含まれる内容:
- フェーズごとのタスク分解
- 各タスクの受入基準
- 依存関係と見積もり時間
- ステータス管理（TODO/IN_PROGRESS/BLOCKED/REVIEW/DONE）
例:
#### タスク1.1: ログインエンドポイント実装
**説明**: POST /auth/loginエンドポイントの実装
**受入基準**:
- [ ] メール/パスワード検証
- [ ] JWTトークン生成
- [ ] エラーハンドリング
**依存関係**: なし
**推定工数**: 4時間
**ステータス**: `TODO`
使い方
基本的な使用フロー
-
要件定義から開始
ユーザー認証機能の要件を定義してください→
docs/requirements.mdにEARS記法で要件が追加される -
設計を文書化
認証機能のアーキテクチャを設計してください→
docs/design.mdにコンポーネント設計が追加される -
タスクに分解
認証機能の実装タスクを作成してください→
docs/tasks.mdに実装可能なタスクが追加される -
実装とレビュー
タスク1.1を実装してください→ コードが実装され、タスクステータスが更新される
-
ドキュメントの検証
ドキュメントをレビューしてください→ チェックリストに基づいてレビューが実行される
高度な使用例
既存プロジェクトのドキュメント化:
このプロジェクトの既存コードから要件と設計を抽出してください
要件の検証:
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: 将来的な拡張機能として検討中です。現在はマークダウンベースでの管理のみです。
トラブルシューティング
問題: スキルが認識されない
原因: スキルファイルのパスが正しくない 解決策:
.claude-plugin/marketplace.jsonのパスを確認sdd-docs/SKILL.mdが存在するか確認
問題: テンプレートが見つからない
原因: テンプレートファイルのパスが間違っている 解決策:
ls -la assets/templates/
で3つのテンプレートファイルが存在するか確認
問題: EARS記法が正しく適用されない
原因: パターンの理解不足 解決策: EARS記法リファレンスを参照し、5つの基本パターンを確認
リファレンス
詳細ドキュメント
- EARS記法の完全ガイド: ears_notation_ja.md
- 実装例集: examples_ja.md
- ECショッピングカート（requirements.md例）
- タスク管理API（design.md例）
- ユーザー認証機能（tasks.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