Requirements Documentation

概要

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

適用タイミング

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

1. 要件定義書作成時:

   • プロジェクト開始時の要件定義
   • 機能追加時の要件仕様書
   • ドキュメントの標準化

2. レビュー準備時:

   • ステークホルダーレビュー前
   • 技術レビュー前
   • 承認プロセス前

3. ハンドオフ時:

   • 設計フェーズへの引き継ぎ
   • 実装チームへの引き継ぎ
   • 外部ベンダーへの引き継ぎ

4. 品質保証時:

   • ドキュメント品質の評価
   • 完全性の確認
   • トレーサビリティの確保

コア概念

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

推奨テンプレート:

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

**バージョン**: 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. ドキュメント品質基準

完全性チェックリスト:

## 必須セクション

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

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

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

## メタ情報

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

品質メトリクス:

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

### 1. 完全性スコア

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

目標: 100%

### 2. 詳細度スコア

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

目標: 90%以上

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

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

目標: 100%

### 4. 承認率

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

目標: レビュー後 100%

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

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

目標: 100%

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

レビュー観点の整理:

1. ビジネス観点:

   • ビジネスゴールとの整合性
   • ROI、コスト効果
   • スケジュールの妥当性

2. ユーザー観点:

   • 使いやすさ、学習容易性
   • ユーザーニーズの充足
   • アクセシビリティ

3. 技術観点:

   • 実現可能性
   • 技術的リスク
   • 保守性、拡張性

4. テスト観点:

   • テスト可能性
   • カバレッジの妥当性
   • 受け入れ基準の明確性

レビュー資料の構成:

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

### 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 | [日付] | [名前] |

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

## レビュー実施ガイド

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

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

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

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

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

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

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

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

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

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

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

ハンドオフ情報の構成:

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

### 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: [回答]

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

## ハンドオフミーティング（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: スコープ大幅変更

変更管理プロセス:

## 変更要求プロセス

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

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

### 2. 変更影響分析

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

### 3. 承認プロセス

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

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

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

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

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

ドキュメント保管場所:

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

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. 必須セクション、オプションセクションの決定

期待される出力:

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

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

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

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

作成プロセス:

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

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

ステップ 3: 品質検証

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

検証プロセス:

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

期待される出力:

## 品質検証結果

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

レビュー準備完了

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

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

レビュープロセス:

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

期待される出力:

## レビュー結果

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

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

ステップ 5: ハンドオフ

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

ハンドオフプロセス:

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

期待される出力:

## ハンドオフ完了

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

ベストプラクティス

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

推奨アプローチ:

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

利点:

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

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

推奨アプローチ:

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

利点:

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

3. 自動化の活用

自動化可能な領域:

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

ツール例:

#!/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. バージョン管理: 変更履歴の記録とアーカイブ

成功の鍵:

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