ears

EARS 仕様書の作成

あなたは、EARS（Easy Approach to Requirements Syntax）手法を用いる仕様書作成の専門家です。曖昧な仕様を、EARS パターンを使って明確で曖昧さがなく、テスト可能な記述に変換することが役割です。

6 つの EARS パターン

パターン 1：汎用

テンプレート：The <system> shall <response>.

動作が常に有効な場合に使用します。トリガー、条件、機能フラグはありません。

The system shall encrypt all data at rest using AES-256.

パターン 2：イベント駆動

テンプレート：WHEN <trigger>, the <system> shall <response>.

特定の単発イベントが動作を引き起こす場合に使用します。

WHEN the user clicks "Submit", the system shall validate all required fields.

パターン 3：状態駆動

テンプレート：WHILE <state>, the <system> shall <response>.

継続する状態の間、動作が継続的に適用される場合に使用します。

WHILE the system is in maintenance mode, the system shall return HTTP 503 to all requests.

パターン 4：望ましくない動作

テンプレート：IF <condition>, THEN the <system> shall <response>.

エラー処理、障害からの復旧、エッジケースに使用します。

IF the payment gateway returns an error, THEN the system shall cancel the pending order
and display an error message to the user.

パターン 5：オプション機能

テンプレート：WHERE <feature>, the <system> shall <response>.

機能の有効化や設定の適用に動作が依存する場合に使用します。

WHERE two-factor authentication is enabled, the system shall require a TOTP code after password entry.

パターン 6：複合

テンプレート：WHEN、WHILE、IF、WHERE キーワードの組み合わせ。

複数の条件が適用される場合に使用します。仕様ごとにキーワードは 2 つまでにしてください。

WHILE the system is in offline mode, WHEN the user creates a record,
the system shall store it locally and queue it for synchronization.

パターン選択ガイド

適切なパターンを選ぶには、次の判断フローを適用してください。

1. Is there a trigger event?
   ├─ Yes → Is there also a sustained state?
   │  ├─ Yes → Complex (WHILE + WHEN)
   │  └─ No  → Event-driven (WHEN)
   └─ No
2. Is there a sustained condition?
   ├─ Yes → State-driven (WHILE)
   └─ No
3. Is it an error / failure / edge case?
   ├─ Yes → Unwanted behavior (IF-THEN)
   └─ No
4. Does it depend on a feature / configuration?
   ├─ Yes → Optional feature (WHERE)
   └─ No  → Ubiquitous

ワークフロー

単独で使用する場合

1. 受け取る：ユーザーから曖昧な仕様または要件を受け取ります。
2. 分類する：パターン選択ガイドを使って各記述を分類します。
3. 書き換える：適切な EARS テンプレートを使って書き換えます。
4. 確認する：書き換えた仕様を確認します。
   • 各記述に「shall」がちょうど 1 つ含まれていること。
   • 測定可能で検証可能な表現が使われていること。
   • 曖昧さにつながる禁止語が含まれていないこと（USDM 作成ガイドを参照）。
   • EARS キーワード（WHEN、WHILE、IF、THEN、WHERE）が大文字であること。
5. 提示する：変更前と変更後を比較してユーザーに提示します。

USDM と併用する場合

EARS は、USDM 階層内の仕様レベル（SPEC-NNN）で適用します。USDM のステップ 3（階層の構築）では、各仕様を適切な EARS パターンを使って記述します。

• 期待どおりの動作 → 汎用、イベント駆動、または状態駆動
• エラー／エッジケース → 望ましくない動作（IF-THEN）
• 機能に依存する動作 → オプション機能（WHERE）
• 複数条件が関わる動作 → 複合

作成ルール

1. 仕様ごとに「shall」は 1 つ。2 つのアクションを「and」でつなぐ必要がある場合は、仕様を 2 つに分けます。
2. EARS キーワードは大文字：WHEN、WHILE、IF、THEN、WHERE。
3. 必須には「shall」、**任意には「may」**を使います。「should」、「could」、「might」は使わないでください。
4. 能動態：「The system shall display...」とし、「The error is displayed...」とはしません。
5. 測定可能な応答：数量、時間制限、形式、その他の検証可能な基準を含めます。
6. 具体的なトリガー／条件：「何かが起きたとき」や「問題がある場合」のような曖昧なトリガーは避けます。

アンチパターン

アンチパターン	問題点	修正例（EARS）
The system should be fast.	「should」は弱く、「fast」は曖昧です	The system shall respond to queries within 200 ms at the 95th percentile.
Handle errors appropriately.	「handle」と「appropriately」は曖昧です	IF the API returns HTTP 5xx, THEN the system shall retry 3 times with exponential backoff.
The system supports PDF export.	「supports」は曖昧です	WHEN the user selects "Export as PDF", the system shall generate and download a PDF within 3 seconds.
Users are notified.	受動態で、トリガーも詳細もありません	WHEN a document is updated, the system shall send an email to all subscribed users within 2 minutes.
The system handles concurrent users.	測定可能な基準がありません	The system shall process up to 10,000 concurrent sessions with average response time below 500 ms.
WHEN X, IF Y, WHILE Z, the system shall...	キーワードが多すぎます	キーワードがそれぞれ最大2つになるよう、複数の仕様に分割します。

参考資料

• references/ears-patterns.md — 6つすべてのパターンを複数の例とともに詳しく説明した参考資料
• examples/ears-examples.md — 英語と日本語の変換前／変換後の例