bmad-spec

BMad Spec

概述

BMad spec-kernel 生态系统的规范转换器。接收任意意图输入——模糊的想法、脑暴记录、PRD、GDD、RFC、简报、Slack 讨论串、客户邮件、会议记录、原型图、混合多来源——并生成 spec-{slug}.md，其中包含五字段内核（Why、Capabilities、Constraints、Non-goals、Success signal），以及用于承载无法纳入内核或会用大量逐项细节使内核膨胀的关键内容的伴随文件。它们共同构成所有下游 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 所属的 epic 或 initiative 文件夹时（如 bmad-ticket 所做的那样），spec 文件夹则为 <that folder>/{workflow.run_folder_pattern}。

{slug} 描述的是被编写 spec 的对象，而非输入形态：

• 源产物已带有 slug（例如 prd-foo-bar/）：继承（foo-bar）。
• 稀疏、聊天内或多来源输入：交互模式会询问；无头模式调用方将其作为输入的一部分提供。如果缺失且无法推导，无头模式会以 error_code: "missing_slug" 阻塞。
• 相同 slug = 相同文件夹。使用相同 {slug} 的第二次调用会落到已有的 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）、假设、开放问题和用户指示的日志，每条一行、按发生顺序排列，从不编辑或重排。spec-{slug}.md 以及每个由 spec 编写的配套文件都在每次运行时派生自 memlog（即记录在案的决策）以及它引用的原始内容来源——从不手工修补。

从一份活的日志派生出契约，而不是就地编辑契约，正是这一点让围绕 spec 的各步骤（PRD、UX、架构、史诗）能以任意顺序运行，并向同一份 spec 提供输入而不会出现合并漂移：日志只累积，产物则重新渲染。因此 spec 只能通过在此重新派生来更新——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>" —— 一次，在创建时。
• 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>" —— 每当有一条落地时。
• 终局时刻（验证结论、"spec finalized"）是 --type event 条目；memlog 不带状态字段。

操作

读取输入及其附属的关联材料。如果没有输入，则遵循 Workspace 中的无输入分支（询问或阻断）。如果目标文件夹中已存在先前的 .memlog.md，请读取它——此时操作变为更新，并且关于已决定内容与能力 ID 的权威来源是 memlog（而非渲染出的 spec-{slug}.md）。保留这些 ID；新能力获得下一个未使用的 CAP-N；绝不重用已停用的 ID。否则这是一次创建，第一步是 memlog.py init。

当输入是结构化且预先分拣好的（带有附录的 PRD、GDD、由上游 BMad 技能产出的 brief），信任其既有的分离方式：将与内核契合的内容提取到 spec-{slug}.md，将溢出的内容提取到命名恰当的伴随文件中。当输入是混杂的（头脑风暴记录、转录稿、RFC、客户邮件），由你自己进行分拣：逐条审视每个主张，应用三视角承重测试（Spec Law 规则 7），并将其路由到内核字段或伴随文件。

以 {workflow.spec_template} 为骨架，将输入提炼为五字段内核。当输入丰富时，直接提取——无需引导。当输入稀疏时，选择：express（尽力提炼，每个缺口都成为一条 open_questions[] 条目）或 guided（与用户逐字段走完这五个字段）。无头模式默认使用 express 并记录该选择。交互模式则询问。

输入未处理的一个已识别领域含义就是这样一个缺口——将其命名为一条 open_questions[] 条目（医疗输入未提及 PHI/HIPAA、支付未提及 PCI、控制系统未提及故障安全），然后继续。标记它；绝不臆造答案或引导用户趋向答案。如果这类缺口占主导，说明输入过于单薄——建议使用 bmad-prd。

从第一遍起就写得精炼：每一句话都必须有其价值。修饰会消耗 token，并稀释下游读者。

在做出每一项决策、能力、约束和已接受的变更时，将其记录到 .memlog.md——渲染所读取的正是这份持续记录。由于该日志是仅追加的，后一条条目会在同一点上取代前一条，而历史仍保持完整。当两个当前存活的来源或伴随文件在同一字段上不一致，或某个二选一始终未解决时，将其呈现给用户，而不是默默选择——该解决本身也是一条新的 memlog 条目。

如果输入确实过于单薄而无法提炼（例如“一个给徒步者的应用”且没有周围上下文），停止并建议使用 bmad-prd（或同类仪式技能）。本技能负责提炼；它不负责引导。

承重性

如果任何消费者（下游技能、实现 Agent、验证环节）在没有某条主张的情况下会改变决策，那么该主张就是承重的。

伴随文件

当承载关键内容无法装入五字段内核时，它会存放在伴随文件中。内核引用它；伴随文件承载它。伴随文件是契约的一部分；每个消费者都会读取 spec-{slug}.md frontmatter 中的 companions: 来发现它们。伴随文件遵循与 spec-{slug}.md 相同的精简准则（Spec Law 规则 8）。

当内容需要超过一行内核形态的内容时，就生成一个伴随文件： 多项目录（按实体划分的矩阵，如 archetypes、drinks、modes、routes）、表格、图表（始终）、编辑语气规则、内核按名称引用的长篇参考材料（glossary、brownfield notes、project conventions）。单行决策摇摆项留在 Constraints 中；intent+success 配对留在 Capabilities 中。如果某个内核字段开始以要点嵌套子要点，说明内容已超出内核，需要伴随文件。

伴随文件要么是：

• Spec 编写的伴随文件由 bmad-spec 编写，并作为 spec-{slug}.md 的同级文件存在（例如 glossary.md、patron-archetypes.md）。bmad-spec 拥有它们，并可在更新操作中编辑它们。
• 采纳的伴随文件是由上游 skill 编写、下游仍需要读取的承载关键内容的产物。bmad-spec 通过相对路径将它们引用到 companions: 中，但不编辑它们（例如来自 UX 运行的 DESIGN.md 或 EXPERIENCE.md、集成合作伙伴的 API spec）。发起它们的 skill 拥有它们。

有两条规则约束伴随文件：

1. 为 Spec 编写的伴随文件按其承载的内容类型命名。 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。原则是："读者在打开它之前就应该知道里面有什么。" 采纳的伴随文件保留其发起 skill 给它们的任何名称。
2. 图表始终放入伴随文件，无论大小。spec-{slug}.md 内核只包含散文。Mermaid 块、ASCII 图表和图像引用都放在伴随文件中（例如 architecture-diagrams.md），并从那里引用同级图像文件。

下游需要的既存项目级文档（例如 project-context.md）被列为采纳的伴随文件，绝不复制到 spec-{slug}.md 或 Spec 编写的伴随文件中。

Spec Law

每个 spec 都必须满足这八条规则。操作以它们为目标；self-validate 扫描强制执行它们。

1. 每个 capability 都同时具有 intent 和 success。 缺少任何一个 = 不是 capability。
2. Intent 描述 WHAT，而不是 HOW。 实现规定属于伴随文件（stack、conventions）。
3. Constraints 确实会改变设计决策。 一个不排除任何东西的 "constraint" 只是装饰。
4. Non-goals 是明确的。 至少一个。缺失意味着下游 skill 会填补这个真空。
5. Success 信号具体到足以测试或演示。 "Users love it" 不符合要求。
6. Capability ID 是稳定且唯一的。 绝不复用，绝不重新编号。
7. Preservation。 每个承载关键内容的源声明都落在 spec-{slug}.md 或伴随文件中。Wrapper ceremony 不算。
8. 精简散文。 每句话都承载关键内容。删去装饰、模糊措辞、背景故事、清嗓子式铺垫。适用于 spec-{slug}.md、伴随文件和 .memlog.md。

自校验

每次创建或更新后，在呈现之前对生成的产物进行两遍扫描。

第 1 遍 — 一致性。 依据 Spec Law 规则 1–6 和 8 评判该规范。对于任何未通过或显得薄弱的地方，尝试在不虚构输入未支持的内容的前提下修复它。未经直接确认而做出的判断成为 assumptions[]；无法填补的缺口成为 open_questions[]。

第 2 遍 — 保留。 逐条遍历来源主张。确认每一条承重主张都已落入 spec-{slug}.md 或某个伴随文件。包装仪式性的删减记录在“仅包装内容”下，使删减有据可查，而非悄无声息。

将每一遍的判定结果记录到 .memlog.md（append --type event）。在交互模式下，与用户一同审阅。在无头模式下，.memlog.md 是返回的文件之一，因此调用方（或其下游大模型）在那里读取判定结果。

没有变更信号的规范

当用户将技能指向一个现有规范文件夹（或其 spec-{slug}.md）且没有变更信号时，主动提出审阅假设或待解决问题，或确定他们想做什么。

移交给 bmad-ticket（可选，仅交互模式）

要求磁盘上存在 spec-{slug}.md —— 若尚不存在，请先运行正常操作。无头运行绝不执行此操作，即使调用文本要求这么做：如果模式检测（On Activation，第 4 步）判定为无头模式，请完全跳过本节，继续正常的无头响应。在交互模式下，当输入读起来像是多个可独立交付的切片时，每次运行最多提供一次移交；一次拒绝仅结束本次运行的提供，而非永久结束。

将规范文件夹作为需求来源移交给 bmad-ticket：它与用户一起将工作规划为一个 epic，其 tickets.toml 条目引用本规范的 CAP-N id，并从那里运行看板。切片对话中浮现的承重细节（一条约束、一个设计决策）会回到这里作为规范更新，绝不只进入工单。

当一次规范更新运行时，在工单根目录中搜索 References 里本规范文件夹的路径；在工单引用它的地方，指出其描述已不再匹配的条目和工单，并主动提出用 bmad-ticket 重新切片。更新本身绝不编辑工单。

输出

交互模式 —— 以对话方式分享规范文件夹路径。用一两句话说明能力数量、生成的伴随文件以及判定结果。如果 assumptions[] 或 open_questions[] 非空，请列出它们（简短 —— 每行一条）并邀请用户逐一过一遍。说明处理它们可以更新来源输入（如果它是一个文件）、规范，或两者兼有 —— 取决于用户偏好哪种组合。不要倾倒 JSON 或呈现一大堵输出。

无头模式 —— 按 assets/headless-schemas.md 返回 JSON。

若已设置，运行 {workflow.on_complete}。

规范输出之后

对规范的任何更新 —— 已解决的假设、已回答的待解决问题、其他变更 —— 都在发生时追加到 .memlog.md。当某项变更覆盖了来自来源输入的内容时，主动提出也更新该来源，以免上游与规范悄无声息地产生分歧。

Frontmatter 约定

• companions: 由下游必须与 spec-{slug}.md 一同阅读的 .md 文件组成的数组，以便获得完整契约。路径可以指向 spec 文件夹内部（由 spec 编写的伴随文件，如 glossary.md），也可以指向其外部（采纳的伴随文件，如 ../ux-foo-bar/DESIGN.md）。由 spec 编写与采纳之间的区分通过路径隐含体现；下游对两者一视同仁。
• sources: 由已被完全吸收进 SPEC、不再具有下游价值的文件路径组成的数组（例如，一份 PRD，其每一条关键主张现均已进入内核）。列出这些文件是为了审计，也供 bmad-spec 在更新时重新读取。下游不读取这些文件。下游仍需读取的文件应放在 companions: 中，而不是这里。
• 不要列出 memlog、README 文件、组织性产物，或任何关于上游技能如何产出其产物的操作记录。这些不是源内容；它们是下游消费者不需要的过程元数据。