Collection

---
name: .claude/skills/requirements-documentation/SKILL.md
description: |
  要件ドキュメントの構造化、品質メトリクス、ハンドオフプロトコルを提供します。
  カール・ウィーガーズの要求工学理論に基づき、ステークホルダーと開発チームの両方にとって
  有用なドキュメントを作成します。
  専門分野:
  - ドキュメント構造: 標準テンプレート、必須セクション、品質基準
  - レビュープロセス: ステークホルダーレビュー準備、観点整理、実施プロトコル
  - ハンドオフ: 設計フェーズへの引き継ぎ、パッケージ構成、ミーティング
  - バージョン管理: 変更履歴、アーカイブ、変更要求プロセス
  使用タイミング:
  - 要件定義書、要件仕様書を作成する時
  - 要件ドキュメントの標準構造が必要な時
  - ステークホルダーレビューの準備をする時
  - 設計フェーズへのハンドオフを行う時
  - ドキュメントの品質基準を適用する時
  Use proactively when documenting requirements or preparing for stakeholder reviews.

  📚 リソース参照:
  このスキルには以下のリソースが含まれています。
  必要に応じて該当するリソースを参照してください:

  - `.claude/skills/requirements-documentation/templates/requirements-document-template.md`: 要件定義書の標準テンプレート（セクション構造と記述例）

version: 1.0.0
---

# Requirements Documentation

## 概要

このスキルは、要件ドキュメントの標準構造、品質基準、ハンドオフプロトコルを提供します。
カール・ウィーガーズの要求工学理論に基づき、ステークホルダーと開発チームの両方にとって有用なドキュメントを作成します。

## 適用タイミング

以下の状況でこのスキルを使用してください:

1. **要件定義書作成時**:
   - プロジェクト開始時の要件定義
   - 機能追加時の要件仕様書
   - ドキュメントの標準化

2. **レビュー準備時**:
   - ステークホルダーレビュー前
   - 技術レビュー前
   - 承認プロセス前

3. **ハンドオフ時**:
   - 設計フェーズへの引き継ぎ
   - 実装チームへの引き継ぎ
   - 外部ベンダーへの引き継ぎ

4. **品質保証時**:
   - ドキュメント品質の評価
   - 完全性の確認
   - トレーサビリティの確保

## コア概念

### 1. 要件ドキュメントの標準構造

**推奨テンプレート**:

```markdown
# 要件定義書: [プロジェクト名/機能名]

**バージョン**: 1.0.0
**作成日**: YYYY-MM-DD
**最終更新**: YYYY-MM-DD
**作成者**: [名前]
**レビュー者**: [名前]
**承認者**: [名前]

---

## 1. 概要

### 1.1 目的

[このドキュメントの目的と対象読者]

### 1.2 背景

[プロジェクトの背景、ビジネスゴール]

### 1.3 スコープ

**含まれるもの**:

- [スコープに含まれる機能や領域]

**含まれないもの**:

- [明示的にスコープ外とするもの]

---

## 2. ステークホルダー

### 2.1 プライマリステークホルダー

| ロール                 | 名前   | 責任                   | 連絡先  |
| ---------------------- | ------ | ---------------------- | ------- |
| プロジェクトオーナー   | [名前] | 最終意思決定           | [email] |
| プロダクトマネージャー | [名前] | 要件定義、優先順位付け | [email] |

### 2.2 セカンダリステークホルダー

| ロール       | 名前   | 関与内容           | 連絡先  |
| ------------ | ------ | ------------------ | ------- |
| 開発リーダー | [名前] | 技術実現可能性評価 | [email] |
| QA リーダー  | [名前] | テスト戦略策定     | [email] |

---

## 3. ビジネス要求

### 3.1 ビジネスゴール

[達成したいビジネス上の目標]

### 3.2 成功基準

| 指標     | 目標値 | 測定方法   |
| -------- | ------ | ---------- |
| [KPI 名] | [目標] | [測定方法] |

### 3.3 制約

- **技術制約**: [使用技術、プラットフォーム]
- **スケジュール制約**: [リリース予定日、マイルストーン]
- **予算制約**: [予算上限、リソース制約]
- **法規制**: [準拠すべき法規制、標準]

---

## 4. 機能要件

### FR-001: [機能名]

**優先度**: Must have / Should have / Could have / Won't have

**概要**:
[機能の簡潔な説明]

**詳細**:
[機能の詳細な説明]

**前提条件**:

- [実行前に満たすべき条件]

**入力**:
| 項目 | 型 | 必須 | 制約 | 例 |
|------|-----|------|------|-----|
| [項目名] | [型] | Yes/No | [制約] | [例] |

**出力**:
| 項目 | 型 | 制約 | 例 |
|------|-----|------|-----|
| [項目名] | [型] | [制約] | [例] |

**処理フロー**:

1. [ステップ 1]
2. [ステップ 2]
3. [ステップ 3]

**ビジネスルール**:

- [BR-001]: [ルール記述]

**受け入れ基準**:

**シナリオ 1: [正常系の名前]**

- **Given**: [前提条件]
- **When**: [実行するアクション]
- **Then**: [期待される結果]

**シナリオ 2: [異常系の名前]**

- **Given**: [前提条件]
- **When**: [実行するアクション]
- **Then**: [期待される結果]

**関連要件**: [他の要件とのリンク]

---

## 5. 非機能要件

### NFR-001: パフォーマンス

**カテゴリ**: Performance

**要件**:
[非機能要件の記述]

**測定指標**:
| 指標 | 目標値 | 測定方法 | 測定タイミング |
|------|--------|---------|--------------|
| API 応答時間 | <200ms (95%ile) | APM 監視 | 常時 |
| スループット | >1000 req/sec | 負荷テスト | リリース前 |

**優先度**: High / Medium / Low

**関連機能要件**: FR-001, FR-002

---

## 6. ユースケース

### UC-001: [ユースケース名]

**ID**: UC-001
**アクター**: [プライマリアクター]、[セカンダリアクター]
**ゴール**: [ユーザーが達成したいこと]

**事前条件**:

- [実行前に満たすべき状態]

**基本フロー**（正常系）:

1. [アクター]が[アクション]
2. システムが[応答]
3. ...

**代替フロー**（異常系・分岐）:

- 2a. [条件]の場合: [代替処理]

**例外フロー**（エラー）:

- E1. [エラー条件]: [エラー処理]

**事後条件**:

- [実行後の期待状態]

**関連要件**: FR-001, NFR-001

---

## 7. データモデル

### 7.1 エンティティ定義

**Entity: User**

| 属性名     | 型        | 必須 | 制約                 | 説明           |
| ---------- | --------- | ---- | -------------------- | -------------- |
| id         | UUID      | Yes  | Primary Key          | ユーザー ID    |
| email      | String    | Yes  | Unique, Email Format | メールアドレス |
| name       | String    | Yes  | 1-100 文字           | ユーザー名     |
| created_at | Timestamp | Yes  | Auto                 | 作成日時       |

### 7.2 関連図

[ER 図またはテキストベースの関連記述]

---

## 8. 用語集

| 用語     | 定義   | 補足       |
| -------- | ------ | ---------- |
| [用語 1] | [定義] | [補足説明] |
| [用語 2] | [定義] | [補足説明] |

---

## 9. 前提と依存関係

### 9.1 前提

- [プロジェクトの前提条件]

### 9.2 依存関係

| 要件 ID | 依存先要件 ID | 依存関係の説明            |
| ------- | ------------- | ------------------------- |
| FR-002  | FR-001        | FR-001 の完了後に実装可能 |

---

## 10. リスクと対策

| リスク ID | リスク内容 | 影響度          | 発生確率        | 対策   | 責任者 |
| --------- | ---------- | --------------- | --------------- | ------ | ------ |
| R-001     | [リスク]   | High/Medium/Low | High/Medium/Low | [対策] | [名前] |

---

## 11. 要件追跡マトリクス

| 要件 ID | 機能要件     | 非機能要件 | ユースケース | 受け入れ基準       | ステータス |
| ------- | ------------ | ---------- | ------------ | ------------------ | ---------- |
| FR-001  | ユーザー登録 | NFR-001    | UC-001       | AC-001-1, AC-001-2 | 確定       |
| FR-002  | ログイン     | NFR-002    | UC-002       | AC-002-1           | レビュー中 |

**ステータス定義**:

- **Draft**: 初稿、未レビュー
- **レビュー中**: レビュー依頼済み
- **確定**: レビュー完了、承認済み
- **保留**: 意思決定待ち
- **却下**: スコープ外

---

## 12. レビュー履歴

| 日付       | バージョン | レビュー者 | コメント   | 対応状況 |
| ---------- | ---------- | ---------- | ---------- | -------- |
| YYYY-MM-DD | 0.9        | [名前]     | [コメント] | 対応完了 |

---

## 13. 承認

| ロール                 | 名前   | 署名   | 日付       |
| ---------------------- | ------ | ------ | ---------- |
| プロジェクトオーナー   | [名前] | [署名] | YYYY-MM-DD |
| プロダクトマネージャー | [名前] | [署名] | YYYY-MM-DD |

---

## 付録 A: 画面遷移図

[画面遷移図またはテキストベースの遷移記述]

## 付録 B: API 仕様概要

[API 仕様の概要または詳細仕様書へのリンク]

## 付録 C: 変更履歴

| バージョン | 日付       | 変更者 | 変更内容 |
| ---------- | ---------- | ------ | -------- |
| 1.0.0      | YYYY-MM-DD | [名前] | 初版作成 |
```

### 2. ドキュメント品質基準

**完全性チェックリスト**:

```markdown
## 必須セクション

- [ ] 概要（目的、背景、スコープ）
- [ ] ステークホルダー
- [ ] ビジネス要求（ゴール、成功基準）
- [ ] 機能要件（FR-XXX 形式）
- [ ] 非機能要件（NFR-XXX 形式）
- [ ] 受け入れ基準（Given-When-Then 形式）
- [ ] 用語集
- [ ] 要件追跡マトリクス

## オプションセクション（プロジェクトに応じて）

- [ ] ユースケース
- [ ] データモデル
- [ ] 画面遷移図
- [ ] API 仕様概要
- [ ] リスクと対策

## メタ情報

- [ ] バージョン番号
- [ ] 作成日、最終更新日
- [ ] 作成者、レビュー者、承認者
- [ ] 変更履歴
```

**品質メトリクス**:

```markdown
## ドキュメント品質メトリクス

### 1. 完全性スコア

完全性スコア = (記入済み必須セクション数) / (必須セクション総数) × 100%

目標: 100%

### 2. 詳細度スコア

詳細度スコア = (詳細記述のある要件数) / (全要件数) × 100%

目標: 90%以上

### 3. トレーサビリティスコア

トレーサビリティスコア = (追跡リンクのある要件数) / (全要件数) × 100%

目標: 100%

### 4. 承認率

承認率 = (承認済み要件数) / (全要件数) × 100%

目標: レビュー後 100%

### 5. レビューカバレッジ

レビューカバレッジ = (レビュー済み要件数) / (全要件数) × 100%

目標: 100%
```

### 3. ステークホルダーレビュー準備

**レビュー観点の整理**:

1. **ビジネス観点**:
   - ビジネスゴールとの整合性
   - ROI、コスト効果
   - スケジュールの妥当性

2. **ユーザー観点**:
   - 使いやすさ、学習容易性
   - ユーザーニーズの充足
   - アクセシビリティ

3. **技術観点**:
   - 実現可能性
   - 技術的リスク
   - 保守性、拡張性

4. **テスト観点**:
   - テスト可能性
   - カバレッジの妥当性
   - 受け入れ基準の明確性

**レビュー資料の構成**:

```markdown
## レビュー資料パッケージ

### 1. エグゼクティブサマリー（1-2 ページ）

- プロジェクト概要
- 主要な機能要件（5-7 個）
- 成功基準
- スケジュールとマイルストーン

### 2. 詳細要件ドキュメント（標準テンプレート）

- 完全版の要件定義書

### 3. 要件サマリー表

| 要件 ID | 要件名 | 優先度    | 工数見積 | リスク |
| ------- | ------ | --------- | -------- | ------ |
| FR-001  | [名前] | Must have | 5 人日   | Low    |

### 4. ユースケース図（該当する場合）

- 主要なユースケースの視覚化

### 5. 受け入れ基準一覧

| 要件 ID | シナリオ | Given-When-Then |
| ------- | -------- | --------------- |
| FR-001  | 正常系   | [詳細]          |

### 6. レビューチェックリスト

- レビュー観点ごとのチェック項目

### 7. 未解決事項一覧

| ID    | 事項   | 影響 | 期限   | 担当   |
| ----- | ------ | ---- | ------ | ------ |
| O-001 | [事項] | High | [日付] | [名前] |
```

**レビュー実施プロトコル**:

```markdown
## レビュー実施ガイド

### 事前準備（1 週間前）

1. レビュー資料の配布
2. レビュー観点の共有
3. 質問の事前収集

### レビュー実施（2-3 時間）

1. **イントロダクション（10 分）**:
   - レビューの目的と進め方の説明

2. **概要説明（20 分）**:
   - エグゼクティブサマリーのウォークスルー

3. **詳細レビュー（90-120 分）**:
   - 要件ごとのレビュー
   - 質疑応答
   - 指摘事項の記録

4. **未解決事項の確認（20 分）**:
   - オープンイシューの共有
   - 対応方針の議論

5. **まとめと次ステップ（10 分）**:
   - 承認状況の確認
   - 次のアクションアイテムの明確化

### 事後フォロー（1 週間以内）

1. レビュー議事録の配布
2. 指摘事項の対応
3. 更新版ドキュメントの配布
4. 承認取得
```

### 4. ハンドオフプロトコル

**ハンドオフ情報の構成**:

```markdown
## ハンドオフパッケージ

### 1. 要件ドキュメント一覧

| ドキュメント名 | バージョン | 最終更新日 | パス/URL |
| -------------- | ---------- | ---------- | -------- |
| 要件定義書     | 1.0.0      | YYYY-MM-DD | [パス]   |
| API 仕様書     | 1.0.0      | YYYY-MM-DD | [パス]   |

### 2. 優先順位付けされた要件リスト

| 要件 ID | 要件名 | 優先度    | 依存関係 | 推奨実装順序 |
| ------- | ------ | --------- | -------- | ------------ |
| FR-001  | [名前] | Must have | -        | 1            |
| FR-002  | [名前] | Must have | FR-001   | 2            |

### 3. 未解決事項とリスク

| ID    | 内容         | 影響度 | 対応期限 | 担当者 |
| ----- | ------------ | ------ | -------- | ------ |
| O-001 | [未解決事項] | High   | [日付]   | [名前] |
| R-001 | [リスク]     | Medium | [日付]   | [名前] |

### 4. 前提と制約

- **技術スタック**: [使用技術]
- **環境**: [開発環境、本番環境]
- **スケジュール**: [マイルストーン]
- **リソース**: [チーム構成]

### 5. 次ステップの推奨

- [ ] 設計書作成（推奨開始日: YYYY-MM-DD）
- [ ] プロトタイピング（高リスク機能: FR-XXX）
- [ ] 技術検証（新技術要素: XXX）

### 6. 連絡先一覧

| ロール             | 名前   | 連絡先  | 対応可能時間  |
| ------------------ | ------ | ------- | ------------- |
| 要件定義担当       | [名前] | [email] | 平日 9-18 時  |
| プロダクトオーナー | [名前] | [email] | 平日 10-17 時 |

### 7. FAQ

**Q1: [よくある質問 1]**
A: [回答]

**Q2: [よくある質問 2]**
A: [回答]
```

**ハンドオフミーティング**:

```markdown
## ハンドオフミーティング（1-2 時間）

### アジェンダ

1. **プロジェクト概要（15 分）**:
   - ビジネスゴール、成功基準
   - スコープと制約

2. **要件ウォークスルー（45 分）**:
   - 主要機能要件の説明
   - 非機能要件の確認
   - 受け入れ基準の説明

3. **設計への影響（15 分）**:
   - アーキテクチャへの影響
   - 技術スタックの選定理由
   - パフォーマンス要件への対応方針

4. **未解決事項とリスク（15 分）**:
   - オープンイシューの共有
   - リスク対策の議論

5. **質疑応答（15 分）**:
   - 設計チームからの質問
   - 明確化が必要な点の洗い出し

6. **次ステップの確認（15 分）**:
   - 設計書作成スケジュール
   - レビューポイントの設定
   - コミュニケーション方法の確認
```

### 5. ドキュメント管理とバージョニング

**バージョニング規則**:

```
バージョン形式: Major.Minor.Patch

Major: 大幅な変更（スコープ変更、主要機能追加）
Minor: 中程度の変更（機能修正、非機能要件追加）
Patch: 小規模な変更（誤字修正、明確化）

例:
- 1.0.0: 初版リリース
- 1.1.0: 機能要件3つ追加
- 1.1.1: 用語定義の明確化
- 2.0.0: スコープ大幅変更
```

**変更管理プロセス**:

```markdown
## 変更要求プロセス

### 1. 変更要求の提出

- 変更要求フォームに記入
- 影響範囲の評価
- 優先度の設定

### 2. 変更影響分析

- 関連要件への影響
- スケジュールへの影響
- コストへの影響

### 3. 承認プロセス

- ステークホルダーレビュー
- 意思決定
- 承認/却下の記録

### 4. ドキュメント更新

- 要件ドキュメントの更新
- バージョン番号の更新
- 変更履歴の記録

### 5. 関係者への通知

- 変更内容の通知
- 影響範囲の共有
- 更新版ドキュメントの配布
```

**ドキュメント保管場所**:

```markdown
## ドキュメント管理構造

project-root/
├─ docs/
│ ├─ 00-requirements/
│ │ ├─ requirements-definition.md (要件定義書)
│ │ ├─ use-cases.md (ユースケース)
│ │ ├─ acceptance-criteria.md (受け入れ基準)
│ │ ├─ glossary.md (用語集)
│ │ └─ archive/
│ │ ├─ requirements-definition-v1.0.0.md
│ │ └─ requirements-definition-v1.1.0.md
│ ├─ 01-design/
│ ├─ 02-implementation/
│ └─ 03-testing/
```

## 実践手順

### ステップ 1: テンプレートの準備

**実行タイミング**: プロジェクト開始時、要件定義開始前

**準備内容**:

1. 標準テンプレートの選択（上記の標準構造）
2. プロジェクト固有のカスタマイズ
3. 必須セクション、オプションセクションの決定

**期待される出力**:

```markdown
## プロジェクト固有テンプレート

[標準テンプレートをベースに、プロジェクト固有のセクションを追加]
```

### ステップ 2: ドキュメント作成

**実行タイミング**: 要件定義中

**作成プロセス**:

1. メタ情報の記入（バージョン、作成者等）
2. 概要セクションの作成（目的、背景、スコープ）
3. 機能要件の記述（FR-XXX 形式）
4. 非機能要件の記述（NFR-XXX 形式）
5. 受け入れ基準の作成（Given-When-Then 形式）
6. 追跡マトリクスの作成

**期待される出力**:
完全な要件定義書ドラフト（バージョン 0.9）

### ステップ 3: 品質検証

**実行タイミング**: ドキュメント作成後、レビュー前

**検証プロセス**:

1. 完全性チェックリストで確認
2. 品質メトリクスの計算
3. 不足セクションの補完

**期待される出力**:

```markdown
## 品質検証結果

- 完全性スコア: 100%
- 詳細度スコア: 92%
- トレーサビリティスコア: 100%

レビュー準備完了
```

### ステップ 4: レビュー実施

**実行タイミング**: 品質検証後

**レビュープロセス**:

1. レビュー資料の準備（1 週間前）
2. レビューミーティング実施（2-3 時間）
3. 指摘事項の記録と対応
4. 承認取得

**期待される出力**:

```markdown
## レビュー結果

- レビュー日: YYYY-MM-DD
- レビュー者: [名前]
- 指摘事項: 3 件
- 対応状況: 全件対応完了
- 承認状況: 承認済み

バージョン: 1.0.0（正式版）
```

### ステップ 5: ハンドオフ

**実行タイミング**: レビュー承認後

**ハンドオフプロセス**:

1. ハンドオフパッケージの準備
2. ハンドオフミーティング実施
3. FAQ 作成
4. 次ステップの明確化

**期待される出力**:

```markdown
## ハンドオフ完了

- ハンドオフ日: YYYY-MM-DD
- 引き継ぎ先: 設計チーム
- ハンドオフ資料: 完備
- 次ステップ: 設計書作成開始（YYYY-MM-DD）
```

## ベストプラクティス

### 1. 早期のテンプレート合意

**推奨アプローチ**:

- プロジェクト開始時にテンプレートを合意
- ステークホルダーと必須セクションを確認
- プロジェクト固有のカスタマイズを最小限に

**利点**:

- 全員が同じ構造を期待
- レビューが効率的
- 一貫性の確保

### 2. 段階的なドキュメント作成

**推奨アプローチ**:

- 概要 → 機能要件 → 非機能要件の順に作成
- 各段階でミニレビューを実施
- 早期フィードバックで手戻りを削減

**利点**:

- 大きな手戻りを防止
- 継続的な品質改善
- ステークホルダーの巻き込み

### 3. 自動化の活用

**自動化可能な領域**:

- 品質メトリクスの計算
- トレーサビリティのチェック
- フォーマットの検証

**ツール例**:

```bash
#!/bin/bash
# doc-quality-check.sh

echo "=== ドキュメント品質チェック ==="

# 必須セクションの存在確認
for section in "## 1. 概要" "## 3. 機能要件" "## 5. 非機能要件"; do
  grep -q "$section" requirements.md || echo "Warning: $section が見つかりません"
done

# 要件IDの重複チェック
grep -o "FR-[0-9]*" requirements.md | sort | uniq -d

# トレーサビリティチェック
# (追跡マトリクスの検証ロジック)

echo "=== チェック完了 ==="
```

### 4. バージョン管理の徹底

**推奨アプローチ**:

- すべての版をアーカイブ
- 変更履歴を必ず記録
- 主要変更時にはバージョン番号を更新

**利点**:

- 変更の追跡が容易
- 履歴の参照が可能
- 監査対応

## アンチパターン

### 1. ドキュメントの過剰作成

**問題**: 必要以上に詳細なドキュメントを作成

**影響**:

- 作成時間の浪費
- メンテナンスの困難
- 読者の負担増加

**対策**:

- 必要十分な詳細度に留める
- 対象読者を明確にする
- 「ちょうど良い」ドキュメントを目指す

### 2. レビューのスキップ

**問題**: 時間がないという理由でレビューを省略

**影響**:

- 品質問題の見落とし
- 後工程での手戻り
- ステークホルダーとの認識齟齬

**対策**:

- レビューを必須プロセスとして組み込む
- 段階的なミニレビューで効率化

### 3. ハンドオフの不足

**問題**: ドキュメントを渡すだけで説明不足

**影響**:

- 設計チームの理解不足
- 誤解に基づく設計
- 頻繁な問い合わせ

**対策**:

- ハンドオフミーティングを必須化
- FAQ の事前準備
- 継続的なサポート体制

### 4. バージョン管理の欠如

**問題**: 変更履歴が記録されていない

**影響**:

- 変更の追跡不能
- 過去の意思決定の不明
- 監査対応の困難

**対策**:

- バージョニング規則の徹底
- 変更履歴の必須記録
- アーカイブの整備

## 関連リソース

### 参照スキル

- `.claude/skills/requirements-verification/SKILL.md`: 要件の品質検証
- `.claude/skills/functional-non-functional-requirements/SKILL.md`: 要件分類
- `.claude/skills/use-case-modeling/SKILL.md`: ユースケース記述
- `.claude/skills/acceptance-criteria-writing/SKILL.md`: 受け入れ基準作成
- `.claude/skills/technical-documentation-standards/SKILL.md`: 技術ドキュメント標準

### 推奨書籍

- 『Software Requirements』（Karl Wiegers）: 要件ドキュメントの標準
- 『Writing Effective Use Cases』（Alistair Cockburn）: ユースケース記述

### テンプレート

- 本スキルの標準テンプレート（セクション 1 参照）
- プロジェクト固有テンプレート（カスタマイズ）

## まとめ

このスキルは、要件ドキュメントの作成、レビュー、ハンドオフを体系的に支援します。

**重要なポイント**:

1. **標準構造**: 一貫性のあるテンプレート使用
2. **品質基準**: メトリクスによる定量評価
3. **レビュー準備**: 4 つの観点（ビジネス、ユーザー、技術、テスト）
4. **ハンドオフ**: 完全なパッケージと説明ミーティング
5. **バージョン管理**: 変更履歴の記録とアーカイブ

**成功の鍵**:

- 早期のテンプレート合意
- 段階的な作成と継続的レビュー
- 自動化による効率化
- 徹底したバージョン管理