dev-story

用途

dev-story 是连接规划与代码的桥梁技能。它读取一个故事文件，汇集程序员所需的全部上下文，路由到正确的专家智能体，并驱动实现直至完成——包括编写测试。

工作流位置

每个故事的标准循环为：

/qa-plan sprint —— 在冲刺开始前定义测试需求
/story-readiness [path] —— 开始前进行校验
/dev-story [path] —— 实现（本技能）
/code-review [files] —— 审查
/story-done [path] —— 验证并关闭

在 workflow: minimal 下，循环简化为 /dev-story [path] → /story-done [path]：没有 QA 计划、就绪检查或冲刺。/story-done 会指出下一个故事。

若有冲刺计划，在所有冲刺故事完成后：运行 /team-qa sprint 执行完整 QA 周期，并在推进项目阶段前获得签核结论。

输出

项目代码根目录下的源代码 + 引擎测试根目录下的测试文件（Godot 为 tests/，Unity 为 Assets/Tests/，Unreal 为 Source/<Module>/Private/Tests/，见 .claude/docs/directory-structure.md）。代码根目录依据 engine.name 解析（Godot 为 src/，Unity 为 Assets/，Unreal 为 Source/<Module>/，见 .claude/docs/code-root-resolution.md）。

配置解析

技能启动时通过 yaml-helper.sh 解析配置项：automation、workflow、story_granularity、qa.level、testing.strict、system_overrides。若无配置块，则使用 .claude/docs/config-resolution.md 中的默认值。

story_granularity 决定预期实现周期：coarse（默认，rigor: minimal）为多日，给程序员子智能体更长的工作上下文；balanced（rigor: standard）为 1–2 天；fine 为小时级（更紧的上下文）。它不改变前置条件门禁。
qa.level 控制程序员简报是否携带测试要求。minimal 时省略“Test requirement”行（第 4 阶段第 7 项）——不要求测试；standard 时包含按类型的测试要求；full 时还传入覆盖率目标。与 workflow: minimal 不同。当不要求测试（minimal）时，第 5 阶段的 testing.strict 门禁为空操作。
workflow 层级按故事所属系统解析（见 .claude/docs/workflow-modes.md）：取故事 GDD: 路径的 GDD 文件名主干（design/gdd/<stem>.md → <stem>），其 TR-[system]-NNN ID 的 [system] 段仅作为回退别名；若配置块列出该系统的 system_overrides 行则使用，否则用项目值。在第 2 阶段开始时解析（故事头部在此读取），并应用于前置条件门禁。

各阶段

第 1 阶段：查找故事。若提供路径则直接读取；若无参数，检查 production/session-state/active.md 中的活动故事并确认；若未找到，询问要实现哪个故事，并 glob production/epics/**/*.md 列出 Status: Ready 的故事。
第 2 阶段：加载完整上下文。读取 references/2-load-context.md 并遵循。
第 3 阶段：路由到正确的程序员。读取 references/3-route.md 并遵循。
第 4 阶段：实现。读取 references/4-implement.md 并遵循。
第 5 阶段：测试证据要求。读取 references/5-test-evidence.md 并遵循。
第 6 阶段：收集与总结。读取 references/6-collect.md 并遵循。
第 7 阶段：更新会话状态。读取 references/7-session-state.md 并遵循。

若对话在本阶段被压缩或恢复，需重新读取对应文件。

错误恢复协议

首先验证产物。若返回契约指定了路径，在将该阶段视为完成前检查路径是否存在——命名了产物但磁盘上不存在即为失败阶段，无论回复读起来多么流畅。智能体可能耗尽整个阶段并返回看似合理的前言却什么都没写，这既不是 BLOCKED 也不是错误或“无法完成”，因此下面的触发器永远不会触发。以未满足的契约重新恢复它；上下文通常仍在。

若任何生成的智能体返回 BLOCKED、错误或无法完成：立即暴露，不要越过它阻塞的依赖继续，并始终生成部分报告。完整流程见 .claude/docs/error-recovery-protocol.md。

常见阻塞：

输入文件缺失（故事未找到、GDD 缺失）→ 重定向到创建它的技能
引用的 ADR 状态为 Proposed → 不实现；待决定后用 /architecture-decision accept ADR-NNNN 接受（不引用任何 ADR 的故事不受此阻塞——见第 2 阶段）
范围过大 → 通过 /create-stories 拆分为两个故事
ADR 与故事之间指令冲突 → 暴露冲突，不要猜测
Manifest 版本不匹配 → 向用户显示差异，询问是沿用旧规则还是先更新故事

协作协议

适用于协作模式（默认）。引导与自主模式见 .claude/docs/automation-modes.md——以下规则描述协作模式的要求，而非通用行为。

文件写入是委托的——所有源代码、测试文件和证据文档由通过 Agent 生成的子智能体写入。每个子智能体单独执行“May I write to [path]?”协议。本编排器仅写入以下内容，且每次都在点名该写入的询问之后：

故事的 Status: / Last Updated: 及其 production/sprint-status.yaml 条目——唯一一次“May I mark this story In Progress?”询问（第 2 阶段）
故事的 ADR Version、ADR Decision Summary 和 ## Implementation Notes（ADR 不匹配选项 [A]），以及其 Manifest Version: / Manifest-Note:（manifest 选项 [A] 或 [B]）——每个选项都点名该编辑，因此选择它即为询问
依赖故事的 Status: Complete（依赖选项 [C]，然后“May I update [dependency path] Status to Complete?”）
Config/Data 故事的数据文件（“May I write to [path]?”）
在 Unity 上，Assets/Scripts/ScreenshotOnArg.cs，逐字写入自 .claude/docs/run-and-observe.md（“May I write Assets/Scripts/ScreenshotOnArg.cs?”，第 6 阶段）

production/session-state/active.md 中的会话状态检查点是唯一无需询问的写入。

实现前须知

实现前加载——在加载完所有上下文（故事、TR-ID、ADR、manifest、引擎偏好）之前不要开始编码。不完整的上下文会产生偏离设计的代码。
ADR 即法律——实现必须遵循 ADR 的 Implementation Guidelines。若指南与看似“更好”的做法冲突，在总结中标记，而不是默默偏离。
保持在范围内——Out of Scope 部分是契约。若实现故事需要触碰范围外文件，停下并暴露：“Implementing [criterion] requires modifying [file], which is out of scope. Shall I proceed or create a separate story?”
测试对 Logic/Integration 不是可选的（在 qa.level: standard/full 下）——没有测试文件存在就不要标记实现完成。在 qa.level: minimal 下不要求测试，此条不适用。
Visual/Feel 和 UI 外观是观察到的，不是推迟的——第 6 阶段的运行保留截图（UI 涉及的每个屏幕；Visual/Feel 还需在 /story-done 前获得负责人签核），qa.level 从不豁免这两者。只有 Visual/Feel 标准的 feel 部分——时机、重量、响应性——被标记为 DEFERRED，留给 /team-qa。
大型结构决策前询问——若故事需要 ADR 未覆盖的架构模式，在实现前暴露：“The ADR doesn't specify how to handle [case]. My plan is [X]. Proceed?”

限制

本技能依赖 .claude/docs/ 下的多个文档（config-resolution.md、directory-structure.md、code-root-resolution.md、automation-modes.md、workflow-modes.md、error-recovery-protocol.md、run-and-observe.md）以及 references/ 下的阶段文件，这些内容的具体细节暂未提供。

技能介绍

用途