Prompt 工程：Agent 总是跑偏，怎样把需求写成它能完成的任务？

假设你给 Agent 发了一句话：

帮我写个脚本，把下载目录整理一下，代码专业一点。

它可能交出一份像样的程序：按扩展名建文件夹，遍历目录，移动文件，还附了使用说明。

但你想要的也许是先看看整理计划；它默认直接移动。你想保留同名文件；它可能选择覆盖。你说的“下载目录”在另一台电脑上又是不同路径。程序写得再整齐，这次任务也已经偏了。

最让人烦的地方在于：它似乎听懂了每个词，却没有实现你脑子里的那个结果。

写好提示词，首先要把脑子里的任务搬到双方都能看到的地方。

一句话里，藏着多少个没说出口的决定？

“整理一下”至少藏着分类规则、目录范围、重名处理、执行时机和错误处理。“专业一点”则可能意味着可测试、无第三方依赖、日志清楚，也可能只是代码格式漂亮。

你拥有项目背景，模型未必拥有。Agent 能读取哪些文件、会话保留了什么上下文、有哪些可用工具，还要看运行环境。你没提供的事实，它有时会询问，有时会按某种常见做法补齐；常见做法刚好不符合你的偏好，就会出现“怎么又是这样”。

这不是让用户承担所有失败。模型会误解，会遗漏，工具也会报错。我们能做的是先减少任务接口里的歧义，让问题更容易定位。

Prompt 工程可以理解为：设计并迭代交给模型的任务说明，观察它是否产生所需结果。OpenAI 的提示词指南强调相关上下文、明确指令和输入输出示例；这些信息有助于描述你期望的行为。

先写“做完后是什么样”，再写“怎么做”

可以把原始需求改成一句更具体的话：

给现有 Node.js 项目增加一个文件整理命令，默认只显示移动计划；我检查后，用明确参数才真正移动文件。

这句话已经确定了交付物、项目背景和默认行为。接下来补齐会影响结果的决定：

“完成标准”会改变 Agent 的决策。如果成功只等于“输出代码”，它交出代码就能结束；如果成功还要求“默认预览不移动任何文件”，它就需要考虑这个行为怎样实现、怎样验证。

把这段提示词交给编码 Agent

下面是完整的教学示例，适用于已经能读取项目和修改代码的 Agent。它没有在本文中经过模型 A/B 实测，读者需要按自己的项目替换要求。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

为当前 Node.js 项目增加一个整理文件的命令行脚本。

目标：默认展示文件移动计划，只有调用者显式传入 --apply 才执行移动。

背景：先查阅 package.json 和相关现有代码，沿用项目的 Node.js 版本、
模块风格及测试方式。优先使用内置能力，不新增依赖。

输入与范围：
- 目录由命令行参数指定，不猜测用户的真实下载目录。
- 只处理该目录第一层的普通文件，不递归，不跟随符号链接。
- PDF 放入 documents，PNG/JPG 放入 images；扩展名忽略大小写。
- 未识别的文件跳过。

行为边界：
- 预览模式不得创建目录、移动或修改文件。
- 执行模式遇到目标同名文件时跳过，报告原因，不覆盖、不删除。
- 每个文件失败后记录错误并继续处理其他文件；有失败时以非零状态退出。
- 你可以修改项目文件并运行使用临时目录的本地测试；
  不要对真实下载目录运行 --apply。

验收：
- 预览前后测试目录保持不变。
- 执行后识别的文件分类正确，未识别文件和符号链接保持不变。
- 同名目标文件内容不变，原文件仍保留。
- 无权限等失败应报告，退出状态符合约定。

交付：实现脚本、补充必要的使用说明，运行相关检查。
最后简要列出修改文件、运行方式、实际验证结果和未完成项。

信息缺失时：能从项目文件确认的先查文件；不影响核心结果的采用
现有约定并注明。若存在会改变范围或数据处理方式的关键歧义，先问我。
若环境无法完成检查，如实说明，不把“未运行”写成“通过”。

这段写得较长，是因为文件移动涉及数据变更，值得明确处理规则。总结一段文字时，你通常不需要这么多关口。提示词的长度应跟着任务的不确定性走，而不是跟着某个万能模板走。

给示例，比再加十个形容词更有用

如果 Agent 仍然误解，可以加一组小例子：

1
2
3
4
5
6
7

目录中有 report.PDF、photo.jpg、notes.txt。
预期计划：
report.PDF → documents/report.PDF
photo.jpg → images/photo.jpg
notes.txt → 跳过，扩展名未识别

若 images/photo.jpg 已存在：跳过移动，保留原 photo.jpg 和目标文件。

例子把大小写、分类和冲突规则落到了具体输入上。它也能暴露提示词自身的矛盾：如果正文说“重名跳过”，示例却展示“自动改名”，模型接收到的就是两套规则。

示例应覆盖你真正关心的差异。顺利路径、信息缺失和冲突路径各给一个，比重复展示几个相似的成功案例更有价值。这也是官方指南对输入输出示例的建议可以在日常任务中落地的地方。

“你是世界顶级专家”，补不齐一条业务规则

角色描述能帮助确定视角。例如“面向第一次使用命令行的人写说明”，直接影响语言和解释程度。至于“拥有二十年经验、绝对专业、永远准确”，这些称号没有告诉 Agent 应该怎样处理重名文件。

另一种常见补救，是每失败一次就追加一条永久规则。最后提示词里同时出现“凡事先问我”和“不要打断，直接完成”，Agent 无论选择哪边，你都可能不满意。

不如写清决策边界：涉及真实文件移动先确认；读取项目和运行临时测试可以继续。再检查旧要求是否已经被新要求替代。

OpenAI 在一篇关于更新 Agent 指令的文章里提醒，过长、冲突或适用范围太宽的指导可能让 Agent 加载不相关的规则。这项提醒同样适用于我们不断打补丁的提示词：留下有用的约定，及时清理已经不适用的补充。

跑偏以后，别急着重写整段 Prompt

先看它最早偏在哪一步：

这张表只是排查顺序，不是凭现象就能确定原因。尤其对 Agent，最终回答之外的调用记录很有价值。OpenAI 的Agent 评估指南把模型调用、工具调用和交接轨迹作为定位工作流问题的依据。

如果环境根本没有写文件的工具，把“请务必完成”重复一百次也不会获得写入能力。提示词描述期望，工具和运行机制负责把动作变成事实。

让提示词也有一组回归案例

改过提示词之后，用相同的任务样本比较，而不是挑一个让你高兴的结果。

对整理脚本，样本可以包括：空目录、普通文件、未知扩展名、同名目标、符号链接和无权限文件。记录哪些要求通过、哪些失败，并区分执行失败与理解偏差。如果要评估模型输出，多次运行更能看出表现是否稳定；这里没有一个适合所有任务的固定次数。

先改一个明确问题，再观察相同案例的变化。否则你同时改模型、提示词、工具和测试数据，即使结果变好了，也不知道该保留哪个改动。官方Agent 评估指南也建议在定义好“好结果”后，使用可重复的数据集比较工作流变化。

日常任务不必搭一套复杂评估平台。保存几个真实失败案例、一个修改前后的提示词版本，再用清单核对结果，就已经比“这次感觉挺像样”更可靠。

下次发任务前，先补齐三句话：我要拿到什么；你可以依据什么、做到哪里；我怎样确认你做完了。

再加上那些会改变答案的具体规则。好的提示词会把你没说出口的需求变成可见的约定，也会让 AI 的错误更容易被发现和纠正。它能提高成功的机会，但不能承诺每次都成功；验证仍然是任务的一部分。

承接阅读：AI、模型与 Agent 的关系、Agent 的运行循环、Skill 工作手册、Hooks 与验证关口。