Initial commit

skills/sdd-docs/references/ears_notation_ja.md

@@ -0,0 +1,197 @@
+# EARS記法リファレンス（日本語版）
+
+## EARS記法とは
+
+EARS（Easy Approach to Requirements Syntax）は、明確で、曖昧さがなく、テスト可能な要件を記述するための構造化された記法です。要件文書の曖昧さを減らし、品質を向上させるために開発されました。
+
+## EARS記法のパターン
+
+### 基本パターン
+```
+システムは[必要な振る舞い]しなければならない
+```
+常に適用される要件に使用します。
+
+**例**:
+- REQ-001: システムは、すべてのパスワードをbcryptで最低12ラウンドで暗号化しなければならない
+
+### イベント駆動パターン
+```
+[トリガーイベント]の時、システムは[必要な振る舞い]しなければならない
+```
+特定のイベントによってトリガーされる要件に使用します。
+
+**例**:
+- REQ-002: ユーザーがログインフォームを送信した時、システムは2秒以内に認証を完了しなければならない
+- REQ-003: データベース接続が失敗した時、システムは指数バックオフで最大3回まで再接続を試みなければならない
+
+### 条件パターン
+```
+もし[前提条件]ならば、システムは[必要な振る舞い]しなければならない
+```
+特定の状態や条件に依存する要件に使用します。
+
+**例**:
+- REQ-004: もしユーザーが認証されていない場合、システムはログインページにリダイレクトしなければならない
+- REQ-005: もしキャッシュが5分以上古い場合、システムはデータベースからデータを更新しなければならない
+
+### 継続パターン
+```
+[条件が真である]間、システムは[必要な振る舞い]しなければならない
+```
+特定の条件下で維持されるべき要件に使用します。
+
+**例**:
+- REQ-006: ファイルアップロード中、システムは進捗インジケーターを表示しなければならない
+- REQ-007: ユーザーセッションがアクティブな間、システムは15分ごとに認証トークンを更新しなければならない
+
+### 場所パターン
+```
+[場所やコンテキスト]において、システムは[必要な振る舞い]しなければならない
+```
+特定の場所やコンテキストに固有の要件に使用します。
+
+**例**:
+- REQ-008: ユーザーがEU地域にいる場合、システムはGDPR同意バナーを表示しなければならない
+- REQ-009: ネットワーク遅延が100msを超える環境において、システムはローカルキャッシュを使用しなければならない
+
+### 複合パターン（組み合わせ）
+```
+[イベント]の時、もし[条件]ならば、システムは[必要な振る舞い]しなければならない
+```
+複数の条件を持つ要件に使用します。
+
+**例**:
+- REQ-010: ユーザーがフォームを送信した時、もしデータ検証が失敗した場合、システムはフィールド固有のエラーメッセージを表示しなければならない
+
+## ベストプラクティス
+
+### 1. 具体的で測定可能な用語を使用
+❌ **悪い例:** システムは速くなければならない  
+✅ **良い例:** システムはユーザークエリに200ミリ秒以内に応答しなければならない
+
+### 2. 1つの文に1つの要件
+❌ **悪い例:** システムはユーザーデータを検証し、保存し、確認メールを送信しなければならない  
+✅ **良い例:** 
+- REQ-011: システムは定義されたスキーマに対してユーザーデータを検証しなければならない
+- REQ-012: ユーザーデータが正常に検証された時、システムはデータベースに保存しなければならない
+- REQ-013: ユーザーデータが正常に保存された時、システムは確認メールを送信しなければならない
+
+### 3. 曖昧な用語を避ける
+避けるべき用語: すべきである、できる、かもしれない、可能性がある、おそらく、通常、一般的に、しばしば、典型的に
+
+常に使用する: しなければならない（必須要件の場合）
+
+### 4. 受入基準を含める
+各要件はテスト可能でなければなりません。自問してください：「この要件が満たされていることをどのように検証するか？」
+
+### 5. 一貫した番号付けを使用
+- 機能要件: REQ-XXX（REQ-001、REQ-002など）
+- 非機能要件: NFR-XXX（NFR-001、NFR-002など）
+
+## カテゴリー別の一般的なパターン
+
+### ユーザーインターフェース要件
+```
+[ユーザーアクション]の時、システムは[UI応答]しなければならない
+```
+例:
+- ツールチップアイコンにマウスを重ねた時、システムはヘルプテキストを表示しなければならない
+- フォームフィールドがフォーカスを失った時、システムはフィールド内容を検証しなければならない
+
+### パフォーマンス要件
+```
+システムは[時間制限]内に[アクション]しなければならない
+[条件]において、システムは[パフォーマンス制約]を満たさなければならない
+```
+例:
+- システムは4G接続でダッシュボードを3秒以内に読み込まなければならない
+- 同時ユーザーが1000人を超える場合、システムは応答時間を5秒以下に保たなければならない
+
+### セキュリティ要件
+```
+システムは[セキュリティ対策]を実施しなければならない
+もし[セキュリティ条件]ならば、システムは[セキュリティアクション]を実行しなければならない
+```
+例:
+- システムは管理者アカウントに多要素認証を強制しなければならない
+- 5分以内に3回のログイン失敗が発生した場合、システムはアカウントを15分間ロックしなければならない
+
+### データ要件
+```
+[データイベント]の時、システムは[データアクション]を実行しなければならない
+システムは[データ制約]を満たさなければならない
+```
+例:
+- ユーザーデータが削除された時、システムは90日間監査ログを保持しなければならない
+- システムはタイムスタンプをUTC形式で保存しなければならない
+
+### 統合要件
+```
+[外部イベント]の時、システムは[統合アクション]を実行しなければならない
+もし[統合条件]ならば、システムは[フォールバック動作]を実行しなければならない
+```
+例:
+- 決済プロバイダーからWebhookを受信した時、システムは注文ステータスを更新しなければならない
+- もし外部APIが利用できない場合、システムはリクエストを再試行のためにキューに入れなければならない
+
+## 検証チェックリスト
+
+要件を最終決定する前に、以下を確認してください：
+
+- [ ] 各要件は「しなければならない」を使用している（すべきである/できる/かもしれないではない）
+- [ ] 各要件は個別にテスト可能である
+- [ ] 要件は一貫して番号付けされている（REQ-XXXまたはNFR-XXX）
+- [ ] 要件に複数の「しなければならない」文が含まれていない
+- [ ] すべてのトリガーイベントが明確に定義されている
+- [ ] すべての時間制約に具体的な値が含まれている
+- [ ] 曖昧な用語が使用されていない
+- [ ] 各要件は独立している（コンテキストに依存しない）
+
+## 良く書かれた要件の例
+
+### 認証システム
+- REQ-101: システムはパスワードを最低12文字以上要求しなければならない
+- REQ-102: ユーザーが誤ったパスワードを入力した時、システムは失敗ログインカウンターを増加させなければならない
+- REQ-103: もし失敗ログインカウンターが5に達した場合、システムはアカウントを30分間ロックしなければならない
+- REQ-104: アカウントがロックされている間、システムは残りのロック時間を表示しなければならない
+- REQ-105: ロック期間が終了した時、システムは失敗ログインカウンターをゼロにリセットしなければならない
+
+### ファイルアップロードシステム
+- REQ-201: システムは最大100MBまでのファイルアップロードを受け入れなければならない
+- REQ-202: ファイルがアップロードされた時、システムはマルウェアをスキャンしなければならない
+- REQ-203: もしマルウェアが検出された場合、システムはファイルを拒否し、インシデントをログに記録しなければならない
+- REQ-204: ファイルがアップロードされている間、システムはアップロード進捗をパーセンテージで表示しなければならない
+- REQ-205: ユーザーのストレージ容量を超過する場合、システムは適切なエラーメッセージと共にアップロードを拒否しなければならない
+
+### 通知システム
+- REQ-301: システムはトリガーイベントから5分以内にメール通知を配信しなければならない
+- REQ-302: 通知の送信に失敗した時、システムは指数バックオフで最大3回まで再試行しなければならない
+- REQ-303: もしすべての再試行が失敗した場合、システムは失敗をログに記録し、運用チームに警告しなければならない
+- REQ-304: システムはユーザーの通知設定を尊重しなければならない
+- REQ-305: ユーザーがメール通知をオプトアウトしている場合、システムはアプリ内通知のみを送信しなければならない
+
+## 日本語でのEARS記法の注意点
+
+### 文体の統一
+- 「しなければならない」で統一（「する必要がある」「するものとする」は使わない）
+- 主語は「システムは」で統一
+
+### 時制の扱い
+- 現在形で記述（「した時」ではなく「する時」）
+- 継続的な動作は「〜している間」
+
+### 条件表現
+- 「もし〜ならば」（仮定）
+- 「〜の場合」（状態）
+- 「〜の時」（タイミング）
+
+### 数値の表記
+- アラビア数字を使用（「五分」ではなく「5分」）
+- 単位を明確に記載
+
+## 参考文献
+
+- EARS - The Easy Approach to Requirements Syntax (Alistair Mavin et al.)
+- IEEE 830-1998 Standard for Software Requirements Specifications
+- ISO/IEC/IEEE 29148:2018 Requirements Engineering