要点速览
写好 AI 代理任务说明的重点，是把代理自己看不到、猜不到的信息明确交代：要做什么、在哪里做、做到什么算完成，以及哪些事不能碰。给它一个能判定通过或失败的检查，并要求它附上证据，比反复叮咛「要小心」有效得多。
AI 代理任务说明，就是你交给代理的那段文字：要它做什么、在哪里做、做到什么程度算完成。AI 代理（AI Agent）是让大型语言模型自己决定下一步、使用工具并依结果调整的系统，如果你还不熟，请先看 AI 代理是什么。
代理做不好事，多半不是它不够聪明，而是它缺少信息。这篇整理出一套不依赖任何特定工具的写法。
内核观念：把它看不到的信息交代清楚
Claude Code 的官方文档有一句很实用的提醒：只写「代理无法从项目里读到的信息」，或是它每次都得花时间重新摸索的信息。因为代理一开始工作就会先读你的文件，它很擅长自己找到文件结构、惯例与测试方式。
它找不到的是从来没有写在文件里的东西：
- 你们在会议上做的决定
- 只存在某个人脑中的作业流程
- 需要用到的环境设置
写之前可以先问两个问题：（1）它读文件就能找到吗？（2）它真的会去找吗？两个都是「是」，就不用写。
另一个检验方法来自 Anthropic 的提示词指南：把你的说明拿给一位对这件事了解很少的同事看，请他照着做；如果他会困惑，代理也会。Anthropic 把模型比喻为「聪明但刚到职、不熟悉你们规矩与流程的新同事」。
任务说明的六个组成
| 组成 | 要回答的问题 | 没写的后果 |
|---|---|---|
| 目标 | 要做什么？做完会看到什么？ | 代理做出和你想的不一样的东西 |
| 背景与原因 | 为什么要这样做？有什么限制？ | 代理无法判断取舍 |
| 范围 | 哪些文件或文件夹可以动？哪些不能碰？ | 动到不该动的东西 |
| 做法偏好 | 两个合理做法之间，你偏好哪一个？ | 代理自己选，不一定是你要的 |
| 验收标准 | 怎样才算完成？用什么检查？ | 代理在「看起来完成」时就停下来 |
| 回报方式 | 完成后要告诉你什么？ | 你不知道它到底做了什么 |
验收标准与检查
Claude Code 的官方文档说得很直接：代理在工作「看起来完成」时就会停下来；如果它没有任何能判定是否真的完成的东西，你就得自己当测试。给它一个能回报通过或失败的检查，它就能自己形成循环：做修改、运行检查、失败就读输出修正，再检查一次。
检查可以是很多形式，只要代理读得懂结果：一份测试、一个建置指令的结束状态、一个格式检查工具，或是把输出和预期范例比对的小程序。
无论用哪种，都要求它附上证据：它运行过的指令与输出。这也是你在没有盯着它做事时，唯一可靠的依据。
说明原因，而不只是下禁令
Anthropic 的提示词指南举了一个例子：与其写「绝不要使用删节号」，不如写「这段回应会被语音合成引擎朗读，所以不要使用删节号，因为引擎不知道怎么念」。有了原因，模型就能推广到你没有逐一列出的情况。
需要固定格式时，给范例
Anthropic 的指南指出，范例是引导输出格式、语气与结构最可靠的方法之一，并建议放 3 到 5 个范例；范例要贴近真实用途、涵盖不同情况，并用清楚的标记和指示分开。
一个模板
下面是通用的格式，可以直接拷贝后修改。（范例内容是本站自己设计的示范，不是实测结果。）
【目标】
把「下载」文件夹里的文件，依扩展名整理到子文件夹（图片、文档、压缩档、其他）。
【背景】
这个文件夹很久没整理，我之后要用文件名找数据，所以文件名不要改。
【范围】
只动「下载」文件夹第一层的文件。不要进入子文件夹，不要删除任何文件。
【验收标准】
1. 第一层不再有散落的文件。
2. 文件总数整理前后相同。
3. 没有文件名被改变。
【回报】
先列出你打算移动的清单给我确认，确认后再运行。完成后贴出整理前后的文件数量与你用的指令。对照看看「帮我整理下载文件夹」这种写法：没有范围、没有验收、没有确认步骤，代理只能自己猜。
交给代理自己跑之前，先问五个问题
Claude Code 的官方文档，列出让代理在无人看管下运行之前的五个问题。以下是整理后的版本：
- 它知道「完成」长什么样子吗？ 一个明确的目标条件、一份规格，或一个要让它转为通过的失败测试。
- 它能检查自己的成果吗？ 测试、检查工具，或某种审查步骤。
- 它被允许碰什么？ 权限规则、隔离环境、只能推送的那一条分支。
- 什么会让它停下来？ 次数上限、花费上限。
- 结果送去哪里、由谁核准？ 最后由人核准合并、部署，或任何收不回来的动作。
第 3 题和第 5 题，在 让 AI 代理安全操作电脑 有更完整的说明。
常见错误
| 常见错误 | 为什么有问题 | 改法 |
|---|---|---|
| 只说「整理好」「改善一下」 | 没有验收标准，代理不知道何时该停 | 写出可检查的完成条件 |
| 把整个项目或大量文档全部贴进去 | 上下文太多，准确度可能下降（见 大语言模型入门） | 只给和任务有关的部分，并指出文件位置 |
| 只列禁止事项，不说原因 | 模型难以推广到未列出的情况 | 说明原因与背后的目标 |
| 没有说明哪些事要先问你 | 难以复原的动作可能直接被运行 | 明确列出需要先确认的动作 |
| 只信任「已完成」 | 没有证据，错误会一直留在那里 | 要求附上指令与输出 |
不确定时，先要计划
如果任务比较大，先请代理列出它打算怎么做、会动到哪些文件，等你确认后再运行。这个习惯能让你在错误变大之前拦下来。需要把成果还原时，给 AI 用户的 Git 入门 说明的版本控制会是你的后盾。
延伸阅读
常见问题
给 AI 代理的任务说明越长越好吗？
不是。重点是把代理「找不到、猜不到」的信息写进去，而不是把所有东西都塞进去。Claude Code 的官方文档建议先问自己两件事：它读文件就能找到吗？它会真的去找吗？两个答案都是肯定的，就不必写。
任务说明要不要写角色，例如「你是资深工程师」？
可以写。Anthropic 的提示词指南指出，替模型设置一个角色，能让它的行为与语气更贴近你的用途，即使只有一句话也有差别。不过角色不能取代目标、范围与验收标准，这三项要先写清楚。
为什么要告诉代理「为什么」？
Anthropic 的文档说明，交代指示背后的原因，能让模型更了解你的目标并产生更贴切的结果，因为它可以从原因推广到没明讲的情况。
怎么知道我的说明够清楚？
把说明拿给一个对这件事了解很少的同事看，请他照着做。如果他会困惑，代理也很可能会。
代理说「已经完成」就可以相信吗？
不要只看这句话。要求它附上实际运行过的指令与输出，或给它一个能判定通过或失败的检查。单单一句「都通过了」，说明不了什么。
可以让代理整晚自己跑吗？
可以，但前提是它知道完成的标准、能检查自己的成果、只能碰该碰的东西、有次数或花费上限，最后由人核准结果。细节见下面的检查清单。
留言
用 GitHub 账号登录就能留言，留言会公开显示在 GitHub Discussions。留言前请先看社区规则。