mcpField
D
doc-bdd

doc-bdd

github.com/vladm3105テスト・品質1761 回インストール1 日前に更新
リポジトリ

doc-bdd について

EARS 要件から構造化された YAML の BDD シナリオを作成・確認するスキルです。シナリオ形式、SPEC セクションへのトレース、検証、インデックス更新を案内し、YAML を正式な記録として扱います。

主な機能

  1. 01YAML の Given/When/Then シナリオ
  2. 025種類のシナリオ分類
  3. 03EARS の要素単位トレース
  4. 04SPEC セクションへのリンク
  5. 05シナリオ構造と ID の確認
  6. 06インデックスと品質ゲートの案内

活用シーン

  1. 01EARS 要件を受け入れシナリオに変換
  2. 02シナリオを要件や SPEC セクションに対応付け
  3. 03シナリオ構造と必須項目を確認
  4. 04BDD インデックスと文書リンクを管理

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/vladm3105/aidoc-flow-framework --skill doc-bdd

インストール後、Claude Code で/doc-bddを入力して読み込まれたか確認します。

詳細

doc-bdd

目的

SDD フローのレイヤー 4 にあたる 振る舞い駆動開発（BDD） シナリオを作成します。BDD スイートでは、EARS の形式的な要件を、構造化された YAML シナリオ（```yaml ブロックに記述する Given／When／Then のフェーズリスト。Gherkin の @ タグではありません）に変換します。各シナリオには、要素レベルの ears: トレースリストと、対象となる SPEC セクションへの前方リンク spec_trace が含まれます。（ランナーで .feature ファイルが必要になった場合は、YAML を正式な記録として、必要に応じて .feature への変換機能を作成できます。現時点では、そのような変換機能は同梱されていません。同梱されているトランスコーダーは、レガシーな Gherkin を YAML 形式に移行するための一回限りの逆方向変換ツール tools/gherkin_to_bdd_yaml.py のみです。）

レイヤー：4。上流：EARS（必須上流契約に基づく。上流の PRD／BRD 系譜には、@ タグの連鎖を通じて推移的にたどれます）。 下流：ADR → SPEC → TDD → IPLAN → Code。

BDD シナリオは受け入れ条件の正式な基準であり、TDD（レイヤー 7）ではこれを具体的なテストケースに対応付けます。実行は QA ステージングのみです。CI では BDD を実行しないでください（CI では TDD の単体テスト／統合テストを使用してください）。

使用するタイミング

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

  • EARS（レイヤー 3）が作成済みで、実行可能な受け入れシナリオが必要な場合。
  • 具体的な Given／When／Then の振る舞いで EARS 要件を検証する場合。
  • ADR／SPEC の前に、要件から SPEC へのトレースブリッジ（spec_trace）を定義する場合。

EARS、プロンプト、または IPLAN からエンドツーエンドで生成するには、 ../doc-bdd-autopilot/SKILL.md を使用してください。まず上流の成果物を作成してください。EARS-XXX のようなプレースホルダーを作成したり、まだ存在しないドキュメントを参照したりしないでください。

前提条件

BDD はレイヤー 4 であるため、必須の上流 EARS がすでに存在している必要があります。作成前に存在を確認し、仕様を読んでください。

  1. テンプレート（正式な基準）： ${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/BDD-TEMPLATE.yaml
  2. レイヤー README： ${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/README.md
  3. ID とタグの標準： ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
  4. 作成スタイル： ${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md

上流の成果物を確認し、ID の重複がないことを確認します。 ls docs/03_EARS/ docs/04_BDD/ 2>/dev/null。トレースタグでは、実在する EARS 要素のみを参照してください。上流の PRD／BRD 系譜には、EARS ドキュメント自体の @ タグの連鎖を通じて推移的にたどれます。

レイヤーのガイダンス

必須の構成（5 セクション）

BDD-TEMPLATE.yaml に従い、すべての BDD ドキュメントには次の内容を含めます。

  1. ドキュメント管理 — バージョン、ステータス、日付、作成者、優先度、および ADR 対応スコア。（@ears／@prd／@brd の参照行はありません。上流へのトレースは各シナリオの ears: リストに記述します。）
  2. フィーチャー定義 — feature: ブロックを含む ```yaml ブロック。EARS 要件と一致する名前、As a / I want / So that の説明、および background（ステップテキストのみと IANA タイムゾーン。デフォルトは America/New_York）を含みます。フィーチャー自体には ears を含めません。その EARS カバレッジは各シナリオのカバレッジの合計です。
  3. シナリオ構造 — ```yaml ブロック内のフラットな scenarios: リスト（Given／When／Then のフェーズリスト）。各シナリオには、5 つのカテゴリ（下記）のいずれかに該当する type: が必要です。
  4. トレーサビリティ — 算出したカバレッジの概要、下流への期待事項、および健全性／カバレッジスコア。
  5. 用語集 — プロジェクト固有の用語のフラットなリスト。

各セクションの内容と規範となるシナリオスキーマについては、BDD-TEMPLATE.yaml を参照してください。

シナリオのカテゴリ（セクション 3）

各シナリオは、id: BDD.NN.03.xxxx、name、type、priority（p0-critical … p3-low）、要素レベルの ears: リスト、given / when / then の各フェーズリスト、および spec_trace リスト（notes は任意）を含む YAML マッピングです。

カテゴリtype: の値最小数優先度
成功success1 / EARSp0–p1
エラーerror1 / エラーp1–p2
復旧recovery1 / サーキットブレーカーp1
パラメーター化parameterized1 / 複数値p1–p2
任意optional1 / 任意のパラメーターp2–p3

parameterized シナリオには、outline: true と examples: {headers, rows} を追加します。

シナリオ YAML のルール
  • シナリオは 構造化 YAML であり、Gherkin の @ タグではありません。トレースには ears: リストを使用します（要素レベルのみ — REFGRAN01 はドキュメント形式の EARS-NN を拒否します）。id / type / priority はフィールドであり、タグではありません。
  • 時刻には秒（HH:MM:SS）と IANA タイムゾーン（America/New_York）を含めます。EST のような略称は使用しません。
  • 定量値には、ステップの文章内に インラインで 記述した @threshold: キーを使用します（例：… WITHIN @threshold:PRD.NN.perf.api.p95）。マジックナンバーは使用しません。
  • シナリオはアトミックに保ちます（各シナリオにつき 1 つの振る舞い）。モジュールごとに BDD ドキュメントを 1 つ作成し、約 50,000 トークンを超える場合は、自己完結した新しい BDD ドキュメントを作成します。
要素 ID と上流トレース
  • 階層型の要素 ID：BDD.{doc_id}.{section_id}.{hash}（例：BDD.01.03.d7a2）。各要素に 安定した 4 桁の 16 進数識別子 を付与し、セクション内で一意にします（HASH01）。衝突した場合は 8 桁に拡張します。このプロンプトで SHA-256 を計算 しないでください — ハッシュ形式は、決定論的なツール処理で生成される正規化の TARGET であり、バイト単位で正確なフィールド抽出が定義されているのは BRD §7 のみです（BDD は Phase 2 以降）。根拠：framework/governance/ID_NAMING_STANDARDS.md。シナリオはセクション 03 にあり、各シナリオの id: フィールドに記述します。
  • BDD で必要な上流トレースは、各シナリオの要素レベルの ears: リストです（必要な上流契約に従い、required_tags: [ears] を満たします）。下流の成果物では、@bdd: BDD.01.03.8f4c タグを使用して BDD シナリオを参照します（変更しません）。上流の PRD/BRD 系譜は、EARS ドキュメント自体の @ タグチェーンを介して推移的にたどれます。BDD に @brd: / @prd: / @ears タグを出力しないでください。
  • 廃止されたパターン（使用しないでください）：SCENARIO-XXX、SCEN-XXX、TS-XXX、STEP-XXX、数値の type コード、従来の 3 セグメント形式 BDD.NN.xxxx、および Gherkin の @ears / @scenario-type / @scenario-id タグ（現在は YAML フィールドです）。
下流トレース（spec_trace）

各シナリオには、対応する SPEC セクションを記録します。例：spec_trace: ["SPEC Section 3 (Interfaces)", "SPEC Section 5 (Behavior)"]。これは、下流レイヤーが利用する要件から SPEC への橋渡しです。

作成プロセス

  1. 上流ドキュメントを読む — この BDD を動かす EARS と、@タグの連鎖を通じて EARS の派生元となる PRD／BRD を読み、テストする振る舞いを理解します。
  2. IDを確保する — 次に空いている BDD-NN を使います（2桁で、先頭に余分なゼロを付けません。例：BDD-01、BDD-99、BDD-102）。 レイヤーごとの独立性（CLEANUP-PR-F item 18）： 自分のレイヤーのインデックスで次に空いている番号を選びます。上流の番号は自分の番号ではありません（ドキュメント番号はレイヤーごとに独立して順番に付与されます。framework/governance/ID_NAMING_STANDARDS.md §Cross-layer cardinality を参照）。
  3. ドキュメントを作成する — ${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/BDD-TEMPLATE.yaml を使い、最初に Document Control を記入して、5つのセクションすべてを完成させます。
  4. feature: ブロックと scenarios: リストを記述する — EARS の要件に従い、5つのカテゴリにわたって YAML で記述します。各シナリオには id、type、priority、要素レベルの ears: リスト、given／when／then フェーズリスト、インラインの @threshold:、および spec_trace を含めます。feature の background も追加します。
  5. 各シナリオの要素レベルの ears: リストを設定する — これは必須の上流トレースです。また、一意の id: を設定します。Gherkin の @タグは使用しません。
  6. 同じ変更で BDD インデックスを更新する — docs/04_BDD/BDD-00_index.md を更新します。
  7. 検証する（以下を参照）— BDD とインデックスをまとめてコミットします。

検証

このスキルがバリデーターです（ランタイムコードはありません）。${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/README.md および ${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md に照らして適用します。

  • Document Control が最初のセクションであり、5つのセクションがすべて存在し、空でないこと。
  • すべてのシナリオに要素レベルの ears: リストがあること（必須の上流トレース要件を満たすこと）。feature に ears がないこと。
  • すべてのシナリオに id、type、priority、given／when／then フェーズリスト、spec_trace があること（BDD-SCHEMA-001 に準拠）。
  • 5つすべてのシナリオ type カテゴリが含まれていること。シナリオがアトミックであること。
  • 定量値にはインラインの @threshold: キーを使用すること。時刻は IANA タイムゾーンを使用した HH:MM:SS 形式であること。
  • 要素 ID が BDD.NN.SS.xxxx に一致すること。削除済みのパターンや Gherkin タグがないこと。
  • トレーサビリティセクション／インデックスが更新されていること。リンク切れがないこと。
  • 図の要件：シナリオのフローを図示する場合は、シーケンス図のタグがあること（../charts-flow/SKILL.md を使用）。

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

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

次のスキル

../doc-adr/SKILL.md — ADR では、この BDD（@bdd: BDD.NN.SS.xxxx）と必須の @ears を参照し、Context-Decision-Consequences 形式でアーキテクチャ上の決定を記録して、各決定を検証する BDD シナリオを引用します。

適用

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

関連リソース

  • テンプレート／作成ルール：${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/BDD-TEMPLATE.yaml
  • レイヤー README：${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/README.md
  • インデックステンプレート：${CLAUDE_PLUGIN_ROOT}/framework/layers/04_BDD/BDD-00_index.TEMPLATE.md
  • ID とタグの標準：${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
  • 品質ゲート：../doc-bdd-audit/SKILL.md · 修正：../doc-bdd-fixer/SKILL.md
  • 生成パイプライン：../doc-bdd-autopilot/SKILL.md

クイックリファレンス

目的Given／When／Then形式の構造化されたYAML受け入れシナリオ
レイヤー4
上流トレースシナリオの ears: リスト（必要な上流契約に基づく）
主要な考え方EARS → SPECへの spec_trace を含むYAMLシナリオ
必須項目ドキュメント管理（最初に配置）、5つのシナリオカテゴリ、しきい値
実行QAステージングのみ — CIでは実行しない
次doc-adr

コメント

Markdown 対応