企业官网建设流程全解析

BMAD-METHOD 自主开发循环：以 bmad-build-auto 构建无人值守的单次迭代 worker 与 orchestrator 调度体系

【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD

本篇技术指南聚焦 BMAD-METHOD 开源仓库（Breakthrough Method for Agile AI Driven Development）中 Autonomous Development Loops 所定义的bmad-build-auto技能：它是「标准 Build a Change 实施模型」的无人值守 worker，一次调用完成"澄清 → 规划 → 实现 → 审查 → 终态写入"的完整闭环，并把 backlog 策略、跨 story 调度与复盘完全交给上层 orchestrator（AI 编码会话或 bmad-loop）。读完本文，你将掌握bmad-build-auto的完整调用契约——五种 intent 输入形态、spec 状态机与恢复路由、folder+id dispatch、输出工件与阻塞条件——并能据此搭建"每 story 一个 worker、由 orchestrator 统一派发"的自动化开发流水线。

一、架构定位：worker 与 orchestrator 的职责边界

bmad-build-auto在 BMAD 实施模型中的定位非常克制：它是一个 session 大小工作单元的无人值守执行者，一次调用只处理一条 intent 或一个 story。它做的事情严格限定为：

1. 澄清传入的 intent
2. 创建（或找到并恢复）spec 文件
3. 实现变更
4. 审查结果
5. 结束时把终态 status写入 spec 文件或 fallback result artifact

它不负责选择下一条 story、不跨 backlog 重复执行、不协调 epic、也不做复盘（retrospective）。这些属于 orchestrator 的职责——例如 AI 编码会话或 bmad-loop。一句话概括分工：Build Auto 拥有自己的 implementation run 及其产出的记录，而 backlog 策略与派发权归 orchestrator。

这一边界在源码中有明确印证。build-a-change.md 的实现技能表中把bmad-build-auto描述为"为 caller 或 orchestrator 无人值守地实现并审查一个单元"，产出"实现记录 + 代码 + 终态 status"；skills-and-agents.md 亦将其登记为"运行一轮无人值守开发循环"。同时，docs/zh-cn/reference/build-auto.md明确指出：bmad-build-auto负责 implementation run 及其生成的 spec artifact，但不负责 backlog policy——当 review 发现真实但不属于当前 story 的问题时，skill 只把 finding 记录在自己负责的 spec 中，是否排队、去重、升级或忽略，完全由 orchestrator 决定。

二、前置条件：subagents 能力与版本控制

该技能强依赖运行 subagent 的能力：

• subagent 不可用即停机：若无法启动 subagent，workflow 以状态blocked、阻塞条件no subagents终止。若由某个 AI 编码会话编排多个 story，该会话必须为每个 story 各启动一个 Build Auto worker，且每个 worker 必须能启动其 run 内部使用的 review subagents。
• 版本控制可选但强烈建议：若启用版本控制，要求 working tree 干净、agent 能更新仓库元数据，且 run 结束时工作副本保持 clean。无版本控制时，基线修订号记作NO_VCS。

三、输入契约：五种 intent 形态与恢复路由

3.1 主调用输入

主输入是 invocation prompt。关键约束：bmad-build-auto把该 prompt 视为 workflow 输入，而非现成的实施计划。支持以下 intent 形态：

• 简短的自由格式变更请求
• ticket、issue 或 story 标识符
• intent 文件路径
• 本 workflow 生成的既有 spec 文件路径
• spec 文件夹 + story id（无具体 spec 文件路径）——即下文"folder+id dispatch"

3.2 恢复输入（Resume Input）

若调用指向 frontmatter 中带已知status的既有 spec 文件，workflow 按状态表从对应入口恢复：

恢复语义在 step-01-clarify-and-route.md 中落地：done状态会先把 frontmatter 的review_loop_iteration重置为0并设置followup_pass: true，然后进入 review 步骤开启新一轮审查——这是"已完成 run 的后续复查"，而非恢复执行。blocked的 spec 被直接调用时，阻塞条件记为blocked spec supplied。

3.3 Folder+ID Dispatch：按故事 id 派发

调用 prompt 可提供 spec 文件夹与 story id，而不给具体 spec 文件路径。此时：

• workflow 读取<spec-folder>/stories.yaml，查找id匹配的条目；
• 只取该条目的title和description——spec_checkpoint、done_checkpoint、invoke_dev_with是派发方 caller 的字段，永远不会从文件本身读取；
• 调用 prompt 中的任何附加文本（如 caller 追加的invoke_dev_with指引）作为额外规划上下文携带，而非对工作的竞争性描述；
• 每次调用只派发恰好一个stories.yaml条目：无论结果如何，workflow 绝不读取其他条目，也绝不推进到另一个 story id。

接着检查<spec-folder>/stories/<story-id>-*.md（id 前缀匹配），以区分首次派发与恢复：

blocked的 story 文件是永久性的：即使原因已修复，此后每次对该 id 的派发都会以story already blocked终止。要重试，必须删除该 story 文件——之后该 id 恢复为 pending，下一次派发从零开始。

跨 story 上下文累积：每当规划运行（首次派发，或对draft恢复的中断规划），workflow 还会加载<spec-folder>/stories/*.md中所有其他文件，把每个文件的 Code Map、Design Notes、Spec Change Log、Tasks & Acceptance 状态与 Auto Run Result 细节作为额外规划上下文带入——使一个 story 的规划能看到同文件夹其他 story 已做的决策与产出。跳过规划步骤的恢复也会跳过这一累积（见 step-01 中draft分支与首次派发分支的具体实现）。

3.4 共享的 spec-backed epic 布局

<spec-folder>/ ├── SPEC.md ├── stories.yaml └── stories/ ├── 1-<slug>.md ├── 2-<slug>.md └── ...

stories.yaml是有序清单；Build 与 Build Auto 在stories/下创建或恢复 Markdown 记录，每条记录的生命周期状态放在 frontmatter 中。下游消费者只依据位置与状态消费记录，而不依赖是哪个 Build workflow 产出的。finish-an-epic.md 中 spec-backed epic 的复盘输入正是这套结构：SPEC.md、有序stories.yaml与stories/<id>-*.md记录，产出RETROSPECTIVE.md于 spec 文件夹内。

四、编排选项：三种将 Build Auto 接入流水线的方式

Build Auto 在每种选项中都是 worker：orchestrator 选定一个单元、启动一个 worker、读取其结果、决定下一步。

4.1 用 bmad-loop 运行有序 manifest

可选的 bmad-loop orchestrator 按列表顺序处理 spec 文件夹的stories.yaml。它是线性调度器：不推断依赖图，因此需自行排列列表，使每个 story 的前置项出现在前面。注意两点：

• 选中一个 story 只运行那一个，不表示"从这里开始跑完剩余部分"；
• 复盘是独立的 epic 收尾活动：bmad-loop 可以推荐复盘，但执行者是bmad-retrospective。

4.2 用 AI 编码会话作为 orchestrator

AI 编码会话可充当 orchestrator：为每个单元派发一个 Build Auto worker，检查产生的 evidence，并在父 spec 或 story 列表不再符合实现所揭示的实际情况时修订后续工作。编排会话负责保持这些修订与更大意图的一致性。

4.3 并行 epic 流

项目级并行需要更高的协调层或独立的 epic 所有者。当依赖与集成边界明确时，独立的 epic 流可以并行运行；bmad-loop 的有序 story 调度器不提供这种项目级协调。

五、上下文输入：激活时解析的内容

激活时 workflow 依次解析：

• _bmad/config.toml、_bmad/config.user.toml，以及_bmad/custom/下可选的团队/用户覆盖
• customize.toml（技能默认定制）、团队覆盖与用户覆盖中的已配置 workflow 定制
• workflow config 中列出的persistent facts——默认空，除非你主动开启，因此默认不加载任何内容

还可能查看：

• BMAD 规划工件（PRD、architecture、UX、epics、product brief 等，见 config.toml 模板 中planning_artifacts指向的目录约定）
• epic 工作的缓存或新编译的 epic context 文件（{implementation_artifacts}/epic-<N>-context.md）
• 同一 epic 中最近完成的上一 story spec，用于连续性
• folder+id dispatch 下同一 spec 文件夹中的其他stories/*.md记录

epic context 的编译规则见 compile-epic-context.md：目标 800–1500 token，严格限定范围（按用途而非来源描述约束、不整段引用规划文档、不收录可从代码库推导的内容、不编造），输出必须以# Epic {N} Context: {Epic Title}开头，且当规划工件缺失时必须在 "Requirements & Constraints" 一节显式声明"Planning artifacts were unavailable"。

六、Spec 状态机：orchestration 的主控信号

spec frontmatter 的status是 orchestration 的主要机器可读状态：

6.1ready-for-dev的两种结局

ready-for-dev通常是 workflow 直接穿过的恢复状态。它变成真正的停机结局只有一个场景：调用 prompt 指示在规划后停机（标准表述Halt after planning.，接受任何清晰等价说法）。此时 spec 通过 READY FOR DEVELOPMENT 门禁后，workflow 置ready-for-dev并停在原地；重新派发同一 spec（或同一 spec 文件夹 + story id）会按上文路由从实现阶段恢复。

规划步骤的详细逻辑见 step-02-plan.md：spec 不达标时先修复一次并重新验证，仍不达标则以blocked/spec failed ready-for-development standard停机。

6.2done时写入的内容

成功完成时，workflow 写入或更新 spec：

• 最终status: done
• ## Auto Run Result小节，包含：实现变更摘要、变更文件、审查发现分解、执行的验证、残余风险
• followup_review_recommended标志——LLM 判断是否值得再做一轮审查。它是建议而非强制；最简单的二次审查方式是重新运行该技能并指向 spec 文件
• baseline_revision——实现前的完整规范修订号；无版本控制时为NO_VCS
• 分诊为defer的审查发现写入 frontmatterdeferred:条目

workflow 会 commit 但绝不 push，退出时 working copy 干净。

6.3blocked时写入的内容

阻塞结束时，workflow 写入：最终status: blocked（当 spec 存在时）、阻塞条件、以及 spec 或 fallback result artifact 中的支撑细节。

intent gap的特殊处理：它意味着捕获的 intent 无法回答 run 中遇到的某个问题，可能在任何代码存在之前停在规划步骤，也可能停在审查步骤。当审查阶段因此停机时，工作树照常回滚，但尝试过的变更会先以 patch 文件保存到{implementation_artifacts}，并在 spec 的分诊日志与 halt 输出中引用。该 patch 展示了这次 run 实现了 intent 的哪种解读——这是修复 intent 的具体证据。若事后确认该解读正确，可git apply该 patch 并把 spec 状态置为in-review以在其上恢复审查，而无需从头重跑。

七、输出工件：终态与证据的持久化

workflow 总是尽力留下描述所发生之事的持久工件。

7.1 主 spec 工件

新工作时创建：{implementation_artifacts}/spec-<slug>.md

该 spec 是规划、实现、审查三方的契约，包含：

• frontmatter status
• frontmatter 机器状态（followup_review_recommended、warnings、deferred、修订标记）
• 不可变的<intent-contract>块
• Code Map
• Tasks & acceptance criteria
• Spec Change Log
• Review Triage Log
• Verification notes

字段细节可见 spec-template.md：frontmatter 还含route（oneshot/full）、route_source（pinned/auto）、review（none/quick/thorough）、review_source、lenses_ran、review_loop_iteration、context与warnings（如oversized、multiple-goals）。

7.2 Story spec 工件（Folder+ID Dispatch 模式）

folder+id dispatch 下，workflow 写入<spec-folder>/stories/<story-id>-<slug>.md，替代主 spec 或 fallback 路径——包括规划开始前的 halt。此模式下 fallback result artifact 永不使用。

当 halt 发生在能从 story 标题派生 slug 之前，回写退化为固定 slug 段：

若解析路径已存在，workflow 更新其statusfrontmatter 并在## Auto Run Result下追加结果细节；若不存在，则创建骨骼 story spec：frontmatter status、标题（条目的title，条目无法解析或磁盘匹配歧义时用Story <story_id>）、以及## Auto Run Result小节。该逻辑在 workflow.md 的 HALT 协议中逐条实现。

7.3 Fallback result artifact

若 workflow 在获得有效spec_file之前 halt（非 folder+id dispatch），写入：{implementation_artifacts}/bmad-build-auto-result-<slug-or-timestamp>.md，记录终态与阻塞条件。

7.4 附加工件

按路由不同，还可能写入：

• {implementation_artifacts}/epic-<N>-context.md（epic 上下文编译产物）
• 审查步骤因intent gap停机时保留尝试变更的 patch 文件（路径记录在 spec 分诊日志中）

八、阻塞条件全清单

典型的阻塞条件包括（前三个为常见通用条件）：

• unclear intent（意图不足以识别要实现什么）
• intent gap（捕获的 intent 无法回答 run 遇到的问题）
• no subagents（无法启动审查子代理）
• missing spec_file before implementation
• implementation verification failed
• review repair loop exceeded 5 iterations (non-convergence)
• blocked spec supplied（直接调用的 spec 文件已是status: blocked）
• no stories.yaml found
• story id not found in stories.yaml
• no epic spec found
• ambiguous story file match
• unrecognized status in existing story file
• story already blocked（仅 folder+id dispatch——与blocked spec supplied相对）

blocked在实操中通常意味着 run 遇到无人值守执行不安全的情形——这往往是更高级 orchestrator、另一 workflow 或人类接手的时机。解决阻塞后，orchestrator 通常应启动一次全新 run；若复用先前工作，应传显式的已知良好 spec 路径，而非依赖隐式发现。

九、源码级深入：route、review 与 triage 的自动化内核

9.1 激活与入口

SKILL.md 规定激活方式：在项目根执行uv run --no-cache "{project-root}/_bmad/scripts/render_skill.py" --project-root "{project-root}" --skill "{skill-root}"（不可改变当前工作目录、只执行一次），成功后读取 stdout 打印的绝对workflow.md指令继续。支持--set workflow.route=<oneshot|full>与--set workflow.review=<none|quick|thorough>显式钉住执行路线与审查深度；workflow.route与workflow.review仅允许oneshot/full/auto与none/quick/thorough/auto取值（见 workflow.md 开头的校验）。

9.2 执行路线：oneshot 与 full

step-02-plan.md 中route决定实现方式，route_source为pinned（显式指定）或auto（按customize.toml的route_selection规则自动选择——估算改动行数，≤100 行用 oneshot，否则 full；改动超 5 个文件且非简单机械时考虑升级 full）。oneshot 在主会话直接实现；full 则通过 customize.toml 的implementation_handoff派发一个无上下文的实现 subagent，spec 是其唯一事实来源。

9.3 审查透镜与分诊

step-04-review.md 与 customize.toml 定义了审查机制：

• review取值none（不启动透镜、跳过 triage）、quick（运行quick_lenses）、thorough（运行thorough_lenses）、auto（oneshot→quick，full→thorough）；
• 审查前先把 spec 状态置为in-review，从baseline_revision重写 unified diff 到临时文件（含 untracked 文件），透镜只读 diff 文件路径，prompt 中从不粘贴 diff 文本；
• quick 集含 1 个透镜：Quick（对照 AC 与仓库规则找未满足项）；
• thorough 集含 4 个透镜：Blind Hunter（按 diff 大小计算发现数下限N = min(floor(sqrt(kB) + 1), 10)）、Edge Case Hunter（读 review-prompts/edge-case-hunter.md）、Verification Gap Reviewer（读 review-prompts/verification-gap.md）、Intent Alignment Auditor（对照{verbatim_intent}描述 diff 实现的是哪一档 intent 解读）。

每个 finding 必须被验证后给出唯一裁决：high（不可容忍）/medium（可容忍）/low（修饰性）/false（核实后不成立）/maybe-false（无法判定，需记录什么证据能判定）。随后按共享根因分组，路由到四种 triage 类别之一：

• intent_gap——由本次变更引起、且 spec 无法裁决（根因在<intent-contract>内）：保存 patch、回滚代码、halt；
• bad_spec——由本次变更引起但 spec 本应避免（根因在 intent-contract 之外）：提取 KEEP 指令、回滚、修订 spec 的 Change Log 后重新进入 step-03 再推导；
• patch——最小修复琐碎、不新增公共表面：自动修复（oneshot 自己打补丁，full 路由重新接续 step-03 的实现 subagent），补丁验证后重写 diff；
• defer——非本 story 引起的前置问题，或全部maybe-false且"若属实将达到 medium 或更糟"的条目：写入 frontmatterdeferred:列表，序列化为 YAML 块标量，校验 frontmatter 完整可解析。

审查-修复回环每轮递增review_loop_iteration，超过 5 轮仍未收敛则以blocked/review repair loop exceeded 5 iterations (non-convergence)停机。

9.4 Deferred Findings：机器可读的审查输出

deferred是技能报告"真实但不属于本 story 问题"的地方。每个条目包含：

• summary——一句话描述该延后问题
• evidence——为何该发现是真实的
• location——可选，file:line 或组件提示
• severity——可选，最终分诊严重度（high/medium/low）；maybe-false条目携带其"若属实"的等级并加 "(unverified)"

maybe-false的发现仅在"若属实将达到medium或更糟"时才延后，其 evidence 记录什么能判定它；更弱的在 spec 分诊日志中以相同注释拒绝。这不是 backlog，而是机器可读的审查输出——决定下一步（建 ticket、追加中央队列、跨 run 去重、或什么都不做）完全在于 orchestrator。

9.5 Finalize：终态与提交

step-04-review.md 的 Finalize 段规定：写## Auto Run Result（实现摘要、变更文件、审查发现分解、验证执行情况、残余风险），按本 pass 的 patch 裁决数计算followup_review_recommended（首轮：任一high被 patch 或 ≥2 个medium被 patch 为 true；follow-up pass：仅当本 pass patch 了high才为 true），随后提交所有未提交的已审查 diff 文件（不 push），验证工作副本干净，否则blocked/finalization left repository dirty，最后以donehalt。无版本控制时直接置done并 halt。

十、Orchestrator 责任清单

集成bmad-build-auto的 orchestrator 应：

• 一次只传一条连贯 intent
• 恢复先前工作时优先传 spec 路径——或 folder+id dispatch 下传同一 spec 文件夹与 story id
• 监控产出的 spec 文件、story spec 工件或 fallback result 文件的终态
• 读取status、blocking condition 与followup_review_recommended，而不是仅凭聊天输出推断成功
• 从 spec frontmatter 的deferred:列表读取延后发现
• 用baseline_revision..<下一个 story 的 baseline_revision>识别一个 story 的提交；没有下一个 story 时在退出点用baseline_revision..HEAD
• 预期自主的文件变更与本地提交
• 把blocked视为路由信号而不仅是失败信号——它通常意味着应由更高级 orchestrator、另一个 workflow 或人类接管

十一、何时使用：与 bmad-build 的分工

build-a-change.md 明确了选择边界：基础性、高风险或重要 story——你的决策可能为后续工作立下范式——先用bmad-build（带人工检查点）；一旦模式稳定，bmad-build-auto可以在无需等待你的情况下运行一个单元。普通的一次性会话（约 500 行代码量级）直接交给bmad-build；更大的工作应先走规划路径拆解为一系列单会话变更，由父 spec 保持共享目标、story 记录承载决策与完成状态，集成检查与复盘（bmad-retrospective，见 finish-an-epic.md）覆盖合并结果。bmad-build-auto不编排这些单元：AI 编码会话或其他 orchestrator 按单元派发一个 worker——这正是本文所述的 autonomous development loops 契约。

【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD