Epic {N} Context: {Epic Title}【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHODGoal{One clear paragraph: what this epic achieves and why it matters.}StoriesStory X.Y: Brief title only...Requirements Constraints{Relevant functional/non-functional requirements and success criteria for this epic (describe by purpose, not source).}Technical Decisions{Key architecture decisions, constraints, patterns, data models, and conventions relevant to this epic.}UX Interaction Patterns{Relevant UX flows, interaction patterns, and design constraints (omit section entirely if nothing relevant).}Cross-Story Dependencies{Dependencies between stories in this epic or with other epics/systems (omit if none).}对各章节的要点逐一说明 - **标题行**# Epic {N} Context: {Epic Title}{N} 为史诗编号标题来自 epics 文件。注意下一行固定带一个 HTML 注释声明该文件由规划产物生成、规划文档变更后需用 compile-epic-context 重新生成——这个注释也是后续缓存有效性判断的辅助线索之一。 - **Goal**一段清晰的话说明该史诗要达成什么、为什么重要。这是**始终必填**的两节之一。 - **Stories**仅列出故事编号与简短标题如 Story X.Y: Brief title only**只用于定位**绝不展开任何故事级细节。 - **Requirements Constraints**与该史诗相关的功能/非功能需求与成功标准。必须按目的描述而非按来源描述详见下文规则。 - **Technical Decisions**关键架构决策、约束、模式、数据模型与约定。 - **UX Interaction Patterns**相关 UX 流程、交互模式与设计约束**若无相关内容整节省略**。 - **Cross-Story Dependencies**该史诗内故事之间、或与其他史诗/系统之间的依赖关系**若无依赖整节省略**。 输出模板中的 HTML 注释与章节占位符本身就是可复制的骨架任何一次编译都应以 # Epic {N} Context: {Epic Title} 开头其余章节按需填充或省略但 Goal 与 Stories 永不缺席。 ## 四、七条编写规则保证上下文的干净与可用 这是整个指令文件中最具实操价值的部分直接决定了产出的上下文质量 1. **激进地限定范围Scope aggressively**只包含实现该史诗内任一故事的开发者真正需要的内容。拿不准就剔除——开发者随时可以回去读完整规划文档。这一条对应干净clean的目标。 2. **按目的描述而非按来源描述Describe by purpose, not by source**写 API responses must include pagination metadata而不是 Per PRD section 3.2.1, pagination is required.。原因是规划文档的内部结构会变而约束本身不会变。这是防文档漂移的关键设计。 3. **禁止全文复制No full copies**绝不引用源文档原文、章节编号或粘贴大段原文永远做提炼distill。 4. **不写故事级细节No story-level details**故事清单仅供定向具体细节由各故事的独立规格story spec承载。 5. **不写可从代码库推导的内容Nothing derivable from the codebase**开发者读代码就能学到的东西不要写进上下文文件避免冗余与失准。 6. **简洁可执行Be concise and actionable**全文目标 **800–1500 tokens**。这条有明确理由该文件会与其他材料一起加载进 bmad-build-auto 的上下文token 预算是硬约束。 7. **绝不编造内容Never hallucinate content**源材料没说的绝不发明。 8. **空章节整体省略Omit empty sections entirely**唯一例外是 Goal 与 Stories 两节始终必填。 其中第 6 条与 bmad-build-auto 的定位直接呼应从 [skills/bmad-build-auto/SKILL.md](https://link.gitcode.com/i/8c259d9cab41684e570e518ed3f283b1) 可知该 skill 通过 uv run --no-cache {project-root}/_bmad/scripts/render_skill.py --project-root {project-root} --skill {skill-root} 渲染工作流且一次运行只有一份上下文预算因此 epic-N-context.md 必须把 token 花在刀刃上——800–1500 token 的目标正是为多份材料共存预留空间。 ## 五、错误处理两条降级路径 指令文件明确规定了两种异常场景的处理方式 - **epics 文件缺失或目标史诗不存在****什么都不写**直接向调用方 Agent 报告问题。理由很硬核没有可用的 epics 文件Goal 和 Stories 两节就无法填充而这两节是必填项产出残缺文件比不产出更糟。 - **规划产物缺失或为空****仍然产出文件**用 epics 文件填充 Goal 与 Stories同时在 Requirements Constraints 小节写入固定提示语Planning artifacts were unavailable; only epics-file context was used.。**绝不用编造内容填补缺失章节**。 这两条路径体现了同一原则可降级但不虚构。上下文文件的完整性可以打折缺规划产物细节但真实性不可妥协。 ## 六、在 bmad-build-auto 工作流中的实际调用 compile-epic-context.md 并非孤立文档它是 bmad-build-auto 工作流的一等公民。查看 [skills/bmad-build-auto/step-01-clarify-and-route.md](https://link.gitcode.com/i/66473ea7498de81a922a46c975f147fa) 可还原其真实调用上下文 1. 步骤一首先要求**判断上下文策略**结合意图intent与产物清单推断当前工作是否属于某个史诗的故事——注意明确要求**不要依赖文件名模式或正则**而要综合意图、清单与 epics 文件内容一起推理。 2. 若判断属于某个史诗**先检查是否有有效的缓存史诗上下文**查找 {{ config.implementation_artifacts }}/epic-N-context.mdN 为史诗编号。文件**有效**需同时满足三个条件存在且非空以 # Epic N Context: 开头史诗编号必须正确且 {{ config.planning_artifacts }} 目录中没有比它更新的文件。 3. 若缓存无效或缺失**才触发编译**以 {{ rendered(compile-epic-context.md) }}即本文讲解的指令文件渲染结果作为 prompt**同步**生成一个 subagent向其传入史诗编号、epics 文件路径、{{ config.planning_artifacts }} 目录与输出路径 {{ config.implementation_artifacts }}/epic-N-context.md由该 subagent 执行编译并产出文件。 从 [skills/bmad-build-auto/customize.toml](https://link.gitcode.com/i/0d0931e88bf8e8301c9bbed67bda10b7) 可以看到implementation_artifacts、planning_artifacts 等工作流参数均属于可定制配置activation_steps_prepend、persistent_facts、route、review、implementation_handoff 等默认值可在 _bmad/custom/bmad-build-auto.toml 或 _bmad/custom/bmad-build-auto.user.toml 中按字符串替换、列表追加、表按键合并的规则覆盖。 值得注意的工程细节是缓存 时间戳失效的组合epic-N-context.md 的 HTML 注释声明规划文档变更后需重新生成而 step-01 用planning_artifacts 目录中是否有更新的文件作为失效判据二者闭环——开发者改动任何规划产物后下一次运行会自动触发重编译保证上下文与规划保持一致。同时step-01 要求 subagent **同步**执行且一次性并行启动见 [skills/bmad-build-auto/workflow.md](https://link.gitcode.com/i/dd487ddd958797b5c6ec41216cd748ea) 中同一消息内阻塞等待所有 subagent 结果的约束因为无人值守循环没有事件循环可供后台任务回交控制权后台化 subagent 会导致运行停滞。 ## 七、一份实战示例从规划到 epic-1-context.md 假设史诗编号为 1epics 文件记录了 Epic 1 的标题为 User onboarding、目标为 让新用户 3 分钟内完成注册并看到首屏价值故事清单含 Story 1.1注册表单、Story 1.2邮箱验证与 Story 1.3欢迎引导。规划产物目录中存在 PRD 与架构文档。那么编译结果应形如 markdown # Epic 1 Context: User onboarding !-- Generated from planning artifacts. Regenerate with compile-epic-context if planning docs change. -- ## Goal 让新用户能够在三分钟内完成注册并看到首屏价值以降低注册漏斗流失。 ## Stories - Story 1.1: 注册表单 - Story 1.2: 邮箱验证 - Story 1.3: 欢迎引导 ## Requirements Constraints - 注册接口必须对重复邮箱返回明确的冲突提示。 - 验证邮件必须在一分钟内送达非功能性要求。 - 全流程必须可在无人工介入的情况下被端到端验证。 ## Technical Decisions - 使用现有账号服务而非新建注册流程复用其 token 签发机制。 - 邮箱验证采用链接式点击即确认不做验证码。 ## UX Interaction Patterns - 注册表单保持单列布局错误提示内联展示。 ## Cross-Story Dependencies - Story 1.2 依赖 Story 1.1 的注册接口Story 1.3 依赖 1.2 的验证通过状态。【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考