BMAD-METHOD Epic Breakdown 模板解析从需求清单到可实施用户故事的拆解规范【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD导读本文深度解析 BMAD-METHOD 开源项目中bmad-create-epics-and-stories技能的文档模板epics-template.md它定义了把 PRD、UX 设计契约与架构决策转化为 Epic史诗和 User Story用户故事的标准文档骨架。模板配套的四个步骤文件step-01-validate-prerequisites.md 至 step-04-final-validation.md规定了填充该模板的完整流程。读完本文你将掌握如何初始化模板、如何按四类需求构建需求清单、如何以用户价值而非技术分层设计 Epic 列表、如何撰写带 Given/When/Then 验收标准的故事以及如何完成覆盖度校验最终产出可直接交给开发 Agent 实施的epics.md。一、模板的定位Epic Breakdown 文档骨架在 BMAD-METHOD 的规划路径中bmad-create-epics-and-stories面向以 PRD 为起点的项目区别于基于SPEC.md的 Story Breakdown 路径。官方文档 明确指出两条分支Spec 支撑的 Epic由bmad-spec输出有序的stories.yaml无需本模板以 PRD 为起点的项目运行bmad-create-epics-and-stories产出Epic 文件即基于本模板生成的epics.md随后接bmad-sprint-planning生成sprint-status.yaml跟踪文件。因此本模板是整条 PRD → Epic → Story → Sprint 跟踪链路的中间产物标准。技能描述中写道它的目标是把 PRD 需求和架构决策转化为按用户价值组织、带完整验收标准的可实施故事供 Developer Agent 直接开发。在技能体系中Agent 扮演产品策略师 技术规格撰写者与产品负责人对等协作而非简单的指令执行。模板本身是一个带占位符的 Markdown 文件头部是 YAML frontmatter正文用{{placeholder}}标记待填充区域。模板通过 step-01 第 7 节Load and Initialize Template被完整拷贝到{planning_artifacts}/epics.md输出位置由配置modules.bmm.planning_artifacts决定再逐步替换占位符。1.1 frontmatter状态与输入文档追踪--- stepsCompleted: [] inputDocuments: [] ---stepsCompleted记录工作流已完成的步骤索引。依据技能 SKILL.md 中的State Tracking原则每完成一步写入最终输出时必须更新该数组用于多步骤流程的状态延续。inputDocuments记录参与分析的输入文档。step-01 规定当确认输入文档后将所有文件含 bmad-ux 脊柱对DESIGN.md与EXPERIENCE.md列入该数组。这一设计呼应了技能层的工作流架构约束SKILL.md 的 Core Principles采用 step-file 架构一次只加载一个步骤文件、顺序执行、只追加append-only构建文档。frontmatter 正是这套机制的持久化载体。二、Requirements Inventory四类需求的提取与填充模板的核心主体是需求清单Requirements Inventory它把需求分为四类分别对应 step-01 中编号为 36 的提取流程占位符内容来源文档提取规则{{fr_list}}功能需求 FRPRD寻找 FR1:、Functional Requirement 1: 等编号描述系统必须做什么{{nfr_list}}非功能需求 NFRPRD性能、安全、可用性、可靠性、合规等质量属性与约束{{additional_requirements}}附加需求Architecture基础设施、集成、数据迁移、监控、API 版本、安全实现等{{ux_design_requirements}}UX 设计需求 UX-DRUX 设计契约设计令牌、组件、无障碍、响应式、交互模式等2.1 输入文档的发现与校验step-01 给出了严格的文档搜索优先级以{planning_artifacts}为根PRD*prd*.md整篇→*prd*/index.md分片版即大文档拆成多文件加 index.md 索引的形式Architecture*architecture*.md→*architecture*/index.mdUX 设计契约可选优先ux-designs/ux-*/DESIGN.md与ux-designs/ux-*/EXPERIENCE.mdbmad-ux 脊柱对其次*ux*.md或*ux*/index.md。UX 契约的处理值得注意DESIGN.md负责视觉标识与设计令牌EXPERIENCE.md负责信息架构、行为、状态、交互与无障碍两者合并视为一个UX 契约若只存在单侧脊柱文件需向用户报告并询问是否纳入不完整的交接内容若有多个 run 文件夹匹配则展示各文件夹的status与updated值由用户选择。2.2 各需求占位符的填充格式step-01 规定的输出格式可直接套用FR1: [Clear, testable requirement description] FR2: [Clear, testable requirement description] NFR1: [Performance/Security/Usability requirement] NFR2: [Performance/Security/Usability requirement] - [Technical requirement from Architecture that affects implementation] - [Infrastructure setup requirement] - [Integration requirement] UX-DR1: [Actionable UX design requirement with clear implementation scope] UX-DR2: [Actionable UX design requirement with clear implementation scope]step-01 特别强调UX-DR 不得被压缩成模糊摘要——若 UX 规范识别出 6 个可复用组件就必须列出全部 6 个而不是写创建可复用组件因为每个 UX-DR 必须具体到能生成带可测试验收标准的故事。同理架构文档中若指定了 starter/greenfield 模板必须在附加需求中显著标注因为它将影响Epic 1 Story 1的内容。2.3 模板初始化要点初始化时{{requirements_coverage_map}}与{{epics_list}}两个占位符保持原样留到后续步骤填充。填充完成后需向用户展示提取结果并征求确认只有用户确认后才允许进入 Epic 设计步骤——这与技能YOU ARE A FACILITATOR, not a content generator的定位一致。三、FR Coverage Map 与 Epic List按用户价值设计 Epic模板中{{epics_list}}与{{requirements_coverage_map}}两个区块由 step-02 填充核心原则是Organize by USER VALUE, not technical layers。3.1 正反例对照step-02 给出了明确的正反示例正确用户价值且独立可交付Epic 1: 用户认证与档案注册、登录、管理档案——独立完整认证系统Epic 2: 内容创建——独立使用认证、创建内容Epic 3: 社交互动——独立使用认证 内容Epic 4: 搜索与发现——独立使用前述全部。错误技术分层、无用户价值数据库搭建、API 开发、前端组件、部署流水线——这类拆分对用户没有价值。错误同一组件反复文件改动文件上传 / 文件状态 / 文件权限三个 Epic 都改 model、controller、web form、web API——应合并为一个文件管理增强Epic内部用有序 Stories 表达。3.2 epics_list 的标准格式## Epic List ### Epic 1: [Epic Title] [Epic goal statement - what users can accomplish] **FRs covered:** FR1, FR2, FR3, etc. ### Epic 2: [Epic Title] [Epic goal statement - what users can accomplish] **FRs covered:** FR4, FR5, FR6, etc.设计过程中需评估方向变化的真实风险边界当架构、UX、测试设计已充分验证、跨 Epic 方向变化可能性低时倾向更少但更大的 Epic当存在真实风险或早期反馈可能改变后续方向时再拆分为多个 Epic。3.3 FR Coverage Map防遗漏映射### FR Coverage Map FR1: Epic 1 - [Brief description] FR2: Epic 1 - [Brief description] FR3: Epic 2 - [Brief description]覆盖映射的唯一目的就是确保没有 FR 被遗漏。step-02 要求 Epic 列表获得用户明确批准Do you approve this epic structure for proceeding to story creation?后才允许进入故事创建步骤。step-02 的菜单还提供 [A] Advanced Elicitation调用bmad-advanced-elicitation与 [P] Party Mode调用bmad-party-mode作为可选的协作增强分支。四、Story N.M 结构故事与验收标准模板中每个 Epic 下的故事采用如下结构### Story {{N}}.{{M}}: {{story_title_N_M}} As a {{user_type}}, I want {{capability}}, So that {{value_benefit}}. **Acceptance Criteria:** **Given** {{precondition}} **When** {{action}} **Then** {{expected_outcome}} **And** {{additional_criteria}}4.1 用户故事三要素As a用户类型角色I want期望获得的能力So that能力带来的价值/收益。step-03 要求故事恰好一个开发 Agent 一个会话内可完成且不得依赖同一 Epic 内的未来故事只能基于已完成的前置故事。反例包括Set up database无用户价值、Create all models过大、Build authentication system过大、Login UI (depends on Story 1.3 API endpoint)未来依赖错误。4.2 验收标准的 Given/When/Then 格式每个验收标准AC独立可测覆盖前置条件、触发动作、预期结果与附加条件四要素。step-03 的 AC 撰写指引还包括包含边界情况与错误条件、尽可能引用具体需求编号。4.3 数据库/实体创建原则step-03 特别强调按需建表错误示范是 Epic 1 Story 1 一次性创建全部 50 张数据库表正确做法是每个故事只创建/修改它自身需要的那部分表。这与 step-04 的 Architecture Implementation Validation 检查项一致。4.4 UX-DR 的落位若 step-01 提取了 UX-DRstory 创建时必须保证每个 UX-DR 至少被一个故事覆盖——可以落在既有功能 Epic 内如某特性的无障碍修复也可以单独设立Design System / UX PolishEpic。五、Step 4 最终校验模板产出如何通过验证step-04 对填充完毕的文档执行五类校验这正是模板结构合规的验收环节FR 覆盖校验逐条核对需求清单中每个 FR 至少出现在一个故事中且验收标准完整回应 FR架构实现校验若架构指定 starter 模板Epic 1 Story 1 必须是从 starter 模板搭建初始项目检查建表是否按需故事质量校验单 Agent 可完成、AC 清晰、引用具体 FR、无前向依赖Epic 结构校验是否交付用户价值、无大额前期技术工作、文件改动重复File Churn检查——若多个 Epic 反复修改同一核心文件且无法证明拆分价值风险缓解、反馈回路、上下文大小限制应建议合并依赖校验关键Epic 间独立性Epic 2 不依赖 Epic 3 即可运转与 Epic 内故事顺序依赖Story N.M 只依赖前序 Stories 输出。全部通过后保存最终epics.md呈现最终菜单[C] Complete Workflow随后调用bmad-help技能收尾。六、模板产出的下游消费与跟踪体系的衔接模板生成的epics.md并非终点而是bmad-sprint-planning的输入。其模板文件 sprint-status-template.yaml 展示了消费方式每个 Epic 与故事以epic-N、N-M-{slug}键登记状态backlog / ready-for-dev / in-progress / review / done故事文件名即从本模板的编号派生如1-1-user-authentication。Epic 在首个故事开始时自动转入in-progress回顾Retrospective的 action items 追加到action_items区块。当需求变更过大、单故事无法吸收时官方文档建议运行 bmad-correct-course对应技能 bmad-correct-course它读取 PRD、epics、架构与 UX 文档评估影响并产出 sprint 变更提案批准后更新sprint-status.yaml并移交文档编辑任务——其中重新创建新故事/变更故事环节仍回到本模板所定义的 Epic/Story 结构。七、自定义与扩展模板所在技能的配置面模板的使用受技能级工作流配置影响。bmad-create-epics-and-stories的 customize.toml 暴露了四个可配置项activation_steps_prepend []标准激活配置加载、问候之前运行的步骤用于预检加载、合规检查等覆盖时追加activation_steps_append []问候之后、主工作流开始前的步骤用于上下文密集型设置persistent_facts []整个工作流期间保持的静态事实标准、合规约束、风格护栏条目可以是字面句子或以file:前缀引用{project-root}下文件/glob文件内容被加载视为事实on_complete 当工作流到达 Step 4 且用户确认[C] Complete后执行的标量指令覆盖优先留空表示无自定义行为。这些覆盖遵循 BMad 结构合并规则标量覆盖、数组追加、带code/id的表数组按匹配替换。团队级覆盖文件位于{project-root}/_bmad/custom/{skill-name}.toml个人级位于{skill-name}.user.toml优先级为 base → team → user见 SKILL.md 的 Step 1 解析逻辑。从模块清单看本技能属于module method、版本6.13.0-nextmodule-manifest.toml知识底座引用bmad技能的references/help.md。八、实战速查模板填充对照表模板占位符填充步骤核心规则校验要点frontmatterstepsCompleted/inputDocumentsstep-01逐步更新、登记输入文档状态可延续{{fr_list}}/{{nfr_list}}step-01从 PRD 提取编号可测用户确认无遗漏{{additional_requirements}}step-01从 Architecture 提取标注 starter 模板影响 Epic 1 Story 1{{ux_design_requirements}}step-01UX-DR 必须具体到可生成故事每个 UX-DR 至少一个故事覆盖{{requirements_coverage_map}}step-02每个 FR 映射到 Epic无 FR 漏映射{{epics_list}}step-02按用户价值组织Epic 独立可交付用户明确批准{{epic_goal_N}}step-02/03描述本 Epic 交付的用户成果与 FR 覆盖一致{{story_title_N_M}}等step-03单 Agent 可完成、无前向依赖AC 独立可测结语BMAD-METHOD 的 Epic Breakdown 模板表面上是占位符文档实质上是需求分解纪律的强制化载体它把按用户价值组织 Epic、故事只依赖前序、验收标准可测、覆盖无遗漏这些原则固化为文档结构配合四步工作流与bmad-sprint-planning的跟踪体系构成从 PRD 到可实施故事再到状态跟踪的完整闭环。开发者可以直接在仓库中查看模板 epics-template.md 及配套步骤文件将其复制到{planning_artifacts}/epics.md后按上文对照表逐段填充即可得到一份开发 Agent 可直接实施的 Epic/Story 规划文档。【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
