name

sdd-docs

description

ソフトウェア設計ドキュメント（SDD）を作成・修正・更新・管理します。3つの主要ファイル - requirements.md（EARS記法によるユーザーストーリー）、design.md（技術アーキテクチャ）、tasks.md（実装計画）の新規作成、既存ドキュメントの編集、EARS記法への変換、要件・設計・タスクの追加や修正が必要な場合に使用してください。

SDD ドキュメンテーションスキル

構造化されたソフトウェア設計ドキュメント（SDD）の作成を支援します。明確な要件定義、設計思想、実行可能なタスクを重視したドキュメント作成手法です。

概要

SDD-Docsスキルは、以下の3つの必須ドキュメントファイルの作成と管理を支援します：

requirements.md: EARS記法を用いたユーザーストーリーと受入基準
design.md: 技術アーキテクチャ、コンポーネント、実装詳細
tasks.md: 追跡可能な個別タスクへの作業分解

すべてのドキュメントはdocsディレクトリに保存され、可視性とGit管理が容易になります。

このスキルを使用する場面

以下の状況でこのスキルを有効にしてください：

新規作成時

新規ソフトウェアプロジェクトで構造化されたドキュメントが必要な場合
明確でテスト可能な受入基準を持つ要件を作成する場合
技術アーキテクチャと設計決定を文書化する場合
機能を実装可能なタスクに分解する場合
プロジェクトのドキュメント構造を設定する場合

既存ドキュメントの修正・更新時

docs/requirements.mdに新しい要件を追加・修正する場合
docs/design.mdの設計内容を更新・変更する場合
docs/tasks.mdにタスクを追加・修正・更新する場合
既存の要件をEARS記法に変換・修正する場合
要件・設計・タスクの整合性を確認・修正する場合
ドキュメントの内容をレビュー・改善する場合

ドキュメント初期化の方法

「docsディレクトリを初期化してください」や「SDDドキュメントを作成してください」と依頼されたら、以下の作業を行います：

docsディレクトリの作成
requirements.md（要件定義書）の作成 - assets/templates/requirements_template_ja.mdを基に作成
design.md（設計書）の作成 - assets/templates/design_template_ja.mdを基に作成
tasks.md（タスク管理書）の作成 - assets/templates/tasks_template_ja.mdを基に作成

作成時は、プロジェクトの内容に応じてテンプレートをカスタマイズします。

既存ドキュメントの編集方法

既存のSDDドキュメント（requirements.md、design.md、tasks.md）を修正・更新する場合は、以下の手順で行います：

要件定義（requirements.md）の修正・追加

「requirements.mdに〜を追加してください」「要件を修正してください」などと依頼されたら：

既存ドキュメントの確認
- docs/requirements.mdの現在の内容を確認
- 既存の要件ID（REQ-XXX、NFR-XXX）を把握
修正・追加の実施
- 新しい要件を追加する場合は、次の要件IDを採番
- 既存の要件を修正する場合は、EARS記法に従っているか確認
- ユーザーストーリーとの整合性を確認
ユーザー確認
- 修正内容をユーザーに確認
- 承認を得てから次のステップへ

設計（design.md）の修正・更新

「design.mdを更新してください」「設計を変更してください」などと依頼されたら：

既存設計の確認
- docs/design.mdの現在のアーキテクチャ、コンポーネント構成を確認
- requirements.mdとの整合性を確認
設計変更の実施
- アーキテクチャ変更の場合は、影響範囲を明確にする
- 新しいコンポーネント追加の場合は、既存との統合方法を明記
- 技術的決定事項を更新
ユーザー確認
- 変更内容をユーザーに確認
- 承認を得てから次のステップへ

タスク（tasks.md）の修正・追加

「tasks.mdにタスクを追加してください」「タスクを更新してください」などと依頼されたら：

既存タスクの確認
- docs/tasks.mdの現在のタスク一覧、フェーズ構成を確認
- 進行中のタスク、依存関係を把握
タスクの追加・修正
- 新しいタスクを追加する場合は、適切なフェーズに配置
- 既存タスクを修正する場合は、受入基準、依存関係を更新
- TDDの実装手順を含める
- AIエージェント向けの具体的な指示を記載
ユーザー確認
- 追加・修正内容をユーザーに確認
- 承認を得て完了

整合性の確認

ドキュメント修正時は、3つのドキュメント間の整合性を確認してください：

requirements.mdの要件変更 → design.mdとtasks.mdへの影響を確認
design.mdの設計変更 → tasks.mdのタスク内容を更新
tasks.mdのタスク追加 → requirements.mdとdesign.mdに対応する内容があるか確認

EARS記法ガイド

EARS（Easy Approach to Requirements Syntax）により、要件を明確で曖昧さがなく、テスト可能にします。

基本パターン（日本語版）

パターン	形式	使用場面
基本	`システムは〜しなければならない`	常時適用される要件
イベント	`〜の時、システムは〜しなければならない`	イベント駆動要件
条件	`もし〜ならば、システムは〜しなければならない`	状態依存要件
継続	`〜の間、システムは〜しなければならない`	継続的要件
場所	`〜において、システムは〜しなければならない`	コンテキスト固有要件

要件の例

- REQ-001: ユーザーが「カートに追加」をクリックした時、システムは500ms以内に商品を追加しなければならない
- REQ-002: カートが空の場合、システムは「カートは空です」と表示しなければならない
- REQ-003: 決済処理中、システムは進捗インジケーターを表示しなければならない
- REQ-004: ユーザーがEU地域にいる場合、システムはGDPR同意オプションを表示しなければならない
- NFR-001: システムは性能劣化なしに1000人の同時ユーザーを処理できなければならない

詳細なEARSガイダンスは references/ears_notation_ja.md を参照してください。

ドキュメント構造の説明

requirements.md（要件定義書）

# 要件定義

## 概要
[機能/システムの高レベルの目的と目標を記載]

## ユーザーストーリー
### ストーリー1: [タイトル]
**私は** [ユーザータイプ]として
**〜したい** [目標]
**なぜなら** [価値/利点]

#### 受入基準（EARS記法）
- REQ-001: [イベント]の時、システムは[振る舞い]しなければならない
- REQ-002: もし[条件]ならば、システムは[振る舞い]しなければならない

## 非機能要件
- NFR-001: システムは[性能/セキュリティ/ユーザビリティ要件]を満たさなければならない

design.md（設計書）

# 設計

## アーキテクチャ概要
[システムアーキテクチャの説明と図]

## コンポーネント
### コンポーネント1: [名前]
**目的**: [機能]
**責務**: [リスト]
**インターフェース**: [API/メソッド]

## データフロー
[シーケンス図とデータフローの説明]

## 技術的決定事項
[主要な技術選択と根拠]

tasks.md（タスク管理書）

# タスク

## 実装計画

### フェーズ1: [名前]
#### タスク1.1: [タイトル]
**説明**: [実施内容]
**受入基準**: [チェックリスト]
**依存関係**: [他のタスク]
**ステータス**: `TODO`

ワークフロー

初期化: docsディレクトリとテンプレートファイルを作成
要件定義: EARS記法を使って何を作るかを定義
設計: どのように作るかを文書化
タスク計画: 実装を計画
レビュー: ドキュメントの品質をチェック
反復: プロジェクトの進展に応じて更新

検証チェックリスト

ドキュメントをレビューする際は以下を確認：

要件定義書のチェック項目

✅ ユーザーストーリーが明確に定義されている
✅ すべての要件がEARS記法に従っている
✅ 要件IDが一意である（REQ-XXX、NFR-XXX）
✅ 各要件がテスト可能である
✅ 非機能要件が含まれている

設計書のチェック項目

✅ アーキテクチャ概要が記載されている
✅ 主要コンポーネントが定義されている
✅ インターフェースが明確である
✅ 技術的決定事項と根拠が記載されている
✅ 必要に応じて図表が含まれている

タスク管理書のチェック項目

✅ タスクが適切な粒度に分解されている
✅ 各タスクに受入基準がある
✅ 依存関係が明確である
✅ 見積もり時間が記載されている
✅ ステータスが有効な値である（TODO、IN_PROGRESS、BLOCKED、REVIEW、DONE）

ベストプラクティス

なぜから始める: 目的を理解するためユーザーストーリーから開始
具体的に: 測定可能な値を使用（「高速」ではなく「2秒以内」）
要件ごとに1つ: 複合要件を避ける（複数の「しなければならない」を含めない）
すべてをテスト可能に: 各要件は検証可能でなければならない
依存関係を追跡: 関連タスクを明確にリンク
最新を保つ: 作業の進行に応じてステータスを更新

ユーザーとの対話ガイドライン

【重要】推測を避け、必ずユーザーに確認する

このスキルを使用する際は、以下の原則に従ってユーザーとコミュニケーションを取ってください：

1. 推測禁止の原則

プロジェクトの詳細、技術スタック、要件などについて推測しない
不明確な点や曖昧な情報がある場合は、必ずユーザーに確認する
仮定を立てる必要がある場合は、その仮定を明示してユーザーに確認を求める

2. 選択肢を提示する

ユーザーに確認を求める際は、以下のような形式で選択肢を提示してください：

良い例：

プロジェクトの種類について確認させてください：
A) Webアプリケーション
B) モバイルアプリケーション
C) API/バックエンドサービス
D) その他

どれに該当しますか？

良い例（Yes/No形式）：

このプロジェクトはWebアプリケーションですか？
- はい
- いいえ

悪い例：

Webアプリケーションとして進めます。

3. AskUserQuestionツールの活用

複数の選択肢がある場合や、重要な決定が必要な場合は、AskUserQuestionツールを積極的に使用してください。

使用例：

プロジェクトタイプの選択
技術スタックの確認
アーキテクチャパターンの選択
非機能要件の優先順位付け
タスクの粒度や見積もりの確認

4. 確認が必要な場面

以下の場合は必ずユーザーに確認してください：

ドキュメント初期化時

プロジェクトの種類や目的
対象ユーザー
主要な機能
技術的制約

要件定義時

ユーザーストーリーの優先順位
非機能要件の具体的な値（性能、セキュリティなど）
受入基準の妥当性

設計時

アーキテクチャパターンの選択
技術スタックの選定
データモデルの構造
外部サービスとの連携方法

タスク分解時

タスクの粒度
優先順位
見積もり時間
実装の順序

5. 確認の形式

推奨される確認パターン：

二択の確認

〜という理解で正しいですか？
- はい
- いいえ

複数選択

以下のうち、どれに該当しますか？
A) 選択肢1
B) 選択肢2
C) 選択肢3
D) その他（詳しく教えてください）

段階的な確認

まず、〜ですか？
- はい → 次の質問へ
- いいえ → 別の質問へ

6. 避けるべき表現

以下のような推測に基づく表現は避けてください：

❌ 「おそらく〜でしょう」 ❌ 「一般的には〜です」 ❌ 「〜と仮定して進めます」 ❌ 「〜のようですので」

✅ 「〜でしょうか？確認させてください」 ✅ 「以下の選択肢から選んでいただけますか？」 ✅ 「〜という理解で正しいですか？」

7. 絵文字の使用ルール

原則: 文章では絵文字を使用しない

ドキュメント作成時、説明文、コメントなどでは絵文字を使わない

良い例：

## 重要な注意事項
システムのセキュリティを確保するため、以下の要件を必ず満たしてください。

悪い例：

## 重要な注意事項 🚨
システムのセキュリティを確保するため 🔒、以下の要件を必ず満たしてください ✨

8. ドキュメント作成の順序と確認プロセス

【重要】必ず要求→設計→タスクの順で作成し、各ステップでユーザー確認を取る

ドキュメントの作成・修正は以下の順序で進めてください：

作業の流れ

requirements.md（要件定義）の作成・修正
- EARS記法を用いて要件を記述
- 完成したら必ずユーザーに内容を確認
- ユーザーの承認を得てから次へ進む
design.md（設計）の作成・修正
- requirements.mdの内容を基に設計を記述
- 完成したら必ずユーザーに内容を確認
- ユーザーの承認を得てから次へ進む
tasks.md（タスク）の作成・修正
- design.mdの内容を基にタスクに分解
- 完成したら必ずユーザーに内容を確認
- ユーザーの承認を得て完了

確認の取り方

各ドキュメント完成時に以下のように確認を求めてください：

requirements.mdの作成が完了しました。
内容を確認していただけますか？

- 承認して次（design.md）に進む
- 修正が必要

注意事項

各ドキュメントは完全に完成してから次のドキュメントに進む
ユーザーの承認なしに次のステップに進まない
修正が必要な場合は、修正後に再度確認を取る
3つのドキュメントを同時に作成・修正しない

ワークフロー例

1. requirements.md作成
   ↓
2. ユーザー確認・承認
   ↓
3. design.md作成
   ↓
4. ユーザー確認・承認
   ↓
5. tasks.md作成
   ↓
6. ユーザー確認・承認
   ↓
7. 完了

9. AIエージェント向けタスク化のガイドライン

【重要】タスクはAIエージェントが実行することを前提に作成する

tasks.mdを作成・修正する際は、以下の原則に従ってください：

実装者の前提

すべてのタスクはAIエージェント（Claude Code等）が実装することを前提とする
人間の開発者ではなく、AIエージェントが理解しやすい表現を使用する
作業時間見積もりはAIエージェントの処理時間として記載する

タスク記述の原則

1. 明確で具体的な指示

AIエージェントが迷わないよう、以下の情報を明記してください：

実装すべきファイルパス
使用する技術やライブラリ
実装の具体的な手順
期待される入出力

良い例：

#### タスク1.1: ユーザー認証APIエンドポイントの実装

**説明**:
`src/api/auth.ts`に以下のエンドポイントを実装する：
- POST /api/auth/login - ユーザーログイン処理
- POST /api/auth/logout - ログアウト処理
- JWTトークンを使用した認証方式
- bcryptでパスワードをハッシュ化

**受入基準**:
- [ ] login/logoutエンドポイントが実装されている
- [ ] JWTトークンが正しく生成・検証される
- [ ] パスワードがbcryptでハッシュ化されている
- [ ] エラーハンドリングが適切に実装されている
- [ ] ユニットテストが実装され、すべて通過する

**依存関係**: なし
**推定工数**: 30分（AIエージェント作業時間）
**ステータス**: `TODO`

悪い例：

#### タスク1.1: 認証機能を作る

**説明**: 認証機能を実装してください

**受入基準**:
- [ ] 認証ができる

**推定工数**: 2時間

2. AIエージェントが理解しやすい構造化

ファイルパス、関数名、クラス名を明記する
技術的な用語を正確に使用する
実装の順序を明確にする
コードの場所を具体的に指定する

3. 作業時間見積もりの基準

AIエージェントの作業時間として、以下を目安に見積もってください：

シンプルな実装: 10-20分
- 単一ファイルの作成
- 基本的な関数の実装
- 設定ファイルの追加
標準的な実装: 20-40分
- 複数ファイルの作成・編集
- APIエンドポイントの実装
- データモデルの定義
- 基本的なテストの作成
複雑な実装: 40-90分
- 複数コンポーネントの統合
- 複雑なロジックの実装
- 包括的なテストの作成
- リファクタリング
非常に複雑な実装: 90分以上
- さらに小さいタスクへの分解を検討する

4. 受入基準の書き方

AIエージェントが検証可能な基準を記載してください：

**受入基準**:
- [ ] `src/components/Button.tsx`ファイルが作成されている
- [ ] Buttonコンポーネントがprops（label, onClick, disabled）を受け取る
- [ ] TypeScriptの型定義が含まれている
- [ ] `src/components/Button.test.tsx`にテストが3つ以上ある
- [ ] すべてのテストが`npm test`で通過する
- [ ] ESLintエラーがゼロである

5. 技術的な文脈の提供

AIエージェントが適切な判断を下せるよう、以下の情報を含めてください：

プロジェクトで使用している技術スタック
コーディング規約やパターン
既存のコードベースとの統合方法
参照すべき既存の実装例

例：

**技術的文脈**:
- フレームワーク: Next.js 14 (App Router)
- スタイリング: Tailwind CSS
- 状態管理: Zustand
- 既存のコンポーネントパターンは`src/components/Card.tsx`を参照

6. エラーハンドリングとテストの明記

すべてのタスクで以下を明記してください：

エラーハンドリングの要件
テストの有無と範囲
バリデーションの要件

タスク分解の粒度

AIエージェント向けのタスクは、以下の粒度を推奨します：

最小単位: 1つのファイルまたは1つの機能
推奨時間: 20-40分程度
最大時間: 90分を超えないこと（超える場合は分解）

依存関係の明示

AIエージェントが正しい順序で作業できるよう：

**依存関係**:
- タスク1.1（データモデルの定義）が完了していること
- `npm install express`が実行済みであること
- 環境変数`.env`に`DATABASE_URL`が設定されていること

10. テスト駆動開発（TDD）の原則

【重要】実装は原則としてTDD（テスト駆動開発）で進める

TDDの基本サイクル

すべての実装タスクは以下のサイクルで進めてください：

テストを書く
- 期待される入出力に基づき、まずテストを作成する
- 実装コードは書かず、テストのみを用意する
テストを実行して失敗を確認する
- テストが正しく失敗することを確認する
- テストが正しいことを確認できた段階でコミットする
実装する
- テストをパスさせる最小限の実装を進める
- 実装中はテストを変更せず、コードを修正し続ける
すべてのテストが通過するまで繰り返す
- テストが通過したら、必要に応じてリファクタリングを行う
- リファクタリング後もテストが通過することを確認する

タスク定義におけるTDDの適用

tasks.mdでタスクを定義する際は、以下のようにTDDのステップを明記してください：

例：

#### タスク1.1: ユーザー認証機能の実装

**説明**:
TDDで`src/auth/authenticate.ts`を実装する

**実装手順（TDD）**:
1. テスト作成: `src/auth/authenticate.test.ts`にテストケースを作成
   - 正常な認証のテスト
   - 無効な認証情報のテスト
   - 空の入力のテスト
2. テスト実行: すべてのテストが失敗することを確認
3. テストコミット: テストのみをコミット
4. 実装: `authenticate.ts`を実装してテストを通過させる
5. 実装コミット: すべてのテストが通過したらコミット

**受入基準**:
- [ ] テストファイル`src/auth/authenticate.test.ts`が存在する
- [ ] テストが3つ以上含まれている
- [ ] 実装前にテストのみのコミットが存在する
- [ ] `src/auth/authenticate.ts`が実装されている
- [ ] すべてのテストが通過する（`npm test`）
- [ ] 実装後のコミットが存在する

**推定工数**: 40分（AIエージェント作業時間）
- テスト作成・コミット: 15分
- 実装・テスト通過・コミット: 25分

TDDのメリット

要件の明確化: テストを書くことで要件が明確になる
品質保証: テストが常に存在するため、リグレッションを防げる
リファクタリングの安全性: テストがあるため、安心してリファクタリングできる
ドキュメント: テストが実装の使用例となる

TDDの注意点

テストファーストを守る: 実装の前に必ずテストを書く
テストのコミットを分ける: テストと実装のコミットを分けることで、レビューしやすくなる
最小限の実装: テストを通すための最小限の実装から始める
テストの変更を避ける: 実装中はテストを変更しない（テストが間違っている場合を除く）

リソース

assets/templates/

requirements_template_ja.md: 日本語の要件定義テンプレート
design_template_ja.md: 日本語の設計テンプレート
tasks_template_ja.md: 日本語のタスクテンプレート

references/

ears_notation_ja.md: EARS記法の完全な日本語リファレンス
examples_ja.md: 3つすべてのドキュメントタイプの日本語例

具体的な支援内容

このスキルが有効な場合、以下のような支援を提供します：

1. ドキュメント初期化

プロジェクトに応じたカスタマイズされたテンプレートでdocsディレクトリを作成します。

2. 要件定義の支援

ユーザーストーリーの作成を支援
EARS記法に従った要件の記述をガイド
要件の曖昧さや不完全性を指摘

3. 設計文書の作成

アーキテクチャ図の作成支援（Mermaid形式）
コンポーネント設計のテンプレート提供
技術的決定事項の文書化支援

4. タスク分解

機能を実装可能なタスクに分解
依存関係の明確化
適切な見積もりのガイダンス

5. レビューと改善

EARS記法への準拠をチェック
ドキュメントの完全性を確認
改善点の提案

拡張可能性

このスキルは将来の機能拡張を考慮して設計されています：

進捗管理: タスクステータスの可視化とレポート生成
自動検証: EARS記法の自動チェックツール
統合機能: GitHub Issues、Jiraなどとの連携
多言語対応: 英語版テンプレートの追加
カスタムテンプレート: プロジェクトタイプ別のテンプレート

よくある質問

Q: なぜdocsディレクトリを使うのですか？ A: docsディレクトリは一般的で、Gitで管理しやすく、他のツールとの互換性が高いためです。

Q: EARS記法は必須ですか？ A: 推奨されますが、プロジェクトのニーズに応じて調整可能です。ただし、EARS記法を使用することで要件の明確性が大幅に向上します。

Q: タスクのステータスはどのように管理しますか？ A: マークダウンファイル内で直接更新します。将来的には自動化ツールの追加も検討しています。

Q: このドキュメント形式の利点は何ですか？ A: 要件・設計・タスクの3つのドキュメントに分けることで、「何を作るか」「どう作るか」「どのように実装するか」が明確に分離され、プロジェクトの見通しが良くなります。

Install Skill

SKILL.md

SDD ドキュメンテーションスキル

概要

このスキルを使用する場面

新規作成時

既存ドキュメントの修正・更新時

ドキュメント初期化の方法

既存ドキュメントの編集方法

要件定義（requirements.md）の修正・追加

設計（design.md）の修正・更新

タスク（tasks.md）の修正・追加

整合性の確認

EARS記法ガイド

基本パターン（日本語版）

要件の例

ドキュメント構造の説明

requirements.md（要件定義書）

design.md（設計書）

tasks.md（タスク管理書）

ワークフロー

検証チェックリスト

要件定義書のチェック項目

設計書のチェック項目

タスク管理書のチェック項目

ベストプラクティス

ユーザーとの対話ガイドライン

1. 推測禁止の原則

2. 選択肢を提示する

3. AskUserQuestionツールの活用

4. 確認が必要な場面

ドキュメント初期化時

要件定義時

設計時

タスク分解時

5. 確認の形式

6. 避けるべき表現

7. 絵文字の使用ルール

8. ドキュメント作成の順序と確認プロセス

作業の流れ

確認の取り方

注意事項

ワークフロー例

9. AIエージェント向けタスク化のガイドライン

実装者の前提

タスク記述の原則

タスク分解の粒度

依存関係の明示

10. テスト駆動開発（TDD）の原則

TDDの基本サイクル

タスク定義におけるTDDの適用

TDDのメリット

TDDの注意点

リソース

assets/templates/

references/

具体的な支援内容

1. ドキュメント初期化

2. 要件定義の支援

3. 設計文書の作成

4. タスク分解

5. レビューと改善

拡張可能性

よくある質問