Agent Skills 的 Definition of Done：AI 编码代理必须通过的统一质量门禁

本文解析 agent-skills 仓库中的 Definition of Done 参考清单：它与按任务定义的验收标准（Acceptance Criteria）有何本质区别、由哪五个维度的常驻检查项组成，以及它如何作为 planning-and-task-breakdown、incremental-implementation 和 shipping-and-launch 三个技能共用的最终关卡。读完本文，你将掌握一套可以逐字落进自己项目、用于约束 AI 编码代理"什么叫做完"的统一质量底线。

什么是 Definition of Done：一套项目级常驻标准

Definition of Done（简称 DoD）是一条项目范围内、长期有效的质量底线：任何变更在声称"完成"之前都必须通过它。它与验收标准的关键差异在于——验收标准因任务而异，回答的是"我们做的是不是对的东西？"；而 DoD 每次都相同，回答的是"这份工作是否达到了我们约定的标准？"。

在 agent-skills 的设计里，DoD 不是一个独立的技能，而是一份被多个技能引用的共享参考清单。仓库的 README.md 在 Reference Checklists 一栏将其描述为"Project-wide standing bar every change clears, contrasted with per-task acceptance criteria"（每个变更都必须通过的、与按任务验收标准相对照的项目级常驻标准）。docs/getting-started.md 的参考资料映射表也把它的作用范围标为"all skills / every change"。这种"放在技能之外、被技能按需引用"的组织方式，正是仓库渐进式披露（progressive disclosure）设计的一部分。

Definition of Done 与 Acceptance Criteria 的对比

原文档用一张表厘清了两者的分工：

维度	验收标准（Acceptance Criteria）	Definition of Done
作用范围	针对单个任务或规格	适用于每一个增量
是否变化	每项任务各不相同	固定不变、反复复用
回答的问题	"我们做的是这个东西吗？"	"它就绪了吗？"
定义时机	规划任务时定义	为项目一次性定义
示例	"用户可通过邮件链接重置密码"	"测试通过、无回归、文档已更新"

两者是互补关系，而非二选一：一个任务只有在其自身的验收标准全部满足、并且常驻的 Definition of Done 同时达标时才算完成。缺掉任何一半，留下的都是"看起来做完了、其实没有"的工作。这一互补关系在 skills/using-agent-skills/SKILL.md 中也被再次确认：每个技能自带的 verification 是局部检查，而项目级的 DoD 是应用于每一次变更的底线，"它补充每个任务的验收标准，而不是取代它们"。

从 skills/planning-and-task-breakdown/SKILL.md 的结构可以看到两者如何衔接：该技能要求每个任务都写出具体的验收标准（如"用户可创建账户"），并在 See Also 一节中明确——"验收标准是按任务划分的，回答'我们做的是对的东西吗'；它们位于项目级 Definition of Done 之上，后者是任务在被记为完成之前必须清过的常驻标准"。

常驻检查清单（The Standing Checklist）

以下是原文档给出的完整检查清单，适用于每个变更在宣布完成之前的逐项核对。

Correctness（正确性）

• [ ] 任务的所有验收标准均已满足
• [ ] 代码可运行且行为符合预期——以运行时验证为准，而不是仅仅编译或类型检查通过
• [ ] 新行为有测试覆盖：没有这个变更时测试失败，有变更时测试通过
• [ ] 既有测试仍然通过，未引入回归
• [ ] 边界情况和错误路径已处理，而不是只覆盖了 happy path

这一节是整份清单里唯一强调"运行时证据"的维度。它呼应了仓库元技能 skills/using-agent-skills/SKILL.md 中"Verify, Don't Assume"的行为准则："Seems right" 永远不够——必须有证据（测试通过、构建输出、运行时数据）。

Quality（质量）

• [ ] 代码通过命名和结构表达意图；解释"它做什么"的注释不需要存在
• [ ] 没有重复的业务逻辑
• [ ] 没有遗留的死代码、调试输出或被注释掉的代码块
• [ ] 变更范围限定在任务之内；没有夹带无关的重构
• [ ] Lint 和格式化检查通过

DoD 文档明确指出，这些条目背后的深度由两个技能承载：code-review-and-quality（五轴评审：正确性、可读性、架构、安全、性能）和 code-simplification（在不改变行为的前提下降低复杂度）。具体而言：

• skills/code-review-and-quality/SKILL.md 的"Dead Code Hygiene"一节要求任何重构后显式列出孤儿代码并先询问再删除——这正是 DoD 中"No dead code"检查项的落地手法；其"Change Sizing"一节给出的 ~100 行变更目标，为"变更范围限定在任务之内"提供了可度量的参照。
• skills/code-simplification/SKILL.md 的验证清单要求"所有既有测试不做修改即可通过"、"没有删除或弱化错误处理"、"没有留下死代码"，与 DoD 质量节逐项对应。

Integration（集成）

• [ ] 变更在系统整体中工作，而不仅是孤立地可用
• [ ] 数据库迁移、配置变更、特性开关（feature flags）均已纳入考虑
• [ ] 任何公开接口或 API 变更都评估了向后兼容性

这一节把检查视角从"这个改动"拉高到"整个系统"。仓库中与之呼应的是 skills/incremental-implementation/SKILL.md 的 Rule 5（Rollback-Friendly）：数据库迁移应配有对应的回滚迁移、避免在同一提交里删除又替换——迁移的"accounted for"在实操中就包含回滚路径。

Documentation（文档）

• [ ] 公开接口、API 和用户可感知的行为都有文档
• [ ] 值得保留的架构决策已被记录（参见 documentation-and-adrs）
• [ ] 文档用"无时代感"的语言描述当前状态，而不是记录变更历史

第三点是 DoD 中容易被忽略的一条：文档应描述"现在是什么样"，而非"我们当时怎么改的"。skills/documentation-and-adrs/SKILL.md 承载了这条原则的展开——ADR 记录决策时的理由，而常规文档保持对现状的准确描述。

Ship-readiness（可发布性）

• [ ] 任何涉及不可信输入、认证或数据处理的地方都经过安全影响审查（参见 security-and-hardening）
• [ ] 新的关键路径已具备可观测性：日志、指标、追踪（参见 observability-and-instrumentation）
• [ ] 任何有风险的部分都有回滚路径（参见 shipping-and-launch）
• [ ] 在合并或部署之前，人类已完成审查并批准

最后一项值得特别留意：DoD 把"人工批准"写成了完成的必要条件之一，而不是流程的可选环节。这与仓库整体"人机协作、人类做最终裁决"的基调一致，例如 skills/code-review-and-quality/SKILL.md 的多模型评审模式图中，链条的终点始终是"Human makes the final call"。

如何按粒度应用 DoD

原文档把检查清单切成了三个应用粒度，避免"每个小改动都跑完全清单"的过度消耗：

• 按任务（Per task）：勾选 Correctness 和 Quality 两节后，才能把任务标记为完成。
• 按功能（Per feature）：功能被认为完成之前，还需确认 Integration 和 Documentation 两节。
• 按发布（Per release）：完整清单是底线（floor），shipping-and-launch 会在其上叠加部署专项检查。

同时，原文档给出了一条关于 DoD 自身的使用纪律：清单只对项目定制一次，之后保持不变地复用。一个每个冲刺都要重新谈判的 Definition of Done，就不配叫 Definition of Done。

这条纪律在仓库的引用方式上得到了印证：三个技能的 See Also 小节都以同一措辞模式引用同一份文件（../../references/definition-of-done.md），从源码结构看，DoD 被当作不变的常量而非可配置项对待——skills/incremental-implementation/SKILL.md 称之为"每个增量无论任务是什么都必须清过的常驻标准"，skills/shipping-and-launch/SKILL.md 则说它是"每个变更在运行发布检查清单之前必须清过的标准"。

DoD 在 agent-skills 仓库中的位置与作用机制

理解 DoD 在仓库中"住在哪、被谁引用"，有助于理解它为何放在 references/ 而非某个技能目录内：

1. 存放位置的设计意图：docs/skill-anatomy.md 说明，被多个技能共用的清单——testing、security、performance、accessibility、definition-of-done——统一放在仓库根部的 references/ 目录，"刻意不放进任何技能目录内"。因为 DoD 同时服务于规划、构建、发布多个阶段，归属某个单一技能反而错误。
2. 引用关系：在 references/definition-of-done.md 之外，引用它的文档包括 skills/planning-and-task-breakdown/SKILL.md、skills/incremental-implementation/SKILL.md、skills/shipping-and-launch/SKILL.md 和元技能 skills/using-agent-skills/SKILL.md。仓库还提供 scripts/validate-reference-links.js 校验脚本，防止这些跨目录引用失效。
3. 渐进式披露：技能本体（SKILL.md）是入口，像 DoD 这样的共享清单只在需要时才被加载，保持 token 开销最小。这意味着你可以把安装某个单技能时的"引用缺失"理解为已知限制——README.md 明确提示：单技能安装只拷贝 skills/<name>/，不带仓库级 references/ 目录，需要整仓集成或手动复制所需清单。
4. 与生命周期各阶段的咬合：从 skills/using-agent-skills/SKILL.md 的 Lifecycle Sequence 看，规划阶段产出的任务验收标准（阶段 4）、构建阶段的增量验证（阶段 7/10）、发布阶段的部署检查（阶段 16）分别对应 DoD 的 task / feature / release 三个应用粒度——DoD 是把这三个阶段的"局部绿灯"收拢成"整体绿灯"的那把尺子。

红旗信号（Red Flags）

原文档列出了五种典型的"假完成"信号，值得在团队中直接张贴：

• "做完了，只是还没运行过"：未经运行验证的工作不算完成。
• 把"测试通过"当成"完成"的同义词，同时跳过了文档、回归检查或运行时验证。
• 标准随截止日期压力而变：赶工期时降低门槛，平时维持高门槛——这本身破坏了"固定复用"的前提。
• 把验收标准当成全部标准，没有常驻的质量底线兜底。
• 在需要人工审查的变更上，未经人工审查就宣布"完成"。

这些红旗与 skills/incremental-implementation/SKILL.md 中的 Red Flags（如"跳过测试/验证步骤图快"、"增量之间构建或测试是坏的"）以及 skills/shipping-and-launch/SKILL.md 的红旗（如"没有回滚计划就部署"）构成呼应：DoD 是项目级总闸，各技能负责在各自阶段把这些信号拦下来。

落地建议：把 DoD 装进你的项目

结合仓库的实际组织方式，落地这份清单的步骤是：

1. 一次性定制：把 references/definition-of-done.md 的五个小节作为起点，按项目的技术栈裁剪（例如纯前端项目可将 Integration 节的"数据库迁移"替换为构建产物与依赖变更），但裁剪只发生一次。
2. 写入代理规则：在项目的 CLAUDE.md / AGENTS.md 中声明这份 DoD 为"完成的定义"，使代理在规划与实现阶段就知道最终闸门在哪。
3. 绑定检查点：沿用 skills/planning-and-task-breakdown/SKILL.md 的做法，在任务列表的每个 Checkpoint 中内嵌 Correctness + Quality 勾选；在每个 Phase 收尾处内嵌 Integration + Documentation 勾选。
4. 发布叠加专项清单：发布时以完整 DoD 为 floor，再叠加 skills/shipping-and-launch/SKILL.md 的 Pre-Launch Checklist（代码质量、安全、性能、可访问性、基础设施、文档六节）以及 references/security-checklist.md、references/performance-checklist.md 等仓库内配套清单。

最后重申原文档的核心主张：任务完成 = 该任务的验收标准 且 项目级 DoD 同时成立。前者保证"做对了东西"，后者保证"做的是达到标准的东西"——对 AI 编码代理而言，把这条双重门禁写成明确的、可勾选的清单，是让它稳定交付生产级工作的最后一道保险。