Using Devflow

使用 DevFlow

DevFlow 是什么

DevFlow 把「产出高质量代码」拆成由外到内的三层质量。第一、二层有阶段技能承载；第三层是贯穿设计、实现、评审的质量约束：

前两层保证外部质量（做对的事、做对），第三层保证内在质量（做好）。devflow-design 是设计阶段：它通过结构、接口契约、错误模型和测试设计为第三层奠基；实现和评审时仍必须叠加 devflow-clean-code 与适用语言/领域技能。三层不是三个产物，而是同一份代码的三个维度。目标一句话：SDD 范式下生成 Clean Code 的代码，而不是仅仅能运行的代码。

协作姿态是 human-on-the-loop：具体的活由 AI 干，人站在环上审查关键产物（规格、设计、测试、代码）。因此每个阶段的产物都必须可冷读、可审查——这是所有技能共同的硬要求。

工作流

需求/任务到达 ──→ [0] 确认运行模式（见下）
    |
    v
[1] devflow-specify     写 spec.md + plan.md 骨架 + 初始化 traceability.md
    |
[R1] devflow-review     独立评审规格 → 记录到 reviews/ ──[人工确认]──
    v
[2] devflow-design      影响组件边界时先修订 component-design-draft.md；
    |                   写 design.md：职责、接口契约、错误模型、测试设计
[R2] devflow-review     独立评审设计 → 记录到 reviews/ ──[人工确认]──
    v[SKILL.md](../devflow-clean-code/SKILL.md)
[3] devflow-tdd         细化 plan.md 任务计划；按测试设计逐用例
    |                   RED→GREEN→REFACTOR；默认逐任务派发 implementer
    |                   subagent；plan.md 记进度与证据行；叠加
    |                   devflow-clean-code 与适用语言/领域规范技能
[R3] devflow-review     独立评审测试与代码 → 记录到 reviews/ ──[人工确认]──
    |                   ├─ 需修改：回 devflow-tdd 定向返工，回填 Resolution 后复审
    |                   └─ 重新设计：回 devflow-design / devflow-specify 修正上游工件
    v                   （同一 R 节点最多自动返工复审 3 轮，仍不通过则升级人裁决）
[4] devflow-ship        DoD 核验 + 追溯终验 + promotion 长期资产 + closeout
    |                   ── 人确认关闭 ──
    v
完成

评审是必经节点，不是可选预审：每个阶段产物完成后必须经 devflow-review 独立评审并把记录写入 reviews/，评审通过（且按运行模式获得人工确认）之前不进入下一阶段。跳过任何一个 R 节点直接进入下一阶段，都是流程违规。

轻量状态机

DevFlow 不维护独立路由器或额外状态文件；plan.md 的门禁表、任务状态、reviews/ 记录就是可恢复状态。恢复或续作时按下面语义解释门禁：

R1 rework 默认回 devflow-specify；R2 rework 默认回 devflow-design；R3 rework 默认回 devflow-tdd。只有评审明确指出规格漏洞、设计方向错误、工件间漂移需要改上游时，才回更上游阶段。pending 和 rework 不能混用：pending 是去评审，rework 是先修再评审。

Todo 投影规则

当需要生成 todo / 计划 / 执行队列时，把上面的生命周期按节点原样投影：阶段节点、R 门禁节点、ship 节点都是一级待办。devflow-specify 完成只表示 spec/traceability/plan 骨架就绪，下一条待办必须是 R1 devflow-review；devflow-design 完成只表示 design 就绪，下一条待办必须是 R2 devflow-review。devflow-tdd 内部的多个任务不是多个人工确认节点：任务 DONE 后只要 plan.md 能唯一选择下一任务，就继续执行。R3 打回时，下一条待办必须是 devflow-tdd 定向返工与回填 Resolution，随后才是 devflow-review 复审；不得把 rework 当成“立刻再评审”。attended 的人工确认附着在对应 R 节点 verdict 之后，不替代独立评审，也不发生在评审之前；unattended 只移除人工停顿，不移除任何 R 节点。

运行模式（工作流启动时确认一次）

启动工作流时先问用户一次：「评审通过后是否需要停下呈人确认，还是连续执行到必须人工决策的点？」并把答案记入 plan.md 头部：

unattended 只移除人工停顿，不移除任何质量动作：独立评审照做、评审记录照写、critical findings 照样阻塞（返工修复并复审，而不是带病推进）、DoD 照核验。所有评审记录留存在 reviews/，供人事后统一审计。用户未明确回答时按 attended 执行；模式记录后，恢复执行的会话沿用 plan.md 中的模式，不重新猜测。无论哪种模式，TDD 任务完成后都按 plan.md 自动续跑到下一个唯一可执行任务；只有 devflow-specify / devflow-design 中无法由 AI 决定的业务规则、验收阈值、架构边界、专家取舍，TDD 任务队列无法唯一判定，以及自动返工达到 3 轮上限，才需要向人提问。

旁路：缺陷修复走 devflow-fix（复现 → 根因 → 最小修复），其中修复实现仍回到 TDD（先写复现缺陷的失败测试），修复后的测试与代码同样经 R3 评审，收尾同样经 devflow-ship。 SKILL.md 阶段允许回溯：写测试时发现规格漏洞就回去补规格；实现时发现设计错误就回去改设计。回溯时更新对应工件并让受影响的评审重新进行，不要让代码与工件漂移。

何时可以裁剪

• 微小修改（几行、无接口变化、风险低）：spec 可压缩成 plan.md 里的一段验收标准，design 可省略（R1/R2 随之合并入 R3），但 TDD、R3 评审与 clean code 不裁剪。
• 纯重构（行为不变）：不需要 spec/design，但必须有覆盖现有行为的测试先行，且代码评审（R3）照做。
• 拿不准时不裁剪。裁剪的是文档量，永远不是质量门槛（测试先行、证据行、独立评审与记录、人工确认（attended 模式）、DoD 核验、整洁标准）。微小修改的 DoD 裁剪规则见 devflow-ship 的 Definition of Done。

工件约定

路径解析纪律

DevFlow 工件路径一律相对于目标组件仓库根目录解析，而不是相对于当前会话所在目录或 DevFlow skills 仓库。开始、恢复、评审、实现、收尾前都先确定组件根：

1. 用户显式给出组件目录时，以该目录为组件根；
2. 否则读取当前仓库根的 AGENTS.md / 团队约定，若声明目标组件根或路径覆盖则遵循；
3. 仍无法确定时，使用当前工作目录所在的组件仓库根；如果当前目录不是目标组件仓库，先停下询问。

默认 features/ 与 docs/ 都是组件根下的相对路径：<component-root>/features/...、<component-root>/docs/...。组件仓库根 AGENTS.md 可以覆盖这些相对路径与模板约定；覆盖后所有阶段必须使用覆盖路径，不再回退到默认根目录路径。产出前先在回复或 plan.md 头部写明解析出的组件根与工件根，避免把工件误建到上级仓库根。

每个工作项一个目录（AR<id>/DTS<id>/CHANGE<id> 或团队等价编号）：

features/<id>-<slug>/
  spec.md                     # 规格（devflow-specify 产出）
  traceability.md             # 追溯矩阵：spec-design-code 一致性约束（specify 初始化，逐阶段补列）
  component-design-draft.md   # 组件级设计修订（影响组件边界时，devflow-design 产出）
  design.md                   # 工作项级设计（devflow-design 产出）
  plan.md                     # 执行计划：运行模式、阶段门禁状态、任务拆解与证据行；
                              #   中断恢复的单一入口（specify 建骨架，tdd 细化并维护）
  reviews/                    # 评审记录：每轮一份，findings + resolution 闭环（devflow-review 产出）
  closeout.md                 # 收尾记录（devflow-ship 产出）

长期资产在组件根下 docs/（component-design.md、ar-specs/、ar-designs/，或团队覆盖路径），由 devflow-ship 在收尾时从过程工件 promotion，平时各阶段只读。

恢复进度时先读 plan.md（运行模式 + 阶段门禁状态 + 当前任务），再按工件状态校验，不依赖聊天记忆：

工件与聊天记忆冲突时，以工件为准。组件仓库根 AGENTS.md 可以覆盖路径与模板约定。

行为准则

适用于所有 DevFlow 技能，不可协商：

1. 不默默补全模糊需求。 实现任何非平凡内容前显式列出假设，请人确认或写入 spec。最常见的失败是做错假设并在未经检查下继续推进。
2. 困惑时停下，不猜。 遇到冲突需求、不一致工件、缺失阈值：指出具体困惑，提出澄清问题或交回对应负责人。
3. 方案有问题就说。 不当 yes-machine：直接指出问题、量化缺点、给替代方案；对方知情后仍坚持则执行。
4. 强制简单。 完成前自问：能用更少代码吗？抽象配得上它引入的复杂度吗？资深工程师会不会说「为什么不直接……」？
5. 范围纪律。 只改任务要求改的。路过的问题登记，不顺手修；不删不理解的代码；不在 spec 外加功能。
6. 验证，而非声称。 「看起来对」永远不够。完成的依据是通过的测试、构建输出、评审记录。
7. 作者不自审，阶段必评审。 每个阶段产物完成后必须经独立上下文（subagent 或新会话）评审并落盘记录；attended 模式下人工确认后才进入下一阶段，unattended 模式下评审与记录照做、critical 照样阻塞。

技能地图

语言与领域技能是叠加约束：它们在规格、设计、实现、评审各阶段被对应技能消费，自身不是流程阶段。

语言规范的发现按命名约定：工作项触及语言 X 的代码 → 叠加 <x>-coding-standards（存在时）。新增语言技能只要遵循同一份结构契约（coding-standards-creator/references/coding-standards-skill-contract.md），无需改动任何阶段技能即可接入；技能尚不存在而团队有该语言规范时，用 coding-standards-creator 生成。

领域技能的发现按 description：工作项的业务/技术语境命中某个领域开发技能的 frontmatter description 时，加载该领域技能并把它加入 Quality Stack。核心 DevFlow 不维护领域技能枚举；新增领域技能时，应把触发词、适用边界、易混淆场景写进该技能自己的 description，让入口、实现、评审和收尾都通过“适用领域技能”这一通用类别消费它。