企业官网建设流程全解析

BMAD-METHOD 入门实战：用 bmad-build 从空项目到第一个可运行程序

【免费下载链接】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）是一套面向 AI 辅助开发的方法论与技能集合，核心实现单元是bmad-build技能。本文以官方入门教程 build-your-first-change.md 为主线，带你从零开始：在一个空目录中安装 BMad、用bmad-build把一个短句请求变成可运行的程序，并完成运行验证与结果检查。读完本文，你将掌握bmad-build的完整调用方式、它"澄清需求 → 出计划 → 实现 → 自查 → 汇报"的内部工作流，以及如何用bmad-help自主排障，从而能把同样的流程复用到你自己的仓库和真实改动上。

环境准备与前置条件

开始之前，需要一台满足以下条件的开发机（教程原文明确给出）：

• 操作系统：macOS 或 Linux 的 shell 环境。
• Node.js 20.12 或更高版本：安装器依赖 Node 运行时，见 install-bmad.md 的前置条件说明。
• Python 3：教程目标程序使用 Python 标准库编写，无需第三方依赖。
• 一个受 BMad 支持的 AI 编码工具：教程中的安装与启动命令以 Claude Code 为例；如果你使用其他受支持工具，在安装时选择它，并在该工具中运行bmad-build技能即可。

另外，从 install-bmad.md 可知，uv是运行 Python 类技能（包括bmad-build与bmad-build-auto）的运行时依赖：如果环境缺少uv，安装器会给出警告但仍会完成安装，只是相关技能在安装uv之前无法正常工作。Git 仅在从 Git 安装外部模块或自定义模块时才需要。

第一步：创建空项目并安装 BMad

BMad 的安装以项目目录为单位，安装器默认使用当前目录。先建一个空目录并进入：

mkdir bmad-first-project cd bmad-first-project

然后运行安装命令，安装当前稳定版并为 Claude Code 完成配置：

npx bmad-method install --directory . --modules bmm --tools claude-code --yes

对照 install-bmad.md 中的命令参数说明，可以这样理解各参数的含义与作用：

上面的写法属于"无交互（headless）安装"。官方推荐的全自动写法在 install-bmad.md 的 "Headless CI installs" 一节也有给出：

npx bmad-method install --yes --modules bmm --tools claude-code

可以通过npx bmad-method install --help查看当前可用的自动化参数，用npx bmad-method install --list-tools获取有效的工具 ID 列表。安装完成后，安装器会显示 "BMAD is ready to use!" 成功摘要和 BMad 的安装路径；BMad 的技能会被安装到所选工具的 skill 目录，项目根下的_bmad目录则存放所有技能共享的配置与辅助脚本。

提示：想体验预发布版本时使用npx bmad-method@next install；预发布版本变更频繁、可能包含未完成改动，日常项目工作建议始终使用稳定版命令。

第二步：启动编码工具并调用 bmad-build

在项目目录中打开你的 AI 编码工具。以 Claude Code 为例：

claude

随后向bmad-build技能发起请求，让它实现著名的 Mars Rover 编程练习（Mars Rover kata，一个用于练习 TDD 与面向对象设计的小型编码训练题），并且明确要求不添加任何设计取舍：

/bmad-build write an implementation of mars rover kata

之所以这样措辞，是因为把设计空间留给bmad-build本身，它才有机会向你提问澄清。实际运行中，它很可能从这样一个问题开始：

`bmad-build`: Before implementation, I need one choice: which language should I use? You: Python 3. Make it a small old-school terminal program I can run locally, with no dependencies beyond Python standard library.

你得到的提问、回答、计划与最终程序都可能与本例不同——请根据你真正想要的行为作答，而不是照抄示例回答。

一次典型会话的完整节奏

根据 build-a-change.md 的流程描述，bmad-build的完整运行分为六个环节：

1. 开启全新会话：在 AI IDE 中新建一个聊天窗口。复用其他工作流的会话可能混淆上下文、干扰本次运行。
2. 表达意图：意图可以在命令之前、之后或同时给出，不需要组织得很整洁——一句话、一段语音转写、一个半成型的想法、一个 issue 链接、一个文件甚至一个计划好的 story 都可以作为输入。
3. 基于证据解析意图：bmad-build会先调查代码库与上游规划产物，只有仓库和规划上下文都无法定夺的问题，才会变成待你回答的开放问题。
4. 必要时批准计划：调查结束后，它会报告三项关键事实——意图缺口（你没说、但会在结果里注意到的内容）、不可逆操作、影响范围。三项都干净时走轻量路径（同一会话内产出精简 spec 并实现）；有任何一项被标记，则先产出完整书面计划，每个意图缺口都记录为开放问题，等你批准后再动手。
5. 实现与自查：计划获批后，它实现改动、用独立评审视角复查自己的工作、修复属于本次改动的问题，并在本地提交。复查是"分诊"而非"倾倒所有意见"：属于当前改动的问题被修复，与本次无关的既有问题被推迟；如果代码错是因为计划弱、计划错是因为目标错，它会回到对应层级重新生成，而不是只修补 diff。
6. 检查结果：完成后给出简短摘要，并提供常见后续动作（创建 PR、走查改动、继续下一个改动）。

回到本教程的会话：回答完问题后，阅读它给出的计划；认可后批准，或提出修改意见。随后bmad-build会写出程序、自查并修复问题，最后向你展示改动了什么。

第三步：运行你的 Mars Rover 程序

根据你在澄清环节做出的选择，结果可能类似这样一个纯标准库实现的命令行程序：

python3 mars_rover.py --size 5x5 --obstacle 2,2

进入程序后依次输入FFRFF、MAP、QUIT。终端会展示一辆在地图上移动、并在障碍物前停下的火星车：

MARS ROVER CONTROL Commands: F/M forward, B backward, L/R turn, MAP, STATUS, HELP, QUIT Position: (0, 0) Heading: N rover> Position: (1, 2) Heading: E OBSTACLE: movement blocked at (2, 2) rover> 4 . . . . . 3 . . . . . 2 . > # . . 1 . . . . . 0 . . . . . 0 1 2 3 4 rover> Mission control signing off.

逐行解读这次运行输出：

• 启动参数--size 5x5定义了一块 5×5 的网格地图，--obstacle 2,2在坐标 (2, 2) 放置了一个障碍物（你实际得到的参数与程序界面可能不同，取决于你与bmad-build的对话内容）。
• F/M前进、B后退、L/R转向、MAP显示地图、STATUS查询状态、HELP帮助、QUIT退出。
• 输入FFRFF后，火星车先前进两格、右转、再前进两格，到达坐标 (1, 2)、朝向 E；随后遭遇 (2, 2) 处的障碍物，输出OBSTACLE: movement blocked at (2, 2)表明移动被阻断。
• 输入MAP后，地图上用>表示火星车当前位置与朝向，#表示障碍物，网格周围标注了行列坐标。

运行结束后，打开会话最后一条消息中列出的文件，查看bmad-build生成的完整程序——这正是你验证它工作质量的第一手材料。

第四步：用 bmad-help 理解刚刚发生的事

bmad-help技能用于回答关于 BMad 本身的问题：理解刚才发生了什么、决定下一步做什么，或者解决某个问题。在会话中直接提问：

/bmad-help Explain what bmad-build just did.

从 skills/bmad/SKILL.md 的实现可以更清楚地认识这个技能的设计原则：

• 它对每一次请求都重新扫描宿主暴露的技能根目录，不复用旧扫描结果；项目技能会遮蔽用户技能，若仍存在重复则以平局处理并明确告知。
• 它只读取每个技能目录旁的module-manifest.toml（模块清单），按module键把已安装技能分组，并依据清单中的knowledge字段指向的文档来给出路由建议——模块清单是磁盘上的成员名单，帮助流程不会把未安装的技能报告为"某集合缺失的成员"。
• 普通帮助请求是只读的：不会去读_bmad下的配置缓存，不会运行resolve_config.py，不会写入任何文件，也不会以副作用方式触发 setup/update 等流程。

这意味着你可以放心地用bmad-help探索技能之间的关联，它只回答、不改变你的安装状态。

bmad-build 做了什么：一个请求如何变成可运行软件

Mars Rover 这个例子浓缩了bmad-build的核心价值：把一个短请求变成可运行软件。整个过程包括：

1. 澄清请求——通过开放问题补齐你未言明的设计决策（本例如语言、界面形态、依赖约束）；
2. 给出计划供批准——报告意图缺口、不可逆操作与影响范围，让你在写代码前就能纠正方向；
3. 实现程序——按计划产出文件；
4. 检查自己的工作——独立评审、分诊发现、修复属于本次改动的问题，最后汇报改动。

什么时候不需要走完整流程

build-a-change.md 的 "Size the Work" 一节给出了务实的边界：一个典型的bmad-build会话适合一个目标、大约 500 行左右（不含测试）的代码改动、涉及少量文件的工作。如果是一次你愿意自行审查的琐碎修改，可以直接让 agent 改；但只要有 bug 可能逃逸到生产环境，就值得交给bmad-build。它还支持"单次直达"（one-shot）或跳过评审的显式要求——这些是面向原型验证或低风险改动的快捷选项。

一次运行你会得到什么

对照 build-a-change.md 的 "What You Get" 一节，一次bmad-build运行的标准交付物包括：

• 应用了改动的源文件；
• 通过测试（如果项目有测试套件）；
• 一个带规范提交信息（conventional commit message）、可直接推送的提交；
• 该次运行的实现记录（implementation record），在有父级 spec 或 story 时保存在其旁边。

此外，如果一次请求包含多个相互独立的目标，或评审发现了与本次改动无关的既有问题，bmad-build会把它们写进实现产物目录下的deferred-work.md，而不是一次做完所有事。每次运行结束后值得检查这个文件——它就是一份后续待办清单，可以逐项喂给新的bmad-build会话。

什么时候应该先规划再构建

当改动影响多个系统、需要跨大量文件协调更新，或范围不明确需要先做需求发现时，应当先在 spec/PRD/UX/架构/story 层面做规划，再交给bmad-build逐单元实现。这正是本教程开头提到的one-session planning path（单会话规划路径）：一个连贯的请求直接进入bmad-build。完整的分级路径见 choose-a-planning-path.md——它用一句话概括决策要点："意图是否已经定义清楚？"清楚了就交给 spec 与 Build；不清楚就先在规划章节里把它弄清楚。更大的工作（一个 epic 或多个 epic 的项目）也只是在同一个 Build 单元外围叠加共享上下文并重复它，并不会切换到另一套交付体系。

你已经完成的事

通过 Mars Rover，你亲眼看到了bmad-build如何把一句简短请求转化为可运行软件：它澄清请求、呈现计划供你批准、写出程序、自查并修复问题，最后把结果展示给你。这也是 build-a-change.md 所描述的"带人工检查点的单意图实现与评审"技能的标准形态。

下一步：把同样的流程用在自己的仓库里

1. 在自有仓库安装并构建一个改动：按 install-bmad.md 在你的仓库中安装 BMad，然后用一句话描述一个小改动并运行bmad-build；完整的有人值守路径见 build-a-change.md。
2. 在成熟代码库中走得更深：继续阅读 getting-deeper.md，先用一个小改动熟悉流程，再使用书面 spec 支撑一个更大的改动。
3. 为更大的工作选择规划路径：当你的下一个改动可能需要多次实现会话或多个 epic 时，使用 choose-a-planning-path.md 决定该做多少规划。

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