让 Codex 少返工：把“帮我优化”写成一张可验收工单

“帮我优化一下页面”看起来已经交代了任务，但执行者仍要猜：哪里不好、哪些结构可以变、用户最终要看到什么，以及做到什么程度才算完成。猜测越多，最后越容易出现代码改了很多，关键问题仍没解决的情况。

写清需求并不等于替工具设计每行代码。你需要提供的是可核对的目标、必要限制和完成标准，让实施者有空间解决问题，同时让结果有依据可以判断。

用五项内容交代一次改动

例如，下面是一个虚构视频列表的需求：“标题很长时，手机端按钮被挤出屏幕。只调整列表标题和操作区；标题最多显示两行，完整内容可查看；390像素和1280像素下都能操作，保留原筛选和排序。”这段话说明了问题、对象、边界和观察方式，执行者不必猜测整个页面是否要重做。

收到任务后，先读取相关项目说明，找出实际页面及样式来源，再复现问题。如果事实与描述不同，记录差异；若缺少决定业务行为的规则，再补齐关键信息。不要靠惯例替用户发明流程。

较大的功能可以按可验证结果拆分。例如筛选功能先明确参数组合，再处理查询，之后连接界面，最后检查空结果、刷新和手机状态。每一步保留差异，避免几个未经检查的改动叠加后难以定位原因。

某次改动的具体目标适合留在任务对话中。整个仓库需要长期遵守的测试命令、目录边界和代码约定，可以放在 AGENTS.md。反复执行的一组步骤，可以整理为 Skill（技能），并按实际需要附参考资料或辅助脚本。

这些文件帮助工具理解工作方式。真正需要强制执行的限制，还要由权限、检查命令和发布流程保障。例如“不读取某目录”不能只靠文字说明；规则涉及访问边界时，应核对实际权限配置。

页面布局问题要看真实页面，接口权限问题要验证服务端响应，部署问题要核对运行环境。一次单元检查通过，不能替代其他层面的验收；文件摘要相同也只说明内容一致，不能直接证明页面好看或业务可用。

对前面的标题挤压示例，至少检查长标题、短标题、无结果、按钮换行和窄屏。若有折叠区域或弹窗，也要观察打开后的状态。验收记录写“检查了哪些状态”，比笼统写“全部正常”更利于后续复查。

第一，具体改了什么，解决哪一步问题。第二，为什么采用这个处理方式。第三，做过什么检查，证据能够支持哪项结论。第四，什么还没测，以及怎样回退。可以简短，但状态要准确。

“代码已改”“本地预览可用”“线上已发布”是不同阶段。报告应明确当前到哪一步，不能因为工具说完成了，就把后续部署和使用效果一起算进去。多人同时修改时，也要以当前文件为基础保护已有工作。

背景：[使用者及问题]
目标：[完成后的具体行为]
范围：[页面、模块及已知文件]
限制：[保留规则、现有改动及权限边界]
验收：[正常、异常、窄屏及权限的预期]
请先核对现状，再做最小必要改动；完成后说明差异、实际验证结果、未验证项和回退方式。

下一次提出需求时，先补齐这五项。执行后选一条核心验收点亲自核对，把发现的问题补回任务与检查方法中。积累的是能够减少同类失误的规则和证据，而不只是更多说明文字。

长期项目指导与可复用流程的适用方式，可阅读 AGENTS.md 官方说明和定制能力概览。