怎样给 Codex 写清楚任务：上下文、约束与验收标准

给 Codex 的任务不需要很长，但必须让目标和边界可判断。“优化一下项目”没有明确终点，而“修复登录超时，保持接口字段不变，并通过指定测试”就能被调查、实现和验收。

## 一个完整任务的六个部分

1. 目标：最终要解决什么用户或业务问题。 2. 现状：当前行为、错误信息和复现步骤。 3. 范围：允许检查和修改哪些模块。 4. 约束：哪些接口、配置和用户改动不能改变。 5. 验收：用什么测试、页面或数据证明完成。 6. 交付：需要哪些文件、说明和风险记录。

这些部分不必使用固定模板，但缺少关键内容时，Codex 应先调查或提出问题，而不是自行补全业务规则。

## 给出证据而不是结论

与其说“后端有问题”，不如提供请求路径、状态码、日志时间和预期响应。与其说“页面很丑”，不如描述目标宽度、移动端行为和参考页面。真实证据能帮助代理找到根因，也能避免修改错误模块。

## 明确禁止项

如果 application.yml、数据库生产数据、公共 API 或现有部署脚本不能改变，要直接写出来。工作区存在未提交文件时，也应说明哪些是用户改动。禁止项越具体，越容易在执行前发现冲突。

## 验收标准要可执行

- 指定测试命令应通过。 - 某接口在特定输入下返回确定状态和字段。 - 页面在桌面端和移动端不存在横向溢出。 - 数据迁移可重复执行且不覆盖现有记录。 - 构建产物能够由当前源码重新生成。

“看起来正常”可以作为补充，不能作为唯一标准。

## 大任务先要求计划

涉及多个系统或高风险操作时，先让 Codex 只读调查并列出最小方案、影响文件、数据变化和回滚方式。人工确认后再实现。这样能在成本较低的阶段纠正错误理解。

## 推荐的结尾要求

要求交付时区分已完成、已验证和未验证内容，并列出实际执行的命令。若任务因权限或缺少信息受阻，应说明具体阻塞条件，不要用猜测补齐。清楚的任务描述不是限制能力，而是让能力作用在正确目标上。