AI Agent / 系统课时
明确目标与验收标准
明确目标与验收标准
模糊需求会让 Codex 自行猜测“做什么”和“何时算完成”。本课将把想法改写为可观察行为、明确输入输出和可执行检查,使实现与验收使用同一套标准。
学习目标
- 用用户可观察行为描述任务目标
- 为正常、异常和边界输入定义结果
- 把完成条件转换为可执行检查
目标描述结果而非手段
“优化登录”“完善接口”“重构订单模块”都缺少可判断的结果。目标应说明谁在什么条件下执行什么操作,以及系统应产生什么变化。
例如,“用户提交无效邮箱时,登录接口返回 400 和固定错误码;有效邮箱保持原有流程”比“增加邮箱校验”更完整。它同时表达了触发条件、可观察结果和必须保持不变的行为。
补齐输入与输出
接口任务应明确请求条件、状态码、响应字段和兼容性;页面任务应描述用户操作与可见结果;后台任务应说明触发条件、数据范围和失败处理。遇到动态值时,使用规则描述,不要虚构固定 ID 或时间。
验收标准应覆盖本次风险最高的路径。小任务通常至少包含一个成功场景和一个失败或边界场景,避免只验证“能运行”。
把需求写成检查清单
下面是一条完整任务指令,其中每项标准都能被测试或人工观察。
text
目标:
为订单查询接口增加可选参数 status,按订单状态过滤结果。
输入与输出:
- status 缺省时,返回行为与当前版本一致。
- status 为已支持值时,只返回对应状态的订单。
- status 为未知值时,返回 HTTP 400,错误码为 INVALID_STATUS。
验收标准:
1. 新增测试覆盖缺省、有效值和无效值三种情况。
2. 保持现有分页字段和排序规则不变。
3. 不修改数据库表结构,不新增运行时依赖。
4. 运行相关测试和静态检查,并报告实际命令与结果。
5. 最后列出修改文件和仍未验证的事项。预期结果
text
Codex 能据此定位接口、实现过滤与错误处理、补充三类测试,并用实际验证结果判断任务是否完成。验收标准不是实现步骤。它规定结果,允许 Codex 依据项目现有架构选择控制器、服务层或查询层的具体实现位置。
检查标准是否可验证
写完后逐条追问:“我能通过什么证据判断它成立?”若答案只是“代码看起来更好”或“逻辑更合理”,说明标准仍然模糊。应改成测试通过、响应匹配、页面出现指定状态、查询计划使用目标索引等可观察结果。
也不要写无法证明的绝对条件,例如“没有任何 Bug”。可以改成“新增测试覆盖已知边界,相关回归测试通过,代码审查未发现阻断问题”。
按自己的节奏,确认真正理解。