gds-create-story

创建 Story 工作流

目标： 创建一份全面的 story 文件，为开发 Agent 提供实现无误所需的一切信息。

你的角色： Story 上下文引擎，防止 LLM 开发者出现错误、遗漏或灾难性失误。

• 所有回复均使用 {communication_language}，语言风格必须适配 {game_dev_experience}
• 使用 {document_output_language} 生成所有文档
• 你的目的不是照搬 epics，而是创建一份全面、经过优化的 story 文件，为 DEV Agent 提供实现无误所需的一切信息
• 需要预防的常见 LLM 错误：重复造轮子、选错库、文件位置错误、导致回归问题、忽视 UX、实现描述含糊、谎称已完成、未从过往工作中吸取经验
• 必须进行详尽分析：必须彻底分析所有材料，提取关键信息——切勿敷衍或略读！这是整个开发流程中最重要的工作！
• 充分利用子流程和子 Agent：如果可用，请使用研究子 Agent、子流程或并行处理，彻底分析不同材料
• 保存问题：如果分析过程中想到问题或需要澄清的事项，请留到完整 story 写好后再提出
• 零用户干预：除最初选择 epic/story 或缺少文档的情况外，流程必须完全自动化

路径

• sprint_status = {implementation_artifacts}/sprint-status.yaml
• epics_file = {planning_artifacts}/epics.md
• gdd_file = {planning_artifacts}/gdd.md
• architecture_file = {planning_artifacts}/architecture.md
• ux_file = {planning_artifacts}/*ux*.md
• story_title = ""（如果无法推断，则会询问）
• project_context = **/project-context.md（如果存在则加载）
• default_output_file = {implementation_artifacts}/{{story_key}}.md

输入文件

输入	描述	路径模式	加载策略
gdd	游戏设计文档（备用来源——epics 文件应包含大部分内容）	整体：{planning_artifacts}/*gdd*.md，分片：{planning_artifacts}/*gdd*/*.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
project_context	项目级规则、约定、MCP 配置及第三方框架要求	**/project-context.md	FULL_LOAD

---

约定

• 裸路径（例如 template.md）相对于 skill 根目录解析。
• {skill-root} 表示此 skill 的安装目录（即 customize.toml 所在目录）。
• {project-root} 是距离项目工作目录最近的、包含 _bmad/ 的文件夹；如果工作目录中没有，则逐级向上搜索父目录。
• {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/gds/config.yaml 加载配置，并解析：

• user_name
• communication_language
• document_output_language
• game_dev_experience
• planning_artifacts
• implementation_artifacts
• sprint_status

步骤 5：问候用户

使用 {communication_language} 向 {user_name} 问候。

步骤 6：执行后置步骤

按顺序执行 {workflow.activation_steps_append} 中的每一项。

激活已完成。如果 activation_steps_prepend 或 activation_steps_append 不为空，请在继续之前确认已按顺序执行其中的每一项。所有激活步骤完成之前，不要开始主工作流。

执行

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

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

<check if="user chooses 'q'">
  <action>停止——无需执行任何工作</action>
</check>

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

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

<check if="user provides story docs path">
  <action>使用用户提供的故事文档路径</action>
  <action>跳转到步骤 2a</action>
</check>

必须从头到尾读取完整的 {sprint_status} 文件，以保留顺序 加载完整文件：{{sprint_status}} 从头到尾读取所有行——不要跳过任何内容 完整解析 development_status 部分 查找第一个（按从上到下的顺序读取）满足以下条件的故事： - 键匹配以下模式：数字-数字-名称（例如“1-2-user-auth”） - 不是 epic 键（epic-X）或回顾（epic-X-retrospective） - 状态值等于“backlog”

<check if="no backlog story found">
  <output>📋 在 sprint-status.yaml 中未找到待办故事

    所有故事均已创建、正在进行或已完成。

    **选项：**
    1. 运行 sprint-planning 以刷新故事跟踪信息
    2. 加载 PM Agent 并运行 correct-course，以添加更多故事
    3. 检查当前冲刺是否已完成，并运行回顾
  </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 步骤 2a</action>

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

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

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

  所有故事均已创建、正在进行或已完成。

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

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

转到步骤 2a

🔬 全面分析工件——这是防止开发人员日后犯错的关键环节！

完整阅读并遵循 ./discover-inputs.md，加载所有输入文件 可用内容：{epics_content}、{gdd_content}、{architecture_content}、{ux_content}、 {project_context}

从 {epics_content} 中提取 Epic {{epic_num}} 的完整上下文： EPIC 分析： - Epic 目标和业务价值 - 此 epic 中的所有 story，以了解跨 story 的上下文 - 当前 story 的需求、用户 story 陈述和验收标准 - 技术要求和约束 - 对其他 story/epic 的依赖 - 指向原始文档的来源提示 提取当前 story（{{epic_num}}-{{story_num}}）的详细信息： STORY 基础信息： - 用户 story 陈述 （作为……，我想要……，以便……） - 详细的验收标准（已采用 BDD 格式） - 此 story 特有的技术要求 - 业务背景和价值 - 成功标准 查找 {{previous_story_num}}：扫描 {implementation_artifacts}，找到 epic {{epic_num}} 中 story 编号小于 {{story_num}} 的文件，并选择编号最大的 story 加载前一个 story 文件：{implementation_artifacts}/{{epic_num}}-{{previous_story_num}}-*.md 前序 story 参考信息： - 来自前一个 story 的开发说明和经验 - 需要处理的评审反馈和修正 - 已创建/修改的文件及其模式 - 有效或无效的测试方法 - 遇到的问题及找到的解决方案 - 已建立的代码模式 提取所有可能影响当前 story 实现的经验

分析 {project_context} 中与故事相关的规则和约束： **项目上下文提取：** - 项目所需的第三方框架和库 - 要使用的 MCP 服务配置和集成 - 要遵循的编码规范和模式 - 项目级约束（例如，特定 API、部署目标） - 适用于此故事实现领域的任何规则 将提取出的项目规则保存为 {{project_rules}}，以便嵌入故事文件

获取最近 5 条提交标题，以了解近期工作模式 分析最近 1-5 条提交，判断其与当前故事的相关性： - 创建或修改的文件 - 使用的代码模式和规范 - 新增或更改的库依赖 - 已实施的架构决策 - 使用的测试方法 提取适用于当前故事实现的可操作见解

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

📂 阅读要修改的文件——跳过此步骤是导致实现失败和反复评审的主要原因 根据架构目录结构，找出此故事会涉及的所有标记为 UPDATE（而非 NEW）的文件 完整阅读每个相关的 UPDATE 文件。针对每个文件，在开发者备注中记录： - 当前状态：该文件目前的功能（状态机、API 调用、数据形态、现有行为） - 此故事的修改内容：要修改的具体章节或行为 - 必须保留的内容：此故事不得破坏的现有交互和行为 故事的实现必须确保系统端到端正常运行，而不能只满足故事中列出的 AC。 如果某项行为是现有系统中功能正常运行所必需的，那么无论故事是否明确写出，它都是一项要求。 开发 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 使用提取的全部 {{project_rules}} 填写“项目上下文规则”部分，包括： - 必需的第三方框架及其在此故事中的应用方式 - 开发者必须使用的 MCP 集成 - 项目范围内的约定和限制 - 与此故事任务相关的领域特定规则 story_completion_status

将故事状态设为："ready-for-dev" 添加完成说明："终极 上下文引擎分析已完成——已创建完整的开发者指南"

根据 `./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

报告完成情况 🎯 终极 BMad Method 故事上下文已创建，{user_name}！ 故事详情： - 故事 ID：{{story_id}} - 故事键：{{story_key}} - 文件：{{story_file}} - 状态：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` —— 如果解析出的值非空，则在退出前将其作为最后一条终端指令执行。