gds-dev-story

开发故事工作流

目标： 根据填写完整上下文的故事规格文件执行故事实现。

你的角色： 实现故事的开发者。

• 所有回复均使用 {communication_language}，且语言风格 MUST 根据 {game_dev_experience} 进行调整
• 所有文档均使用 {document_output_language} 编写
• 仅修改故事文件中的以下部分：YAML frontmatter baseline_commit、Tasks/Subtasks 复选框、Dev Agent Record（Debug Log、Completion Notes）、File List、Change Log 和 Status
• 严格按照顺序执行所有步骤；不得跳过任何步骤
• 绝对不要因为“里程碑”“取得重大进展”或“会话边界”而停止。除非触发 HALT 条件或 USER 给出其他指示，否则必须在一次执行中持续进行，直到故事 COMPLETE（满足所有 AC，且所有任务/子任务均已勾选）。
• 除非适用 HALT 条件，否则不得安排“下次会话”或要求暂停等待审核。只有 Step 6 决定是否完成。
• 游戏开发经验（{game_dev_experience}）只影响对话风格，不影响代码更新。

路径

• story_file = ``（明确指定的故事路径；若为空则自动发现）
• sprint_status = {implementation_artifacts}/sprint-status.yaml

上下文

• project_context = **/project-context.md（若存在则加载）

---

约定

• 裸路径（例如 template.md）相对于技能根目录解析。
• {skill-root} 表示此技能的安装目录（即 customize.toml 所在位置）。
• {project-root} 表示最近的、包含 _bmad/ 的文件夹，从项目工作目录开始并沿父目录向上查找。
• {skill-name} 表示技能目录的基本名称。

激活时

步骤 1：解析工作流块

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

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

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
• implementation_artifacts
• sprint_status
• date，使用系统生成的当前日期时间

步骤 5：问候用户

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

步骤 6：执行后置步骤

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

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

执行

所有回复均使用 {communication_language}，且语言风格必须适合 {game_dev_experience} 所有文档均使用 {document_output_language} 编写 仅修改故事文件中的以下部分：YAML frontmatter `baseline_commit`、任务/子任务复选框、Dev Agent Record（Debug Log、Completion Notes）、File List、 Change Log 和 Status 必须严格按顺序执行所有步骤；不得跳过任何步骤 绝对不要因为“里程碑”、“取得重大进展”或“会话边界”而停止。必须在一次执行中持续进行，直到故事 COMPLETE（所有 AC 均已满足且所有任务/子任务均已勾选），除非触发 HALT 条件或用户给出其他指示。 除非适用 HALT 条件，否则不得安排“下一次会话”或要求暂停以等待审核。只有步骤 6 决定是否完成。 游戏开发经验（{game_dev_experience}）仅影响对话风格，不影响代码更新。 直接使用 {{story_path}} 读取完整的故事文件 从文件名或元数据中提取 story_key

<check if="{{sprint_status}} file exists">
  <critical>必须从头到尾完整读取 sprint-status.yaml 文件，以保持原有顺序</critical>
  <action>加载完整文件：{{sprint_status}}</action>
  <action>从头到尾读取所有行；不得跳过任何内容</action>
  <action>完整解析 development_status 部分，以了解故事顺序</action>

  <action>按从上到下的顺序查找第一个符合以下条件的故事：
    - 键符合格式：number-number-name（例如，“1-2-user-auth”）
    - 不是 epic 键（epic-X）或回顾项（epic-X-retrospective）
    - 状态值为 "ready-for-dev"
  </action>

  <check if="no ready-for-dev or in-progress story found">
    <output>📋 sprint-status.yaml 中没有 ready-for-dev 故事

      **当前 Sprint 状态：** {{sprint_status_summary}}

      **你想怎么做？**
      1. 运行 `create-story`，根据史诗创建下一个故事并提供完整上下文
      2. 运行 `*validate-create-story`，在开发前完善现有故事（推荐的质量检查）
      3. 指定要开发的故事文件（提供完整路径）
      4. 查看 {{sprint_status}} 文件，了解当前 Sprint 状态

      💡 **提示：** `ready-for-dev` 状态的故事可能尚未经过验证。建议先运行 `validate-create-story` 进行质量检查。
    </output>
    <ask>请选择 [1]、[2]、[3] 或 [4]，或指定故事文件路径：</ask>

    <check if="user chooses '1'">
      <action>HALT - 运行 create-story 以创建下一个故事</action>
    </check>

    <check if="user chooses '2'">
      <action>HALT - 运行 validate-create-story 以完善现有故事</action>
    </check>

    <check if="user chooses '3'">
      <ask>请提供要开发的故事文件路径：</ask>
      <action>将用户提供的故事路径保存为 {{story_path}}</action>
      <goto anchor="task_check" />
    </check>

    <check if="user chooses '4'">
      <output>正在加载 {{sprint_status}}，以便详细查看状态……</output>
      <action>显示详细的 Sprint 状态分析</action>
      <action>HALT - 用户可以查看 Sprint 状态并提供故事路径</action>
    </check>

    <check if="user provides story file path">
      <action>将用户提供的故事路径保存为 {{story_path}}</action>
      <goto anchor="task_check" />
    </check>
  </check>
</check>

直接在 {implementation_artifacts} 中搜索故事 在文件中查找状态为 "ready-for-dev" 的故事 查找符合模式：*-*-*.md 的故事文件 读取每个候选故事文件，检查 Status 部分

  <check if="no ready-for-dev stories found in story files">
    <output>📋 未找到状态为 ready-for-dev 的故事

      **可用选项：**
      1. 运行 `create-story`，根据史诗创建下一个故事，并提供完整上下文
      2. 运行 `*validate-create-story`，改进现有故事
      3. 指定要开发的故事
    </output>
    <ask>你想怎么做？请选择选项 [1]、[2] 或 [3]：</ask>

    <check if="user chooses '1'">
      <action>停止 - 运行 create-story 以创建下一个故事</action>
    </check>

    <check if="user chooses '2'">
      <action>停止 - 运行 validate-create-story 以改进现有故事</action>
    </check>

    <check if="user chooses '3'">
      <ask>不清楚你想开发哪个故事。请提供故事文件的完整路径：</ask>
      <action>将用户提供的故事路径存储为 {{story_path}}</action>
      <action>继续处理提供的故事文件</action>
    </check>
  </check>

  <check if="ready-for-dev story found in files">
    <action>使用找到的故事文件并提取 story_key</action>
  </check>
</check>

<action>存储找到的 story_key（例如 "1-2-user-authentication"），以便稍后更新状态</action>
<action>使用 story_key 模式 {{story_key}}.md，在 {implementation_artifacts} 中查找匹配的故事文件</action>
<action>从找到的路径读取完整故事文件</action>

<anchor id="task_check" />

<action>解析以下部分：Story、Acceptance Criteria、Tasks/Subtasks、Dev Notes、Dev Agent Record、File List、Change Log、Status</action>

<action>从故事文件的 Dev Notes 部分加载完整上下文</action>
<action>从 Dev Notes 中提取开发者指南：架构要求、以往经验、技术规格</action>
<action>使用增强后的故事上下文，为实现决策和方案提供依据</action>

<action>识别 Tasks/Subtasks 中第一个未完成的任务（未勾选的 [ ]）</action>

<action if="no incomplete tasks">
  <goto step="6">完成流程</goto>
</action>
<action if="story file inaccessible">停止："无法访问故事文件，无法开发该故事"</action>
<action if="incomplete task or subtask requirements ambiguous">请用户澄清，或停止</action>

加载所有可用上下文，为实现提供依据 加载 {project_context}，以获取编码标准和项目范围的模式（如果存在） 从 {project_context} 中提取可执行规则： - 必须使用的第三方框架和库（必须使用这些，不得使用替代方案） - 实现过程中应利用的 MCP 服务集成 - 编码约定和命名模式 - 项目范围的约束和强制模式 存储为 {{active_project_rules}}——这些规则优先于默认实现选择 解析各个部分：Story、Acceptance Criteria、Tasks/Subtasks、Dev Notes、Dev Agent Record、File List、Change Log、Status 从 Story 文件的 Dev Notes 部分加载完整上下文 检查 Dev Notes 中 Story 的“Project Context Rules”部分，查找预先提取的项目规则 从 Dev Notes 中提取开发者指导：架构要求、以往经验、技术规范 使用增强后的 Story 上下文和 {{active_project_rules}} 来指导实现决策 ✅ **上下文已加载** Story 和项目上下文可用于实现 确定这是全新开始，还是代码审查后的继续处理

<action>检查 Story 文件中是否存在“Senior Developer Review (AI)”部分</action>
<action>检查 Tasks/Subtasks 下是否存在“Review Follow-ups (AI)”子部分</action>

<check if="Senior Developer Review section exists">
  <action>设置 review_continuation = true</action>
  <action>从“Senior Developer Review (AI)”部分提取：
    - 审查结果（Approve/Changes Requested/Blocked）
    - 审查日期
    - 带复选框的行动项总数（统计已勾选与未勾选项）
    - 严重程度分类（High/Med/Low 数量）
  </action>
  <action>统计“Review Follow-ups (AI)”子部分中未勾选的 [ ] 审查后续任务</action>
  <action>将未勾选的审查项列表存储为 {{pending_review_items}}</action>

  <output>⏯️ **代码审查后继续处理 Story**（{{review_date}}）

    **审查结果：** {{review_outcome}}
    **行动项：** 还有 {{unchecked_review_count}} 项待处理
    **优先级：** {{high_count}} 项 High、{{med_count}} 项 Medium、{{low_count}} 项 Low

    **策略：** 将优先处理审查后续任务（标记为 [AI-Review]），然后再继续常规任务。
  </output>
</check>

<check if="Senior Developer Review section does NOT exist">
  <action>设置 review_continuation = false</action>
  <action>设置 {{pending_review_items}} = 空</action>

  <output>🚀 **开始全新实现**

    Story：{{story_key}}
    Story 状态：{{current_status}}
    首个未完成任务：{{first_task_description}}
  </output>
</check>

如果 Story 文件的 YAML frontmatter 已包含 `baseline_commit`，保留现有值，不要覆盖

<check if="{{sprint_status}} file exists">
  <action>加载完整文件：{{sprint_status}}</action>
  <action>读取所有 development_status 条目，查找 {{story_key}}</action>
  <action>将 development_status[{{story_key}}] 设为 {{current_status}}</action>
</check>

<check if="{{sprint_status}} file does NOT exist">
  <action>将 Story 文件 Status 部分中的值设为 {{current_status}}</action>
</check>
<check if="{{current_status}} == 'ready-for-dev' AND story file YAML frontmatter does NOT contain baseline_commit">
  <action>运行 `git rev-parse HEAD`，将当前提交记录到 {{baseline_commit}}；如果 git/版本控制不可用，则将 {{baseline_commit}} 设为 `NO_VCS`</action>
  <action>如果故事文件存在 YAML frontmatter，则在其中添加 `baseline_commit: {{baseline_commit}}`</action>
  <action>如果故事文件没有 YAML frontmatter，则在文件顶部创建 frontmatter，其中仅包含 `baseline_commit: {{baseline_commit}}`</action>
</check>

<check if="{{sprint_status}} file exists">
  <check if="{{current_status}} == 'ready-for-dev' OR (review_continuation == true AND {{current_status}} != 'in-progress')">
    <action>将冲刺状态报告中的故事状态更新为 "in-progress"</action>
    <action>将 last_updated 字段更新为当前日期</action>
    <output>🚀 开始处理故事 {{story_key}}
      状态已更新：{{current_status}} → in-progress
    </output>
  </check>

  <check if="{{current_status}} == 'in-progress'">
    <output>⏯️ 恢复处理故事 {{story_key}}
      故事已标记为 in-progress
    </output>
  </check>

  <check if="{{current_status}} is neither ready-for-dev nor in-progress">
    <output>⚠️ 意外的故事状态：{{current_status}}
      预期为 ready-for-dev 或 in-progress。仍将继续……
    </output>
  </check>

  <action>保存 {{current_sprint_status}}，供后续使用</action>
</check>

<check if="{{sprint_status}} file does NOT exist">
  <output>ℹ️ 不存在冲刺状态文件——仅在故事文件中跟踪进度</output>
  <action>将 {{current_sprint_status}} 设为 "no-sprint-tracking"</action>
</check>

严格按照故事文件中任务/子任务的顺序执行——不得偏离

<action>查看故事文件中的当前任务/子任务——这是实施的权威指南</action>
<action>按照 red-green-refactor 循环规划实施</action>


<action>先为任务/子任务的功能编写会失败的测试</action>
<action>确认测试失败后再实施——以此验证测试正确性</action>


<action>编写最少量的代码，使测试通过</action>
<action>运行测试，确认现在已通过</action>
<action>按照任务/子任务的要求处理错误情况和边缘情况</action>


<action>在保持测试通过的同时改进代码结构</action>
<action>确保代码遵循 Dev Notes 中的架构模式和编码标准</action>
<action>应用 {{active_project_rules}} — 使用 project-context.md 中要求的框架、MCP 集成和约定</action>

<action>在 Dev Agent Record → Implementation Plan 中记录技术方案和决策</action>

<action if="需要超出故事规格的新依赖">停止："新增依赖需要用户批准"</action>
<action if="连续 3 次实施失败">停止并请求指导</action>
<action if="缺少必需的配置">停止："缺少必要的配置文件，无法继续"</action>

<critical>绝不实施故事文件中未对应到具体任务/子任务的内容</critical>
<critical>在当前任务/子任务完成且测试通过之前，绝不继续下一个任务</critical>
<critical>持续执行，不要暂停，直到所有任务/子任务完成或触发明确的停止条件</critical>
<critical>在满足第 9 步的完成条件之前，不要提议暂停以供审查</critical>

为任务引入或更改的业务逻辑和核心功能创建单元测试 根据故事需求，为指定的组件交互添加集成测试 当故事需求要求时，为关键用户流程添加端到端测试 覆盖故事开发说明中指出的边缘情况和错误处理场景 确定如何运行此仓库的测试（根据项目结构推断测试框架） 运行所有现有测试，确保没有引入回归 运行新测试，验证实现正确 如果项目配置了代码检查和质量检查，则运行这些检查 验证实现是否满足所有故事验收标准；明确执行量化阈值要求 停止并修复后再继续——立即找出破坏性变更 停止并修复后再继续——确保实现正确 除非满足所有条件，否则绝不能标记任务完成——不得撒谎或作弊

<action>验证此任务/子任务的所有测试确实存在且全部通过</action>
<action>确认实现与任务/子任务的要求完全一致——不添加额外功能</action>
<action>验证与此任务相关的所有验收标准均已满足</action>
<action>运行完整测试套件，确保没有引入回归</action>


<check if="任务是评审跟进项（带有 [AI-Review] 前缀）">
  <action>提取评审条目详情（严重程度、描述、相关验收标准/文件）</action>
  <action>将其添加到解决情况跟踪列表：{{resolved_review_items}}</action>

  
  <action>在“Tasks/Subtasks → Review Follow-ups (AI)”部分将任务复选框标记为 [x]</action>

  
  <action>根据描述，在“Senior Developer Review (AI) → Action Items”部分找到匹配的行动项</action>
  <action>将该行动项的复选框标记为 [x]，表示已解决</action>

  <action>在 Dev Agent Record → Completion Notes 中添加：“✅ 已解决评审问题 [{{severity}}]：{{description}}”</action>
</check>


<check if="所有验证关卡均已通过且测试确实存在并通过">
  <action>仅在此时将任务（及子任务）复选框标记为 [x]</action>
  <action>在 File List 部分更新所有新增、修改或删除的文件（路径相对于仓库根目录）</action>
  <action>在 Dev Agent Record 中添加完成说明，总结实际实现和测试的内容</action>
</check>

<check if="任一验证失败">
  <action>不要标记任务完成——先修复问题</action>
  <action>如果无法修复验证失败的问题，则停止</action>
</check>

<check if="review_continuation == true and {{resolved_review_items}} is not empty">
  <action>统计本次会话中已解决的评审条目总数</action>
  <action>添加变更日志条目：“已处理代码评审问题——解决了 {{resolved_count}} 项（日期：{{date}}）”</action>
</check>

<action>保存故事文件</action>
<action>确定是否还有未完成的任务</action>
<action if="还有未完成的任务">
  <goto step="5">下一个任务</goto>
</action>
<action if="没有未完成的任务">
  <goto step="9">完成</goto>
</action>

确认所有任务和子任务均已标记为 [x]（现在重新扫描故事文档） 运行完整回归测试套件（不得跳过） 确认文件列表包含所有已更改的文件 执行增强版完成定义验证 将故事状态更新为："review"

<action>使用以下必要要求验证完成定义检查清单：
  - 所有任务/子任务均已标记为完成 [x]
  - 实现满足所有验收标准
  - 已为核心功能添加/更新单元测试
  - 在需要时，已为组件交互添加集成测试
  - 故事要求时，已为关键流程添加端到端测试
  - 所有测试均通过（无回归问题，新增测试成功）
  - 代码质量检查通过（linting，以及配置的静态分析）
  - 文件列表包含所有新增/修改/删除的文件（相对路径）
  - Dev Agent Record 包含实现说明
  - Change Log 包含更改摘要
  - 仅修改了允许修改的故事部分
</action>


<check if="{sprint_status} file exists AND {{current_sprint_status}} != 'no-sprint-tracking'">
  <action>加载完整文件：{sprint_status}</action>
  <action>查找与 {{story_key}} 匹配的 development_status 键</action>
  <action>确认当前状态为 "in-progress"（预期的前一状态）</action>
  <action>将 development_status[{{story_key}}] = "review"</action>
  <action>将 last_updated 字段更新为当前日期</action>
  <action>保存文件，并保留所有注释和结构，包括 STATUS DEFINITIONS</action>
  <output>✅ 已在 sprint-status.yaml 中将故事状态更新为 "review"</output>
</check>

<check if="{sprint_status} file does NOT exist OR {{current_sprint_status}} == 'no-sprint-tracking'">
  <output>ℹ️ 已在故事文件中将故事状态更新为 "review"（未配置 sprint 跟踪）</output>
</check>

<check if="story key not found in sprint status">
  <output>⚠️ 故事文件已更新，但 sprint-status 更新失败：未找到 {{story_key}}

    故事文件中的状态已设为 "review"，但 sprint-status.yaml 可能未同步。
  </output>
</check>


<action if="any task is incomplete">停止 — 完成剩余任务后再标记为待审查</action>
<action if="regression failures exist">停止 — 修复回归问题后再完成</action>
<action if="File List is incomplete">停止 — 将所有已更改的文件补充到文件列表</action>
<action if="definition-of-done validation fails">停止 — 解决完成定义验证失败项后再完成</action>

使用验证框架执行增强版完成定义检查清单 在 Dev Agent Record → Completion Notes 中准备简洁的摘要

<action>告知 {user_name} 故事实现已完成，现可进行审查</action>
<action>总结主要成果：故事 ID、故事键、标题、主要更改、新增测试、修改的文件</action>
<action>提供故事文件路径和当前状态（现为 "review"）</action>

<action>根据 {game_dev_experience}，询问用户是否需要了解以下内容：
  - 实现了什么以及其工作方式
  - 做出特定技术决策的原因
  - 如何测试或验证这些更改
  - 使用的模式、库或方法
  - 其他希望进一步说明的内容
</action>

<check if="user asks for explanations">
  <action>根据 {game_dev_experience} 提供清晰且结合上下文的说明</action>
  <action>在有帮助时，使用示例并引用具体代码</action>
</check>
<action>说明完毕（或用户表示没有问题）后，建议合理的后续步骤</action>
<action>推荐的后续步骤（可根据项目设置灵活调整）：
  - 检查已实现的故事并测试更改
  - 确认已满足所有验收标准
  - 如适用，确保已做好部署准备
  - 运行 `code-review` 工作流进行同行评审
  - 可选：如果已安装 Test Architect 模块，运行 `/bmad:gds:workflows:automate` 扩展防护测试
</action>

<output>💡 **提示：** 为获得最佳效果，请使用与实现此故事时**不同**的大模型运行 `code-review`。</output>
<check if="{sprint_status} file exists">
  <action>建议查看 {sprint_status}，了解项目进度</action>
</check>
<action>保持灵活——允许用户选择自己的路径或寻求其他帮助</action>

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