BMAD-METHOD bmad-walkthrough 技能解析从命令渲染到五阶段人工代码审查工作流【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD导读bmad-walkthrough是 BMAD-METHODBreakthrough Method for Agile AI Driven Development方法论体系中负责引导人类审查代码变更的专用技能Skill。它解决的是 AI 生成代码后「谁来把关、如何把关」的核心问题不是让 AI 直接下结论而是把变更拆解为「定位变更 → 按关注点走查 → 风险细节扫描 → 可观察行为验证 → 最终决策」五个阶段把设计判断权交还给人类。读完本文你将掌握该技能从触发命令、底层渲染原理到五个工作流步骤的完整执行机制以及如何通过customize.toml定制它的行为边界。技能定位与触发方式触发场景与命令入口bmad-walkthrough的定位在 SKILL.md 的 frontmatter 中定义得十分明确Walk the user through reviewing a change——引导用户审查一次变更回答三个问题这次变更做了什么what it is for、应该重点看哪里what to look at closely、以及如何测试它how to test it。触发词包括walkthroughwalk me through this changehuman review当用户说出上述任一短语时该技能被激活。SKILL.md 的核心指令是恰好执行一次下面的命令且不改变当前工作目录uv run --no-cache {project-root}/_bmad/scripts/render_skill.py --project-root {project-root} --skill {skill-root}其中{project-root}是项目根目录的绝对路径{skill-root}是本技能目录的绝对路径。命令成功时stdout 会打印出一个绝对的workflow.md路径Agent 需要读取并严格遵循该文件中的指令。失败处理的三级策略SKILL.md 规定了清晰的失败分支值得在实际使用中严格照做未找到{project-root}/_bmad/scripts/render_skill.py说明该 BMad 安装尚未完成初始化。此时应读取同级bmad技能的 SKILL.md即 skills/bmad/SKILL.md按其 setup 流程完成安装然后重新运行上面的命令。其他任何失败包括uv不可用报告命令输出并HALT停止禁止绕过渲染器直接运行任何 workflow 源文件。这一设计保证了工作流永远以「渲染后的快照」为准避免 Agent 直接读取源文件而遗漏定制内容。底层原理render_skill.py 如何把模板渲染成工作流_bmad/scripts/render_skill.py在仓库中的源文件位于 skills/bmad/scripts/render_skill.py安装阶段会被部署到项目的_bmad/scripts/目录下参见 skills/bmad/scripts/setup.py 中对_bmad目录的就位逻辑。从 render_skill.py 的main()可以看到命令行参数设计参数必填说明--project-root是项目根目录绝对路径用于解析{project-root}前缀--skill是技能目录绝对路径渲染源即该目录下的所有 markdown 文件--overrides否仅本次调用生效的定制 TOML 文件--set KEYVALUE否命令行的键值对定制可重复出现渲染机制的核心思想是内容寻址的快照生成见 render_skill.py先以占位目标目录做一次探测渲染probe pass收集所有模板实际读取过的定制输入如果调用方提供了某个模板从未读取的 key会直接抛RenderErrorinvocation override not used by this render从机制上杜绝无效定制。随后基于project_root、skill_root、渲染器自身 SHA-256、Jinja2 版本、已解析的定制值、所有源文件哈希计算出一个generation_hash输出到_bmad/render/{skill-name}/{slug}-{root-hash}/{generation-hash}/workflow.md。最后把workflow.md的绝对路径写到 stdoutread and follow {entry}并生成包含schema_version、skill、project_root、outputs哈希等字段的 manifest。这套「内容寻址 渲染快照」的设计配合 skills/bmad/scripts/tests/test_render_skill.py 中对渲染流程的端到端测试保证了同一个技能在不同项目、不同定制下产出的是确定性强、可审计的工作流文件而 SKILL.md 中「只运行一次、直接读 stdout 结果」的约定正是为了简化 Agent 侧的状态管理。工作流总览五阶段结构与全局规则渲染出的 workflow.md 是执行蓝图。它的总体目标是引导人类从「变更的目的与上下文」出发一路深入到细节from purpose and context into details。激活序列每个工作流运行都先经过激活步骤顺序执行Prepend 步骤激活前的预置步骤如预加载、合规检查_None._表示跳过加载持久事实Persistent Facts所有条目作为本次运行的基础上下文常驻——file:前缀的条目是{project-root}下的文件路径或 glob需要把文件内容读入作为事实其余条目原样作为事实_None._表示无Append 步骤持久事实加载后、工作流正式开始前的补充步骤。全局步骤规则代码引用格式所有文件路径和file:line引用必须以「当前展示环境可点击」的形式呈现聊天中可用 markdown 链接终端中建议使用无前导/的 CWD 相对path:line形式先整体呈现再闭嘴每个步骤的完整输出必须在一条消息中一次性呈现步骤中途不问问题、不挤牙膏、不在段落间停顿。步骤执行顺序Orientation → Walkthrough → Detail Pass → Testing → Wrap-Up严格按序读取、执行、再加载下一步禁止跳步、重排或预加载只有被明确指向时才能读取下一步。第一步 Orientation确定「审查什么」step-01-orientation.md 解决的是审查前最关键的问题——找到正确的变更对象。定位变更的五级级联对话上下文是起点而非空白画布按以下顺序检查一旦命中立即停止显式参数用户消息里是否带了 PR、commit SHA、分支或 spec 文件PR → 用gh pr view解析到分支/commit解析失败则请求 SHA 或分支spec 文件、commit、分支 → 直接使用。最近对话最近几条消息是否揭示了要审查的变更spec 路径、commit 引用、分支、PR 或变更描述。Sprint 跟踪在{config.implementation_artifacts}或{config.planning_artifacts}中查找*sprint-status*文件扫描状态为review的故事——恰好一个则建议并确认多个则编号列出没有则继续下探。当前 git 状态查看当前分支和 HEAD向用户确认「我看到的 HEAD 是short-shaonbranch——这是你要审查的变更吗」询问以上全部失败才开口问——改了什么、为什么改、看哪个 commit/分支/PR、有没有 spec 或 bug report。若 3 轮对话仍无法定位变更HALT。级联之外禁止追问额外问题——这保证了审查从不偏离用户意图。ENRICH补充关联工件定位到变更后补齐互补信息有 spec → 读取其 frontmatter 中的baseline_commit作为 diff 基线有 commit/branch → 在{config.implementation_artifacts}中查找baseline_commit是该 commit/branch 祖先的 spec说明该 spec 描述的是基于该基线之上的工作两者都有 → 同时使用。确定 change_type 与 review_modechange_type按用户的指称设置PR、commit、branch或用户自己的措辞如auth refactor不确定则默认change。review_mode取第一个匹配模式判定条件意图来源full-trailENRICH 找到含## Suggested Review Order章节的 specspec 的 Intent 章节spec-only找到 spec 但无 Suggested Review Orderspec 的 Intent 章节bare-commit无 speccommit message若不足 10 词扫描 diff 推断主要变更模式起草一句话意图并在输出中标记[inferred]供用户纠正产出 OrientationIntent 摘要若来自 spec 的 Intent 章节逐字呈现无论多长其他来源commit message、bug report、用户描述≤200 tokens 逐字呈现超出则压缩到 ≤200 tokens 并链接到完整来源。格式为 **Intent:** {summary}。Surface Area Stats表面积统计尽力而为地从 diff 得出基线按顺序尝试spec frontmatter 的baseline_commit与main或默认分支的 merge-baseHEAD~1..HEAD仅最新提交需告知用户全部失败则跳过并注明 Could not compute stats。使用git diff --stat与git diff --numstat计算文件级计数并扫描完整 diff 内容获取更丰富的指标最终呈现为一行N files changed · M modules touched · ~L lines of logic · B boundary crossings · P new public interfaces其中Files changed来自--statModules touched是有变更的不同顶层目录数Lines of logic是排除空行/import/格式化的新增与修改行~表示近似Boundary crossings是跨越多个顶层模块的变更数单模块为 0New public interfaces是 diff 中出现的新导出、端点、公共方法。无法计算的指标宁可省略绝不猜测。Fallback Trail 生成若非full-trail模式读取并执行 references/generate-trail.md基于 diff 生成 2–5 个关注点每个关注点选 1–4 个path:line停靠点优先入口点、决策点、边界跨越点最后是外围测试、配置、类型格式为「关注点名 每行 ≤15 词的定位短语 path:line」。生成的轨迹即作为后续步骤的 Suggested Review Order并把review_mode设为full-trail。若 git 不可用回到 step-01 并报告 Could not generate trail — git unavailable.。生成轨迹的质量虽低于作者亲手撰写的轨迹但远胜于没有。第二步 Walkthrough按「关注点」而非「文件」走查step-02-walkthrough.md 是走查的主体核心理念是按 concern关注点组织而不是按文件组织。一个 concern 是内聚的设计意图例如「输入校验」「状态管理」「API 契约」——一个文件可以出现在多个 concern 下一个 concern 也可以横跨多个文件。这一阶段激活的是设计判断而非正确性检查把每个 concern 表述为「这个变更做了什么、为什么这么做」由人类评估它对系统而言是否是正确的方法。构建走查有 Suggested Review Orderfull-trail模式正常路径读取 spec或 step-01 生成的轨迹中的停靠点 → 解析为仓库内文件 → 阅读 diff 理解每个停靠点的实际行为 → 按设计意图分组为 concern无 Suggested Review Order轨迹生成失败时的回退直接取 diff按内聚的设计意图识别 concern——功能性分组每簇变更支撑什么用户可见行为、架构层次是否跨越 API → 服务 → 数据边界、设计决策作者在哪些备选方案中做了选择。理解顺序的编排自上而下排序先最高层意图是什么、为什么再深入支撑性实现concern 内部的停靠点要让每个都能建立在前一个之上读者永远不会遇到「还没见过的引用」如果变更存在自然入口点新公共 API、配置变更、UI 入口用它打头阵。每个 concern 的写法标题一句命名设计意图的短语不是文件名不是模块名Why1–2 句讲清该 concern 解决什么问题、为什么选此方案而非备选若 spec 记录了被否决的备选方案在此引用Stops每个停靠点独占一行path:line 一句 ≤15 词的定位短语。典型变更的目标是2–5 个 concern单 concern 的变更也完全可以不要凭空发明分组超过 7 个 concern 是「范围可能过大」的信号但仍需照常呈现。呈现与早期退出输出格式为进度条Orientation → [Walkthrough] → Detail Pass → Testing随后是各 concern 组消息以「Take your time」引导语结尾邀请用户在走查过程中随时提问例如run advanced elicitation on the error handling、party mode on whether this schema migration is safe准备好后说next进入风险扫描。早期退出如果人类在任何时刻表达出决策意愿lets ship it、this needs a rethink、Im done reviewing 等确认意图后直接跳转到 step-05若误解了用户则致歉并继续当前步骤。第三步 Detail Pass风险感知而非纠错step-03-detail-pass.md 的定位非常关键机器加固已经处理了正确性这一步激活的是风险意识——呈现的是人类「应该思考什么」而不是「代码哪里错了」。LLM 只负责按模式识别风险类别人类判断其重要性不给严重度打分或排名按爆炸半径排序只是为了可读性。识别风险点扫描 diff 中触及风险敏感模式的变更寻找2–5 个「犯错代价最高」的位置不是最复杂的代码而是错了最贵的地方标签覆盖范围[auth]认证、授权、会话、令牌、权限、访问控制[public API]新增/变更的端点、导出、公共方法、接口契约[schema]数据库迁移、schema 变更、数据模型修改、序列化[billing]支付、定价、订阅、计量、用量跟踪[infra]部署、CI/CD、环境变量、配置文件、基础设施[security]输入校验、消毒、加密、密钥、CORS、CSP[config]特性开关、环境相关行为、默认值[other]其他风险敏感项并发、数据隐私、向后兼容等用描述性标签排序规则爆炸半径大的在前错了会破坏多少东西而不是按 diff 顺序或文件顺序。超过 5 个则展示前 5 并注明 N additional spots omitted — ask if you want the full list.。没有任何匹配则明确说明 No high-risk spots found in this change — the diff speaks for itself.绝不强行编造发现。机器加固发现检查 spec 是否有## Spec Change Log章节由对抗式审查循环填充有条目 → 阅读并呈现对人类审阅者有启发意义的条目——不是已修复的 bug而是审查循环标记过、人类应该知情的决策格式为「标记了什么 决定了什么」无条目或无 spec →整节跳过提都不要提。定向复审Targeted Re-Review当人类说 dig into [area]如 dig into the auth changes指定区域不映射到 diff 中任何代码 → 说明 I dont see [area] in this change — did you mean something else? 并回到收尾菜单定位 diff 中与该区域相关的所有代码位置读完整上下文不只 diff hunk要读周边代码切换到正确性模式追踪边界情况、检查边界条件、验证错误处理、查找 off-by-one、竞态条件、资源泄漏以紧凑列表呈现发现path:line 发现了什么 为什么重要无可担忧项 → 明确说明 Looked closely at [area] — nothing concerning. The implementation is solid.呈现后只显示收尾菜单不再重复风险点列表。定向复审可多次触发每次都只呈现新发现和收尾菜单。第四步 Testing用「眼见为实」建立信心step-04-testing.md 是体验式的而非分析式的。Detail Pass 问的是「你想过 X 吗」这一阶段说的是「你可以亲眼看到 X」。三条纪律不规定动作人类决定观察是否值得花时间建议以选项而非义务的形式提出不重复自动化假定 CI、测试套件、自动化检查都存在且工作正常这里关注的是任何自动化测试都无法提供的那种信心——手动观察无可观察行为就明说绝不编造观察项。识别可观察行为扫描 diff 和 spec 中能产生人类直接观察结果的变化UI 变更新界面、布局修改、交互变化、错误状态CLI/终端输出新命令、输出变化、新 flag 或选项API 响应新端点、载荷变化、不同状态码状态变更数据库记录、文件系统产物、配置效果错误路径坏输入、缺失依赖、边界条件。对每个可观察行为确定三要素What to do——具体动作要运行的命令、要点的按钮、要发的请求What to expect——确认变更生效的可观察结果Why bother——一句话把该观察与变更意图关联起来上下文自明时可省略。典型变更目标 2–5 条建议超过 5 条按「观察带来的信心/付出的努力」排序。呈现格式为### How to See It Working 每条**描述** / Do: / Expect:命令和请求用代码块包裹。无可观察行为时替换为 This change is internal — no user-visible behavior to observe. The diff and tests tell the full story.。第五步 Wrap-Up让决策显式化step-05-wrapup.md 是整个流程的收口核心是HALT——在人类做出选择之前绝不继续Review complete. Whats the call on this {change_type}? - **Approve** — ship it (I can help with interactive patching first if needed) - **Rework** — back to the drawing board (revert, revise the spec, try a different approach) - **Discuss** — somethings still on your mind决策后的行动Approve简短确认。若人类想在发布前修补某些内容交互式地帮助应用修复若在审查 PR可提议用gh pr review --approve批准——但必须事先与人类确认因为这是对共享资源的可见操作Rework追问哪里出了问题——是方案、spec 还是实现帮助人类决定下一步revert commit、开 issue、修订 spec 等若是他人提交的 PR帮助起草绑定path:line位置的具体、可操作的反馈Discuss开放对话回答问题、探索顾虑、深挖任何方面讨论结束后回到上面的决策提示。工作流到达最后一步且决策做出后若on_complete配置了内容将其作为退出前的最终指令执行否则正常退出。定制扩展点customize.toml 的四个钩子skills/bmad-walkthrough/customize.toml 是该技能的定制面与[workflow]命名空间下的 Agent 定制形状保持一致。文件头明确标注DO NOT EDIT——每次更新都会被覆盖真正的定制通过覆盖合并完成标量覆盖生效override wins数组persistent_facts、activation_steps_*追加append含code/id的数组表替换匹配项、追加新项。四个可配置项配置项类型默认值用途activation_steps_prepend数组[]标准激活前运行的步骤用于预加载、合规检查等activation_steps_append数组[]持久事实加载后、工作流正式开始前运行的步骤适合需要激活上下文就位的重上下文设置persistent_facts数组[]整个运行期间常驻的静态事实标准、合规约束、风格护栏。每条可以是字面句子或file:前缀的文件引用支持 glob文件内容被加载视为事实on_complete标量工作流到达最后一步、审查决策approve/rework/discuss做出后执行的收尾指令留空则无自定义行为这些钩子与渲染器 render_skill.py 中「override 必须被模板实际读取否则报错」的校验配合构成了 BMAD 方法论中「技能可定制、但定制必须有效」的结构性约束——同样的机制也服务于项目级配置解析参见 skills/bmad/scripts/resolve_config.py。与其他 BMAD 技能的协作关系从整个技能库的结构看bmad-walkthrough处于 BMAD 工作流的质量把关环节它的触发词和输出风格与 skills/bmad-code-review 形成互补——后者偏重正确性审查claims-check、deletion-check前者偏重人工引导式走查它在走查过程中允许随时调用其他技能深入局部如 run advanced elicitation on the error handling 指向 skills/bmad-advanced-elicitationparty mode on whether this schema migration is safe 指向 skills/bmad-party-mode它读取 spec 的## Suggested Review Order与## Spec Change Log章节与 skills/bmad-build 等产出 spec 的技能形成数据契约。版本方面module-manifest.toml 声明该模块当前为6.13.0-next知识来源指向bmad技能的references/help.md。实践建议严格走渲染通道永远通过uv run --no-cache ... render_skill.py触发不要直接读源文件执行——定制内容只有在渲染后才生效绕过渲染等于丢弃定制。尊重 HALT 点step-01 定位不到变更、step-05 决策前都是强制停止点。审查流程的价值恰恰在于「不做未授权的事情」。区分三个阶段的心智模式Walkthrough 用设计判断、Detail Pass 用风险意识、Testing 用体验观察混用会破坏整个流程的节奏。善用定向复审dig into [area] 是 Detail Pass 阶段最高效的深潜工具多次触发只呈现新发现不会打断主线。理解统计口径Surface Area Stats 中「无法计算就省略」的原则保证呈现给人类的每个数字都是可信的宁缺毋滥。【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考