BMAD-METHOD 入门指南从安装、首次变更到多 Epic 项目的开发路径选择【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD导读本文以 BMAD-METHODBreakthrough Method for Agile AI Driven Development的官方韩文版入口文档为主线系统讲解AI 辅助软件开发方法的核心理念——想清楚再实现决定权始终在开发者手中。你将掌握如何安装 BMad、判断一次变更该走多深的流程直接编辑 / 单会话 / Epic / 项目、使用bmad-build落地第一次变更以及如何借助bmad-help、bmad-project-context、bmad-spec等技能在既有代码库和团队环境中持续交付。BMad 是什么两套相辅相成的技能体系BMad 并不是一个独立的编程框架而是向 Claude Code、Cursor 等 AI 编码工具添加的一组名为 技能skill 的具名命令集合。整个仓库的skills/目录下放置着数十个技能每个技能都配有SKILL.md技能说明与module-manifest.toml模块清单。从入口文档docs/ko-kr/index.md的定位看这些技能可以清晰地分成两类类别职责典型技能探索与决策类探索想法、展开调研、从反面视角审视并把决定记录下来bmad-brainstorming、bmad-deep-recon、bmad-forge-idea、bmad-product-brief、bmad-prfaq实现类把意图变成经过审查的代码bmad-build有人参与的构建、bmad-build-auto无人值守构建两类技能既可以独立使用也可以组合使用。入口文档特别强调了两点许多用户只使用处理想法的技能一行代码也不交给 BMad——决策类技能本身就能带来价值对于小修小补完全可以直接实现无需额外规划。这种按需取用的设计是 BMad 方法论的基石流程深度与变更规模匹配不做过度工程。将你想要的变更交给bmad-build它会负责写代码、审查代码并给出结果。找到你的起点七个典型入口入口文档的核心价值在于对号入座——针对不同处境给出不同的起点建议。下表把原文的七个场景整理为一张决策速查表你的处境建议起点对应文档不确定一次变更需要多少流程阅读选择开发路径找到最安全且最简单的路径docs/ko-kr/how-to/choose-a-development-path.md想直观看到 BMad 如何工作跟随实现你的第一个变更从空项目执行一次 Builddocs/ko-kr/start/build-your-first-change.md明确知道改什么且改动很小直接运行bmad-build并描述变更内容docs/ko-kr/build/build-a-change.md在既有代码库中工作先考虑运行bmad-project-context之后照常使用 Builddocs/ko-kr/how-to/established-projects.md、docs/ko-kr/how-to/project-context.md正在做更大的功能或整个产品若意图已完整可直接交给bmad-spec否则从开发路径选择或工作流地图中挑选路径docs/ko-kr/reference/workflow-map.md想法还很模糊、不确定是否值得做用头脑风暴发散选项用 Deep Recon 收集依据或对想法进行压力测试docs/ko-kr/explanation/deep-recon.md希望 BMad 遵循团队规则与工作方式参考定制 BMad与为组织扩展 BMaddocs/ko-kr/how-to/customize-bmad.md小贴士如果不知道从哪里开始直接运行bmad-help即可。它会检查项目现状、结合已安装模块给出选项并理解自然语言提问是所有工作流结束时的自动指引。安装与验证把 BMad 接入你的 AI 编码工具无论是新项目还是既有项目安装 BMad 只需一条命令npx bmad-method install该命令会把 BMad 技能安装到所选 AI 工具使用的技能目录并在项目下生成_bmad/目录用于存放技能共享的配置与支撑脚本。详见 安装 BMad。环境前提依赖用途说明Node.js 20.12运行安装程序硬性要求支持的 AI 编码工具运行已安装的技能当前支持列表可通过npx bmad-method install --list-tools查询uvbmad-build、bmad-build-auto等以 Python 渲染产物的技能缺失时安装仍可完成但会显示警告相关技能在安装 uv 前无法工作Git从 Git 安装外部或自定义模块仅在需要时要求安装后的验证三步查看完成摘要安装结束会显示BMAD is ready to use!消息与安装路径验证工具联动在项目目录打开选定的 AI 编码工具运行bmad-help技能询问接下来该做什么——工具若能识别并执行技能说明联动成功更新与重配置在包含_bmad/的项目中重新运行npx bmad-method install安装程序会检测既有安装并提供更新或修改路径。预发布版本与 CI 安装预发布安装npx bmad-methodnext install同一命令也用于更新预发布安装。预发布构建变更更频繁、可能包含未完成改动普通项目请使用稳定版Headless CI 安装例如为新环境配置 Claude Code 版 BMMnpx bmad-method install --yes --modules bmm --tools claude-code自动化场景下请用npx bmad-method install --help查看当前自动化参数、用--list-tools确认正确的工具 ID。源码级佐证技能如何被执行从仓库中的技能定义skills/bmad-build/SKILL.md可以看到bmad-build的入口并非硬编码逻辑而是通过一条渲染命令把技能内容展开为可执行的工作流uv run --no-cache {project-root}/_bmad/scripts/render_skill.py --project-root {project-root} --skill {skill-root}支持通过--set workflow.routevalue指定执行路线oneshot或full支持通过--set workflow.reviewvalue选择审查强度none、quick或thorough成功执行后技能会读取标准输出中打印的workflow.md绝对路径并按其执行若_bmad/scripts/render_skill.py不存在说明安装尚未完成需要先按bmad技能的 SKILL.md 完成初始化流程再重新执行上述命令。这解释了为何安装步骤如此关键render_skill.py与uv是技能真正落地的运行环境。仓库中对应的渲染实现位于 skills/bmad/scripts/render_skill.py其配套测试见 skills/bmad/scripts/tests/test_render_skill.py。选择开发路径从单行编辑到多 Epic 项目一次变更到底需要多少流程是 BMad 用户最常遇到的判断难题。选择开发路径给出了系统的决策方法。核心原则不要看工作范围大小而要看意图的清晰度、风险与影响面。高风险、需求不明、影响整体架构、跨系统、需要多人协调的变更需要更多规划。四层路径速查表路径使用时机起点简单任务编辑内容明确、风险低、系统化审查无额外收益时直接编辑单会话任务一个连贯意图可在一次实现会话内完成时bmad-buildEpic 规模任务达成一个连贯结果需要多次实现会话时bmad-spec之后拆分故事Story Breakdown项目规模任务跨越多个 Epic或实现会话可能约 20 次以上时完整 BMad 流程见工作流地图上表中的会话次数只是参考基准而非硬性要求——一个小的安全类变更可能比一个大的普通任务需要更规范的流程。即便变更很小只要显式规划与审查有助益就应使用bmad-build而不是直接编辑。各路径如何落地简单任务 / 单会话任务简单任务直接用日常开发工具改单会话任务把期望结果直接交给 Build例如/bmad-build 给 diffsettings 命令添加 JSON 输出但不要改变现有格式。Build 可以接受你手写的意图、Issue、意图文件、既有 Build 规范或已规划的故事作为输入。它会明确工作单元、按需规划、实现并审查结果、留下工作记录。Epic 规模任务当需要多次 Build 会话但目标一致时走轻量 Epic 路径输入 Epic 意图运行bmad-spec请求故事拆分Story Breakdown在SPEC.md旁生成带顺序的stories.yaml审查建议顺序决定哪些故事需要检查点checkpoint。故事列表是执行计划而非不可变的承诺——后续工作若暴露出遗漏的约束、更好的拆分方式或故事间冲突应修改规范并重新执行故事拆分。重要、高风险或奠基性的故事用bmad-build实现形成后续复用的模式后再自动化重复性工作。每个故事各执行一次 Build完成后不要只逐个检查故事还要验证所有故事协同工作再对规范文件夹运行bmad-retrospective它会读取stories.yaml并对照上层规范评估整体结果。项目规模任务新产品或多 Epic 倡议、实现会话可能约 20 次以上时使用完整 BMad 流程。规划产出探索、PRD、UX、架构、Epic、就绪检查、冲刺计划构成围绕实现的共同契约与协调基准但不替代 Build——每个 Epic 仍是会话级工作单元的序列。依赖与集成边界清晰时可并行推进相互独立的 Epic 流程每个流程需有负责人且都必须遵循同一产品意图与架构在 Epic 边界处执行集成检查与回顾。大型路径的运营要点在决策稳定后再加入自动化bmad-build-auto在单个会话中执行一个工作单元且不等待人工输入但它不负责选择下一个故事或管理 backlog。可选的bmad-loop编排器能按stories.yaml的顺序确定性执行但它不做依赖图推断、也不提供项目级并行协调保护上层意图任务拆分过程中信息会流失——需求被稀释、约束被遗漏、两个各自正确实现的故事组合运行时可能失败。大型 BMad 路径通过产品/UX/架构/Epic 产出物保存共同决策、每个实现单元可回溯到上层契约、故事记录把实现决策与完成状态传给后续工作、集成检查评估组合行为、回顾评估整个 Epic 并沉淀经验等机制降低此类风险。工作流地图BMM 的四阶段全景工作流地图把 BMad MethodBMM的软件交付组织为四个阶段每个阶段只添加当前工作所需的上下文。以下为各阶段核心技能、目的与产出物清单可直接按技能名调用。阶段一分析可选在敲定计划前探索问题域、验证想法详见分析阶段说明。工作流目的产出物bmad-brainstorming在头脑风暴教练引导下发散项目想法brainstorm.html存档与可选的brainstorm-intent.mdbmad-forge-idea锤炼并验证想法或以低成本将其证伪每次运行产出forge-report.html想法成型后产出forged-idea.mdbmad-deep-recon为决策调研任意主题生成提示、处理报告或在本环境执行调研含验证与引用的六种类型包调研报告或摘要 可选的 HTML 简报bmad-product-brief捕捉战略愿景概念清晰时效果最佳brief.mdaddendum.md需要时输出 HTML 或演示稿bmad-prfaq以工作反向working backward方式从客户优先视角对产品概念做压力测试prfaq-{project}.md阶段二规划定义为谁做什么。工作流目的产出物bmad-prd生成、更新、验证 PRD用分步提问细化需求一个技能承载三种意图生成/更新prd.md、addendum.md、.memlog.md验证validation-report.html.mdbmad-ux在 UX 关键时设计用户体验产出 DESIGN.md视觉与 EXPERIENCE.md行为两份核心文档DESIGN.md、EXPERIENCE.md、.memlog.mdbmad-spec把 Brief、PRD、对话记录、脑图、设计文件夹等多样意图输入提炼为简洁的SPEC.md契约与伴随文件先定 WHAT 再谈 HOW{output_folder}/specs/spec-{slug}/下的SPEC.md 伴随文件需要时含stories.yaml值得注意的细节bmad-prd在一个技能内承载生成 / 更新 / 验证三种意图调用时说明意图即可bmad-spec是唯一能编写SPEC.md的技能其五字段内核Why、Capabilities、Constraints、Non-goals、Success signal会验证是否完整保留原始文档的核心主张bmad-product-brief阶段一产出的product-brief.md可作为bmad-prd细化需求的输入但两者并非互相必需。阶段三解决方案设计决定怎么做并把工作拆分为故事。工作流目的产出物bmad-architecture把技术决策显式化核心文档ARCHITECTURE-SPINE.md按需扩展为输出或演示形式bmad-create-epics-and-stories把需求拆分为可实现的单元含故事的 Epic 文件bmad-sprint-planning实现前经过就绪门Readiness Gate提供故事跟踪与状态视图PASS/CONCERNS/FAIL sprint-status.yaml就绪门、确定性跟踪与状态视图的协同机制见冲刺规划说明。阶段四实现实现以会话级工作单元推进bmad-build处理有人参与的单元bmad-build-auto处理无人值守单元。工作流目的产出物bmad-build以人工检查点为界实现并审查一个意图或计划故事实现记录 代码bmad-build-auto为调用方或编排器无人值守地实现并审查一个工作单元实现记录 代码 退出状态bmad-code-review按需单独审查指定代码变更发现项 已应用的补丁bmad-correct-course处理冲刺中的重大变更更新后的计划或路径调整bmad-retrospective按验收标准与依据回顾已完成的 Epic回顾文档、行动项、验收裁定直接进入与规划后进入清晰的单会话任务可直接交给bmad-build规范驱动的 Epic 通过故事拆分在单个SPEC.md下创建多个工作单元多 Epic 项目则可在选定每个工作单元前追加 PRD、UX、架构、Epic、就绪结果与冲刺跟踪。Build Auto 本身不协调工作单元由 AI 编码会话或bmad-loop等外部编排器为每个单元选择并运行一个 worker。上下文管理每份文档都是后续决策的上下文PRD 记录产品需求架构记录每个实现单元应遵循的模式与边界规范与故事记录在拆分与重组过程中保全意图、决策与完成状态。强烈建议设置bmad-project-context管理AGENTS.md中简洁且经过验证的规则块使 AI 智能体在所有工作流中遵守项目规则。绿地从规范或架构出发棕地从代码库中提取并验证规则、经用户确认旧版bmad-generate-project-context已废弃并收敛到此技能。bmad-build 实操一次有人参与的构建实现变更详细描述了bmad-build的完整运行流程。它接受任何形式的意图——一句话、Issue、规范或已规划的故事流程分为六步开启新会话在 AI IDE 中打开新聊天避免复用其他工作流的会话造成上下文混杂传达意图命令前后或与命令一起描述变更无需整理干净——凌乱的描述、语音转文字的想法、未成形的点子、Issue 链接、文件、规划好的故事都可以基于依据确认意图bmad-build从请求出发调查代码库与上层规划产物。依据充足就直接推进只有仓库与计划上下文都无法判定的内容才作为未决问题留给用户——它不会在开始前进行冗长的访谈。未决问题的回答务必慎重越晚发现错误修正成本越高请求时批准计划调查结束后Build 选择最简单安全的路径并报告意图缺失、不可逆操作、影响范围三类信息。三类信息均无问题时走简单路径同会话内写最小规格→实现→审查任一有问题则先写详细计划。计划描述的结果正确就批准否则要求修改——修改计划远比修改代码便宜实现与审查路径确定后Build 实现变更并以独立审查者身份审查。只修复属于本次变更引入的问题无关的既有问题暂缓。若计划薄弱导致代码错误则退回计划层目标错误导致计划错误则退回目标层——不临时修补 diff而是从问题起源的层级重新生成审查结果这是主要检查点。浏览 diff 确认与意图一致发现异常直接在同一会话中要求修改满意后推送提交技能也可能建议推送或创建 PR。/bmad-build 修复登录校验中允许空密码的 bug。/bmad-build https://github.com/org/repo/issues/42 请修复这个 Issue。/bmad-build 请实现 _bmad-output/implementation-artifacts/my-intent.md 中记录的意图。出问题时的处理推送后若引发意外问题用git revert HEAD安全回退最后一个提交然后开启新会话、换一种方式重新运行bmad-build。一次构建的产出反映变更的源文件若项目有测试套件则通过测试遵循 Conventional Commit 格式、可随时推送的提交一次执行的实现记录若存在上层规范或故事则保存在其旁边。延期工作deferred workbmad-build每次运行只专注一个目标。请求包含多个独立目标或审查中发现与本次变更无关的既有问题时不会一并处理而是写入实现产出目录下的deferred-work.md。运行后请检查该文件——它是后续任务的 backlog每个条目都可重新交给一次新的bmad-build执行。何时应先规划影响多个系统或需同时修改大量文件范围不明需先细化需求需要留下供团队参考的文档或架构决策澄清意图过程中持续暴露单会话内难以解决的矛盾。首次实战从空项目到可运行的 Mars Rover如果你还没有代码库构建你的第一个变更提供了一条单会话开发路径的完整体验。前提是 macOS/Linux shell、Node.js 20.12、Python 3 与受支持的编码工具示例以 Claude Code 为准。步骤一创建空项目并安装mkdir bmad-first-project cd bmad-first-project npx bmad-method install --directory . --modules bmm --tools claude-code --yes然后在该目录打开编码工具Claude Code 中运行claude。步骤二请求实现 Mars Rover不给bmad-build附加任何设计选项直接请求实现经典编程练习 Mars Rover 卡塔/bmad-build 请实现 Mars Rover 卡塔。bmad-build会就必要选择提问例如用哪种语言。你可以回答用 Python 3 实现做成可在本地运行的小型经典终端程序且不依赖 Python 标准库之外的任何库。回答后阅读计划并批准或要求修改技能随即编写程序、检查工作、修复问题并展示变更。步骤三运行验证以python3 mars_rover.py --size 5x5 --obstacle 2,2为例依次输入FFRFF、MAP、QUIT即可在终端看到漫游车在障碍物前停下的完整表现真实输出可能因实现而异。最后打开技能提示的文件查看完成后的程序。步骤四向 bmad-help 提问/bmad-help 请解释 bmad-build 刚才做了什么。bmad-help用于理解已完成的工作、决定下一步或排查问题是整个流程中随时可用的向导。既有代码库接入先立上下文再谈实现在既有代码库中使用 BMad Method 的推荐路径详见既有项目分四步清理已完成规划产物若 BMad 流程已完成的 PRD、Epic、故事文件仍在docs/、_bmad-output/planning-artifacts/、_bmad-output/implementation-artifacts/中请归档、删除或依赖版本历史不要继续保留在约定位置之外创建项目上下文运行bmad-project-context。技能会阅读既有资料、评估现状、询问需要智能体遵守的规则其余信息自行查找并验证命令在记录前全部实际执行确认。最终不膨胀文档而是在仓库的AGENTS.md中写入简洁且验证过的规则块人工维护的既有文件作为改进基准臃肿的docs/作为对照代码的参考资料而不继续增补维护高质量项目文档docs/应包含准确反映项目的简洁文档——意图与商业依据、业务规则、架构及其他相关信息。上下文过期时重新运行审计做减法而非继续堆内容获取帮助不确定时随时运行bmad-help可询问这个变更实现前需要多少规划等所有工作流结束都会自动执行帮助。规划深度方面所有实现都用bmad-build区别只在于前置上下文——明确的更新/新增直接传请求、Issue 或既有规范给bmad-build大的变更/新增则先备好 PRD、UX、架构、Epic、故事、就绪状态与冲刺上下文。UX 工作是否必要取决于是否涉及 UX 变更、是否需要有意义的 UX 新模式仅更新满意现状的既有界面则无需完整 UX 流程架构工作要警惕重复造轮子或做出违背既有架构的决策。总结从本文可以看到BMAD-METHOD 的方法论核心是让流程深度匹配变更规模模糊的想法交给头脑风暴与 Deep Recon清晰的意图交给bmad-spec形成契约小变更直接bmad-build大项目则用 Epic、故事与回顾把共同意图一层层保护起来。整个过程里决策始终由人做出——Build 只在依据无法解决时征求你的意见让你既了解将要交付什么又不必成为流程的瓶颈。要继续深入可按顺序阅读安装 BMad → 实现你的第一个变更 → 选择开发路径 → 工作流地图 → 实现变更。若想了解大型变更的完整演练可继续阅读 getting-deeper 教程。【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考