Collection

---
name: .claude/skills/ambiguity-elimination/SKILL.md
description: |
  曖昧性検出と除去スキル。定性的・不明確な表現を具体的・測定可能な要件に変換します。

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

  - `.claude/skills/ambiguity-elimination/resources/ambiguity-patterns.md`: 5つの曖昧性パターンの詳細な検出・除去手法と実践例（300行超）
  - `.claude/skills/ambiguity-elimination/templates/clarification-checklist.md`: 曖昧性を明確化するための体系的な質問チェックリスト
  - `.claude/skills/ambiguity-elimination/scripts/detect-ambiguity.mjs`: 要件ドキュメントから曖昧性を自動検出するNode.jsスクリプト

  使用タイミング:
  - 要件に「速い」「多い」「適切に」などの曖昧な表現がある時
  - 定量化が必要な非機能要件の記述時
  - 「など」「等」で範囲が不明確な時
  - 条件や主体が曖昧な要件の明確化時

  Apply when: ambiguous requirements, qualitative expressions, vague terms, unclear scope
version: 1.0.0
---

# Ambiguity Elimination

## 概要

このスキルは、カール・ウィーガーズの要求工学理論に基づく曖昧性検出と除去の体系的手法を提供します。
定性的・不明確な表現を具体的で測定可能な要件に変換するためのパターンと技法を収録しています。

## 曖昧性の5つのパターン

### パターン1: 量的曖昧性（Quantitative Ambiguity）

**定義**:
数値や量を表す表現が具体的でない状態。

**検出キーワード**:

- 「高速」「速い」「遅い」
- 「多い」「少ない」「大量」
- 「頻繁に」「たまに」「しばしば」
- 「大きい」「小さい」「軽い」
- 「高い」「低い」（パフォーマンス、コスト等）

**除去手法**:

1. **具体的な数値と単位を要求**:

   ```
   曖昧: 「高速な応答」
   明確: 「API応答時間<200ms（95パーセンタイル）」

   曖昧: 「大量のデータを処理」
   明確: 「1秒あたり10,000レコードを処理」

   曖昧: 「頻繁にバックアップ」
   明確: 「1時間ごとに自動バックアップ」
   ```

2. **パーセンタイルと分布を明示**:

   ```
   曖昧: 「ほとんどのリクエストは速い」
   明確: 「95パーセンタイルで応答時間<500ms、99パーセンタイルで<1s」
   ```

3. **範囲と条件を明示**:
   ```
   曖昧: 「多くのユーザーが同時にアクセス」
   明確: 「同時接続ユーザー数1,000-10,000人をサポート」
   ```

**質問技法**:

- 「どのくらい速ければ良いですか？（具体的な時間）」
- 「どの程度の量を想定していますか？（具体的な数）」
- 「どのくらいの頻度ですか？（時間単位、回数）」
- 「それをどうやって測定しますか？」

### パターン2: 質的曖昧性（Qualitative Ambiguity）

**定義**:
品質や状態を表す形容詞が測定不可能な状態。

**検出キーワード**:

- 「使いやすい」「分かりやすい」「簡単」
- 「適切に」「正しく」「うまく」
- 「効率的」「効果的」「最適」
- 「安定した」「信頼性の高い」
- 「柔軟な」「拡張可能な」

**除去手法**:

1. **測定可能な基準を定義**:

   ```
   曖昧: 「使いやすいUI」
   明確: 「新規ユーザーが3クリック以内で目的の操作を完了できる」

   曖昧: 「分かりやすいエラーメッセージ」
   明確: 「エラーメッセージに具体的な原因と解決手順を含む」

   曖昧: 「安定したシステム」
   明確: 「稼働率99.9%（月間ダウンタイム<43分）」
   ```

2. **ユーザー行動を基準にする**:

   ```
   曖昧: 「直感的な操作」
   明確: 「チュートリアルなしで80%のユーザーが5分以内に基本操作を習得」
   ```

3. **具体的なシナリオを記述**:
   ```
   曖昧: 「柔軟な設定」
   明確: 「管理者が画面上で以下の項目を変更可能：ロゴ、配色、メニュー構成」
   ```

**質問技法**:

- 「『使いやすい』とは、具体的にどのような状態ですか？」
- 「それをどうやって確認しますか？」
- 「ユーザーがどのような行動をとれば『適切』と言えますか？」
- 「測定可能な指標はありますか？」

### パターン3: 範囲の曖昧性（Scope Ambiguity）

**定義**:
対象範囲が「など」「等」で省略され、完全に列挙されていない状態。

**検出キーワード**:

- 「など」「等」「その他」
- 「いくつかの」「さまざまな」
- 「主な」「代表的な」
- 「複数の」（具体的な数がない）

**除去手法**:

1. **完全な列挙**:

   ```
   曖昧: 「画像ファイルなど」
   明確: 「.jpg, .png, .gif, .webp（最大10MB）」

   曖昧: 「主要なブラウザ」
   明確: 「Chrome 90+, Firefox 88+, Safari 14+, Edge 90+」
   ```

2. **パターンの明示**:

   ```
   曖昧: 「各種レポート」
   明確: 「日次レポート、週次レポート、月次レポート、カスタム期間レポート」

   曖昧: 「いくつかの通知方法」
   明確: 「Email、Slack、Webhook（最大5つまで同時設定可能）」
   ```

3. **除外項目の明示**:
   ```
   曖昧: 「一般的なファイル形式をサポート」
   明確: 「サポート: PDF, Word, Excel, PowerPoint / 非サポート: 実行ファイル(.exe), スクリプト(.sh)」
   ```

**質問技法**:

- 「『など』には他に何が含まれますか？」
- 「すべてのケースを列挙できますか？」
- 「含まないものは何ですか？」
- 「上限はありますか？」

### パターン4: 条件の曖昧性（Conditional Ambiguity）

**定義**:
動作の条件が「場合によって」「必要に応じて」など不明確な状態。

**検出キーワード**:

- 「場合によって」「状況次第で」
- 「必要に応じて」「適宜」
- 「時には」「場合がある」
- 「可能であれば」「できれば」

**除去手法**:

1. **すべての条件を列挙**:

   ```
   曖昧: 「必要に応じてログ出力」
   明確: 「以下の条件でログ出力:
           - エラー発生時（ERROR level）
           - API応答時間>1s（WARN level）
           - メモリ使用率>80%（WARN level）
           - デバッグモード有効時（DEBUG level）」

   曖昧: 「場合によってメール通知」
   明確: 「以下の条件でメール通知:
           - 支払い完了時
           - 注文キャンセル時
           - システムエラー（管理者のみ）」
   ```

2. **条件式で表現**:

   ```
   曖昧: 「状況次第で承認が必要」
   明確: 「承認が必要な条件:
           - 金額 >= 10万円 AND 申請者 != 部長
           - カテゴリ == '資産購入'
           - 前月の予算超過率 > 10%」
   ```

3. **デフォルト動作の明示**:
   ```
   曖昧: 「可能であればキャッシュを使用」
   明確: 「デフォルト: キャッシュを使用（TTL=5分）
           キャッシュ無効化の条件:
           - クエリパラメータに?nocache=true
           - 管理者によるデータ更新後5秒以内」
   ```

**質問技法**:

- 「具体的にはどのような状況ですか？」
- 「すべての条件を列挙できますか？」
- 「条件が満たされない場合はどうなりますか？」
- 「デフォルトの動作は何ですか？」

### パターン5: 主体の曖昧性（Subject Ambiguity）

**定義**:
誰が・何がアクションを行うのかが不明確な状態。

**検出キーワード**:

- 「ユーザーは」（どのユーザー？）
- 「システムは」（どのコンポーネント？）
- 「管理者は」（どの権限レベル？）
- 「自動的に」（何がトリガー？）

**除去手法**:

1. **具体的なアクターを特定**:

   ```
   曖昧: 「ユーザーは削除できる」
   明確: 「管理者ロールのユーザーは、自分が作成したレコードを削除できる」

   曖昧: 「システムは自動的にバックアップ」
   明確: 「cron jobが毎日午前2時にSQLiteのバックアップを実行」
   ```

2. **権限レベルを明示**:

   ```
   曖昧: 「管理者は設定を変更できる」
   明確: 「システム管理者: すべての設定を変更可能
           組織管理者: 自組織のユーザー設定のみ変更可能
           一般ユーザー: 自分のプロフィール設定のみ変更可能」
   ```

3. **トリガーと責任を明確化**:
   ```
   曖昧: 「データは定期的に同期される」
   明確: 「AWS EventBridgeが15分ごとにLambda関数をトリガー、
           Lambda関数がサードパーティAPIからデータを取得し、
           RDSに保存」
   ```

**質問技法**:

- 「具体的に誰が行いますか？」
- 「どの権限レベルのユーザーですか？」
- 「自動実行のトリガーは何ですか？」
- 「責任者は誰ですか？」

## 曖昧性除去のワークフロー

### ステップ1: 曖昧性の検出

**実行内容**:

1. 要件ドキュメントを読む
2. 5つのパターンのキーワードを検索
3. 検出された曖昧性をリストアップ

**ツール**:

```bash
# 量的曖昧性の検出
grep -E "高速|速い|多い|大量|頻繁|大きい" requirements.md

# 質的曖昧性の検出
grep -E "使いやすい|適切に|効率的|安定" requirements.md

# 範囲の曖昧性の検出
grep -E "など|等|その他|いくつかの" requirements.md

# 条件の曖昧性の検出
grep -E "場合によって|必要に応じて|状況次第|可能であれば" requirements.md
```

**成果物**:

```markdown
## 検出された曖昧性

| 箇所    | パターン | 曖昧な表現           |
| ------- | -------- | -------------------- |
| FR-001  | 量的     | 「高速な応答」       |
| FR-003  | 範囲     | 「画像ファイルなど」 |
| NFR-002 | 質的     | 「使いやすいUI」     |
```

### ステップ2: 明確化の質問設計

**実行内容**:

1. 各曖昧性に対する質問を作成
2. ステークホルダーに確認
3. 回答を記録

**質問例**:

```markdown
## FR-001「高速な応答」について

- Q1: 「高速」とは具体的に何ミリ秒ですか？
- Q2: すべてのAPIエンドポイントで同じ基準ですか？
- Q3: 95パーセンタイル？99パーセンタイル？
- Q4: 測定方法は？（サーバー側？クライアント側？）
```

### ステップ3: 具体的な要件への変換

**実行内容**:

1. 回答を基に要件を再記述
2. 測定可能な基準を追加
3. レビューとフィードバック

**変換例**:

```markdown
## Before（曖昧）

「システムは高速に応答し、使いやすいUIを提供する。
画像ファイルなどをアップロードでき、必要に応じてログを出力する。」

## After（明確）

「システムは以下の性能要件を満たす:

- API応答時間: 95パーセンタイルで<200ms、99パーセンタイルで<500ms
- UIの使いやすさ: 新規ユーザーが3クリック以内で基本操作を完了

ファイルアップロード機能:

- サポート形式: .jpg, .png, .gif, .webp
- ファイルサイズ: 最大10MB
- 非サポート: 実行ファイル(.exe), スクリプト(.sh, .bat)

ログ出力条件:

- ERROR level: すべてのエラー
- WARN level: API応答時間>1s、メモリ使用率>80%
- INFO level: ユーザーアクション（ログイン、ログアウト等）
- DEBUG level: デバッグモード有効時のみ」
```

### ステップ4: 検証と確認

**実行内容**:

1. 変換後の要件をステークホルダーに提示
2. 測定可能性を確認
3. テスト可能性を確認

**検証チェックリスト**:

- [ ] すべての曖昧な表現が除去されているか？
- [ ] 数値が具体的に記述されているか？
- [ ] 測定方法が明示されているか？
- [ ] テストケースに変換可能か？

## 実践例

### 例1: パフォーマンス要件の明確化

**Before（曖昧）**:

```markdown
NFR-001: システムは高速に動作し、大量のリクエストを処理できること。
```

**曖昧性分析**:

- 「高速」→ 量的曖昧性（具体的な時間がない）
- 「大量」→ 量的曖昧性（具体的な数がない）

**質問**:

- Q1: 「高速」とは何ミリ秒ですか？
- Q2: どのAPIエンドポイントですか？
- Q3: 「大量」とは何リクエスト/秒ですか？
- Q4: ピーク時の同時接続数は？

**After（明確）**:

```markdown
NFR-001: パフォーマンス要件

**応答時間**:

- GET /api/users: 95パーセンタイルで<100ms
- POST /api/orders: 95パーセンタイルで<300ms
- GET /api/reports: 95パーセンタイルで<2s

**スループット**:

- 通常時: 1,000 req/sec
- ピーク時: 5,000 req/sec（3ヶ月後）

**同時接続**:

- WebSocket接続: 10,000同時接続をサポート

**測定方法**:

- New Relicでサーバー側の応答時間を計測
- 95パーセンタイル値で評価
```

### 例2: セキュリティ要件の明確化

**Before（曖昧）**:

```markdown
NFR-002: システムは適切なセキュリティ対策を実施すること。
```

**曖昧性分析**:

- 「適切な」→ 質的曖昧性（具体的な基準がない）
- 「セキュリティ対策」→ 範囲の曖昧性（何を含むか不明）

**質問**:

- Q1: 「適切な」とは、どの標準に準拠しますか？
- Q2: 具体的にどのようなセキュリティ対策ですか？
- Q3: 優先度の高い脅威は何ですか？

**After（明確）**:

```markdown
NFR-002: セキュリティ要件

**認証**:

- JWT（JSON Web Token）を使用
- トークン有効期限: 1時間
- リフレッシュトークン: 30日

**認可**:

- RBAC（Role-Based Access Control）
- ロール: システム管理者、組織管理者、一般ユーザー

**通信の暗号化**:

- すべてのHTTP通信をHTTPS（TLS 1.2以上）
- データベース接続もSSL/TLS

**パスワードポリシー**:

- 最小8文字
- 大文字、小文字、数字、記号を各1文字以上含む
- bcryptでハッシュ化（cost factor=12）

**セッション管理**:

- 30分間操作がない場合は自動ログアウト
- 同時ログインセッション数: 最大3

**監査ログ**:

- すべてのログイン試行を記録
- データ変更操作（作成、更新、削除）を記録
- ログ保存期間: 1年
```

### 例3: ユーザビリティ要件の明確化

**Before（曖昧）**:

```markdown
NFR-003: UIは使いやすく、直感的であること。
```

**曖昧性分析**:

- 「使いやすく」→ 質的曖昧性（測定不可能）
- 「直感的」→ 質的曖昧性（測定不可能）

**質問**:

- Q1: 「使いやすい」を何で測定しますか？
- Q2: 新規ユーザーの学習時間はどのくらいですか？
- Q3: タスク完了までのクリック数は？

**After（明確）**:

```markdown
NFR-003: ユーザビリティ要件

**学習容易性**:

- 新規ユーザーが5分以内に基本操作（ログイン、データ閲覧、簡単な編集）を習得
- チュートリアルなしで80%のユーザーが基本操作を完了

**効率性**:

- 頻繁に使う操作（データ検索、フィルタリング）は3クリック以内
- キーボードショートカットを主要操作10個に提供

**エラー回復**:

- すべてのフォームに「やり直し」ボタン
- データ削除前に確認ダイアログを表示
- エラーメッセージに具体的な解決手順を含む

**アクセシビリティ**:

- WCAG 2.1レベルAA準拠
- キーボードのみで全操作が可能
- スクリーンリーダー対応（ARIA属性）

**測定方法**:

- ユーザビリティテスト（被験者5名以上）
- タスク完了時間とエラー率を計測
- SUS（System Usability Scale）スコア70点以上
```

## 品質チェックリスト

曖昧性除去完了前に以下を確認:

**検出の網羅性**:

- [ ] 5つのパターンすべてでキーワード検索を実行したか？
- [ ] 検出された曖昧性がすべてリストアップされているか？

**明確化の具体性**:

- [ ] すべての数値に単位が付いているか？
- [ ] 「など」「等」が完全に列挙されているか？
- [ ] 条件がすべて明示されているか？
- [ ] 主体（誰が・何が）が明確か？

**測定可能性**:

- [ ] すべての非機能要件が測定可能か？
- [ ] 測定方法が記述されているか？
- [ ] 目標値が具体的か？

**テスト可能性**:

- [ ] 各要件が受け入れ基準に変換可能か？
- [ ] Given-When-Thenで記述できるか？

## 関連スキル

このスキルは以下のスキルと連携します:

- **.claude/skills/requirements-triage/SKILL.md**: トリアージ前に曖昧性を除去
- **.claude/skills/acceptance-criteria-writing/SKILL.md**: 明確化後に受け入れ基準を作成
- **.claude/skills/functional-non-functional-requirements/SKILL.md**: 明確化後に要件を分類

## 参考文献

- Karl Wiegers『Software Requirements』: 曖昧性の検出と除去手法
- Alistair Cockburn『Writing Effective Use Cases』: 明確なユースケース記述
- ISO/IEC/IEEE 29148: 要件の品質特性（明確性、一貫性、検証可能性）