doc-ears

doc-ears

目的

**EARS（Easy Approach to Requirements Syntax）**ドキュメントを作成します。これは SDD フローのレイヤー 3 です。EARS では、BRD／PRD の要件を WHEN-THE-SHALL-WITHIN 構文を用いて、明確で、原子的かつテスト可能なステートメントに形式化し、BDD に変換できる状態にします。

レイヤー：3 — Context（BRD）から Container（PRD）への移行を形式化する詳細化ステップです。独自の C4 レベルはありません。 上流：PRD（レイヤー 2）。（必要な上流情報に関する契約に従い、@ タグの連鎖をたどることで、上流の BRD の系譜にも間接的に到達できます。） 下流：BDD → ADR → SPEC → TDD → IPLAN → コード。

各 EARS ステートメントは、テスト可能（Given-When-Then に導出可能）、測定可能（定量化可能な制約がある）、追跡可能（@prd）、かつ原子的（1 ステートメントにつき 1 つの概念）である必要があります。

使用するタイミング

次の場合に doc-ears を使用します。

• PRD（レイヤー 2）が存在し、形式的な要件が必要な場合（上流の BRD には、PRD 自身の @brd タグをたどって間接的に到達します）。
• 製品機能を、明確な振る舞いを示すステートメントに変換する場合。
• イベント駆動、状態駆動、オプション／機能ゲート、エラー処理、またはシステム全体に適用されるルールを定める場合。

PRD、プロンプト、または IPLAN からエンドツーエンドで生成するには、 ../doc-ears-autopilot/SKILL.md を使用します。

前提条件

作成する前に、以下を読みます。

1. テンプレート（信頼できる唯一の情報源）： ${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/EARS-TEMPLATE.yaml
2. レイヤーの README： ${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/README.md
3. ID とタグの規則： ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
4. 作成スタイル： ${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md
5. この EARS の基となる上流の PRD（および PRD 自身の @brd タグをたどって導出元の BRD）。

ID が重複していないことを確認します：ls docs/03_EARS/ 2>/dev/null。実在する上流ドキュメントのみを参照し、PRD-XXX や TBD のようなプレースホルダーを決して作らないでください。

レイヤーのガイダンス

必須構成（番号付きセクション 5 つ＋巻末の用語集）

document_control はセクション 1です（ステータス、バージョン、日付 YYYY-MM-DD、 優先度、単一の @prd: ソース、BDD 対応スコア、改訂履歴テーブル）。 続いて以下のセクションがあります。

2. 目的とコンテキスト · 3. 要件（5 つのパターン） · 4. 品質属性（表形式） · 5. トレーサビリティ。

さらに、巻末に用語集セクション（テンプレートキー glossary: — 必須、番号なし）を設けます。セクション番号と識別子は、EARS-TEMPLATE.yaml 自身の # Section N: の番号付けに従います。テンプレートが信頼できる唯一の情報源です。

セクションごとの内容と、テンプレートに埋め込まれた作成ガイダンスについては、EARS-TEMPLATE.yaml を参照してください。

5 つの EARS パターン（セクション 3）

パターン	構文	用途
イベント駆動	WHEN [trigger], THE [component] SHALL [action] WITHIN [timing].	ユーザー／API／タイマーのイベント
状態駆動	WHILE [state], THE [component] SHALL [behavior] WITHIN [context].	継続的な振る舞い／モードに依存する振る舞い
オプション	WHERE [feature enabled], THE [component] SHALL [behavior].	機能フラグ／設定によって制御される振る舞い
非望ましい事象	IF [error], THE [component] SHALL [recovery] WITHIN [timing].	障害、エッジケース、フォールバック
普遍的	THE [component] SHALL [behavior] for [scope].	グローバルな不変条件、ロギング、監査

真に複数の条件を含む要件は、これらを組み合わせて表現します（例：WHILE [state], WHEN [event], THE … SHALL …）。これはパターンの組み合わせであり、6 つ目のパターンではありません。EARS では応答節に THE … SHALL … を使用し、THEN の接続詞は使用しません。

各要件は原子的（テスト可能な概念が 1 つ）であり、要素 ID と、要件ごとの @prd: … トレーサビリティ行を含みます。該当する場合は、テンプレートの境界値マトリクス、状態遷移（エラー状態を含む）、およびフォールバック経路のパターンを使用します。

定量化可能な表現（セクション 3 ／ 4）

SHALL ／ SHALL NOT ／ SHOULD ／ MAYを正しく使ってください。曖昧なレイテンシはパーセンタイルに置き換えてください。real-time → p50<100ms/p95<300ms/p99<1000ms、immediately → <500ms、fast／quickly → 正確なレイテンシ。セクション 4（品質属性：パフォーマンス、セキュリティ、信頼性）は、測定可能な目標を含む表形式にします。 レイテンシ／応答時間は p50/p95/p99 表記を使い、非レイテンシの上限（サイクル／イテレーション数、イベントウィンドウ、バッチサイズ、*.count）は具体的な値＋単位で定量化します（パーセンタイルは適用されません）。変更可能な値には、@threshold: PRD.NN.category.key タグを付けます（タグには PRD のセクション番号を含めません）。

要素 ID とタグ

• 階層型要素 ID：EARS.{doc_id}.{section_id}.{hash}（例： EARS.01.03.c4d8。Requirements = セクション 03、Quality Attributes = セクション 04）。各セクション内で重複しない安定した 4 桁の 16 進数識別子（HASH01）を要素ごとに割り当てます。衝突時は 8 桁に拡張します。このプロンプトでは SHA-256 を計算しないでください。ハッシュ形式は、決定論的なツール処理で生成される正規形の TARGET です。バイト単位で正確なフィールド抽出が定義されているのは BRD §7 のみです（EARS は Phase 2 以降）。準拠基準：framework/governance/ID_NAMING_STANDARDS.md。
• EARS は Layer 3 なので、必要な上流タグの契約に従い、必須の @prd 上流タグを付けます。Document Control に @prd: を 1 つだけ記載し（追加分は要件ごとのタグに記載）、範囲指定はしません。上流の BRD との系譜は、PRD 自身の @brd タグを介して推移的にたどれます。EARS 要素に @brd: を付けないでください。
• 廃止されたパターン（使用禁止）：Event-XXX、State-XXX、UB-XXX、 REQ-XXX、旧形式の 3 セグメント EARS.NN.xxxx、数値型コード形式の EARS.NN.25.SS、ハイフン形式の EARS-NN-XXX。

作成プロセス

1. 上流を読む — これらの要件の基となる PRD（および、その @brd タグを介して PRD の基となる BRD）を読みます。
2. ID を確保する — 次に空いている EARS-NN（2 桁：EARS-01、EARS-99、EARS-102）を割り当てます。 レイヤーごとの独立性（CLEANUP-PR-F 項目 18）： 上流の番号ではなく、自身のレイヤーのインデックスで次に空いている番号を選びます（ドキュメント番号はレイヤーごとに独立して連番で付与します。framework/governance/ID_NAMING_STANDARDS.md §Cross-layer cardinality を参照）。
3. 入れ子のフォルダーを作成する — サイズにかかわらず、すべての EARS は docs/03_EARS/EARS-NN_{slug}/ に配置します。モノリシック形式： その中に EARS-NN_{slug}.md を配置します。セクション分割形式（>25 KB）： EARS-NN.S_{section}.md を配置します。
   • ${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/EARS-00_index.TEMPLATE.md からインデックスを作成します。
4. まず Document Control（セクション 1）を作成し、次にテンプレートの §2–§5 と用語集の後付け部分を完成させます。
5. 要件を 5 つのパターンに分類し、@threshold: 制約を付けて、原子的な THE … SHALL … ステートメント（該当する場合は WITHIN のタイミング指定を含む）を記述します。
6. 品質属性（表形式。レイテンシ → パーセンタイル、非レイテンシの上限 → 値＋単位）とトレーサビリティ（必要な上流タグの契約に従い @prd を付与）を記入します。
7. 同じ変更内で EARS インデックス docs/03_EARS/EARS-00_index.md を更新します。
8. 検証（以下を参照）し、EARS とインデックスをまとめてコミットします。

検証

このスキルはバリデーターです（実行時コードはありません）。${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/README.md と ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md に照らして確認します。

• Document Control が最初のセクションである。
• 5 つのセクションがすべて存在し、内容が空ではない。
• すべてのステートメントが WHEN-THE-SHALL-WITHIN 構文を使用している。SHALL／SHOULD／MAY が適切である。
• 要件が分類（Event、State、Optional、Unwanted、Ubiquitous）され、アトミックである。
• 要素 ID が EARS.NN.SS.xxxx に一致している。削除済みのパターンは含まれていない。
• 必須の上流タグ @prd がある（necessary-upstream 契約に従う）。範囲指定はない。
• Document Control に @prd: が 1 つだけある。制約が定量化されている（「高速」などの表現がない）。
• まだ存在しない成果物への数値による下流参照がない。
• トレーサビリティマトリクス／インデックスが作成または更新されている。リンク切れがない。

エラーコード（すべて重大度は error）：XDOC-006 タグ形式が無効 · XDOC-008 内部リンク切れ · XDOC-009 トレーサビリティセクションがない。

品質ゲート（ブロッキング）： 次に進む前に、BDD-Ready スコアが 90/100 以上であること。問題が見つかった場合は修正して再確認します。修正できない場合は、手動レビュー用に記録します。

次のスキル

../doc-bdd/SKILL.md — BDD はこの EARS を参照し（@ears: EARS.NN.SS.xxxx）、各ステートメントを実行可能な Given-When-Then シナリオに変換します。（BDD の必須上流は @ears のみです。それより上流の系譜は、@-tag チェーンを通じて推移的にたどれます。）

適応

.aidoc/profile.yaml を読み、このスキルのノブ（section_toggles、glossary）のみを適用します。不明なキーは無視します。プロファイルがない場合は、フレームワークのデフォルトを使用します。準拠先： ${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md。

関連リソース

• テンプレート／作成ルール：${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/EARS-TEMPLATE.yaml
• レイヤーの README：${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/README.md
• インデックスのテンプレート：${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/EARS-00_index.TEMPLATE.md
• ID とタグの標準：${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
• 品質ゲート：../doc-ears-audit/SKILL.md · 修正：../doc-ears-fixer/SKILL.md
• 生成パイプライン：../doc-ears-autopilot/SKILL.md
• 図（状態／シーケンス）：../charts-flow/SKILL.md

クイックリファレンス

目的	WHEN-THE-SHALL-WITHIN 構文で要件を形式化する
レイヤー	3（詳細化。C4 レベルなし）
上流タグ	@prd（necessary-upstream 契約に従う）
主なルール	アトミックでテスト可能かつ定量化可能なステートメントを 1 つずつ記述する
必須項目	Document Control（最初）、5 つのパターン、5 つのセクション
品質ゲート	BDD-Ready ≥ 90/100
次	doc-bdd