BMad v4 到 v6 升级指南：用安装程序完成迁移、清理遗留技能与产出物
【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD
本指南基于 docs/ko-kr/how-to/upgrade-to-v6.md 编写，面向已安装 BMad v4（.bmad-method目录）并希望迁移到 v6 新架构的开发者。读完本文，你将掌握：如何通过npx bmad-method install自动检测并处理遗留安装、如何手动清理 v4 时代的 IDE 命令与技能、如何把已有规划产出物和进行中的开发工作迁移进 v6 的_bmad-output/结构，以及 v4/v6 在目录、配置、文档与模块层面的全部差异。
适用场景与升级前置条件
什么时候需要走这套升级流程
升级到 v6 并非对所有人都必要，官方文档明确列出三类典型场景：
- 当前装有 BMad v4：项目中存在
.bmad-method文件夹，说明使用的是旧版安装布局； - 希望迁移到 v6 新架构：v6 将安装目录收敛为单一的
_bmad/，并把 BMad Method 本体、构建器、通用框架分层存放； - 存在需要保留的既有规划产出物：如产品概述、PRD、UX 设计、架构文档等，这些内容不应丢弃，而应迁移到 v6 的输出目录中。
前置条件
升级前请确认环境满足以下两条硬性要求（原文以 note 形式强调）：
- Node.js 20.12 及以上：安装程序本身依赖该版本的 Node.js 运行；
- 已存在 BMad v4 安装：安装程序才能自动检测到遗留安装并触发迁移路径。
补充说明：在 docs/start/install-bmad.md 中，官方还提到uv是渲染类技能（如bmad-build、bmad-build-auto）的运行时依赖；若缺失，安装程序会给出警告但不会中断安装，只是相关技能在装上 uv 之前无法工作。此外，仅当从 Git 安装外部模块或自定义模块时才需要 Git。
第一步：运行 v6 安装程序
升级的第一步是运行官方安装程序，完整流程见 docs/start/install-bmad.md（韩文版见 docs/ko-kr/start/install-bmad.md）：
npx bmad-method install安装程序会在当前目录检测已有安装，并引导你选择模块、配置项与支持的 AI 编码工具。与全新安装不同，当检测到 v4 遗留目录时，它会进入升级/迁移路径而非全新初始化。
以下几个命令在升级场景中也很有用：
# 查看当前支持的 AI 编码工具 ID npx bmad-method install --list-tools # 查看安装程序的自动化参数（无头/CI 场景） npx bmad-method install --help # 无头安装示例：为 Claude Code 安装 BMM 模块 npx bmad-method install --yes --modules bmm --tools claude-code安装完成后，安装程序会显示"BMAD is ready to use!"以及 BMad 的实际安装路径，并列出仍需处理的警告。随后在项目中打开 AI 编码工具，调用bmad-help技能验证集成是否生效。
第二步：处理遗留 v4 安装
当安装程序检测到 v4 的.bmad-method目录时，你有两种处理方式：
- 由安装程序自动处理：让安装程序对
.bmad-method执行备份并移除； - 手动清理：先退出安装程序，自行整理后再继续。
需要特别注意的是：如果你曾把 BMad Method 文件夹改名为其他名称，安装程序将无法识别，必须手动删除该文件夹。
从源码层面看，v6 安装运行时对 v4 遗留痕迹有明确的清单。在 skills/bmad/scripts/setup.py 中，定义了LEGACY_LEFTOVERS常量，列出了安装程序会在_bmad下追踪的经典遗留文件，包括：
LEGACY_LEFTOVERS = ( "_config/manifest.yaml", "_config/files-manifest.csv", "_config/skill-manifest.csv", "_config/bmad-help.csv", "config.user.toml", "core/config.yaml", "bmm/config.yaml", "core/v6-shims", )该文件的注释明确说明这些痕迹属于"旧安装程序世界"（old-installer world），doctor 模式只读报告它们、从不触碰——它们正是升级过程中需要被识别和清理的对象。这段代码也印证了 v4 时代安装布局与 v6 的差异：v4 的清单文件（manifest/files/skill CSV）与config.user.toml在 v6 中已不再是运行时配置的一部分。
第三步：清理 v4 时代的 IDE 技能
v4 与 v6 在 AI 编码工具中的技能安装位置不同，升级后旧技能不会自动消失，需要手动清理。
- v4 遗留位置：以 Claude Code 为例，旧版命令/技能位于
.claude/commands/，且包含以bmad开头的嵌套文件夹，需要找到并逐个删除； - v6 新位置：新技能安装在
.claude/skills/下。
从变更日志看，这一问题在 v6 版本迭代中被反复强调：CHANGELOG.md 记录安装程序会警告遗留命令目录中的过时bmad-*条目，建议移除它们以避免工具中显示重复命令。如果你的 AI 编码工具不是 Claude Code，原理相同：找到该工具对应技能目录（如.claude/commands/）中bmad前缀的遗留项并清理。
第四步：规划产出物迁移
规划产出物指产品概述、PRD、UX 设计、架构文档等规划阶段产生的文档。如果你已经有这些文档：
将它们移动到_bmad-output/planning-artifacts/，并使用具有描述性的文件名：
- PRD 文档的文件名中应包含
PRD； - 按文件类型包含对应的关键词，如
brief（产品简介）、architecture（架构）、ux-design（UX 设计）； - 分片（sharded）文档可以放在具名的子文件夹中。
_bmad-output/在 v6 中取代了 v4 的文档文件夹，是规划与开发产出的统一输出位置。
如果你正处于规划中途：官方建议考虑直接用 v6 工作流重新开始。已有的文档可以作为输入材料继续使用；v6 提供的"结合 Web 搜索与 IDE 规划模式、分步骤细化需求"的新工作流，比 v4 的旧流程产出更好。v6 在规划阶段还引入了更多方法学支撑，可参考 docs/plan/explore-and-validate-an-idea.md 与 docs/plan/define-requirements-and-a-specification.md 了解规划路径的差异。
第五步：进行中的开发工作迁移
如果你已经创建或实现了部分故事（stories），按以下顺序迁移：
- 先完成 v6 安装（前面所有步骤）；
- 将
epics.md或epics/epic*.md放入_bmad-output/planning-artifacts/； - 运行开发者的
bmad-sprint-planning工作流（对应技能位于 skills/bmad-sprint-planning）； - 明确告诉 Agent 哪些史诗/故事已经完成，避免重复实现。
这一迁移路径与 v6 的迭代闭环设计一致：从 CHANGELOG.md 可以看到，v6 将实施阶段收敛为bmad-sprint-planning → bmad-build → bmad-code-review的单链流程，bmad-sprint-planning内置了就绪门禁（readiness gate），会按内容而非文件名 glob 查找规划产物——这正是把epics.md放进planning-artifacts/后能被正确识别的原因。
v6 集成结构解析
升级完成后，你的项目将呈现如下目录结构：
your-project/ ├── _bmad/ # 单一安装文件夹 │ ├── _config/ # 自定义配置 │ │ └── agents/ # Agent 自定义文件 │ ├── core/ # 通用 core 框架 │ ├── bmm/ # BMad Method 模块 │ ├── bmb/ # BMad 构建器 │ └── cis/ # 创造性智能产品套件 └── _bmad-output/ # 输出文件夹（取代 v4 的文档文件夹）对比 v4，这一结构的核心变化是：
_bmad/取代了分散的_bmad-core、_bmad-method等目录，所有安装内容收敛到单一文件夹；core/与bmm/职责分离：core/是通用的核心框架（不依赖 BMad 方法论），bmm/才是 BMad Method 本体；_config/agents/提供 Agent 级自定义：团队可以在此放置各 Agent 的定制文件；_bmad-output/统一承载产出物：既包括本指南迁移的规划产出物，也包括后续工作流产生的输出。
从安装运行时看，skills/bmad/scripts/setup.py 的setup()流程会合并模板配置（assets/config.template.toml）与已有团队配置（_bmad/config.toml），实例化所有已安装模块的脚本并创建输出文件夹，这与上述目录结构一一对应。
模块迁移对照表
如果你使用了 v4 时代的领域模块，升级时需按下表核对状态：
| v4 模块 | v6 状态 |
|---|---|
.bmad-2d-phaser-game-dev | 整合进 BMGD 模块 |
.bmad-2d-unity-game-dev | 整合进 BMGD 模块 |
.bmad-godot-game-dev | 整合进 BMGD 模块 |
.bmad-infrastructure-devops | 已弃用——新的 DevOps Agent 计划中 |
.bmad-creative-writing | 尚未移植——新的 v6 模块计划中 |
解读这张表需要注意两点：
- 三个游戏开发模块（Phaser/Unity/Godot）统一并入 BMGD 模块：如果你在 v4 下使用了其中任何一个，升级后应切换到 v6 的 BMGD 模块，而不是继续沿用旧目录；
- 两个模块处于过渡状态：DevOps 与创意写作模块在 v6 尚无直接等价物，官方将其标记为"已弃用/未移植"，并预告了后续的新模块。迁移前请确认你的项目是否依赖这两个模块，必要时保留 v4 安装作为参考，直到 v6 对应模块发布。
关键变更对照表
v4 到 v6 不仅是安装布局的调整，更是架构理念的转变，官方文档给出的对照如下：
| 概念 | v4 | v6 |
|---|---|---|
| 核心（Core） | _bmad-core实际上就是 BMad Method | _bmad/core/是通用框架 |
| 方法（Method） | _bmad-method | _bmad/bmm/ |
| 配置（Config） | 直接修改文件 | 模块级config.yaml |
| 文档（Docs） | 必须设置分片或非分片 | 完全灵活，自动扫描 |
结合 CHANGELOG.md 可以进一步理解这些变更的实现深度：
- 配置方式的演进：v6 引入分层 TOML 配置（
_bmad/config.toml→config.user.toml→custom/config.toml→custom/config.user.toml），模块级config.yaml仍然随包发布且旧技能仍会读取，v6 版本本身就是"迁移期"而非"切换点"； - 文档自动扫描：v6 移除了
bmad-index-docs与bmad-shard-doc两个技能，分片/非分片的强制设定成为历史，文档处理交给自动扫描机制； - 模块清单：skills/bmad/module-manifest.toml 展示了 v6 模块的元数据格式（模块名、SemVer 版本、更新源、知识引用），
setup.py会解析这类清单并安全地把脚本物化到_bmad/下对应的模块目录。
升级常见问题与注意事项
1. 升级后 IDE 中命令重复
如果在.claude/commands/（或等价目录）中仍残留 v4 的bmad-*条目，AI 编码工具可能同时展示新旧两套命令。删除遗留目录（见第三步）后重新打开工具即可。
2. 自定义配置去哪了
v4 下直接修改文件的方式在 v6 中不再适用。v6 采用模块级config.yaml与分层 TOML 配置，团队级自定义应落在_bmad/_config/（含agents/子目录）中。从 CHANGELOG.md 还可以看到，v6 要求自定义文件按新技能名重命名（例如bmad-quick-dev改名为bmad-build后，对应覆盖文件也要随之更名），旧技能名通过v6-shims/中的转发垫片（shim）保持兼容直到 v7 切割。
3. 分片文档怎么办
v6 已取消分片/非分片的强制设定，文档处理改为完全灵活且自动扫描。已有的分片文档可以放入具名子文件夹后一并迁入_bmad-output/planning-artifacts/，无需再遵守 v4 的命名约定。
4. 升级失败或不确定状态
可以重新运行npx bmad-method install，安装程序会检测现有安装并提供更新或修改路径；也可以借助 docs/start/get-answers-about-bmad.md 中介绍的提问方式获取针对当前安装状态的解答。安装程序的 doctor 能力（skills/bmad/scripts/setup.py 中的--doctor模式）可对比已安装技能与_bmad运行时的一致性并报告遗留痕迹，是排查升级后状态的有效手段。
总结
v4 到 v6 的升级可以概括为四条主线：安装收敛（分散目录 → 单一_bmad/）、职责分离（core 通用框架与 bmm 方法论分层）、配置规范化（直接改文件 → 模块级config.yaml+ 分层 TOML）、产出物集中化（规划文档与开发产物统一汇入_bmad-output/）。整个过程以官方安装程序为主通道，配合遗留技能清理与产出物迁移这两个手动步骤即可完成。对于使用游戏开发类模块的用户，升级后应切换到统一的 BMGD 模块；对于依赖 DevOps 或创意写作模块的用户，则需留意这两个模块在 v6 尚处于过渡状态。
【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
