bmad-spec

BMad Spec

概要

BMad spec-kernel エコシステムの正規トランスフォーマーです。あらゆる意図の入力 — 漠然としたアイデア、ブレインダンプ、PRD、GDD、RFC、ブリーフ、Slack スレッド、顧客メール、会議の文字起こし、モックアップ、複数ソースの混在 — を受け取り、5 フィールドのカーネル（Why、Capabilities、Constraints、Non-goals、Success signal）を保持する spec-{slug}.md と、カーネルに収まらない、あるいは詳細な行項目でカーネルを肥大化させてしまう重要な内容のためのコンパニオンファイルを生成します。これらは全体として、下流のあらゆる BMad スキルが消費するマシンコントラクトとなります。

複数のスキルが、時間の経過とともに同じ spec を更新するために呼び出されることがあります。

規約

• ベアパス（例: assets/spec-template.md）はスキルルートから解決されます。
• {skill-root} はこのスキルのインストールディレクトリです。{project-root} は _bmad/ を含む最も近いフォルダで、作業ディレクトリから始めて親をたどって上方向に探索します。
• {workflow.<name>} は customize.toml 内のフィールドに解決されます。

アクティベーション時

1. カスタマイズを解決します: uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow。
   • スクリプトが見つからない場合: ここでは BMad がセットアップされていません。bmad スキルのセットアップを実行するよう提案し、bmad を持っていなければ先にインストールして（npx skills add bmad-code-org/BMAD-METHOD --skill bmad）、その後コマンドを再実行します。
   • その他の失敗: {skill-root}/customize.toml を直接読み取ります。
2. {workflow.activation_steps_prepend} を実行します。{workflow.persistent_facts} を基盤となるコンテキストとして扱います（file: エントリは読み込まれます）。
3. 設定を解決します: uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key core.output_folder --key core.active_initiative。{date} は現在のシステム日時です。
   • スクリプトが見つからない、または output_folder がない場合: ここでは BMad がセットアップされていません。bmad スキルのセットアップを実行するよう提案し、bmad を持っていなければ先にインストールして（npx skills add bmad-code-org/BMAD-METHOD --skill bmad）、その後コマンドを再実行します。
   • active_initiative がない場合: bmad スキルに引き継いで設定または作成し、その後コマンドを再実行して続行します。ヘッドレス: ルーズに書き込みます。
4. モードを検出します。次のいずれかに該当する場合はヘッドレスです: TTY がない、プログラムによる呼び出し元（別のスキルまたは非対話型ランナー）、または最初のメッセージですべての入力を事前に提供し成果物のパスを返すよう求める場合。それ以外は対話型です。対話型モードでは、ユーザーに挨拶し、任意のフィールドについてより深く探索するために bmad-party-mode と bmad-advanced-elicitation が利用可能であることに言及します。

{workflow.activation_steps_append} を実行します。

アクティベーションが完了しました。activation_steps_prepend または activation_steps_append が空でなかった場合は、続行する前にすべてのエントリが順番に実行されたことを確認してください。すべてのアクティベーションステップが完了するまで、メインワークフローを開始しないでください。

ワークスペース

spec は常にフォルダであり、{workflow.spec_output_path}/{workflow.run_folder_pattern} という名前で、デフォルトでは {output_folder}/{active_initiative}/spec-{slug}/ に解決されます。spec は、それが指定する対象の内部に置かれます: 呼び出し元が spec の対象となるエピックまたはイニシアチブのフォルダを指定する場合、bmad-ticket がそうするように、spec フォルダは代わりに <that folder>/{workflow.run_folder_pattern} となります。

{slug} は、入力の形ではなく、spec 化される対象を表します:

• ソース成果物がすでに slug を持っている場合（例: prd-foo-bar/）: それを継承します（foo-bar）。
• 疎な入力、チャット内、または複数ソースの入力: 対話型では確認します。ヘッドレス呼び出し元は入力の一部として提供します。存在せず導出もできない場合、ヘッドレスは error_code: "missing_slug" でブロックします。
• 同じ slug = 同じフォルダ。同じ {slug} での 2 回目の呼び出しは既存の spec フォルダに着地し、その場で更新し、ケイパビリティ ID を保持します。

入力なし。 対話型: ユーザーにファイルパスを共有する、内容を貼り付ける、アイデアを詳細に説明する、またはソースを指定するよう求めます。ヘッドレス: error_code: "insufficient_intent" を含む JSON を返します。

spec フォルダ内:

<spec-folder>/
  spec-<slug>.md           ← the kernel, named after the folder — DERIVED from .memlog.md, never hand-edited
  <companion-1>.md         ← optional, content-typed (e.g. glossary.md); spec-authored ones are derived too
  <companion-2>.md
  .memlog.md               ← canonical, append-only memory; what spec-{slug}.md is distilled from

メモリと派生

.memlog.md は正典です — すべての決定、制約、機能（安定した CAP-N 付き）、仮定、未解決の問い、およびユーザーからの指示を、発生した順に 1 行ずつ追記する時系列の記録であり、編集や並べ替えは決して行いません。spec-{slug}.md および仕様が作成するすべてのコンパニオンは、実行のたびに メモリログ（記録された決定）と、生のコンテンツのためにそれが引用するソースから派生され、手動でパッチを当てることはありません。

契約をその場で編集するのではなく、生きたログから契約を派生させることで、仕様を取り巻くステップ（PRD、UX、アーキテクチャ、エピック）を任意の順序で実行し、マージのずれなく同じ仕様に供給できます。ログは蓄積されるだけで、成果物は再レンダリングされます。したがって、仕様はここで再派生することによってのみ更新されます — bmad-spec がその唯一の書き込み者であり、外部から spec-{slug}.md を手動で編集することはサポートされておらず、次回の派生時に上書きされます。

書き込みは共有スクリプト — {project-root}/_bmad/scripts/memlog.py（resolve_customization.py と同じ場所。アトミックであり、再開する場合を除いて読み戻すことはありません）を介して行われます。

• uv run {project-root}/_bmad/scripts/memlog.py init --workspace {spec-folder} --field topic="<what is being specced>" — 作成時に 1 回。
• uv run {project-root}/_bmad/scripts/memlog.py append --workspace {spec-folder} --type <decision|constraint|capability|assumption|question|direction|note|event> --text "<one-line gist, reason included>" — それぞれが記録されるたびに。
• 終端の瞬間（検証の判定、「仕様確定」）は --type event エントリです。メモリログにステータスフィールドはありません。

操作

入力とその関連リンク資料を読みます。入力がない場合は、ワークスペースの no-input 分岐に従ってください（質問するかブロックします）。対象フォルダに以前の .memlog.md が存在する場合は、それを読みます。この場合、操作は更新となり、何が決定されたか、およびケイパビリティ ID については、レンダリングされた spec-{slug}.md ではなく memlog が権威となります。それらの ID は保持してください。新しいケイパビリティには次に未使用の CAP-N を割り当て、廃止された ID を再利用してはいけません。それ以外の場合は作成となり、最初の操作は memlog.py init です。

入力が構造化され事前に整理されている場合（追補付きの PRD、GDD、上流の BMad スキルによって生成されたブリーフ）、作成された分離を信頼してください。カーネルに適合する内容を spec-{slug}.md に取り込み、あふれた内容を適切な名前のコンパニオンに取り込みます。入力が混在している場合（ブレインダンプ、文字起こし、RFC、顧客からのメール）、自分で整理してください。各主張を順に確認し、3 つのレンズによる耐荷重テスト（Spec Law ルール 7）を適用して、カーネルフィールドまたはコンパニオンに振り分けます。

{workflow.spec_template} を骨組みとして、入力を 5 フィールドのカーネルに蒸留します。入力が豊富な場合は、直接抽出します。誘導は行いません。入力が乏しい場合は、選択します。express（最善努力で蒸留し、すべてのギャップを open_questions[] のエントリにする）または guided（5 つのフィールドをユーザーと 1 つずつ確認する）です。ヘッドレスでは express がデフォルトとなり、その選択をログに記録します。対話型では質問します。

入力が対処していない、認識可能なドメイン上の含意は、まさにそのようなギャップです。それを open_questions[] のエントリとして挙げ（医療入力が PHI/HIPAA について触れていない、決済が PCI について触れていない、制御システムがフェイルセーフについて触れていないなど）、次に進みます。それをフラグとして示してください。決して答えをでっち上げたり、その方向に誘導したりしてはいけません。これらが支配的な場合、入力は薄すぎます。bmad-prd を提案してください。

最初のパスから簡潔に書いてください。すべての文はその場に値しなければなりません。装飾はトークンを消費し、下流の読み手を薄めます。

各決定、ケイパビリティ、制約、受け入れられた変更を、それが行われた時点で .memlog.md に記録してください。この実行記録こそが、レンダリングが読み取るものです。ログは追記専用であるため、同じ論点について後のエントリが前のエントリを上書きしますが、履歴はそのまま残ります。現在有効な 2 つのソースまたはコンパニオンが同じフィールドで矛盾している場合、または二者択一が解決されていない場合は、黙って選ぶのではなくユーザーに提示してください。その解決自体が新しい memlog エントリとなります。

入力が蒸留するには本当に薄すぎる場合（例: 周辺的な文脈のない「ハイカー向けのアプリ」）、停止して bmad-prd（または兄弟のセレモニースキル）を提案してください。このスキルは蒸留します。コーチングはしません。

耐荷重

耐荷重である主張とは、それなしでは何らかの消費者（下流のスキル、実装エージェント、検証パス）が決定を変えるであろう主張です。

コンパニオン

耐荷重性のあるコンテンツが 5 フィールドのカーネルに収まらない場合、それはコンパニオンに置かれます。カーネルはそれを引用し、コンパニオンがそれを保持します。コンパニオンはコントラクトの一部であり、すべてのコンシューマーは spec-{slug}.md のフロントマターにある companions: を読んでそれらを発見します。コンパニオンは spec-{slug}.md と同じリーンな規律に従います（Spec Law ルール 8）。

コンテンツがカーネル形状の 1 行を超える必要がある場合にコンパニオンを生成します: 複数項目のカタログ（アーキタイプ、ドリンク、モード、ルートのようなエンティティごとのマトリクス）、テーブル、図（常に）、エディトリアルボイスのルール、カーネルが名前で引用する長文のリファレンス資料（用語集、ブラウンフィールドのメモ、プロジェクトの規約）。1 行の意思決定を左右するものは Constraints に残ります。intent+success のペアは Capabilities に残ります。カーネルのフィールドがサブ箇条書きへと箇条書きになり始めたら、そのコンテンツはカーネルを超えて成長しており、コンパニオンを求めています。

コンパニオンは次のいずれかです:

• Spec-authored コンパニオンは bmad-spec によって書かれ、spec-{slug}.md の兄弟として存在します（例: glossary.md、patron-archetypes.md）。bmad-spec がそれらを所有し、更新操作でそれらを編集することがあります。
• Adopted コンパニオンは、上流のスキルによって書かれ、下流が依然として読む必要がある耐荷重性のある成果物です。bmad-spec はそれらを相対パスで companions: に参照しますが、それらを編集しません（例: UX 実行からの DESIGN.md や EXPERIENCE.md、統合パートナーの API 仕様）。それらを所有するのは発生元のスキルです。

コンパニオンを統べる 2 つのルール:

1. Spec-authored コンパニオンには、それが保持するコンテンツタイプに応じた名前を付けます。 glossary.md、<entity-class>.md（例: patron-archetypes.md、medication-routes.md、flight-modes.md）、stack.md、conventions.md、brownfield.md、architecture-diagrams.md、state-machines.md、failure-modes.md、compliance-references.md。原則は「読者は開く前に中身が何であるかを知っているべきである」です。Adopted コンパニオンは、発生元のスキルが付けた名前をそのまま保ちます。
2. 図は常にコンパニオンに置かれます、サイズに関係なく。spec-{slug}.md のカーネルは散文のみを保持します。Mermaid ブロック、ASCII 図、画像参照はすべてコンパニオンに置かれ（例: architecture-diagrams.md）、そこから参照される兄弟画像ファイルとともに存在します。

下流が必要とする既存のプロジェクト全体のドキュメント（例: project-context.md）は adopted コンパニオンとして列挙され、spec-{slug}.md や spec-authored コンパニオンに複製されることは決してありません。

Spec Law

すべての仕様はこれらの 8 つのルールを満たさなければなりません。操作はそれらを目指し、自己検証スイープがそれらを強制します。

1. 各ケイパビリティは intent と success の両方を持ちます。 どちらかが欠けていれば = ケイパビリティではありません。
2. Intent は HOW ではなく WHAT を記述します。 実装の指示はコンパニオン（スタック、規約）に属します。
3. 制約は実際に設計上の決定を左右します。 何も排除しない「制約」は装飾です。
4. 非目標は明示的です。 少なくとも 1 つ。欠如は下流のスキルが空白を埋めることを意味します。
5. 成功シグナルは、テストまたは実証できるほど具体的です。 「ユーザーが気に入る」は該当しません。
6. ケイパビリティ ID は安定しており一意です。 決して再利用されず、決して番号を振り直されません。
7. 保存。 耐荷重性のあるソースの主張はすべて spec-{slug}.md またはコンパニオンに置かれます。ラッパーの儀式はそうではありません。
8. リーンな散文。 すべての文が耐荷重性のあるコンテンツを運びます。装飾、ヘッジ、バックストーリー、前置きを削ります。spec-{slug}.md、コンパニオン、.memlog.md に適用されます。

セルフバリデーション

作成または更新のたびに、提示する前に成果物を2つのパスで精査します。

パス 1 — 整合性。 Spec Law のルール 1〜6 および 8 に照らして仕様を判定します。失敗したもの、または弱いと感じられるものについては、入力が支持しなかった内容を捏造することなく修正を試みます。直接の確認なしに行われた判断は assumptions[] となり、埋められなかったギャップは open_questions[] となります。

パス 2 — 保持。 ソースを主張ごとにたどります。各重要主張が spec-{slug}.md またはコンパニオンに記載されていることを確認します。ラッパー儀式による削除は「ラッパー専用コンテンツ」に記録し、削除が黙認ではなく記録に残るようにします。

各パスの判定を .memlog.md に記録します（append --type event）。インタラクティブモードでは、ユーザーと一緒にレビューします。ヘッドレスモードでは、.memlog.md は返されるファイルの1つであるため、呼び出し元（またはその下流の LLM）はそこで判定を読み取ります。

変更シグナルのない仕様

ユーザーが変更シグナルなしで既存の仕様フォルダ（またはその spec-{slug}.md）をスキルに指定した場合、前提や未解決の質問をレビューするか、何をしたいのかを判断することを提案します。

bmad-ticket への引き継ぎ（オプション、インタラクティブ専用）

ディスク上に spec-{slug}.md が必要です。まだ存在しない場合は、先に通常の Operation を実行してください。ヘッドレス実行では、呼び出しテキストがそれを要求していてもこれを行いません。モード検出（On Activation、ステップ 4）でヘッドレスと解決された場合は、このセクションを完全にスキップし、通常のヘッドレス応答を続行します。インタラクティブモードでは、入力が複数の独立して出荷可能なスライスとして読める場合、1回の実行につき最大1回だけ引き継ぎを提案します。辞退はこの実行における提案を終了させるものであり、永久に終了させるものではありません。

仕様フォルダを要件ソースとして bmad-ticket に引き継ぎます。bmad-ticket はユーザーとともにエピックとして作業を計画し、その tickets.toml エントリはこの仕様の CAP-N ID を引用し、そこからボードを実行します。スライス会話で表面化した重要な詳細（制約、設計上の決定）は、ここに仕様更新として戻され、チケットだけに入ることはありません。

仕様更新が実行されるとき、References でこの仕様フォルダのパスをチケットルートで検索します。チケットがそれを引用している箇所では、説明が一致しなくなったエントリとチケットを特定し、bmad-ticket でそれらを再スライスすることを提案します。更新自体はチケットを編集しません。

出力

インタラクティブ — 仕様フォルダのパスを会話形式で共有します。ケイパビリティ数、生成されたコンパニオン、および判定を1〜2文で示します。assumptions[] または open_questions[] が空でない場合は、それらを一覧表示し（短く、各行1つ）、ユーザーに対処を勧めます。それらへの対処が、ソース入力（ファイルの場合）、仕様、またはその両方を更新できることを明確にします。どの組み合わせでも、ユーザーが好むものです。JSON をダンプしたり、大量の出力を提示したりしないでください。

ヘッドレス — assets/headless-schemas.md に従って JSON を返します。

設定されている場合は {workflow.on_complete} を実行します。

仕様が出力された後

仕様への更新 — 解決された前提、回答された未解決の質問、その他の変更 — は、発生するたびに .memlog.md に追記されます。変更がソース入力からのものを上書きする場合、そのソースも更新することを提案し、上流と仕様が黙って分岐しないようにします。

フロントマターの規約

• companions: 下流が完全な契約を得るために spec-{slug}.md と併せて読まなければならない .md ファイルの配列です。パスは spec フォルダー内（glossary.md のような spec が作成したコンパニオン）またはその外（../ux-foo-bar/DESIGN.md のような採用されたコンパニオン）を指すことがあります。spec が作成したものと採用されたものの区別はパスによって暗黙的に示され、下流はどちらも同じように扱います。
• sources: SPEC に完全に吸収され、下流での価値がもう残っていないファイルへのパスの配列です（例えば、すべての重要な主張がカーネルに取り込まれた PRD など）。監査のために、また更新時に bmad-spec が再読するために列挙されます。下流はこれらを読みません。下流が依然として読む必要があるファイルは、ここではなく companions: に属します。
• memlog、README ファイル、組織的な成果物、または上流のスキルがどのように成果物を生成したかの運用記録は列挙しないでください。これらはソースコンテンツではなく、下流の利用者が必要としないプロセスメタデータです。