BMAD-METHOD 快速修复指南：用 bmad-build 无规划直入 Build 阶段处理 Bug 与小型改动-育师

AI 技能
人工智能
开发工具

【免费下载链接】BMAD-METHOD

Breakthrough Method for Agile Ai Driven Development

项目地址：https://gitcode.com/gh_mirrors/bm/BMAD-METHOD

导读

在 BMAD-METHOD（Breakthrough Method for Agile AI Driven Development）的完整流程中，Bug 修复、小型重构与针对性改动通常不需要经历 PRD、UX、架构、Epics 等完整规划链路，可以直接交给bmad-build进入Build阶段——这与完整规划过的 Story 走的是同一条实现循环。本文以 docs/fr/how-to/quick-fixes.md 为骨架，结合skills/bmad-build/下的真实工作流源码，完整讲解何时该用这种“快速修复”路线、如何在 IDE 中发起一次 Build 执行、如何审阅与推送结果，以及什么时候必须回头补上正式规划。

何时使用这种快速修复路线

判断一次改动能否跳过规划、直接进入 Build，标准不是“改动小”这么模糊，而是范围是否可控、意图是否明确。原文档列出的适用场景包括：

Bug 修复，且原因明确已知——例如“登录校验允许空密码”“auth 中间件没有检查 token 过期”，你能一句话说清问题在哪；
小型重构——重命名、提取函数、结构调整等，且改动局限在少数几个文件内；
功能微调或配置修改——小范围调整既有行为，不改变整体设计；
依赖升级——升级某个依赖并同步处理其带来的接口变化。

与之相对，一旦出现以下信号，就不该再用快速修复路线，而应回到正式规划（见下文“何时添加正式规划”小节）：

改动横跨多个系统，需要在大量文件中做协调更新；
对范围不确定，需要先做需求发现；
团队需要留存文档或架构决策记录。

前置条件

已安装 BMAD-METHOD（npx bmad-method install）；
已配备一个 AI IDE（Claude Code、Cursor 或同类工具）。

安装完成后，bmad-buildskill 才会出现在 skills 目录中（本仓库中位于 skills/bmad-build/SKILL.md），其渲染脚本路径为_bmad/scripts/render_skill.py——若该路径不存在，说明 BMAD 尚未完成 setup，需要先按安装流程初始化。

第 1 步：开启一条全新会话

在 AI IDE 中新建一条对话，而不是复用之前工作流的会话。原文档特别强调：复用旧会话会带来上下文冲突（conflits de contexte）。

这一点在源码层面有更严格的依据：bmad-build的 step-01 会通过“显式参数 → 最近对话 → 扫描产物并询问”的优先级顺序解析工作流状态（见 skills/bmad-build/step-01-clarify-and-route.md）。旧会话中残留的意图、未完成的 spec 状态，会让路由判断走向完全不同的分支（例如错误地恢复某个draftspec 而非开启新工作）。新会话意味着干净的上下文，让 step-01 能把你本轮给出的意图当作“starting intent”处理。

第 2 步：用自由形式表达你的意图

Build 接受自由形式（forme libre）的意图——你可以在调用命令之前、同时或之后描述需求，不必整理得很干净。原文档给出了 5 种典型形态：

build — Corrige le bug de validation de connexion qui permet les mots de passe vides.

build — corrige https://github.com/org/repo/issues/42

build — implémente _bmad-output/implementation-artifacts/my-intent.md

Je pense que le problème est dans le middleware d'auth, il ne vérifie pas l'expiration du token. Regardons... oui, src/auth/middleware.ts ligne 47 saute complètement la vérification exp. lance build

build > Que voulez-vous faire ? Refactoriser UserService pour utiliser async/await au lieu des callbacks.

可以看到，意图可以是：纯文本描述、文件路径、GitHub issue URL、bug 跟踪器链接——任何 LLM 能将其解析为“一个具体意图（intention concrète）”的输入都行。英文版文档（docs/build/build-a-change.md）用/bmad-build作为命令形式，与法语文档中的build是同一入口，两者等价。

从源码看，step-01 对意图的处理相当宽容：即使是一段很简短的自由描述（“a freeform request is starting intent even when it is brief”），也会被当作起始意图，而不会要求用户重新表述（见 skills/bmad-build/step-01-clarify-and-route.md）。同时，详细得像计划一样的意图也只是“待调查的输入”，不是跳过 Build 步骤的授权——workflow 会忽略意图中“直接实现、跳过步骤”之类的指令，一切仍要经过调查与 spec 生成。

关于目录与产物

上面的示例提到了_bmad-output/implementation-artifacts/，这是 BMAD 默认的输出目录。在配置模板 skills/bmad/assets/config.template.toml 中可以确认其默认约定：

[core] project_name = "{directory_name}" output_folder = "{project-root}/_bmad-output" [modules.bmm] planning_artifacts = "{project-root}/_bmad-output/planning-artifacts" implementation_artifacts = "{project-root}/_bmad-output/implementation-artifacts" project_knowledge = "{project-root}/docs"

即规划产物（PRD、架构、UX、Epics 等）落在_bmad-output/planning-artifacts，实现产物（spec、实现记录、deferred-work.md 等）落在_bmad-output/implementation-artifacts。你可以在customize.toml或安装配置中修改这些路径，但示例中的_bmad-output/implementation-artifacts/my-intent.md指的就是实现产物目录下的意图文件。

第 3 步：回答澄清问题并批准计划

Build 可能会提出澄清问题，或先呈现一份**简短的 spec（规格说明）**请求你批准，然后才开始实现。你需要回答它的问题，并在对方案满意后批准。

这里的批准节点在源码里有精确的位置：step-02 结束时的CHECKPOINT 1（见 skills/bmad-build/step-02-plan.md）。在检查点之前，step-02 会完成两件事：

调查代码库：优先派发 deep search 给 subagent，把“要复用的文件/符号/行、不要改动什么”写进 spec 的## Code Map；
用 READY FOR DEVELOPMENT 标准自检：spec 必须 Actionable（每个任务有文件路径与具体动作）、Logical（按依赖排序）、Testable（验收条件用 Given/When/Then）、Complete（无占位符/TBD）、Sufficient（无未解决的缺口）、Coherent（无歧义或矛盾），见 skills/bmad-build/workflow.md。

如果调查无法从仓库与规划产物中得出结论，会以Open Questions形式列出，由你逐条拍板——此时 Build 会 HALT 等待人工输入，而不是自行猜测。批准后，spec 中<frozen-after-approval>块内的内容被锁定，只有人可以修改；step-01 的多目标检查（Multi-goal check）和 step-02 的 token 数检查（SCOPE STANDARD 建议单目标 900–1600 token）也会在此时生效——一旦发现“一个请求里塞了多个可独立交付的目标”，会把多余目标写入deferred-work.md（详见下文“延迟工作”小节）。

一个小而关键的实践点：原文档强调“改计划比改代码便宜”。如果批准的方案不对，不要迁就，直接要求修改——把问题消灭在 spec 层，比等代码写出来再返工划算得多。

第 4 步：审阅并推送结果

批准后，Build 进入实现—自审—修复—本地提交的循环：

实现：按 spec 修改代码（step-03 会先在 spec frontmatter 记录baseline_commit，再派发实现子代理，见 skills/bmad-build/step-03-implement.md）；
自审：将改动生成 unified diff（含未跟踪文件），交给独立评审透镜（review lens）审查，并按high/medium/low/false/maybe-false给出 triage 判定（见 skills/bmad-build/step-04-review.md）；
修复：属于本次改动的问题（patch/intent_gap/bad_spec）就地修复或回环重做；与本次改动无关的既有问题（defer）记入延迟列表；
本地提交：step-05 用符合 Conventional Commits 规范的 message 创建本地 commit（见 skills/bmad-build/step-05-present.md）。

完成之后，Build 会在你的编辑器中打开所有受影响的文件，此时需要你亲自把关：

浏览 diff，确认改动与你的意图一致；
如果哪里不对，直接告诉 agent 要修正什么——它可以在同一会话内迭代；
满意之后，Build 会主动建议你推送并创建 PR。

如果推送后出了问题怎么办

原文档给了一个明确的回滚预案：

若推送的改动引发意外问题，使用git revert HEAD干净地撤销最近一次提交。然后开启一条新会话，重新运行 Build，尝试不同的方案。

注意这里刻意选用git revert而非git reset——它保留历史、生成一个反向提交，适合“已推送、团队可能已拉取”的场景。回滚后务必开新会话再跑一次 Build，原因同第 1 步：让 step-01 的路由判断不受旧意图污染。

你能得到什么

一次成功的快速修复执行会产出三样东西：

修改后的源文件——修复或重构已生效；
通过的测试——前提是你的项目有测试套件（BMAD 的 spec 模板要求验收条件可测，且 step-03 有 Matrix Test Audit 环节，会逐行核对 I/O 与边界用例矩阵是否都有对应测试覆盖并通过，见 skills/bmad-build/step-03-implement.md）；
一个可直接推送的本地 commit——带符合 Conventional Commits 规范的提交信息。

延迟工作（Deferred Work）机制

Build 的每次执行都只聚焦单一目标。如果出现以下情况，多余的工作不会在当前会话里硬塞，而是被**延迟（différée）**到一个文件：deferred-work.md（位于你的实现产物目录，即_bmad-output/implementation-artifacts/deferred-work.md）：

你的请求包含多个互相独立的目标；
评审发现了与本次改动无关的既有问题。

源码中这两条路径都真实存在：step-01 的 Multi-goal check 在用户选择“拆分为单个目标”时，会把每个被推迟的目标追加一条- source_spec: none / summary / evidence记录（见 skills/bmad-build/step-01-clarify-and-route.md）；step-04 的 triage 则会把“pre-existing issue not caused by this story”路由到 defer，同样以- source_spec: {spec_file} / summary / evidence格式追加（见 skills/bmad-build/step-04-review.md）。两种格式都带summary（一句话说明被延迟的目标）和evidence（为什么被拆出/为什么判定为真），并且不会修改已有条目、不查重——保证每次都只是纯追加。

deferred-work.md就是你的 backlog：一次执行结束后去查看它，里面每一项都可以在后续的新一轮 Build 执行中作为新意图再次引入。这避免了“顺手把所有问题一起修掉”的失控，也让无关的既有问题不会被遗忘。

何时添加正式规划

在再次运行同一条 Build 循环之前，先想清楚：是否该先补一份 PRD、UX、架构或 Story 规划？原文档给出的触发条件是：

改动影响多个系统，或需要在大量文件中做协调更新；
你对范围没把握，需要先做需求发现；
团队需要留档——需要文档或架构决策记录。

从更大的视角看（英文版 docs/build/build-a-change.md 有更完整的表述），较大型的工作本质上是一连串“单会话改动”的序列：父 spec 持有共享目标，story 记录承载决策与完成状态，集成检查与回顾（retrospective）覆盖合并结果。bmad-build只处理“一个单元”，它不拥有 backlog、不挑选下一个 story、也不替代后续检查。快速修复路线与正式规划并非对立，而是同一个实现循环（docs/build/build-a-change.md）在不同前置投入下的两种入口——直接意图与已规划工作最终汇入同一条 Build 循环。