如何为你的 AI 编码智能体提供清晰的“完成的定义”

当一位人类同事接手一张含糊的工单时，他会凭判断力填补空白并提出问题。而一个 AI 编码智能体两者都不会。它读取你的请求、编写代码、运行它力所能及的各种检查，然后宣布功能已完成——往往一个澄清性问题都不问。正如一篇指南所言，当你把模糊的需求交给智能体时，“余地不会被消化——而会被直接构建出来。”

这使得你的完成的定义成为你所能写下的、杠杆率最高的一件事。本指南将介绍如何写出一份智能体真正能据以行动的定义。

验收标准 vs. 完成的定义

这是两个相关但值得区分开来的概念：

• 验收标准是针对具体功能的：这项特定工作必须做到什么，才能算作正确。
• 完成的定义是贯穿整个项目的：每一次变更在交付前必须通过的质量关卡——测试、评审、文档、不提交任何密钥。

可以把验收标准理解为“我们是否构建了正确的东西”，把完成的定义理解为“我们是否按我们的标准构建了它”。你的智能体两者都需要。（Atlassian 对这一区别有一篇不错的入门介绍。）

让它可测试，而非空泛的愿景

判断一条标准是否优秀的检验方法：一段脚本——或者智能体本身——能否检查它是否成立？“登录表单应该感觉很快”是无法验证的。把它改写成有明确边界的东西：

• 提交有效凭据后，在 500ms 内重定向到 /dashboard
• 提交错误密码时显示行内错误，并且不跳转离开页面
• 提交空字段时在客户端拦截，任何网络请求都不会发出
• 登录失败按每个 IP 每分钟 5 次进行速率限制

每一行都是智能体既能朝着构建、又能加以确认的东西。Addy Osmani 关于为 AI 智能体撰写优秀规范的建议是聚焦于是什么和为什么，而非逐行的怎么做——描述意图和约束，让智能体自行选择实现方式。

一个具体的例子

针对同一项任务，对比下面两条提示。

含糊版：

为用户添加一种重置密码的方式。

带有完成的定义版：

添加一套密码重置流程。完成意味着：

• 一个 POST /auth/reset-request 端点接受一个邮箱，并始终返回 200（绝不透露该邮箱是否存在）
• 一个有效期为 1 小时、经过签名的一次性 token 通过 src/lib/mail.ts 中现有的邮件发送器发送
• POST /auth/reset-confirm 校验该 token、强制执行当前的密码策略，并在使用后使该 token 失效
• 测试覆盖：有效重置、过期 token、被重复使用的 token、未知邮箱
• 未经事先说明不得引入任何新依赖

第二个版本更长，并不是因为它官僚繁琐——而是因为智能体原本会自行猜测的每一处模糊之处，如今都已被明确决定。那些涉及安全的选择（不泄露账户是否存在、让 token 过期、一次性使用）恰恰是你最不希望智能体临场发挥的部分。

把“完成”接入智能体的循环

一份可测试的完成的定义，其真正的威力在于它闭合了智能体的反馈回路。一个编码 → 测试 → 修复 → 重复的智能体循环，只有在存在一个清晰的目标可供命中时才会收敛。当你的标准映射到实际的测试上时，智能体就能运行它们、看到失败，并在把工作交回给你之前修正自己的成果。

所以不要仅仅描述“完成”——要给智能体一种检查它的方式：

• 把测试命令（npm test、pytest）指给它，并告诉它在这些测试通过之前功能都不算完成。
• 对于那些在代码中难以断言的东西——可读性、遵循既有模式——使用一次 LLM 作为评判者的处理：用第二条提示来对照你的质量标准评审输出。Anthropic 及其他方发现这种方式对主观检查很有效。
• 把安全性以及“不允许占位/mock 代码”保留在你贯穿整个项目的完成的定义里，这样它就会应用于每一次变更，而不只是你恰好记得提及的那些。

把它放在智能体会看到的地方

把你贯穿整个项目的完成的定义写下来一次，放进一个智能体会自动读取的文件里——仓库根目录下的 AGENTS.md 或 CLAUDE.md。针对具体功能的验收标准则放进任务提示本身。这样一来，“我们的标准”始终在上下文中，而你只需把今天这项工作独有的部分讲清楚即可。

这一转变很微妙，但它就是整场博弈的全部：有了一个足够强大的智能体，你的验收标准不再是写给同事的一张便条，而是成了代码据以构建的规范。请像对待规范那样去撰写它们。