agent-core-java 的 DevFlow Definition of Done 实战指南:三层质量核验与工作项收尾闭环
agent-core-java 的 DevFlow Definition of Done 实战指南:三层质量核验与工作项收尾闭环
本文以仓库 .claude/skills/devflow-ship/references/definition-of-done.md 为骨架,结合
.claude/skills/下devflow-ship、using-devflow、devflow-tdd、devflow-review、devflow-specify、devflow-fix等技能与模板,完整讲解 DevFlow 工作项关闭前的完成定义(DoD)如何逐项核验。读完本文,你将掌握:DoD 的 12 项核验条目与三层质量模型、证据(RED/GREEN 证据行、评审 Resolution、静态分析输出)的合格标准、attended/unattended运行模式下人工把关的位置,以及微小修改、缺陷工作项两类裁剪规则下哪些门槛「不降低」。
DoD 是什么:收尾阶段的固定核验清单
在 DevFlow 工作流中,devflow-ship 负责收尾。它回答两个问题:这个工作项真的可以关闭吗?关闭之后给仓库留下什么? 第一个问题对应的动作,就是对照 definition-of-done.md 逐项核验完成证据。
definition-of-done.md 开头明确其定位:「配套 devflow-ship。工作项关闭前的完成定义,人在最后把关时的固定核验清单」。这意味着 DoD 不是一份"建议",而是一份可勾选、必须逐项写结论的清单——每一项核验都要写结论:满足 或 缺口 + 返工去向。
DoD 解决的核心问题是:"评审通过了"不等于"可以关闭"。devflow-ship/SKILL.md 的总览部分专门强调,DoD 是防止"靠印象关单"的机制。收尾不修代码、不补测试:核验发现缺口,要回对应阶段补完再回来,而不是在收尾阶段顺手消化。
DoD 按 DevFlow 的三层质量模型组织,共 12 项核验,外加一节裁剪说明。下面逐层展开。
第一层 SDD:意图正确(第 1-3 项)
第一层回答的问题是:做的是不是对的事?(对应 devflow-specify 技能承载的规格驱动开发阶段)。这层的失败模式是:需求含糊 → 模型靠猜补全 → 做出来的不是用户要的东西。
| 项 | 核验内容 | 证据落点 |
|---|---|---|
| 1 | spec.md 存在且 R1 门禁通过;本轮实现范围与 spec 范围一致(没有 spec 外的功能混进来) |
features/<id>/spec.md、plan.md 门禁表 R1 行 |
| 2 | spec 评审记录存在(reviews/),critical/important findings 的 Resolution 列已逐条回填(修复+commit / 人接受+理由 / 债务+去向) |
features/<id>/reviews/ |
| 3 | blocking Open Questions 全部闭合(答案已写回 spec),没有被悄悄遗忘的待决项 | spec.md 的 Open Questions 节 |
第 1 项:spec 存在、R1 通过、范围一致
spec.md 是模型与人之间的第一份契约,由 devflow-specify/SKILL.md 产出,模板见 requirement-template.md。DoD 核验的不是"spec 写没写",而是三层事实:
- spec 存在且通过 R1 评审:R1 是规格评审门禁,评审按 spec-review-rubric.md 执行,核心怀疑是「两个不同的人读这份规格,会做出同一个东西吗?」。
- 实现范围与 spec 范围一致:没有 spec 外的功能混进来。这对应
using-devflow行为准则中的"范围纪律:只改任务要求改的。路过的问题登记,不顺手修"。DoD 核验时要检查 diff 里有没有"走私"进实现、却从未出现在 spec 验收标准中的行为。
第 2 项:findings 的 Resolution 逐条回填
评审记录存在于 features/<id>/reviews/,每份记录包含 findings 表(含 Resolution 列)、分类、verdict。DoD 核验的重点是:critical/important findings 的 Resolution 列是否逐条回填。三种合法的回填方式:
- 修复 + commit:怎么改的,锚定到具体 commit;
- 人接受 + 理由:人明确接受不修,记录谁接受的、为什么;
- 债务 + 去向:升级为债务,登记到 plan.md 债务节或新工作项。
devflow-review/SKILL.md 明确规定:Resolution 列有空着的 critical/important,门禁不算通过。DoD 核验时如果发现某条 finding 的 Resolution 是空的,即使 verdict 写着"通过",也要按缺口打回。
第 3 项:blocking Open Questions 全部闭合
devflow-specify/SKILL.md 要求每个开放问题标注 blocking/non-blocking、负责人、它阻塞了什么决策;blocking 问题闭合前规格不能确认。把待决问题藏在正文里而不列出来,等于把猜测走私进规格。DoD 核验的就是:spec.md 的 Open Questions 节中,blocking 项是否已全部闭合且答案已写回 spec,而不是在 spec 里留下一个"先这么定,后面再想"的隐患。
第二层 TDD:功能正确(第 4-7 项)
第二层回答的问题是:功能被证明正确了吗?(对应 devflow-tdd 技能)。这层的失败模式是:代码未验证 → 留一堆 BUG 给人。DoD 在这一层的核验围绕"证据"展开——证据是本轮真实产生的,不接受只有叙述没有输出的"证据"。
| 项 | 核验内容 | 证据落点 |
|---|---|---|
| 4 | plan.md 全部任务为 done;每个任务带 RED/GREEN 证据行(命令、关键输出、commit 锚点),证据是本轮真实产生的;门禁状态表与 reviews/ 实际记录一致 |
features/<id>/plan.md |
| 5 | spec 每条验收标准(含 NFR 的 Response Measure)有对应通过的测试;modify 条目有回归测试、remove 条目有删除后语义测试的通过记录 |
plan.md 任务与证据行 |
| 6 | 完整测试套件在最终代码上全绿;构建无新增警告 | mvn test 等套件命令输出 |
| 7 | R1/R2/R3 全部评审记录存在于 reviews/,最终 verdict 为通过,findings 全部有 Resolution;attended 模式下各门禁均有人工确认记录,unattended 模式下已把 reviews/ 全量呈给人做事后审计 |
features/<id>/reviews/ |
第 4 项:plan.md 全 done + RED/GREEN 证据行
plan-template.md 是 plan.md 的模板,它同时是"执行计划与中断恢复的单一入口"。DoD 核验的要点:
- 全部任务状态为 done:
done表示本任务 RED/GREEN/REFACTOR 证据齐全、traceability 已更新、提交完成,不表示等待人工确认。 - 每个任务带证据行:标准格式如下——
- 证据:
- RED: `ctest -R ModeServiceTest` → FAIL: SetModeRejectsInvalid…
(expected ERR_INVALID_ARG, got OK) @ a1b2c3d
- GREEN: `ctest` → 47/47 passed, 0 warnings @ d4e5f6a
- REFACTOR: 提取 `is_valid_mode()`,替换裸值;`ctest` → 47/47 passed @ e7f8a9b
RED/GREEN/REFACTOR 三行证据各自锚定 commit,这是评审者和人核验"测试真的失败过、真的在最终代码上跑过、代码已经过 clean-code 检视"的最低限度证据。"证据是本轮真实产生的" 意味着:不能把其他工作项的测试输出、或者"看起来应该能过"的叙述拿来充数。
- 门禁状态表与 reviews/ 实际记录一致:
plan.md头部的门禁表是工作流状态机——pending(产物已就绪待评审)、passed(verdict 通过)、rework(打回待返工)。DoD 核验会交叉比对:门禁表写着 R3passed,reviews/里却没有对应评审记录文件,或记录里 verdict 是需修改——两者不一致本身就是缺口。using-devflow/SKILL.md 明确把"plan.md 门禁状态表与 reviews/ 实际记录不一致"列为返工项,且"状态造假按 critical 处理"。
第 5 项:验收标准 ↔ 通过测试的双向覆盖
spec 的每条验收标准(含 NFR 的 Response Measure)必须有对应通过的测试。关键在于两类特殊条目的处理:
modify条目有回归测试:修改既有行为(错误码、默认值、阈值、兼容承诺)时,旧行为中要保留的部分必须有回归测试。这正是 devflow-specify/SKILL.md 中"Acceptance 覆盖保留的行为与批准的破坏"的落实。remove条目有删除后语义测试:移除/禁用既有能力时,必须有"删除后的可观察语义"的通过记录。
规格到测试的映射从设计阶段就锚定:devflow-design/SKILL.md 要求"把 spec 的每条验收标准映射成测试用例表",modify 需求必须有回归用例、remove 必须有删除后语义用例,且 Case ID 必须稳定(TC-xxx)并能双向追溯。
第 6 项:完整套件全绿、构建无新增警告
"完整测试套件在最终代码上全绿"意味着不能只跑新测试就宣布完成——devflow-tdd/SKILL.md 的风险信号里明确列出"跳过完整套件,只跑新测试就宣布完成"。在本仓库的落地环境中,套件命令即 AGENTS.md 中的约定:
mvn compile # 编译
mvn test # 全部单元测试(默认排除 system-test 标签)
mvn test -Dsurefire.groups=system-test # 运行系统测试
mvn test -Dtest=ClassName # 定向测试
"构建无新增警告"与本仓库的代码规范直接相关:AGENTS.md 要求新代码 UTF-8、四空格缩进、无 tab、行宽不超过 120 字符、import 显式分组排序等,这些规则由 coding-standard-full/SKILL.md(144 条规则,华为 CodeArts Check)承载。
第 7 项:R1/R2/R3 全量评审记录 + verdict 通过 + 人工确认
- 评审记录全量存在:R1(spec 评审)、R2(design 评审)、R3(test+code 评审)各轮记录都在
reviews/,最终 verdict 为通过,findings 全部有 Resolution。 - attended 模式(默认):各门禁均有人工确认记录。评审 verdict 通过后停下,把评审记录与 verdict 呈给人,人同意后才进入下一阶段。
- unattended 模式:R 节点后不停顿连续执行,但"只移除人工停顿,不移除任何质量动作"——独立评审照做、评审记录照写、critical findings 照样阻塞。DoD 核验时要把
reviews/全量呈给人做事后统一审计,人工确认列记N/A(unattended)。
第三层 Clean Code:内在质量(第 8-10 项)
第三层回答的问题是:代码本身写得好吗?(对应 devflow-clean-code + <language>-coding-standards + 领域技能)。这层的失败模式是:能跑但烂 → 难维护、难审查、难演进。
| 项 | 核验内容 | 证据落点 |
|---|---|---|
| 8 | 实现与 design.md(及组件设计,如适用)一致;所有偏离已回写工件并重新确认 |
design.md、reviews/ |
| 9 | 适用约束审计逐项标注状态(clean / documented-debt / critical-open / N/A+理由),并给出证据引用 |
约束审计表 |
| 10 | 静态分析新增项已修复或带理由抑制;无未解释的 critical 项 | 静态分析输出 |
第 8 项:实现与设计一致
实现必须与 design.md(及组件设计,如适用)一致;所有偏离(无论是有意的优化还是无奈的变通)都必须回写工件并重新确认,而不是让代码与工件默默漂移。using-devflow/SKILL.md 规定:实现中发现设计错误或规格漏洞,停下任务,在 plan.md 记录阻塞原因,回 devflow-design / devflow-specify 修正工件并重新评审,不在代码里悄悄绕过。
第 9 项:适用约束审计表
DoD 要求对适用约束逐项标注状态并给出证据引用,只写 clean 没有证据,按缺口处理。约束审计表如下(完整继承自原文档):
| 约束项 | 来源 |
|---|---|
| 整洁代码 | devflow-clean-code |
| 语言编码规范 | 适用的 <language>-coding-standards,工作项涉及的每种语言一行 |
| 领域约束 | 命中 description 的领域开发技能各一行;未命中的相邻领域不用列,除非评审要求说明 N/A |
四种状态的判定规则:
clean:必须有证据引用——任务 REFACTOR 证据、implementer 的clean_code_check、R3 finding/resolution、静态分析输出、review 摘要、commit,或债务登记。clean不是"我觉得没问题",而是"能指到具体证据"。documented-debt:必须有可定位的登记与去向(plan.md 债务节 / 新工作项 / 登记的 issue)。critical-open:任一critical-open→ 阻塞关闭。N/A:必须说明为什么该约束不适用(例如纯文档改动不涉及语言编码规范;未命中领域技能时,除非评审要求,不用硬列)。
devflow-clean-code 的五维判据(简洁、可靠、可维护、可测试、高性能)是 clean_code_check 的最低覆盖要求,clean-code-check-template.md 提供了返回模板;REFACTOR: N/A 也要逐项说明已对照五维自检的理由,而不是写一句"looks clean"。
第 10 项:静态分析新增项闭环
静态分析新增项已修复或带理由抑制;无未解释的 critical 项。"带理由抑制"不是"为了过检查而抑制"——AGENTS.md 明确禁止"用空分支、无意义强转、宽泛包装、抑制、行为变更来满足检查器",而是要求按规则推荐的语义重构去做。对本仓库而言,静态分析对应 .claude/skills/coding-standard-full/SKILL.md 的 144 条规则与 CodeArts Check;AGENTS.md 的 Verification Gate 还要求在提交前运行 git diff --check、扫描 tab/尾随空格/wildcard import/超长行/TODO/FIXME/未用 import/死代码,以及逐条复检 recurring checklist(G.MET.01、G.DCL.02、G.ERR.02、G.CON.10 等)。
一致性与追溯(第 11-12 项)
| 项 | 核验内容 | 证据落点 |
|---|---|---|
| 11 | traceability.md 链路闭合:每条需求 → 设计章节 → 测试用例 → 代码/测试文件 → 证据;N/A 有理由 |
features/ |
| 12 | 触及组件边界的工作项:组件设计修订已经模块架构师确认,promotion 已规划 | component-design-draft.md、promotion-checklist |
第 11 项:追溯矩阵链路闭合
traceability-template.md 规定追溯矩阵的列结构:需求条目 | Change Type | 上游锚点 | 组件设计章节 | 设计章节 | 测试设计用例 | 任务(可多个) | 代码文件/函数 | 测试代码 | 验证证据。各阶段只追加自己负责的列:specify 填需求与上游锚点,design 填设计章节与测试设计用例,tdd 填任务/代码/测试/证据。
DoD 核验的是整条链路闭合:每条需求 → 设计章节 → 测试用例 → 代码/测试文件 → 证据。断链是 spec-design-code 不一致的直接信号,devflow-ship/SKILL.md 将"通读 traceability.md 做追溯终验"作为收尾第二动作,且断链按 critical 处理。N/A 必须有理由(例如纯内部修改无组件设计章节)。
第 12 项:组件边界工作项的组件设计修订
触及组件边界(对外接口、组件依赖、状态机、组件职责变化)的工作项,必须满足:
- 组件设计修订已先行:按 devflow-design/SKILL.md 的硬性顺序——影响组件边界时,必须先修订
component-design-draft.md并经评审与模块架构师确认,再写工作项设计。 - promotion 已规划:收尾时按 promotion-checklist.md 将过程工件沉淀为长期资产——
spec.md→docs/ar-specs/<id>-<slug>.md、design.md→docs/ar-designs/<id>-<slug>.md、component-design-draft.md→docs/component-design.md。promotion 的核心原则是保留原模板,做最小清理:已确认的规格、设计和组件设计正文是交付件,Open Questions、评审应答、过程笔记这类草稿专属内容留在features/,不带入长期文档。
裁剪说明:哪些门槛"不降低"
DoD 明确规定了两种裁剪,但裁剪的是核验项的替换,不是质量门槛的下调:
微小修改
按 using-devflow 裁剪规则省略了 spec/design 的微小修改(几行、无接口变化、风险低),第 1-3、8 项替换为:「plan.md 中的验收标准已全部有通过测试」;其余各项不降低。
缺陷工作项(DTS)
缺陷修复走 devflow-fix(复现 → 根因 → 最小修复),DoD 第 1-3 项替换为:「fix.md 的复现/根因/修复边界完整,复现测试先失败后通过」。fix.md 模板见 fix-template.md,三段记录不可省:复现(最小步骤 + 证据 + 稳定性)、根因(直接原因/根本原因/波及范围三层 + 已排除假设)、修复边界(最小安全修复范围 + 显式不修 + 回退策略 + 分流判断)。复现测试先失败后通过,就是回归屏障。
紧急不等于绕过
DoD 特别强调:任何情况下证据要求(4-7、10)与一致性要求(8、11)不可裁剪。也就是说,即使紧急修复,RED/GREEN 证据行、完整套件全绿、静态分析闭环、design 一致性、追溯链路闭合这些门槛一个都不能省。"紧急"可以加速流程,但不能跳过证据生产。
收尾闭环全景:从 DoD 核验到人确认关闭
把 DoD 放回完整收尾流程中,devflow-ship/SKILL.md 定义了五步:
- DoD 核验:对照 12 项逐项写结论。发现缺口按返工表回对应阶段——需求无对应通过测试回
devflow-tdd;reviews/ 缺记录或 Resolution 空缺补评审或返工;门禁表与 reviews/ 不一致修正门禁表(造假按 critical);实现与设计漂移回devflow-design或devflow-tdd;证据缺失或过期回devflow-tdd补真实证据,不补叙述。 - 追溯终验:通读
traceability.md,断链按 critical 处理。 - Promotion:按 promotion-checklist 同步长期资产,保留原模板做最小清理。
- Closeout 记录:写
features/<id>/closeout.md(一页内)——DoD 核验结果摘要、promotion 路径表(同步了什么 / N/A 及理由)、遗留债务清单(带去向:新工作项 / 登记的 issue)、复盘一句话。 - 人确认关闭:把 closeout 呈给人,人确认后工作项关闭;
features/<id>/原地保留(不移动、不删除),保证追溯链接长期有效。
需要警惕的收尾风险信号
- 跳过 DoD 直接写 closeout("评审都过了肯定没问题"——这正是 DoD 要防的靠印象关单);
- promotion 过度改写原模板正文、重排章节或压缩表格,导致长期交付件丢失规格/设计内容;
- promotion 把过程内容原样带入长期文档(Open Questions、过程笔记、评审应答);
- 只 promote 设计不 promote 规格,长期库里设计与规格断链;
- 遗留债务写"后续优化"却没有去向;
- 把"补证据"做成"补叙述"——证据必须是真实命令输出与锚点。
小结
definition-of-done.md 把"工作项可以关闭"从主观判断变成 12 项可逐条勾选的核验,对应 DevFlow 三层质量模型:SDD 层管意图正确(spec + R1 + Open Questions)、TDD 层管功能正确(plan 证据行 + 测试覆盖 + 套件全绿 + 评审闭环)、Clean Code 层管内在质量(design 一致 + 约束审计 + 静态分析),最后以一致性与追溯(traceability 链路、组件边界 promotion)收口。裁剪规则只允许替换核验项,不允许降低证据与一致性门槛。对 agent-core-java 仓库的任何工作项(AR/CHANGE/DTS),收尾时对照 definition-of-done.md 逐项核验,配合 devflow-ship/SKILL.md 的五步收尾与 promotion-checklist.md 的资产沉淀规则,即可让每一个关闭的工作项都留下可追溯、可审计、可复用的完成证据与长期资产。