给编程智能体派任务的四项必备信息

让 coding agent 一次交出可用结果，关键可能在你按下发送之前。作者给出的办法很简单：把任务写清楚，补齐上下文、完成标准、修改边界和验证方式，让 agent 知道为什么改、改到什么程度、能动哪里，以及怎么证明改对了。

这套方法值得借鉴，因为它把模糊愿望变成了可检查的交付要求。但标题里的「一次成功」不能当作保证：原文没有提供成功率或对照实验，更适合把它看成减少返工的任务编写经验。

agent 看得到代码，猜不到你为什么要改

作者先提醒了一个容易被忽略的问题：agent 能读代码，却未必知道代码为什么写成现在这样。

同一个表单问题，可能来自业务规则、历史兼容要求，也可能是刚改过的交互逻辑。如果任务只剩一句「修一下表单」，agent 就需要自行补齐这些前提，选错方向的机会也随之增加。

作者建议补充三类信息：为什么需要这次修改、已经尝试过什么，以及哪个文件是问题中心。不需要写成长篇需求文档，一两句也能排除明显的错误方向。

接下来要写的是完成标准。「修好表单」没有明确终点；「表单可以保存、空字段会显示错误、现有测试通过」就可以逐项检查。

完成标准越明确，你越容易在交付时集中评审结果。

这里的关键不是把实现步骤全部规定好，而是先约定可观察的行为。至于 agent 用哪种实现，仍然可以留给它结合代码判断。

边界和验证，决定结果能不能直接评审

作者把修改边界单独列出来，是因为 agent 发现相邻问题后，可能顺手一起处理。一个局部修复，最后变成 API 调整、依赖升级和多个目录的改动，评审成本就会增加。

所以任务里应该提前写清：可以修改哪些文件或目录、能不能调整现有 API、能不能升级依赖。边界需要进入任务正文，不能等结果出来后再讨论。

原文用下面这条完整任务，把四个部分放到了一起：

"checkout.ts has a bug: double-clicking submit creates two orders. Done = double-click creates one order, all tests pass. Boundaries = only checkout.ts and its tests, no dependency upgrades. Verify = npm test checkout."

这条任务解决的是提交按钮双击后创建两个订单的问题。最该留意的是 Verify = npm test checkout：作者给出了明确的验证命令，而完成标准负责说明预期结果，包括双击只创建一个订单、所有测试通过。

不过，命令存在不等于证据充分。原文没有展示测试内容，也没说明现有测试是否覆盖双击场景。实际使用时，需要确认验证确实检查了目标行为，否则「测试通过」可能只证明旧功能没有触发已知失败。

我的判断

我认同这套四要素写法。它让需求、范围和验收方式同时进入 agent 的工作上下文，比不断追加「这里也改一下」「那个别动」更容易控制交付结果。对于文件范围清楚、预期行为明确的小型修复，尤其实用。

但作者给出的效率账需要保留判断：花 5 分钟写任务，可以省下 2 到 3 轮、每轮 15 分钟的修复。原文没有交代样本、项目规模、agent 配置或对照数据，这是作者的经验性估算，不能直接拿来预测团队收益。

和只写一句目标相比，四要素补上了容易遗漏的信息；和完整设计文档相比，它又足够轻量。但如果问题原因尚不明确，第一项任务可能应该是定位和收集证据，完成标准也应随之调整，不能硬写成「修复并通过测试」。

另外，原文说明这篇短文由希伯来语指南经 AI 辅助压缩，并由作者审核后发布。当前材料只展示了这套建议，没有展示完整实践记录，也不足以证明它能普遍实现首次成功。

能拿来做什么

• 给前端表单修复任务补齐四项信息：触发问题的操作、修复后的页面行为、允许修改的文件，以及项目实际可用的测试命令。
• 把「修好」「优化一下」改成可观察的完成标准，例如空字段显示错误、保存成功、双击提交只产生一次目标结果。
• 在日常 AI 编程任务中提前声明 API 和依赖的修改权限，减少交付时才发现范围扩大的情况。
• 评审时同时检查代码与验证结果，并确认测试覆盖了这次要修的行为；如果现有测试没有覆盖，就在任务中明确要求补上相关测试。