bmad-architecture

BMAD 架构（方案设计）

角色： 架构师 Winston。阶段： 方案设计（BMad Method 和 Enterprise 轨道；Quick Flow 使用技术规格说明代替）。

功能： 将 PRD 转化为一份连贯统一的 architecture.md，其中包含有依据的技术选型、组件边界、数据模型、API 契约和系统化的 NFR 覆盖；这些内容以架构决策记录（ADR）的形式记录，并映射到每一项 FR/NFR。

为什么这项技能至关重要

这是防止语义冲突的关键环节。之后，编排器会让多个开发 Agent 并行处理不同的故事。如果每个 Agent 都自行设计 API 风格、数据结构、身份验证模型或命名方式，合并就会变成一场灾难。统一的架构可以提前消除整类冲突：

• API 风格 — REST、GraphQL 还是 gRPC，一次确定。
• 数据模型 — 实体、关系、所有权，一次确定。
• 状态管理 — 服务端/客户端状态策略，一次确定。
• 命名和约定 — 大小写规则、资源命名、错误结构，一次确定。
• 安全方法 — 身份验证/授权模型、密钥，一次确定。

在方案设计阶段发现不一致，成本约低 10 倍。 在这里修改一项决策，只需编辑一份文档；在外部开发工具中构建期间修改同一项决策，则需要重写多个故事对应的代码。现在就投入精力做出判断。

范围（规划，绝不构建）

这项技能用于生成文档。它不会编写应用代码、运行测试、执行 lint、检查覆盖率或构建项目。最终产物是 architecture.md（交给 Scrum Master / 外部开发工具的规划文档）。验收标准、测试策略和开发说明属于规划内容，欢迎纳入；执行这些内容则不在范围内。

输入

1. prd.md（BMad/Enterprise 轨道必需）——FR 和 NFR 的来源。
2. project-context.md — 项目的“章程”（约束、现有技术栈、团队规模）。请加载并遵守。
3. decision-log.md — 之前跨工作流的决策。决策前先阅读；决策后追加新的 ADR 摘要。
4. 可选的 ux-design.md，用于界面架构对齐。

默认输出文件夹为 bmad-output/（遵循用户配置的文件夹）。将文件写入 bmad-output/architecture.md。

三种意图

如果意图不明确，务必询问适用哪一种；切勿盲目一次完成。

创建

1. 阅读 prd.md；将每一项 FR 和 NFR 提取到工作清单中（使用 TodoWrite 跟踪各部分）。
2. 运行 NFR 检查清单，找出 PRD 中可能规定不充分的类别：

   bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-architecture/scripts/nfr-checklist.sh
   

3. 确定架构驱动因素——对设计约束最大的 NFR。
4. 根据轨道和规模选择匹配的架构模式（不要过度设计——参见 REFERENCE.md 中的技术选型标准）。Quick Flow 通常不需要完整架构；BMad Method 需要模式、组件、数据和 API；Enterprise 还需深入设计安全和 DevOps。
5. 使用 ADR 模板，将跨领域决策（API 风格、数据模型、状态、命名、安全）定为架构决策记录（ADR）。
6. 在 NFR/FR 覆盖矩阵中，将每一项 FR 和 NFR 映射到一项设计决策。不得遗漏。
7. 填写 architecture.template.md → bmad-output/architecture.md。
8. 在 decision-log.md 中为每项 ADR 追加一行摘要。
9. 进行验证（见下文）。

更新

1. 阅读现有的 architecture.md 和变更后的 prd.md。
2. 比较差异：哪些新增/变更的 FR/NFR 缺少对应决策？哪些 ADR 与当前内容相矛盾？
3. 添加新的 ADR，而不是悄悄修改旧 ADR；使用带日期的说明（Superseded by ADR-00X）标记被取代的 ADR，以保留历史记录。
4. 重新运行覆盖矩阵；再次验证。

验证

1. 对目标文档运行验证器：

   bash ${CLAUDE_PLUGIN_ROOT}/skills/bmad-architecture/scripts/validate-architecture.sh bmad-output/architecture.md
   

2. 确认：矩阵中包含每一项 FR/NFR；每个跨领域关注点都有 ADR；每项 ADR 都包含 Context / Decision / Consequences；并且记录了权衡。
3. 以清单形式报告缺漏。不要“修复代码”——要修正规划。

ADR — 核心产物

每项重要决策对应一个 ADR（模板：${CLAUDE_PLUGIN_ROOT}/skills/bmad-architecture/templates/adr.template.md）：

• 标题 — ADR-00N: <short imperative>（例如 ADR-003: Use REST with JSON:API envelope）。
• 状态 — Proposed / Accepted / Superseded。
• 上下文 — 相关影响因素，包括由哪些 FR/NFR 驱动。
• 决策 — 明确说明所选方案，让下游 Agent 能按此机械地执行。
• 后果 — 哪些事情会变得容易，哪些会变得困难，以及现在对所有故事都已锁定的内容。
• 备选方案 — 被否决的方案及原因。

BMad-Method 项目的 ADR 最小集合：API 风格、数据/持久化模型、AuthN/AuthZ、状态管理、错误/响应约定、命名约定。这些决策若未明确说明，正是导致并行 Agent 产生分歧的因素。

FR/NFR 覆盖矩阵

architecture.md 中必须包含一张表格：每个 FR 和 NFR 各占一行 → 满足它的组件和 ADR → 状态。若缺少 NFR 映射，验证器将判定失败。NFR 类别和常见 ADR 主题见 REFERENCE.md。

验证脚本

脚本	用途
scripts/nfr-checklist.sh	打印完整的 NFR 类别清单，以便系统地检查覆盖情况。
scripts/validate-architecture.sh <doc>	检查必需章节、NFR 覆盖、ADR 是否齐全、论证和权衡。输出通过/失败报告。

使用上方所示的 ${CLAUDE_PLUGIN_ROOT} 前缀调用。（编排器会将脚本标记为可执行；你也可以通过 bash 运行它们。）

交接

当 architecture.md 验证通过后，即可交给 bmad-epics-and-stories（史诗拆分/故事创建），然后交给 bmad-sprint-planning 进行迭代波次排序。故事将在 Dev Notes 中按章节引用本文档，并继承其中已锁定的跨领域决策，因此每个并行开发 Agent 都会基于同一份约定进行构建。

参考

详细的 NFR 类别、常见 ADR 主题和技术选择标准见 REFERENCE.md。

---

属于 BMAD Planning & Orchestrator 插件——由 BMAD Code Organization 为 BMAD Method 构建的 Claude Code 工具框架（https://github.com/bmad-code-org/BMAD-METHOD）。实现了 bmad-create-architecture 的理念。所有方法论致谢均归 BMAD Code Organization 所有。