dev-story

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation,workflow,qa.level,gate_level,engine_values,specialists,perf_budgets,system_overrides

已在上方解析——直接使用。没有区块 → 默认值见 .claude/docs/config-resolution.md。

使用提问工具提问。若没有提问工具，则为选项编号并在末尾结束本轮 以等待回答。跳过或关闭问题不算回答：请用纯文本再次提问。

开发故事

实现一个故事：检查是否可以开始，将其标记为进行中，把代码交给合适的程序员 Agent，附上一份根据故事编写的简报，然后检查结果能否解析且看起来正确，最后移交。

写入内容（每项都要先询问并明确指出）：故事的 Status、Last Updated 和 ## Files，以及其 production/sprint-status.yaml 条目。程序员 Agent 会在代码根目录和测试根目录下编写代码和测试 （.claude/docs/code-root-resolution.md）。会话检查点和证据标记无需询问即可写入。 下一步： /story-done [story-path]；在 standard 和 full 模式下，先运行 /code-review [files]。

提问遵循 .claude/docs/automation-modes.md（协作模式始终提问，引导模式在重大选择时提问，自主模式记录后继续；automation_always_ask 类别始终提问）。

清单（复制后逐项勾选）：

- [ ] Phase 1: story found, tier resolved
- [ ] Phase 2: prerequisites checked (ADR, manifest, dependencies)
- [ ] Phase 3: story marked In Progress (one ask)
- [ ] Phase 4: programmer and engine specialist chosen
- [ ] Phase 5: work handed out with a full brief
- [ ] Phase 6: finished? parse check, run and look, one Run result line
- [ ] Phase 7: summary, ## Files, checkpoint, closing block

阶段 1：故事

在技能名称后输入的文本就是故事路径。如果未输入，则使用 production/session-state/active.md 中检查点指明的故事，并确认： “正在继续处理 [title]——确认吗？”如果那里没有故事，则用 bash .claude/scripts/story-facts.sh --all 中的 TODO 条目作为选项，询问“我们要实现哪个故事？”如果 production/epics/ 下完全没有故事文件，则停止并提示： “在 production/epics/ 中未找到故事——运行 /create-stories [epic-slug] 来创建它们（在 standard 和 full 模式下，如果还没有 Epic，请先运行 /create-epics）。”

bash .claude/scripts/story-facts.sh <story-path> 会给出故事类型、层、TR-ID、ADR 和依赖项。然后完整阅读故事。

层级。 根据故事所属系统的 workflow 确定层级，系统由其 GDD: 路径中的 GDD 文件名主干标识（design/gdd/<stem>.md → <stem>；仅在没有 GDD 路径时使用 TR-ID 中的 [system]）：如果该系统有 system_overrides 条目，就使用该条目；否则使用项目值。在首次回复中说明：Tier: workflow [value]。该值（绝不是 rigor 或 qa.level）决定阶段 2 的列和结束时的下一步。

阶段 2：能否开始？

输入	full	standard	minimal
TR 注册表 docs/architecture/tr-registry.yaml	缺失：停止，提示“运行 /architecture-review 以完成初始化”	可选	不应存在
故事中提到的 ADR	缺失、状态为 Proposed、Deprecated 或 Superseded：停止	同左，但仅当故事中提到 ADR 时	同左，但仅当故事中提到 ADR 时
控制清单 docs/architecture/control-manifest.md	缺失：警告并继续	缺失：警告并继续	不应存在

ADR 字段写着 N/A — [reason] 的故事表示未指定 ADR。

ADR。 bash .claude/scripts/adr-status.sh <ADR id> 会显示 ADR 的状态和 version。停止提示：Proposed — “ADR-NNNN 仍处于 Proposed 状态。请先通过 /architecture-decision accept ADR-NNNN 接受它，再开始实现。” Deprecated 或 Superseded — “ADR-NNNN 已[status]；请将故事指向[successor]（编辑其 ADR 字段； /create-stories 不会改写现有故事），再开始实现。” NOT_FOUND — “未找到 ADR 文件。请运行 /architecture-decision，或更正故事的 ADR 字段。”

不要打开 ADR。 程序员应读取的是故事中的 ADR 决策摘要和实现说明。比较 ADR 的 version 与故事的 ADR Version：

• 两者相同，或故事没有 ADR Version（在添加版本戳之前编写），或两者都是 unversioned：信任故事。对于后两种情况，在摘要中注明“摘要已信任，未经验证”。
• 两者不同，或 ADR 为 unversioned，但故事指定了日期：阅读 references/version-mismatch.md。如果匹配，则不要加载它。

切勿将缺少版本戳视为过期：未知时以故事为准；之后由 /story-readiness 和 /code-review 检查是否存在偏差。

清单。 清单存在时，比较其中的 Manifest Version 行与故事中的版本。两者不同： 阅读 references/version-mismatch.md。

依赖项。 对于故事 Depends on 行中的每个路径，运行 bash .claude/scripts/story-facts.sh <path>。如果状态不是 COMPLETE，询问：“[this story] 依赖于 [dependency]，其状态为 [status]，而非 Complete。你希望如何继续？” 选项：继续 — 我接受风险 / 停止 — 我会先完成依赖项 / 已完成，但状态从未更新 — 将其标记为 Complete。 停止：该故事处于 BLOCKED 状态（阶段 7），不运行 Agent。标记之前先询问：“可以将 [path] 的 Status 设置为 Complete 吗？”继续：在 Deviations 下记录。NOT_FOUND： 警告“未找到依赖故事：[path]”。

出现上述任何停止情况：不运行 Agent。转到阶段 7 并写入 BLOCKED 检查点。

阶段 3：将状态标记为 In Progress

运行任何 Agent 之前，只询问一次：“可以将此故事标记为 In Progress 吗？这会在 [story path] 中设置 Status 和 Last Updated，并在结尾的 ## Files 下列出已更改 的文件。”如果文件不存在，则不要在问题中提及冲刺文件。在提问前说明接下来要做什么： 该问题必须是回复的最后内容。对方同意后：

• 运行 bash .claude/scripts/md-section.sh set-field <story> Status "In Progress"，然后 运行 set-field <story> "Last Updated" <YYYY-MM-DD> --after Status。在 minimal 模式下， 故事文件是唯一的进度记录。
• production/sprint-status.yaml：将此故事条目的 status 设为 in-progress，并将 顶层 updated 设为今天。如果文件不存在，则说明 Sprint status not updated: production/sprint-status.yaml absent。

对方拒绝：两者都不更改，在摘要中打印 Story not marked In Progress — declined， 然后继续。

阶段 4：由谁来实现

配置/数据类故事不需要 Agent。 将每项值的变化显示为「从 → 到」，询问“可以编辑[数据文件]吗？”，然后进行编辑。转到阶段 6。

故事	程序员 Agent
基础层，任意类型	engine-programmer
类型为 UI	ui-programmer
类型为 Visual/Feel	gameplay-programmer
Core 或 Feature，游戏玩法	gameplay-programmer
Core 或 Feature，AI 或寻路	ai-programmer
Core 或 Feature，网络	network-programmer

每个代码类故事都要由引擎专家参与。 从上面的 specialists 行中选择： code（specialists.code，语言专家：它能区分 Godot C# 项目和 GDScript 项目，而 engine.name 无法做到）；如果故事涉及着色器或材质，则还要选择 shader；如果是 UI 故事，则还要选择 ui；当 code 为 unset 时，选择 primary（通用引擎专家）。不要凭记忆指定专家：该行列出的才是项目的选择。如果每个值都是 unset，且没有 primary，则说明“No engine specialist configured”，并继续处理，不要使用专家。

阶段 5：分派工作

将实现工作交给程序员 Agent。任务说明应指向文件；绝不要把整份文档粘贴进去。

• 目标： 根据验收标准实现[故事路径]，并遵守其范围之外的内容。
• 资料来源：
  1. 故事文件。文件中包含验收标准、范围边界和 QA 测试用例。
  2. 要查找的每个 TR-ID（TR-[system]-NNN）：在 docs/architecture/tr-registry.yaml 中查找匹配 id: <TR-ID>\s*$ 的行。 以其中的 requirement 文本为准，而非故事中引用的文本。
  3. ADR 指引，内嵌提供：故事中的 ADR 决策摘要和实现说明。绝不提供 ADR 路径。
  4. 控制清单中按章节列出的 [Layer] 层规则。
  5. project.yaml 中的 naming.* 和上文的 perf_budgets 行。
  6. 故事「测试证据」部分中的测试文件路径。
• **测试：**对于逻辑类和集成类故事，根据 qa.level 处理：
  • minimal：“不要为此故事编写测试文件——qa.level: minimal 表示免除测试证据。”要明确说明：省略这一行和忘记写这一行，在 Agent 看来没有区别。
  • standard：“编写代码时，在[路径]处编写测试。每条验收标准至少需要一个测试函数。”命名规则见引擎对应的 .claude/rules/test-standards.md。不得使用随机种子、依赖时间的断言或外部 I/O。
  • full：同上，并补充：“必须覆盖每条标准：任何一条未测试，/story-done 都会阻止完成。”
• **输出：**创建或更改的文件、编写的测试函数、任何问题或阻碍，以及是否已完成。
• **边界：**仅在解析出的代码根目录下编写代码，并仅在测试根目录下编写测试。若代码根目录尚未解析，则不要写入任何内容，并报告此情况。不得修改故事范围之外的文件；如有需要，报告原因。为公共 API 编写文档注释。ADR 未涵盖的架构选择：报告计划，不要自行决定。不得为一次性用途编写辅助代码或抽象；不得处理不可能发生的情况（仅在输入和数据文件边界进行验证）；编写通用逻辑，绝不能通过特判某个值来让测试通过。

向双方说明任务说明中未包含的内容。 阶段 2 发现不存在的输入（TR 注册表、ADR、清单）不会包含在内：告知 Agent：“未传递[输入]——此层级不存在该内容；不要尝试查找。”并在分派工作前用一行告知用户：简报未包含：[输入] — 将依据验收标准和 [GDD | brief] 实现。

然后，在程序员报告后将引擎检查交给专家。 任务说明：检查变更文件中是否存在错误使用或已变更的 [引擎 + 版本] 引擎 API，并对照 docs/engine-reference/<engine>/；返回文件、行号、问题和修复方案的列表；不要编辑任何内容。若问题会导致验收标准无法通过，则交回程序员修复一次；其余问题列入总结。

阶段 6：检查结果

Agent 完成了吗？ 如果它提前停止、触及限制，或报告在任务中途结束：故事就是未完成。将此作为标题，列出已有内容，说明中断之处，并提出恢复 Agent。绝不要用“Implementation Complete”覆盖它，并保持状态不变。

它写了声称写的内容吗？ 首先验证产物：如果 Agent 报告中提到的文件不在磁盘上，无论报告写得多流畅，这一步都算失败：恢复 Agent 并指出缺失的文件。如果报告为 BLOCKED、出现错误或写着“cannot complete”：立即说明，不要继续处理受其阻碍的部分，并提供部分报告 （.claude/docs/error-recovery-protocol.md）。范围太大：用 /create-stories 将其拆分。如果 ADR 和故事相互矛盾：报告冲突；绝不要猜测。

测试文件在吗？ 对于 qa.level: standard 和 full，如果是 Logic 或 Integration 故事，请检查 Test Evidence 路径中的文件。若缺失：在 gate_level 行指定的该类型 BLOCKING 级别，将“story unverifiable — test required before /story-done”标记为阻塞项；在 ADVISORY 级别，将其列为建议。minimal 不需要检查：测试已豁免。

能解析吗？ 运行能够通过退出码回答此问题的检查，并报告命令、退出码和任何错误行：

• **Godot：**先运行一次 godot --headless --path . --import，然后运行 godot --headless --path . -s res://.claude/scripts/godot-parse-check.gd -- res://<each changed .gd>。 退出码为 1 表示脚本未能加载；其 PARSE FAIL: 行会指出文件名。绝不要使用 --check-only，单独运行 --import 也不算解析检查。可执行文件使用 commands.test 指定的文件名中包含 godot 的那个（像 bash run-tests.sh 这样的包装脚本不算编辑器），否则使用 engine.path，再否则使用 godot。绝不要在磁盘上搜索可执行文件：这三个都无法运行时，该检查未通过验证。
• **Unity、Unreal：**阅读 references/engine-checks.md。
• 没有引擎可执行文件：parse NOT VERIFIED — engine binary not available。 绝不要仅凭阅读代码推断它可以解析。

运行并观察（.claude/docs/run-and-observe.md）。对于每个玩家可见的故事（所有 Visual/Feel 和 UI 故事，以及任何其他有可视界面的故事）：直接启动进入该故事涉及的场景，将截图直接保存到 production/qa/evidence/[story-slug]/（[story-slug] 是故事文件名去掉 .md；先用 mkdir -p 创建文件夹），然后运行 bash .claude/scripts/review-receipts.sh hash <each changed file> > production/qa/evidence/[story-slug]/stamp.txt，再打开图片并对照验收标准。qa.level: minimal 不豁免此项。只报告一行纯文本，以 Run result: 开头（不要加粗： /story-done 会按原样读取）：

• Run result: OBSERVED — <what was on screen>，并提供保留文件的路径；
• Run result: NOT VERIFIED — <reason>（没有引擎、未捕获截图）；在默认 gate 级别下，这会阻止 Visual/Feel 或 UI 故事通过 /story-done；
• Run result: N/A — <reason>，适用于没有可观察内容的故事；理由要说明为什么没有（/story-done 不接受“it's a Logic story”）。

Visual/Feel 验收标准中只有感受部分（时机、力度）会 DEFERRED 至 /team-qa：静态图无法展现这些内容。

此技能预先批准了 PATH 中的 godot。如果通过 engine.path 或 commands.test 指定的可执行文件运行引擎，需要先获得批准：用户批准一次，或将 Bash(<that executable> *) 添加到 .claude/settings.local.json。

阶段 7：摘要、文件、检查点

## Implementation Complete: [title]

**Files changed**:
- `[code root path]` — created / modified ([what])
- `[test path]` — [N] test functions
**Test evidence**: waived at `qa.level: minimal` — no test was required or written   (Logic/Integration at minimal, instead of the test line)
**Verification**: [command] — [exit code and result | parse NOT VERIFIED — <reason>]

**Acceptance criteria**:
- [x] [criterion] — [file:function | test name | OBSERVED in <image path>]
- [ ] [criterion] — DEFERRED: feel, needs a playtest
**Deviations**: [None | files outside scope, an accepted dependency or version risk]
**Engine risks**: [None | the specialist's findings]
**Blockers**: [None | each]

在 qa.level: standard 和 full 时，添加：“在 /story-done 之前运行测试套件并确认新测试通过：它会检查测试文件是否存在，但不会运行任何测试。”在 minimal 时省略此项：没有测试需要运行。对于没有保留图像的 Visual/Feel 或 UI 故事，添加：“在 /story-done 之前，必须在 production/qa/evidence/[story-slug]/ 下保留截图”（对于 Visual/Feel，还需在 production/qa/evidence/[story-slug]-evidence.md 中签字确认）。

## Files。 按照阶段 3 的要求，将该节正文替换为已更改的代码和测试文件列表，每行一个文件： 将列表通过 stdin 传给 bash .claude/scripts/md-section.sh replace <story> "Files"。 如果故事没有该节：在末尾添加 ## Files 和列表，并通过文件编辑完成，绝不要使用 shell 命令（shell 写入会跳过项目的写入检查）。如果阶段 3 的要求被拒绝，则跳过此项。

检查点，适用于所有结果。将代码块传递给 bash .claude/scripts/session-state.sh checkpoint，以替换旧检查点：

**Updated:** [date]
**Branch:** `[current git branch]`
**Current task:** /dev-story — [story path] ([title])
**Next step:** [the Next step below]
**Blocked on:** [nothing, or the blocker]
**Files in progress:** [changed files, comma-separated]
**Run result:** [OBSERVED — … | NOT VERIFIED — … | N/A — …, as in the closing block: /story-done reads it here]
**Open questions:** [none, or one line each]

本次运行的最后一条回复必须以此代码块结尾；Run result: 行只在此处打印，回复中的其他地方不得打印。Next step 应根据你在阶段 1 中说明的级别（workflow 行，而不是 rigor 或 qa.level）。Next step：minimal 时，/story-done [path]。standard 和 full 时，先运行 /code-review [files]，然后运行 /story-done [path]。INCOMPLETE：运行 /dev-story [path] 以继续。BLOCKED：执行解除阻塞所需的操作（/architecture-decision accept ADR-NNNN、完成依赖项、审查 diff）。

Story: [path] — [Implemented | INCOMPLETE — <breakage> | BLOCKED — <reason>]
Run result: [OBSERVED — … | NOT VERIFIED — … | N/A — …]
Next step: [Implemented, Tier: workflow minimal → /story-done [path] | Implemented, Tier: workflow standard or full → /code-review [changed files], then /story-done [path] | INCOMPLETE → /dev-story [path] to resume | BLOCKED → the unblocking action]