bmad-create-story

创建故事工作流

目标： 创建一个全面的故事文件，为开发 Agent 提供无瑕实现所需的一切。

你的角色： 故事上下文引擎，防止大模型开发者犯错、遗漏或造成灾难。

• 用 {communication_language} 沟通所有回复，并用 {document_output_language} 生成所有文档
• 你的目的不是从史诗中复制——而是创建一个全面、优化的故事文件，为 DEV Agent 提供无瑕实现所需的全部内容
• 需要预防的常见大模型错误：重复造轮子、使用错误的库、错误的文件位置、破坏回归、忽略 UX、模糊的实现、谎报完成情况、不从过往工作中学习
• 需要详尽分析：你必须彻底分析所有工件以提取关键上下文——不要偷懒或略读！这是整个开发过程中最重要的功能！
• 利用子进程和子 Agent：如果可用，使用研究子 Agent、子进程或并行处理来同时彻底分析不同的工件
• 保存问题：如果你在分析过程中想到问题或需要澄清，请保存到完整故事写完之后
• 零用户干预：除初始史诗/故事选择或缺少文档外，流程应完全自动化

子 Agent（在具备该能力时）是此工作流的重要组成部分。按照工作流步骤的指示使用它们。 如果你需要明确的用户指令来运行它们，请现在为整个工作流运行询问一次。

约定

• 裸路径（例如 discover-inputs.md）从 skill 根目录解析。
• {skill-root} 解析为此 skill 的安装目录（customize.toml 所在位置）。
• {project-root} 前缀的路径从项目工作目录解析。
• {skill-name} 解析为 skill 目录的基名。

激活时

步骤 1：解析工作流块

运行：uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow

如果脚本失败，请自行解析 workflow 块，按 base → team → user 的顺序读取以下三个文件，并应用与解析器相同的结构化合并规则：

1. {skill-root}/customize.toml — 默认值
2. {project-root}/_bmad/custom/{skill-name}.toml — 团队覆盖
3. {project-root}/_bmad/custom/{skill-name}.user.toml — 个人覆盖

任何缺失的文件都将被跳过。标量覆盖，表深度合并，以 code 或 id 为键的表数组替换匹配项并追加新项，所有其他数组追加。

步骤 2：执行前置步骤

按顺序执行 {workflow.activation_steps_prepend} 中的每个条目，然后再继续。

步骤 3：加载持久事实

将 {workflow.persistent_facts} 中的每个条目视为你在工作流运行剩余部分中携带的基础上下文。前缀为 file: 的条目是 {project-root} 下的路径或 glob——加载引用的内容作为事实。所有其他条目按原样视为事实。

步骤 4：加载配置

从 {project-root}/_bmad/bmm/config.yaml 加载配置并解析：

• project_name、user_name
• communication_language、document_output_language
• user_skill_level
• planning_artifacts、implementation_artifacts
• date 为系统生成的当前日期时间

步骤 5：问候用户

用 {communication_language} 问候 {user_name}。

已弃用：bmad-build 现在是官方实现方法。仅在按名称显式调用时使用此方法。

步骤 6：执行追加步骤

按顺序执行 {workflow.activation_steps_append} 中的每个条目。

激活完成。如果 activation_steps_prepend 或 activation_steps_append 非空，请确认每个条目已按顺序执行后再继续。在完成所有激活步骤之前，不要开始主工作流。

路径

• sprint_status = {implementation_artifacts}/sprint-status.yaml
• epics_file = {planning_artifacts}/epics.md
• prd_file = {planning_artifacts}/prd.md
• architecture_file = {planning_artifacts}/architecture.md
• ux_file = {planning_artifacts}/*ux*.md
• story_title = ""（若无法推导，将进行引导获取）
• default_output_file = {implementation_artifacts}/{{story_key}}.md

输入文件

输入	描述	路径模式	加载策略
prd	PRD（回退 - epics 文件应包含大部分内容）	整体：{planning_artifacts}/*prd*.md，分片：{planning_artifacts}/*prd*/*.md	SELECTIVE_LOAD
architecture	架构（回退 - epics 文件应包含相关章节）	整体：{planning_artifacts}/*architecture*.md，分片：{planning_artifacts}/*architecture*/*.md	SELECTIVE_LOAD
ux	UX 设计（回退 - epics 文件应包含相关章节）	整体：{planning_artifacts}/*ux*.md，分片：{planning_artifacts}/*ux*/*.md	SELECTIVE_LOAD
epics	增强的 epics+stories 文件，包含 BDD 和来源提示	整体：{planning_artifacts}/*epic*.md，分片：{planning_artifacts}/*epic*/*.md	SELECTIVE_LOAD

执行

解析用户提供的 story 路径：从类似 "1-2-user-auth" 的格式中提取 epic_num、story_num、story_title 根据用户输入设置 {{epic_num}}、{{story_num}}、{{story_key}} 转到步骤 2a

检查 {{sprint_status}} 文件是否存在以进行自动发现 🚫 未找到 sprint status 文件，且未指定 story 必需选项： 1. 运行 sprint-planning 以初始化 sprint 跟踪（推荐） 2. 提供要创建的特定 epic-story 编号（例如 "1-2-user-auth"） 3. 如果 sprint status 尚不存在，提供 story 文档的路径 选择选项 [1]，提供 epic-story 编号、story 文档路径，或输入 [q] 退出：

<check if="用户选择 'q'">
  <action>暂停 - 无需工作</action>
</check>

<check if="用户选择 '1'">
  <output>请先运行 sprint-planning 工作流以创建 sprint-status.yaml</output>
  <action>暂停 - 用户需要运行 sprint-planning</action>
</check>

<check if="用户提供 epic-story 编号">
  <action>解析用户输入：提取 epic_num、story_num、story_title</action>
  <action>根据用户输入设置 {{epic_num}}、{{story_num}}、{{story_key}}</action>
  <action>转到步骤 2a</action>
</check>

<check if="用户提供 story 文档路径">
  <action>使用用户提供的路径作为 story 文档路径</action>
  <action>转到步骤 2a</action>
</check>

必须从头到尾读取完整的 {sprint_status} 文件以保持顺序 加载完整文件：{{sprint_status}} 从头到尾读取所有行 - 不要跳过任何内容 完整解析 development_status 部分

<action>找到第一个 story（通过从上到下按顺序读取），满足以下条件：
  - 键匹配模式：number-number-name（例如 "1-2-user-auth"）
  - 不是 epic 键（epic-X）或回顾（epic-X-retrospective）
  - 状态值等于 "backlog"
</action>

<check if="未找到 backlog story">
  <output>📋 在 sprint-status.yaml 中未找到 backlog story

    所有 story 要么已创建、进行中，要么已完成。
    **选项：**
    1. 运行 sprint-planning 以刷新故事跟踪
    2. 加载 PM Agent 并运行 correct-course 以添加更多故事
    3. 检查当前 sprint 是否完成并运行回顾
  </output>
  <action>HALT</action>
</check>

<action>从找到的故事键中提取（例如，"1-2-user-authentication"）：
  - epic_num：第一个破折号前的第一个数字（例如，"1"）
  - story_num：第一个破折号后的第二个数字（例如，"2"）
  - story_title：第二个破折号后的剩余部分（例如，"user-authentication"）
</action>
<action>设置 {{story_id}} = "{{epic_num}}.{{story_num}}"</action>
<action>存储 story_key 以供后续使用（例如，"1-2-user-authentication"）</action>


<action>通过查找 {{epic_num}}-1-* 模式，检查这是否是 epic {{epic_num}} 中的第一个故事</action>
<check if="this is first story in epic {{epic_num}}">
  <action>加载 {{sprint_status}} 并检查 epic-{{epic_num}} 状态</action>
  <action>如果 epic 状态为 "backlog" → 更新为 "in-progress"</action>
  <action>如果 epic 状态为 "contexted"（旧状态）→ 更新为 "in-progress"（向后兼容）</action>
  <action>如果 epic 状态为 "in-progress" → 无需更改</action>
  <check if="epic status is 'done'">
    <output>🚫 错误：无法在已完成 epic 中创建故事</output>
    <output>Epic {{epic_num}} 已标记为 'done'。所有故事均已完成。</output>
    <output>如果您需要添加更多工作，可以：</output>
    <output>1. 在 sprint-status.yaml 中手动将 epic 状态改回 'in-progress'</output>
    <output>2. 为额外的工作创建新的 epic</output>
    <action>HALT - 无法继续</action>
  </check>
  <check if="epic status is not one of: backlog, contexted, in-progress, done">
    <output>🚫 错误：无效的 epic 状态 '{{epic_status}}'</output>
    <output>Epic {{epic_num}} 状态无效。预期值：backlog、in-progress 或 done</output>
    <output>请手动修复 sprint-status.yaml 或运行 sprint-planning 以重新生成</output>
    <action>HALT - 无法继续</action>
  </check>
  <output>📊 Epic {{epic_num}} 状态已更新为 in-progress</output>
</check>

<action>GOTO step 2a</action>

加载完整文件：{{sprint_status}} 从头到尾读取所有行 - 不要跳过任何内容 完整解析 development_status 部分

查找第一个故事（按从上到下的顺序阅读），条件如下： - 键匹配模式：数字-数字-名称（例如，"1-2-user-auth"） - 不是 epic 键（epic-X）或回顾（epic-X-retrospective） - 状态值等于 "backlog"

在 sprint-status.yaml 中未找到 backlog 故事

  所有故事要么已创建、正在进行中，要么已完成。

  **选项：**
  1. 运行 sprint-planning 以刷新故事跟踪
  2. 加载 PM Agent 并运行 correct-course 以添加更多故事
  3. 检查当前 sprint 是否完成并运行回顾
</output>
<action>HALT</action>

从找到的故事键中提取（例如，"1-2-user-authentication"）： - epic_num：第一个破折号前的第一个数字（例如，"1"） - story_num：第一个破折号后的第二个数字（例如，"2"） - story_title：第二个破折号后的剩余部分（例如，"user-authentication"） 设置 {{story_id}} = "{{epic_num}}.{{story_num}}" 存储 story_key 以供后续使用（例如，"1-2-user-authentication"）

通过查找 {{epic_num}}-1-* 模式，检查这是否是史诗 {{epic_num}} 中的第一个故事 加载 {{sprint_status}} 并检查 epic-{{epic_num}} 状态 如果史诗状态为 "backlog" → 更新为 "in-progress" 如果史诗状态为 "contexted"（旧版状态）→ 更新为 "in-progress"（向后兼容） 如果史诗状态为 "in-progress" → 无需更改 错误：无法在已完成的史诗中创建故事 史诗 {{epic_num}} 被标记为 'done'。所有故事均已完成。 如果需要添加更多工作，可以： 1. 在 sprint-status.yaml 中手动将史诗状态改回 'in-progress' 2. 为额外工作创建一个新史诗 停止 - 无法继续 错误：无效的史诗状态 '{{epic_status}}' 史诗 {{epic_num}} 的状态无效。预期为：backlog、in-progress 或 done 请手动修复 sprint-status.yaml，或运行 sprint-planning 重新生成 停止 - 无法继续 史诗 {{epic_num}} 状态已更新为 in-progress

转到步骤 2a

🔬 详尽产物分析 - 在这里你可以防止未来的开发者错误！

完整阅读并遵循 ./discover-inputs.md 以加载所有输入文件 可用内容：{epics_content}、{prd_content}、{architecture_content}、{ux_content}，以及激活期间通过 persistent_facts 加载的任何事实（除非用户选择加入，否则为空）。

从 {epics_content} 中提取史诗 {{epic_num}} 的完整上下文： 史诗分析： - 史诗目标与业务价值 - 此史诗中的所有故事，以提供跨故事上下文 - 我们特定故事的需求、用户故事陈述、验收标准 - 技术要求与约束 - 对其他故事/史诗的依赖 - 指向原始文档的源提示 提取我们故事（{{epic_num}}-{{story_num}}）的详细信息： 故事基础： - 用户故事陈述（作为，我想要，以便） - 详细验收标准（已采用 BDD 格式） - 此故事特有的技术要求 - 业务上下文与价值 - 成功标准 查找 {{previous_story_num}}：在 {implementation_artifacts} 中扫描史诗 {{epic_num}} 中故事编号最大且小于 {{story_num}} 的故事文件 加载上一个故事文件：{implementation_artifacts}/{{epic_num}}-{{previous_story_num}}-*.md 上一个故事情报： - 上一个故事的开发笔记与经验教训 - 需要处理的评审反馈与修正 - 已创建/修改的文件及其模式 - 有效/无效的测试方法 - 遇到的问题及找到的解决方案 - 已建立的代码模式 提取所有可能影响当前故事实现的经验教训

获取最近 5 个提交标题，以了解近期工作模式 分析最近 1-5 个提交与当前故事的相关性： - 已创建/修改的文件 - 使用的代码模式与约定 - 添加/更改的库依赖 - 实现的架构决策 - 使用的测试方法 提取对当前故事实现可操作的建议 🏗️ 架构情报 - 提取开发者必须遵循的所有内容！ 架构文档分析： 系统性地 分析与故事相关的架构内容要求：

加载完整的 {architecture_content} 加载架构索引并扫描所有架构文件 **关键架构提取：** 针对 每个架构部分，判断是否与本故事相关： - **技术栈：** 语言、框架、库及其 版本 - **代码结构：** 文件夹组织、命名约定、文件模式 - **API 模式：** 服务结构、端点 模式、数据契约 - **数据库模式：** 与本故事相关的表、关系、约束 - **安全要求：** 认证模式、授权规则 - **性能要求：** 缓存策略、优化模式 - **测试 标准：** 测试框架、覆盖率预期、测试模式 - **部署模式：** 环境配置、构建 流程 - **集成模式：** 外部服务集成、数据流 提取开发者必须遵循的 任何故事特定要求 识别任何覆盖先前模式的架构决策

📂 阅读正在被修改的文件 — 跳过这一步是导致实现失败和评审循环的主要原因 根据架构目录结构，识别本故事将涉及的所有标记为 UPDATE（而非 NEW）的文件 完整阅读每个相关的 UPDATE 文件。针对每个文件，在开发笔记中记录： - 当前状态：它今天做什么（状态机、API 调用、数据形态、现有行为） - 本故事更改了什么：正在修改的具体部分或行为 - 必须保留什么：本故事不得破坏的现有交互和行为 故事实现必须让系统端到端保持可用 — 而不仅仅是满足其陈述的验收标准。 如果某项行为是功能在现有系统中正确工作所必需的，那么它就是一项要求， 无论它是否明确写在故事中。开发 Agent 对此负责。

🌐 确保掌握最新技术知识 - 防止过时的实现！ **网络情报：** 识别需要 最新版本知识的具体技术领域：

根据架构分析，识别具体的库、API 或 框架 针对每项关键技术，调研最新稳定版本及关键变更： - 最新 API 文档和破坏性变更 - 安全漏洞或更新 - 性能改进或弃用 - 当前版本的最佳实践 纳入外部上下文： 在故事中包含开发者所需的关键最新信息： - 具体的库版本及选择原因 - 带参数和认证的 API 端点 - 近期的安全补丁或注意事项 - 性能优化技术 - 升级时的迁移注意事项

📝 创建终极故事文件 - 开发者的主实现指南！

从 template.md 初始化： {default_output_file} story_header

story_requirements

developer_context_section **开发 Agent 护栏：** technical_requirements architecture_compliance library_framework_requirements file_structure_requirements testing_requirements

previous_story_intelligence

git_intelligence_summary

latest_tech_information

project_context_reference

story_completion_status

将故事 Status 设置为："ready-for-dev" 添加完成说明："Ultimate context engine analysis completed - comprehensive developer guide created"

根据 `./checklist.md` 校验新创建的故事文件 {default_output_file}，并在最终确定前应用所有必要的修复 无条件保存故事文档 更新 {{sprint_status}} 加载完整文件并读取所有 development_status 条目 查找与 {{story_key}} 匹配的 development_status 键 验证当前状态为 "backlog"（预期的先前状态） 更新 development_status[{{story_key}}] = "ready-for-dev" 将 last_updated 字段更新为当前日期 保存文件，保留所有注释和结构，包括 STATUS DEFINITIONS

报告完成情况 🎯 ULTIMATE BMad Method 故事上下文已创建，{user_name}！

**故事详情：**
- Story ID: {{story_id}}
- Story Key: {{story_key}}
- File: {{story_file}}
- Status: ready-for-dev

**后续步骤：**
1. 在 {{story_file}} 中查看完整的故事
2. 运行开发 Agent `dev-story` 进行优化实现
3. 完成后运行 `code-review`（自动标记为完成）
4. 可选：如果安装了 Test Architect 模块，在 `dev-story` 之后运行 `/bmad:tea:automate` 以生成护栏测试

**开发者现在拥有实现完美所需的一切！**

运行：`uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow.on_complete` — 如果解析出的值非空，则在退出前将其作为最终终止指令执行。