agent-core-java 的 DevFlow Definition of Done 实战指南:三层质量核验与工作项收尾闭环

原创2026-10-11 22:21:341,630 阅读
文章标签:人工智能大模型AI AgentAgent 框架Agent 工作流多智能体工具调用MCP 服务Agent 记忆RAG后端Agent 沙箱

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 核验会交叉比对:门禁表写着 R3 passed,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//traceability.md
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 项:组件边界工作项的组件设计修订

触及组件边界(对外接口、组件依赖、状态机、组件职责变化)的工作项,必须满足:

  1. 组件设计修订已先行:按 devflow-design/SKILL.md 的硬性顺序——影响组件边界时,必须先修订 component-design-draft.md 并经评审与模块架构师确认,再写工作项设计。
  2. 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 定义了五步:

  1. DoD 核验:对照 12 项逐项写结论。发现缺口按返工表回对应阶段——需求无对应通过测试回 devflow-tdd;reviews/ 缺记录或 Resolution 空缺补评审或返工;门禁表与 reviews/ 不一致修正门禁表(造假按 critical);实现与设计漂移回 devflow-design 或 devflow-tdd;证据缺失或过期回 devflow-tdd 补真实证据,不补叙述。
  2. 追溯终验:通读 traceability.md,断链按 critical 处理。
  3. Promotion:按 promotion-checklist 同步长期资产,保留原模板做最小清理。
  4. Closeout 记录:写 features/<id>/closeout.md(一页内)——DoD 核验结果摘要、promotion 路径表(同步了什么 / N/A 及理由)、遗留债务清单(带去向:新工作项 / 登记的 issue)、复盘一句话。
  5. 人确认关闭:把 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 的资产沉淀规则,即可让每一个关闭的工作项都留下可追溯、可审计、可复用的完成证据与长期资产。

登录后查看全文
agent-core-java