你把一个 bug、一个需求，或者一篇待发布的文章交给 Agent。它很快给出一大段看起来专业的回复：分析做了，方案写了，文件也可能改了。

可你回头一看，真正想要的东西并没有落地。

测试没有跑；不该改的接口被动了；需要确认的发布动作被它顺手做了；它说“已经处理”，却没有任何能复查的证据。

这类失败经常被归咎于“Prompt 不够好”。但我越来越觉得，问题通常不是少了一句“你是一位资深工程师”，而是任务从一开始就没有被定义成一个可执行的闭环。

Prompt Engineering 没有过时。它只是从寻找一句万能咒语，变成了为 Agent 写一份简洁、可验收的任务契约。

一、先区分：请求、偏好和任务不是一回事

下面这句话很常见：

帮我修一下登录页的 bug，认真一点，别出错。

它表达了一个请求，也表达了焦虑，但没有定义任务。

Agent 仍然不知道：哪个 bug、是否要先复现、公共接口能不能改、什么叫“修好”、它能不能改数据库或发版。

一个能自主推进的任务，至少应回答下面七个问题：

它们合在一起，才是一份任务契约。

任务契约 = 目标 + 相关上下文 + 约束 + 授权边界 + 验收标准 + 证据 + 交付格式

重点不是把 Prompt 写得更长，而是让每一项都能改变 Agent 的下一步决策。

二、一个好任务，不是一直催它“认真”

“认真一点”“一步一步想”“这件事很重要”并非完全无效，但它们解决不了结构性缺口。

例如，下面两种写法的区别不在语气，而在反馈闭环。

低信息量写法

帮我处理博客的发文流程。一定要小心，不要出错。

这会把大量关键判断留给 Agent 猜：它不知道写什么主题、能否直接公开、该在哪里修改、如何验证、是否能碰服务器配置。

可执行写法

# Goal

把“如何设计 Agent 的任务契约”写成一篇中文技术文章草稿。

# Relevant context

- 项目是 Hexo 博客，文章位于 `source/_posts/`。
- 读者是正在使用 Codex、Claude Code 等编程 Agent 的开发者。
- 文风需要先讲真实问题，再给出工程化做法；不要写成概念罗列。

# Constraints

- 不写入密钥、私有地址、评论数据或部署环境变量。
- 不虚构测试结果、项目数据或引用来源。
- 保持文章可独立阅读，并提供可复制的示例。

# Authority and approval boundaries

- 可自主：阅读公开源码、创建文章草稿、运行本地构建检查。
- 必须确认：提交 Git、发布线上、修改服务配置、发送外部消息。

# Success criteria

- 有明确标题、摘要、至少一个完整示例和行动清单。
- 构建通过；若只是草稿，不公开发布。

# Required evidence

- 列出新增文件。
- 给出构建命令与结果。
- 说明没有执行的外部写入动作。

# Output

按“核心结论、文件改动、验证、风险/下一步”汇报。

第二段不是更“会说话”。它是把原本藏在你脑中的验收方式、权限边界和风险判断，提前变成了 Agent 能遵循的工作条件。

三、最值得补齐的三个字段

七个字段不一定每次都要写成一张完整表格。简单任务可以很短，但下面三项最容易被省略，也最值得优先补齐。

1. 把目标写成结果，不要只写动作

“修改登录逻辑”是动作；“登录失败时能显示明确错误，且不改变现有 OAuth 回调接口”才是结果。

一个实用的检查方法是：如果 Agent 已经完成了你写下的动作，你仍会问‘所以现在能用了吗？’，那目标就还不够完整。

不够好：给订单页加筛选。

更好：用户可以按订单状态和日期筛选；刷新页面后条件不丢失；
现有导出接口和默认排序保持不变。

目标里不必先规定实现方式。先定义用户或系统最终获得的能力，才能保留 Agent 在现场选择合理方案的空间。

2. 先写授权边界，再让它调用工具

Agent 最危险的时刻，往往不是不会做，而是太顺利地做了不该做的事。

因此不要笼统地说“不要乱动”。应该把动作分成几类：

这不是限制 Agent，而是让它不必在每个安全动作前停住，也不会把“帮我处理一下”误读成“直接上线”。

3. 用证据定义完成，而不是用一句“已完成”

对代码任务，证据可以是最小复现、测试输出和 diff；对调研任务，证据可以是来源与交叉核对；对发文任务，证据可以是构建成功、生成页面和公开链接。

例如：

完成条件：原始失败 case 通过，相关单元测试通过，公共 API 不变。
证据：复现命令、测试命令、测试结果摘要、修改文件列表。

这样做还有一个额外收益：当 Agent 卡住时，它会更容易知道下一步该补什么证据，而不是继续生成看似合理的解释。

四、把大任务拆成可验证的小闭环

一个常见误区是，既然 Agent 能连续工作，就把“调研、设计、实现、测试、部署”一次性塞进同一条指令。

这在目标明确、风险低的小任务中也许可行；在真实项目里，更稳妥的方式是让每一阶段都有可检查的中间产物：

Inspect
→ Plan
→ Implement
→ Test
→ Review
→ Ask for approval / Deploy

以“修复一个线上异常”为例：

1. Inspect：先找到日志、错误条件和相关代码，不急着改。
2. Plan：写出根因假设、最小修改范围和验证方法。
3. Implement：只实现已确认的改动。
4. Test：让原始失败条件变成测试或可复现命令。
5. Review：检查 diff 是否越过了接口、权限或数据边界。
6. Approval / Deploy：到了共享环境或生产写入，停下来确认。

每一环都不要求 Agent 永远正确。它要求系统在错误还小、还便宜时给出反馈。

五、可以直接使用的任务模板

下面这份模板适合编码、写作、调研和项目维护任务。不要机械填满；只保留会改变本次决策的字段。

# Goal

[描述最终结果，而不是只描述一个动作。]

# Relevant context

- [关键目录、已有决策、读者或用户背景]
- [可查看的文件、数据或历史记录]

# Constraints

- [不可破坏的接口、兼容性、安全和范围限制]

# Authority and approval boundaries

- 可自主：[只读检查、本地修改、测试等]
- 必须先确认：[外部写入、删除、付费、生产变更等]

# Success criteria

- [可测试或可检查的完成条件]
- [无回归或质量要求]

# Required evidence

- [测试、引用、diff、计算过程或链接]

# Output

- [最终报告应包含什么]

如果你只想先改一个习惯，就从下面这句开始：

在把任务交给 Agent 前，先写清楚“怎样证明它做完了”。

它会倒逼你澄清目标、约束和验证方式，也会显著减少“看着像完成了”的返工。

六、什么时候不需要完整任务契约

不是每次让 Agent 改一个变量名，都值得写七段 Markdown。

以下情况可以简化：

• 结果显而易见且没有外部副作用，例如解释一段代码；
• 任务只读、可逆、范围极小；
• 项目已经把稳定规则写进了 AGENTS.md、脚本或 CI；
• 本次只是探索，目标就是收集候选方案，而非直接执行。

但一旦涉及长任务、多人协作、生产环境、私有数据、不可逆操作，或者你过去已经为同类任务返工过，就应该恢复完整结构。

七、开始实践：把下一条模糊请求改写一次

在下一次使用 Agent 前，挑一条你本来会这样说的话：

帮我把这个功能完善一下。

不要急着增加形容词。只补四件事：

1. 用户最终能得到什么；
2. 什么绝对不能被破坏；
3. Agent 可以自主做到哪一步；
4. 你需要看到什么证据才会认可完成。

如果这四件事都写清楚，绝大多数工程任务已经从“猜测式协作”进入了“可验证协作”。

下一篇会继续解决另一个很常见的问题：任务明明写清楚了，为什么 Agent 聊得越久，反而越容易忽略关键事实？

AI 实现摘要

• 要解决的问题：把模糊的自然语言请求转化为 Agent 可自主推进、可验证且有权限边界的任务契约。
• 适用版本与前置条件：适用于具备文件、代码、浏览器或其他工具调用能力的 AI Agent；不依赖特定模型或客户端。
• 输入、输出与验收标准：输入是一个待处理任务；输出至少包含目标、相关上下文、约束、授权边界、成功标准、证据与交付格式。验收时应能依据预先定义的证据判断是否完成。
• 文件改动清单：读者可在项目根目录新增或更新 AGENTS.md、任务说明或 issue 模板；具体路径按项目约定调整。
• 完整命令：无通用命令。若任务包含代码变更，使用项目已有的 build、test、lint 或验证脚本。
• 测试步骤与预期结果：选取一条真实模糊请求，按模板补齐四项关键字段；Agent 的执行范围、停止点与验收证据应变得明确。
• 常见错误、回滚方法与安全边界：不要把任务契约误当作权限系统。删除、发布、付费、生产写入和敏感数据操作仍应由工具权限、环境隔离或人工审批共同约束。