如何用 BMAD-METHOD 的 bmad-architecture 生成架构脊柱文档，让多个 epic 的决策不再互相冲突
【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD
当多个 epic 由不同的 AI 会话或不同的人分别实现时，每个实现者都会独立做技术选择：一个 epic 暴露 REST，另一个写 GraphQL；snake_case列碰上camelCase；这边用 session cookie，那边用 JWT。每个选择单独看都合理，合在一起就是集成问题和返工。BMAD-METHOD 的bmad-architectureskill 用来解决这个问题：它产出一份短小的架构文档（称为spine，脊柱文档），只记录"如果两个单元独立决策就会冲突"的那部分决定，并给每个决定分配稳定的AD-n编号，让 spec、story 和后续会话都能引用同一份决策。
前提是项目里已安装 BMad（BMM 模块），使用一个受支持的 AI coding tool（Claude Code、Cursor 等）来运行 skill。本文的验证步骤依赖uv，因此需要本机装有uv（Python 3.10+）。
先判断：你的项目现在需不需要 spine
设计 UX 与架构 给出了一张判断表，可以直接对照：
| 工作特征 | 结论 |
|---|---|
| 清晰的局部改动，有既定模式 | 通常不需要 |
| 多个相关组件，约束已知 | 可选，看协调风险 |
| 多个 epic 或跨系统决策 | 需要对齐实现 |
| 受监管、高风险或企业级计划 | 通常需要 |
判断规则是文档里的一句话：如果几个 epic 可能被不同的 agent 或人实现，你就需要 architecture spine。
安装并确认 bmad-architecture 可用
在目标项目目录运行安装器（要求 Node.js 20.12+）：
npx bmad-method install按提示选择模块（选 BMM 模块）和 AI coding tool。安装完成后，终端会显示BMAD is ready to use!及安装路径。缺少uv时安装器只给警告、不阻断安装，但依赖uv的 skill 会不可用，所以装完uv再往下走。
验证集成是否就绪：在 AI coding tool 里调用bmad-helpskill，问它下一步做什么。如果工具能识别并运行该 skill，说明 skill 体系已接入。bmad-architecture属于 BMM 模块的 workflow skill，也可以从 Architect agent（bmad-agent-architect）的CA菜单代码进入。
运行 skill：两条路径与一个必答问题
在 AI 工具中输入bmad-architecture即可启动。skill 会读取你的输入来判断这次任务的类型——输入可以是 spec 包（SPEC.md+ memlog）、一个原始想法、一份冗长的架构文档、现有代码库，或一份已有的 spine。输入本身决定任务，skill 不会反过来反复质问你。
启动后 skill 会先让你选工作模式：
- Coaching path（默认）：开放式提问，skill 把范式、技术栈、主要边界这些关键决策连同备选方案摆出来，由你拍板；
- Fast path：skill 快速起草整份 spine，用
[ASSUMPTION]标签标出推断，留到评审时纠正。
两条路径都有一条强制步骤：起草前 skill 会问 spine 是不是唯一交付物。如果还要给人看的架构说明、演示稿之类的东西，在这里说清用途和受众，否则 skill 会在收尾时补问。
运行中所有决策、约束、版本、假设和未决问题都追加记录到运行目录的.memlog.md（只追加、不删改）；ARCHITECTURE-SPINE.md本身是结束时从 memlog 蒸馏出来的，不是边聊边写。
产出物在哪里，长什么样
默认情况下，运行目录位于：
{planning_artifacts}/architecture/architecture-{project_name}-{date}/里面有两个核心文件：ARCHITECTURE-SPINE.md（脊柱文档）和.memlog.md（工作记忆）。如果{workflow.spine_output_path}下已存在同名目标的运行目录，skill 会先问你是否从它的 memlog 恢复，而不是重开一次。
spine 的结构来自 spine-template.md，frontmatter 声明type: architecture-spine、altitude（initiative / feature / epic 三个层级）、paradigm、scope、status（draft / final）等字段。正文的关键区块：
- Invariants & Rules：核心。每条决策一个
### AD-n — {decision}块，含三个必填字段——Binds（约束哪些单元）、Prevents（防止哪种分歧）、Rule（下游必须遵守的约束）。已由用户或现有代码事实敲定的决策标[ADOPTED]。 - Inherited Invariants：仅当本 spine 继承更高 altitudes 的父 spine 时出现（见下一节）。
- Consistency Conventions：命名、数据格式、状态与横切关注点的约定表。
- Stack：只写名称 + 版本号（如语言、框架、关键依赖），"为什么"留在 memlog 里。
- Deferred：明确推迟的决策及理由——这是 spine 保持精简的另一半契约。
- Structural Seed：目录树、部署与外部 provider 拓扑等 mermaid 图或文本树。
AD-n编号是稳定且只增不改序的：Update 场景下修改决策是改 Rule 原文，新决策用下一个编号，永不重排或复用退役编号。这正是"多个 epic 不再冲突"的机制——epic 的 stories 和 spec 引用AD-3时，它始终指向同一条规则。
为每个 epic 生成 spine，并防止与父 spine 冲突
如果项目整体已经有一份 feature/initiative 级 spine，而你要为某个 epic 生成子 spine，需要两件事：
1. 运行目录带上 epic 身份，避免同天多次运行互相覆盖。默认的run_folder_pattern是architecture-{project_name}-{date}，在 epic 级别需要覆盖它。编辑团队级覆盖文件_bmad/custom/bmad-architecture.toml（个人级用_bmad/custom/bmad-architecture.user.toml）：
[workflow] run_folder_pattern = "architecture-epic-{epic_id}"{epic_id}由驱动 spec 或激活参数绑定。这个写法直接来自 customize.toml 中的注释说明。
2. 父 spine 的决策作为只读约束继承。skill 会先加载父ARCHITECTURE-SPINE.md，把父级AD、约定和范式按原编号（不重新编号）记入本 spine 的Inherited Invariants区块，并在 memlog 中逐条记为constraint条目，不重新推导。父 spine 留给你的工作只有它Deferred的条目，以及本 epic 的 stories 可能撞到的分歧点。一条新的AD如果与继承的决策矛盾或削弱它，会被当作冲突上报，而不是本地覆盖。epic spine 只固定该 epic 的 stories 必须共享的不变量，不展开 story 级细节。
验证：Reviewer Gate 与 lint_spine.py 的机械检查
spine 定稿前有固定的 Reviewer Gate（机制详见 reviewer-gate.md）：先跑确定性检查，再上语义评审。
机械检查可以直接手动执行。下面命令中的两个花括号变量需要按你的环境替换：{skill-root}是 skill 安装目录（例如 Claude Code 下为.claude/skills/bmad-architecture/，以安装器实际输出为准），{doc_workspace}是本次运行的文件夹（即存放ARCHITECTURE-SPINE.md的目录）：
uv run {skill-root}/scripts/lint_spine.py --workspace {doc_workspace}脚本以 JSON 输出到 stdout（也可用-o写文件），退出码恒为 0，结果以 JSON 字段传递。它检查四类问题（见 lint_spine.py 的源码）：
| category | 检查内容 |
|---|---|
placeholder | 残留的TBD/TODO、similar to AD-n未展开引用、未填充的{模板token} |
ad_id | AD-n编号重复或不单调递增 |
ad_fields | 某个AD-n块缺Binds/Prevents/Rule字段 |
version_pin | ## Stack表格中某行没有版本号 |
干净文件的输出示例（来自脚本实现的字段结构）：
{ "ok": true, "spine": "ARCHITECTURE-SPINE.md", "total_findings": 0, "by_severity": {}, "findings": [] }机械检查之后是语义评审：一个对照 good-spine 清单的 rubric walker，加上{workflow.finalize_reviewers}中的每个评审视角（默认包含"核对技术是否经网络验证为当前版本"和"作为攻击者构造两个遵守所有 AD 却仍能建出互相不兼容实现的单元"两个视角），全部作为并行 subagent 对ARCHITECTURE-SPINE.md运行，各自把完整评审写入{doc_workspace}/reviews/review-{slug}.md，只回传摘要。Finalize 时 skill 直接修掉明确的发现；如果以Validate意图单独运行（批判一份已有 spine 但不修改它），则把所有评审合并成一份 HTML 报告交给你，再问你是否要把发现滚入一次 Update。
Finalize 收尾时，skill 会把 spine frontmatter 的status设为final、更新updated日期，并记一条spine finalized事件到 memlog。
限制与已知的失败模式
设计 UX 与架构 列出了这个步骤失败的三种方式，值得对照自查：
- 在实现过程中"顺手"决定 API 风格等跨 epic 决策——这些必须先进 spine；
- 把每个小选择都记进 spine——spine 只放"独立决策会冲突、且不显然、且是真实取舍"的决定，其余进 Deferred 或留给代码；
- spine 一次写完就不再更新——学到新东西时保持它最新；实现中途发生显著变更时，用
bmad-correct-course评估并产出变更提案，而不是直接在代码里分叉。
另有一条来自 SKILL.md 的边界：如果输入薄到无法建立 spine（缺需求、缺约束），skill 会建议先跑bmad-spec，并把缺失的答案记入共享 spec workspace，而不是替你想答案。
下一步
spine 定稿后，skill 的收尾动作是推荐把它挂到 spec 上（bmad-spec采用/刷新 spine 作为 companion，保持AD编号稳定以便下游引用）——这也是 Build 和 readiness gate 找到它的方式。之后再进入bmad-create-epics-and-stories拆 story；epic 级的 spine 则直接对接bmad-build。用bmad-help可以查看当前项目下按优先级排序的后续 skill。
【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
