# EARS フォーマットガイドライン

## 概要
EARS（Easy Approach to Requirements Syntax）は、要件定義書でテスト可能かつ検証可能な受入基準を記述するための標準化されたフォーマットです。すべての要件において明確性、一貫性、テスト可能性を保証します。

## なぜEARSを使うのか？

従来の要件定義には以下の問題があります：
- ❌ 曖昧な表現（「〜すべき」「〜かもしれない」「適切に」）
- ❌ テスト不可能な記述（「使いやすい」「高速」「信頼性が高い」）
- ❌ コンテキストの欠如（いつ適用されるのか？）
- ❌ 1つの要件に複数の振る舞いを含む

EARSはこれらの問題を、明確性を強制する構造化されたパターンで解決します。

## 5つのEARSパターン

### 1. イベント駆動要件
**パターン**: `WHEN [イベント], the [システム] SHALL [応答/動作]`

**使用例**: 特定のイベントやトリガーへの応答

**例**:
```
✅ WHEN ユーザーが「送信」ボタンをクリックする, the Order System SHALL すべてのフォームフィールドを検証する
✅ WHEN 支払いが受領される, the Notification Service SHALL 確認メールを送信する
✅ WHEN APIレート制限を超過する, the Gateway SHALL HTTP 429ステータスを返す

❌ 悪い例: 「システムはフォームを検証すべき」（イベントトリガーが欠如）
❌ 悪い例: 「ユーザーが送信すると、検証が行われる」（SHALLでない、主体が不明確）
```

**重要ポイント**:
- 常にWHENで開始
- トリガーイベントを明確に特定
- 必須動作にはSHALLを使用
- システム/サービスを明示的に命名

### 2. 状態駆動要件
**パターン**: `WHILE [前提条件/状態], the [システム] SHALL [応答/動作]`

**使用例**: システムの状態や前提条件に依存する振る舞い

**例**:
```
✅ WHILE 支払い処理中である, the Checkout UI SHALL ローディングインジケーターを表示する
✅ WHILE ユーザーがログアウト状態である, the Dashboard SHALL ログインページにリダイレクトする
✅ WHILE 在庫が最小閾値を下回っている, the System SHALL 新規注文を防止する

❌ 悪い例: 「処理中はローディングを表示」（WHILEを継続状態に使用）
❌ 悪い例: 「在庫が少ないとき、システムは注文をブロックする」（SHALLでない）
```

**重要ポイント**:
- 継続的な状態/条件にはWHILEを使用
- 状態中の振る舞いを記述
- 状態は観察可能/テスト可能でなければならない

### 3. 望ましくない振る舞い要件（エラー処理）
**パターン**: `IF [トリガー/エラー条件], THEN the [システム] SHALL [応答/動作]`

**使用例**: エラー、障害、望ましくない状況へのシステム応答

**例**:
```
✅ IF 無効なクレジットカード番号が入力される, THEN the Payment Form SHALL 「無効なカード番号」エラーを表示する
✅ IF データベース接続が失敗する, THEN the API SHALL retry-afterヘッダー付きHTTP 503を返す
✅ IF ユーザーが3回誤ったパスワードを入力する, THEN the Auth System SHALL アカウントを30分間ロックする

❌ 悪い例: 「エラーを適切に処理する」（具体性が不足）
❌ 悪い例: 「エラー時、メッセージを表示」（どのエラー？どのメッセージ？）
```

**重要ポイント**:
- エラーシナリオにはIF...THENを使用
- エラー条件について具体的に記述
- 正確なエラー応答を定義

### 4. オプション機能要件
**パターン**: `WHERE [機能が含まれる/有効である], the [システム] SHALL [応答/動作]`

**使用例**: オプション、条件付き、または設定可能な機能の要件

**例**:
```
✅ WHERE ダークモードが有効である, the UI SHALL ダークカラースキームを使用する
✅ WHERE プレミアムサブスクリプションが有効である, the App SHALL 高度な分析機能を有効にする
✅ WHERE A/Bテストバリアント Bが割り当てられている, the Homepage SHALL 代替ヒーロー画像を表示する

❌ 悪い例: 「プレミアムなら分析を表示」（設定/機能にはWHEREを使用）
❌ 悪い例: 「プレミアムユーザーは分析が見られる」（SHALLでない、振る舞いが不明確）
```

**重要ポイント**:
- 機能フラグ/設定にはWHEREを使用
- IF（エラー）やWHILE（状態）とは異なる
- オプション機能を記述

### 5. 普遍的要件（常に有効）
**パターン**: `The [システム] SHALL [応答/動作]`

**使用例**: 常に有効な要件と基本的なシステム特性

**例**:
```
✅ The User Service SHALL bcrypt（コストファクター12）を使用してパスワードを暗号化する
✅ The API SHALL 95パーセンタイル要求に対して200ms以内に応答する
✅ The Mobile App SHALL iOS 14以上をサポートする

❌ 悪い例: 「パスワードは暗号化すべき」（SHALLを使用、「すべき」でない）
❌ 悪い例: 「アプリは高速である」（測定不可能）
```

**重要ポイント**:
- 条件接頭辞なし（常に有効）
- 基本的特性に使用
- テスト可能でなければならない

## 複合パターン

複雑な要件には、パターンを組み合わせることができます：

```
✅ WHILE ユーザーが認証済みである, WHEN ログアウトボタンがクリックされる, the Auth Service SHALL セッショントークンを無効化する
✅ WHERE 二要素認証が有効である, IF 誤ったOTPが3回入力される, THEN the System SHALL アカウントをロックする
✅ WHEN ファイルアップロードが完了する AND ファイルサイズが10MBを超える, the Storage Service SHALL ファイルを圧縮する
```

## 主語選択ガイドライン

明確性のために適切な主語（システム/サービス）を選択：

### ソフトウェアプロジェクト
具体的なシステム/サービス/コンポーネント名を使用：
- ✅ 「the User Auth Module」
- ✅ 「the Payment Service」
- ✅ 「the Dashboard UI」
- ❌ 「the system」（複数サービスがある場合は曖昧すぎる）

### API要件
特定のAPIまたはエンドポイント名を使用：
- ✅ 「the POST /api/users endpoint」
- ✅ 「the GraphQL resolver」
- ✅ 「the REST API」

### UI要件
画面/コンポーネント名を使用：
- ✅ 「the Login Form」
- ✅ 「the Product List Component」
- ✅ 「the Mobile Navigation」

## 品質基準

すべてのEARS要件は以下を満たす必要があります：

1. **テスト可能**: テストを書いて検証できるか？
   - ✅ 「SHALL HTTP 200を返す」（テスト可能）
   - ❌ 「SHALL ユーザーフレンドリーである」（テスト不可能）

2. **検証可能**: 客観的に動作を確認できるか？
   - ✅ 「SHALL 200ms以内に応答する」（測定可能）
   - ❌ 「SHALL 高速である」（主観的）

3. **単一の振る舞い**: 1要件 = 1振る舞い
   - ✅ 必要に応じて複数の要件に分割
   - ❌ 1つの要件に複数のSHALLを詰め込まない

4. **客観的な言語**:
   - ✅ 必須動作には「SHALL」を使用
   - ✅ 推奨事項には「SHOULD」を使用（控えめに）
   - ❌ 避ける：「〜かもしれない」「〜できる」「適切に」「使いやすい」

5. **明確な条件**: コンテキストは曖昧であってはならない
   - ✅ 「WHEN ユーザーが送信ボタンをクリックする」
   - ❌ 「WHEN ユーザーが送信したい」（不明確なイベント）

## よくある間違いを避ける

### ❌ 間違い1: 曖昧な表現
```
❌ 悪い例: 「システムはエラーを適切に処理すべき」
✅ 良い例: 「IF データベースクエリが失敗する, THEN the API SHALL エラー詳細付きHTTP 500を返す」
```

### ❌ 間違い2: 1つの要件に複数の振る舞い
```
❌ 悪い例: 「WHEN ユーザーがフォームを送信する, the System SHALL フィールドを検証し、データを保存し、メールを送信する」
✅ 良い例: 3つの要件に分割：
  1. WHEN ユーザーがフォームを送信する, the System SHALL すべての必須フィールドを検証する
  2. WHEN 検証が成功する, the System SHALL データをデータベースに保存する
  3. WHEN データが保存される, the System SHALL 確認メールを送信する
```

### ❌ 間違い3: テスト不可能な要件
```
❌ 悪い例: 「The UI SHALL 直感的で使いやすい」
✅ 良い例: 「WHEN 新規ユーザーがオンボーディングを完了する, the System SHALL 3クリック以内に最初のタスクにガイドする」
```

### ❌ 間違い4: トリガー/条件の欠如
```
❌ 悪い例: 「The System SHALL エラーメッセージを表示する」
✅ 良い例: 「IF ログイン認証情報が無効である, THEN the Login Form SHALL 「ユーザー名またはパスワードが無効です」エラーを表示する」
```

### ❌ 間違い5: 間違ったパターンの使用
```
❌ 悪い例: 「IF ダークモードが有効である, the UI はダーク色を表示する」（機能にはWHEREを使用）
✅ 良い例: 「WHERE ダークモードが有効である, the UI SHALL ダークカラースキームを使用する」
```

## 要件定義書のEARSテンプレート

```markdown
## 要件 1: [機能名]

**目的**: [役割]として、[機能]がほしい。なぜなら[利点]だから

### 受入基準

1. WHEN [イベント], the [System] SHALL [応答]
2. WHILE [状態], the [System] SHALL [応答]
3. IF [エラー条件], THEN the [System] SHALL [エラー応答]
4. WHERE [機能有効], the [System] SHALL [応答]
5. The [System] SHALL [常に有効な振る舞い]
```

## ドメイン別の例

### Eコマース
```
1. WHEN ユーザーがカートに商品を追加する, the Cart Service SHALL カート合計を更新する
2. WHILE 支払い処理中である, the Checkout UI SHALL すべてのフォーム入力を無効にする
3. IF 支払いが失敗する, THEN the System SHALL 具体的なエラーメッセージを表示し再試行を許可する
4. WHERE ゲストチェックアウトが有効である, the System SHALL アカウントなしでの購入を許可する
5. The Product API SHALL 95パーセンタイル要求に対して100ms以内に結果を返す
```

### SaaSアプリケーション
```
1. WHEN ユーザーがプレミアムにアップグレードする, the Subscription Service SHALL プレミアム機能を即座に有効化する
2. WHILE トライアル期間が有効である, the Dashboard SHALL 残り日数バナーを表示する
3. IF 使用量がクォータを超過する, THEN the System SHALL 80%と100%で警告メールを送信する
4. WHERE SSOが設定されている, the Login SHALL アイデンティティプロバイダーにリダイレクトする
5. The Application SHALL 30日間の期間で99.9%のアップタイムを維持する
```

### モバイルアプリ
```
1. WHEN アプリが起動する, the System SHALL 最大2秒間スプラッシュ画面を表示する
2. WHILE ネットワークが利用不可である, the App SHALL オフラインモードインジケーターを表示する
3. IF APIリクエストがタイムアウトする, THEN the App SHALL 指数バックオフで最大3回再試行する
4. WHERE プッシュ通知が有効である, the App SHALL 通知バッジを表示する
5. The App SHALL iOS 14.0以降を実行するデバイスをサポートする
```

## テストとの統合

EARS要件はテストケースに直接マッピングされます：

```
要件:
WHEN ユーザーが有効なログインフォームを送信する, the Auth Service SHALL JWTトークンを返す

テストケース:
Test: test_login_with_valid_credentials
Given: 有効なユーザー名 "user@example.com" とパスワード "Password123!"
When: 認証情報で POST /api/auth/login
Then: レスポンスステータスは200 AND レスポンス本文にJWTトークンが含まれる
```

## 良いEARS要件を書くためのヒント

1. **トリガーから始める**: この振る舞いを引き起こすものは何か？
2. **主体を命名する**: どのシステム/サービス/コンポーネント？
3. **SHALLを使用する**: 必須にする
4. **具体的にする**: 正確な値、メッセージ、振る舞い
5. **1要件につき1振る舞い**: 必要に応じて分割
6. **テスト可能にする**: 自動テストを書けるか？
7. **レビューと改善**: 開発者が曖昧さなく実装できるか？

## チェックリスト

要件を確定する前に検証：

- [ ] 5つのEARSパターンのいずれかを正しく使用している
- [ ] トリガー/条件が明確に定義されている
- [ ] システム/サービスが明示的に命名されている
- [ ] 「SHALL」を使用している（「すべき」「かもしれない」「だろう」でない）
- [ ] 単一の具体的な振る舞いを記述している
- [ ] テスト可能かつ検証可能である
- [ ] 曖昧な表現がない
- [ ] 明確化の質問なしで実装できる

---

**覚えておいてください**: 良い要件は開発とテストの時間を節約します。EARSフォーマットは、要件が明確で、テスト可能で、初日から実装可能であることを保証します。

**最終更新**: [Steering Agentによる自動生成または手動メンテナンス]