如何把 BMAD-METHOD 从 v4 升级到 v6：清理旧目录并迁移规划产物
【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD
如果你的项目里还装着 BMad v4（安装目录通常叫.bmad-method），而你已经写好了规划文档或进行中的开发工作，这篇文章给出从 v4 迁移到 v6 的完整路径：用npx bmad-method install安装程序识别并清理旧目录，把规划产物（Brief/PRD/UX/Architecture）迁移到 v6 的_bmad-output/planning-artifacts/目录，最后用bmad-help验证迁移结果。
适用前提（来自 升级指南）：
- Node.js 20.12+（安装程序必需）
- 现有 BMad v4 安装
- 项目里有要保留的规划产物或进行中的开发工作
开始之前先做一件事：如果仓库里还有未提交的重要变更，先完成提交或备份，再执行升级。
1. 运行安装程序
在项目根目录执行：
npx bmad-method install安装程序会自动检测现有安装。v4 会被识别出来，安装程序提供迁移辅助。完整的交互流程（选择安装位置、AI 工具、模块）见安装说明；如果安装的是预发布版本，则改用npx bmad-method@next install。
判断是否正常的标准：安装结束时，安装程序会显示BMAD is ready to use!并给出 BMad 的安装路径；如有未处理的警告也会一并列出。缺失uv只产生警告、不阻断安装，但依赖uv的技能在补装uv之前无法使用。
2. 处理旧的 v4 安装目录
当安装程序检测到 v4 时，你有两种处理方式：
- 允许安装程序自动备份并删除
.bmad-method - 先退出安装流程，之后手动清理旧目录
注意一个例外：如果你把 BMad Method 目录改成了其他名字，安装程序无法自动处理，需要你自己手动定位并删除。
3. 清理 IDE 命令与技能目录
v4 的 IDE 命令/技能不会随安装程序自动清除，需要手动删除。以 Claude Code 为例，到.claude/commands/目录下删除所有以bmad开头的嵌套目录。v6 的新技能会安装到.claude/skills/，两个目录用途不同，不要混淆。
这一步的意义：如果遗留了旧版bmad-*条目，你的 AI 工具可能会同时显示新旧两套重复命令，删除后重复现象消失。
4. 迁移规划产物
已有规划文档（Brief/PRD/UX/Architecture）的情况：
把这些文档移动到_bmad-output/planning-artifacts/，并使用可读的文件名：
- PRD 文档的文件名包含
PRD - 其他文档按类型包含
brief、architecture或ux-design - 分片文档可以放在命名清晰的子目录中
规划仍在进行中的情况：
文档建议直接用 v6 工作流重启规划，把现有文档作为输入，而不是强行搬运半成品文档。
5. 迁移进行中的开发工作（可选分支）
只有在你已经创建或实现了部分用户故事（story）时才需要这一步：
- 完成 v6 安装
- 将
epics.md或epics/epic*.md放入_bmad-output/planning-artifacts/ - 运行 Developer 的
bmad-sprint-planning工作流 - 告知智能体哪些史诗/故事已经完成
没有进行中的故事时跳过此节，不影响升级结果。
迁移后的目录结构
升级完成后项目呈现 v6 统一结构：
your-project/ ├── _bmad/ # 单一安装目录 │ ├── _config/ # 你的自定义配置 │ │ └── agents/ # 智能体自定义文件 │ ├── core/ # 通用核心框架 │ ├── bmm/ # BMad Method 模块 │ ├── bmb/ # BMad Builder │ └── cis/ # Creative Intelligence Suite └── _bmad-output/ # 输出目录（v4 时代常见为 doc 目录）几个容易踩坑的旧名/新名差异：
| 概念 | v4（旧） | v6（新） | 迁移提示 |
|---|---|---|---|
| 核心框架 | _bmad-core实际上承载的是 BMad Method | _bmad/core/变成通用框架层 | 迁移时不要再把_bmad/core/当成 Method 本体 |
| 方法模块 | _bmad-method | _bmad/bmm/ | 旧脚本、路径引用需同步更新到bmm |
| 配置方式 | 直接改模块文件 | 每个模块通过config.yaml管理 | 优先改配置，不要直接改生成文件 |
| 文档读取 | 需要手动区分分片/非分片 | 自动扫描完整文档与分片入口 | 只有在兼容性场景下才建议手动分片 |
另外，如果你之前装过这些 v4 模块，升级后它们的去向是：
| v4 模块 | v6 状态 |
|---|---|
.bmad-2d-phaser-game-dev | 已集成到 BMGD 模块 |
.bmad-2d-unity-game-dev | 已集成到 BMGD 模块 |
.bmad-godot-game-dev | 已集成到 BMGD 模块 |
.bmad-infrastructure-devops | 已弃用 — 新的 DevOps 智能体即将推出 |
.bmad-creative-writing | 未适配 — 新的 v6 模块即将推出 |
依赖后两个模块的工作流在升级后不可用，规划后续工作时需要留意。
验证升级结果
按 升级指南 给出的后续建议做三件事：
- 运行
bmad-help，确认可用工作流与下一步建议——如果 AI 工具能识别并运行该技能，说明工具集成正常 - 如果是既有项目，补充或更新
project-context.md，减少后续实现偏差，参考管理项目上下文 - 在继续开发前，先做一次关键链路验证：安装、命令触发、文档读取
bmad-help会确认安装正常工作、列出已安装模块的可用内容，并推荐第一步操作；遇到报错时，把安装程序输出交给 AI 助手处理即可。
【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
