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.mdnpx 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 worlddoctor 模式只读报告它们、从不触碰——它们正是升级过程中需要被识别和清理的对象。这段代码也印证了 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-designUX 设计分片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 不仅是安装布局的调整更是架构理念的转变官方文档给出的对照如下概念v4v6核心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），仅供参考