Requirements Verification

概要

このスキルは、カール・ウィーガーズの要求工学理論に基づく要件検証手法を提供します。 要件の一貫性、整合性、完全性を体系的に評価し、品質を保証するためのフレームワークです。

プロジェクト固有の適用（master_system_design.md 準拠）:

このスキルは以下のプロジェクト要件を反映して要件品質を検証します:

• ハイブリッドアーキテクチャ検証（第4.1, 5.1節）:

  • shared/core: 外部依存ゼロの検証（依存関係ルール）
  • shared/infrastructure: AI、DB、Discord の共通サービス範囲確認
  • features/[機能名]/: 機能間の独立性検証（相互依存禁止）
  • app/: API エンドポイント境界の明確性確認

• TDD準拠性検証（第1.5, 2.4節）:

  • 要件 → ユースケース → テスト → 実装の順序が明記されているか
  • テストピラミッド（静的100% → ユニット60% → 統合 → E2E）への対応
  • 受け入れ基準が Vitest/Playwright テストに変換可能か

• 技術スタック整合性（第3節）:

  • Next.js 15（App Router、Server Actions）への適合性
  • TypeScript strict モード前提の型安全性
  • Drizzle ORM、Turso（SQLite）のデータ設計整合性
  • Zod バリデーションの必須化（features/*/schema.ts）

• 品質メトリクス基準（第2.4節）:

  • 明確性スコア: 90%以上（曖昧性除去）
  • 完全性スコア: 85%以上（CRUD、NFR の網羅）
  • 一貫性スコア: 100%（矛盾ゼロ）
  • 検証可能性スコア: 80%以上（テスト変換可能性）
  • 追跡可能性スコア: 100%（要件ID体系）

適用タイミング

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

1. 要件レビュー時:

   • 要件定義完了後の品質チェック
   • ステークホルダーレビュー前の事前検証
   • 要件ドキュメントの最終検証

2. 矛盾検出時:

   • 複数の要件間で矛盾がないか
   • 機能要件と非機能要件の整合性
   • ユースケースと受け入れ基準の一貫性

3. 完全性評価時:

   • すべての機能がカバーされているか
   • 非機能要件が網羅されているか
   • エラー処理、境界値が考慮されているか

4. 品質評価時:

   • 要件の品質メトリクスの計算
   • 検証可能性の評価
   • テスト可能性の確認

コア概念

1. 一貫性検証（Consistency Verification）

定義: 要件間で矛盾がなく、論理的に整合していること

検証の観点:

1. 機能要件間の一貫性:

   • 同じデータに対する処理が矛盾していないか
   • 画面遷移が論理的か
   • ビジネスルールが一貫しているか

2. 機能要件と非機能要件の整合性:

   • 機能要件が非機能要件の制約内で実現可能か
   • 性能要件とデータ処理要件が矛盾していないか

3. ユースケースと受け入れ基準の一貫性:

   • ユースケースの基本フローが受け入れ基準でカバーされているか
   • 代替フロー、例外フローに対応する受け入れ基準があるか

検証手法:

一貫性チェックリスト:
├─ データの整合性
│  ├─ 同じデータの定義が一貫しているか？
│  ├─ データの単位が統一されているか？
│  └─ データの範囲が矛盾していないか？
├─ ビジネスルールの整合性
│  ├─ 同じ条件で異なる結果を期待していないか？
│  ├─ ビジネスルールが矛盾していないか？
│  └─ 優先順位が明確か？
└─ 画面フローの整合性
   ├─ 画面遷移が論理的か？
   ├─ 戻るフローが定義されているか？
   └─ エラー時の遷移が明確か？

矛盾の例:

• NG: FR-001「ユーザーは削除できる」、FR-002「管理者のみ削除可能」
• OK: FR-001を「ユーザーロールに応じて削除権限が付与される」と統合

2. 完全性検証（Completeness Verification）

定義: すべての必要な要件が漏れなく定義されていること

検証の観点:

1. 機能の完全性:

   • CRUD操作がすべてカバーされているか
   • エラー処理が定義されているか
   • 境界値ケースが考慮されているか

2. 非機能要件の完全性:

   • 性能、スケーラビリティ、セキュリティが定義されているか
   • 可用性、保守性が考慮されているか
   • 互換性、ユーザビリティが明確か

3. 受け入れ基準の完全性:

   • 各機能要件に対応する受け入れ基準があるか
   • 正常系、異常系、境界値がカバーされているか

完全性チェックリスト:

## CRUD操作の完全性

- [ ] Create（作成）: 新規作成の要件
- [ ] Read（参照）: 一覧表示、詳細表示の要件
- [ ] Update（更新）: 編集、更新の要件
- [ ] Delete（削除）: 削除、論理削除の要件

## エラー処理の完全性

- [ ] 入力エラー: バリデーションエラーの処理
- [ ] システムエラー: サーバーエラー、タイムアウトの処理
- [ ] ネットワークエラー: 接続エラー、リトライの処理
- [ ] 権限エラー: 認証、認可エラーの処理

## 非機能要件の完全性

- [ ] パフォーマンス: 応答時間、スループットの定義
- [ ] スケーラビリティ: 同時ユーザー数、データ量の定義
- [ ] セキュリティ: 認証、認可、暗号化の定義
- [ ] 可用性: 稼働率、MTBF、MTTRの定義
- [ ] 保守性: コードの可読性、テストカバレッジの定義
- [ ] ユーザビリティ: 学習容易性、エラー回復の定義
- [ ] 互換性: ブラウザ、OS、デバイスの定義

## 境界値ケースの完全性

- [ ] 最小値: 0件、空、NULLの処理
- [ ] 最大値: 上限値、制限値の処理
- [ ] 特殊文字: 記号、絵文字、全角半角の処理

3. 検証可能性の評価（Verifiability Assessment）

定義: 要件がテスト可能で、客観的に検証できること

評価フレームワーク:

検証可能性の評価:
├─ レベル1: 検証不可能
│  └─ 例: 「使いやすい」「分かりやすい」
├─ レベル2: 主観的
│  └─ 例: 「十分な速度」「適切に処理」
├─ レベル3: 曖昧だが測定可能
│  └─ 例: 「高速な応答」→「応答時間<500ms」に修正可能
├─ レベル4: 測定可能
│  └─ 例: 「応答時間<500ms」
└─ レベル5: 自動テスト可能
   └─ 例: Given-When-Then形式の受け入れ基準

検証可能性の判断基準:

• 要件が具体的な数値、単位で記述されているか？
• 測定方法が明確か？
• 自動テストに変換可能か？
• 合否判定の基準が明確か？

検証可能性の向上例:

• NG: 「システムは高速に応答する」（レベル1-2）
• OK: 「APIは95パーセンタイルで200ms以内に応答する」（レベル4-5）

4. 追跡可能性の確保（Traceability Assurance）

定義: 要件が上流（ビジネスゴール）から下流（テストケース）まで追跡できること

追跡マトリクスの構造:

| 要件ID | 機能要件     | 非機能要件 | ユースケース | 受け入れ基準       | テストケース       |
| ------ | ------------ | ---------- | ------------ | ------------------ | ------------------ |
| FR-001 | ユーザー登録 | NFR-001    | UC-001       | AC-001-1, AC-001-2 | TC-001-1, TC-001-2 |
| FR-002 | ログイン     | NFR-002    | UC-002       | AC-002-1           | TC-002-1           |

追跡可能性チェックリスト:

• すべての機能要件に対応するユースケースがあるか？
• すべての機能要件に対応する受け入れ基準があるか？
• すべての受け入れ基準に対応するテストケースが計画されているか？
• 非機能要件が機能要件と関連付けられているか？

5. 要件品質メトリクス（Requirements Quality Metrics）

測定指標:

1. 明確性スコア（Clarity Score）:

   明確性スコア = (曖昧な表現がない要件数) / (全要件数) × 100%
   
   目標: 90%以上
   

2. 完全性スコア（Completeness Score）:

   完全性スコア = (チェックリスト項目の充足数) / (チェックリスト項目総数) × 100%
   
   目標: 85%以上
   

3. 一貫性スコア（Consistency Score）:

   一貫性スコア = 1 - (矛盾の数) / (要件ペア数)
   
   目標: 矛盾ゼロ
   

4. 検証可能性スコア（Verifiability Score）:

   検証可能性スコア = (レベル4-5の要件数) / (全要件数) × 100%
   
   目標: 80%以上
   

5. 追跡可能性スコア（Traceability Score）:

   追跡可能性スコア = (追跡リンクのある要件数) / (全要件数) × 100%
   
   目標: 100%
   

総合品質スコア:

総合品質スコア = (明確性 + 完全性 + 一貫性 + 検証可能性 + 追跡可能性) / 5

評価基準:
├─ 90%以上: 優秀（Excellent）
├─ 80-89%: 良好（Good）
├─ 70-79%: 要改善（Fair）
└─ 70%未満: 不可（Poor）

実践手順

ステップ1: 一貫性検証

実行タイミング: 要件定義完了後、レビュー前

検証プロセス:

1. 機能要件間の矛盾をチェック
2. 機能要件と非機能要件の整合性をチェック
3. ユースケースと受け入れ基準の一貫性をチェック

検証ツール:

# データ定義の一貫性チェック（例: ユーザー、使用者、利用者の混在）
grep -n "ユーザー\|使用者\|利用者" requirements.md

# 単位の一貫性チェック（例: ms, ミリ秒, msecの混在）
grep -n "ms\|ミリ秒\|msec" requirements.md

期待される出力:

## 一貫性検証結果

### 検出された矛盾

1. FR-001とFR-005の間で削除権限の定義が矛盾
   - 修正案: FR-001を「ロールベースの削除権限」に統合

### 用語の不統一

1. 「ユーザー」「使用者」「利用者」が混在
   - 修正案: 「ユーザー」に統一

一貫性スコア: 95%

ステップ2: 完全性検証

実行タイミング: 一貫性検証後

検証プロセス:

1. CRUDチェックリストで機能の完全性を確認
2. 非機能要件チェックリストで網羅性を確認
3. エラー処理、境界値ケースの完全性を確認

検証ツール:

# 機能要件の識別子をリストアップ
grep "^### FR-" requirements.md

# 非機能要件の識別子をリストアップ
grep "^### NFR-" requirements.md

# エラー処理の定義をチェック
grep -n "エラー\|例外\|失敗" requirements.md

期待される出力:

## 完全性検証結果

### CRUD操作の完全性

- [x] Create: FR-001で定義
- [x] Read: FR-002, FR-003で定義
- [x] Update: FR-004で定義
- [ ] Delete: **未定義**（要追加）

### 非機能要件の完全性

- [x] パフォーマンス: NFR-001で定義
- [x] セキュリティ: NFR-002で定義
- [ ] 可用性: **未定義**（要追加）

完全性スコア: 78%

ステップ3: 検証可能性評価

実行タイミング: 完全性検証後

評価プロセス:

1. 各要件の検証可能性レベルを評価
2. レベル1-2の要件を特定し、改善案を提示
3. レベル4-5の要件の比率を計算

検証ツール:

# 曖昧な表現の検出（レベル1-2）
grep -n "使いやすい\|分かりやすい\|適切に\|効率的" requirements.md

# 定量的表現の検出（レベル4-5）
grep -n "[0-9]" requirements.md

期待される出力:

## 検証可能性評価結果

### レベル1-2の要件（要改善）

1. FR-003: 「使いやすいUI」
   - 改善案: 「3クリック以内で目的の操作が完了」

2. NFR-001: 「高速な応答」
   - 改善案: 「API応答時間<200ms（95パーセンタイル）」

### レベル4-5の要件

- FR-001: 「ユーザー登録時間<5秒」
- NFR-002: 「稼働率>99.9%」

検証可能性スコア: 75%
目標: 80%以上

ステップ4: 追跡可能性の確保

実行タイミング: 検証可能性評価後

確保プロセス:

1. 要件追跡マトリクスの作成
2. 機能要件→ユースケース→受け入れ基準のリンクを確認
3. 未リンクの要件を特定

期待される出力:

## 追跡可能性マトリクス

| 要件ID | 機能要件         | ユースケース | 受け入れ基準       | カバレッジ |
| ------ | ---------------- | ------------ | ------------------ | ---------- |
| FR-001 | ユーザー登録     | UC-001       | AC-001-1, AC-001-2 | 100%       |
| FR-002 | ログイン         | UC-002       | AC-002-1           | 100%       |
| FR-003 | プロフィール編集 | **未定義**   | **未定義**         | 0%         |

追跡可能性スコア: 67%
目標: 100%

ステップ5: 総合品質評価

実行タイミング: すべての検証完了後

評価プロセス:

1. 各品質メトリクスのスコアを集計
2. 総合品質スコアを計算
3. 改善が必要な領域を特定

期待される出力:

## 総合品質評価

### 品質メトリクス

- 明確性スコア: 92%
- 完全性スコア: 78%
- 一貫性スコア: 95%
- 検証可能性スコア: 75%
- 追跡可能性スコア: 67%

### 総合品質スコア

**81%（良好 - Good）**

### 改善が必要な領域

1. 追跡可能性（67% → 目標100%）
   - FR-003にユースケースと受け入れ基準を追加
2. 完全性（78% → 目標85%）
   - Delete操作の要件を追加
   - 可用性の非機能要件を追加
3. 検証可能性（75% → 目標80%）
   - FR-003の「使いやすいUI」を定量化

ベストプラクティス

1. 検証のタイミング

推奨タイミング:

• 要件定義の各フェーズ完了時
• ステークホルダーレビュー前
• 設計フェーズ移行前

避けるべきタイミング:

• 要件が未確定の段階
• 大量の変更が予想される段階

2. 段階的な検証

第1段階: 一貫性検証（矛盾の早期検出） 第2段階: 完全性検証（漏れの特定） 第3段階: 検証可能性評価（テスト可能性の確保） 第4段階: 追跡可能性の確保（上流から下流への接続） 第5段階: 総合品質評価（全体の品質判定）

3. 自動化の活用

検証スクリプトの例:

#!/bin/bash
# requirements-verification.sh

echo "=== 要件検証開始 ==="

# 一貫性チェック: 用語の不統一
echo "1. 用語の一貫性チェック..."
grep -n "ユーザー\|使用者\|利用者" requirements.md

# 完全性チェック: 非機能要件の網羅性
echo "2. 非機能要件の完全性チェック..."
grep -c "^### NFR-" requirements.md

# 検証可能性チェック: 曖昧な表現
echo "3. 曖昧な表現の検出..."
grep -n "使いやすい\|分かりやすい\|適切に" requirements.md

# 追跡可能性チェック: リンク切れ
echo "4. 追跡リンクのチェック..."
# (追跡マトリクスの検証ロジック)

echo "=== 検証完了 ==="

4. チェックリスト駆動検証

推奨アプローチ:

• 標準チェックリストを用意
• プロジェクト固有の項目を追加
• チェックリストの結果を記録
• 継続的に改善

チェックリストの例:

## 要件検証チェックリスト

### 一貫性

- [ ] 用語が統一されている
- [ ] 単位が統一されている
- [ ] データ定義が一貫している
- [ ] ビジネスルールに矛盾がない

### 完全性

- [ ] CRUD操作がすべて定義されている
- [ ] エラー処理が定義されている
- [ ] 非機能要件が網羅されている
- [ ] 境界値ケースが考慮されている

### 検証可能性

- [ ] 曖昧な表現がない（目標90%以上）
- [ ] 定量的な基準がある（目標80%以上）
- [ ] Given-When-Then形式の受け入れ基準がある

### 追跡可能性

- [ ] すべての要件にIDがある
- [ ] 機能要件→ユースケースのリンクがある
- [ ] 機能要件→受け入れ基準のリンクがある

アンチパターン

1. 検証のスキップ

問題: 時間がないという理由で検証をスキップ

影響:

• 設計・実装フェーズでの手戻り
• テスト工数の増大
• 品質問題の発生

対策:

• 検証を必須プロセスとして組み込む
• 自動化により検証時間を短縮

2. 主観的な評価

問題: 「たぶん大丈夫」「だいたい良い」といった主観的判断

影響:

• 品質のばらつき
• レビューの非効率
• 問題の見落とし

対策:

• 品質メトリクスによる定量評価
• チェックリストによる体系的検証

3. 部分的な検証

問題: 一貫性だけ、完全性だけなど、一部の観点のみ検証

影響:

• 他の観点での品質問題
• 総合的な品質保証の欠如

対策:

• 5つの観点（一貫性、完全性、検証可能性、追跡可能性、総合評価）をすべて実施

4. 検証結果の放置

問題: 検証で問題を検出したが、修正しない

影響:

• 品質問題の蓄積
• 後工程での大幅な手戻り

対策:

• 検出された問題の修正を必須化
• 修正完了まで次工程に進まない

関連リソース

参照スキル

• .claude/skills/acceptance-criteria-writing/SKILL.md: Given-When-Then形式の受け入れ基準作成
• .claude/skills/functional-non-functional-requirements/SKILL.md: 要件分類の詳細
• .claude/skills/use-case-modeling/SKILL.md: ユースケース記述の詳細

推奨書籍

• 『Software Requirements』（Karl Wiegers）: 要件検証の理論と実践
• 『Requirements Engineering』（Klaus Pohl）: 要件品質の評価手法

ツール

• 要件管理ツール: Jira, Azure DevOps
• 検証スクリプト: bash, Python
• 品質メトリクス計算: Excel, Google Sheets

まとめ

このスキルは、要件の品質を体系的に評価し、保証するためのフレームワークを提供します。

重要なポイント:

1. 5つの観点: 一貫性、完全性、検証可能性、追跡可能性、総合評価
2. 定量的評価: 品質メトリクスによる客観的な評価
3. 段階的な検証: 矛盾検出→漏れ検出→テスト可能性確保の順序
4. 自動化: 検証スクリプトによる効率化
5. 継続的改善: チェックリストとメトリクスの継続的な改善

成功の鍵:

• 検証を必須プロセスとして組み込む
• 品質メトリクスで定量的に評価する
• 検出された問題を確実に修正する
• 検証プロセス自体も継続的に改善する