本文最后更新于 2026-05-19，文章内容可能已经过时。

给代码Agent写Prompt，你一直在用错误的沟通模型

你有没有遇到过这种翻车现场：

让Agent帮你改一个小Bug，结果它把整个文件夹重写了一遍，还信心满满地回复"任务已完成，所有问题已修复"——然后你打开项目，发现它连文件结构都动了，测试全红，原来好好的功能也挂了。

或者更经典的：你说"帮我优化一下这个函数的性能"，Agent开始跑，跑了两分钟，调用了十几次工具，最后给你返回一个几乎一模一样的函数，说"已优化，性能提升显著"。

这种体验让人抓狂。更让人困惑的是：同一段描述需求的话，发给ChatGPT能得到漂亮答案，扔给Cursor、Claude Code、Devin却开始乱跑。

问题出在哪？模型变笨了？工具有Bug？

都不是。是你在用错误的沟通模型跟Agent说话。

---

第一章：你的Prompt没变，为什么Agent越用越拉垮？

普通对话式AI（比如直接问ChatGPT一个问题）和代码Agent，本质上是两种完全不同的系统。

前者是一次性问答：你问，它答，你不满意，你再问。整个过程你全程在场，随时可以纠偏。

后者是自主执行：你给一个任务，它开始行动，调用工具、读文件、写代码、执行命令，可能跑几十步才回来告诉你结果。在这几十步里，你不在场，它也不知道你想看到什么中间状态。

这就是问题的根源。

你对着导航软件说"帮我开车去北京"，导航不会动。你得输入目的地，选路线，它才能一步步给你指引。Agent也一样——你的Prompt是它唯一的地图，但大多数人给Agent的Prompt，根本不是地图，只是一个模糊的愿望。

---

第二章：fchollet的「盲松鼠撞迷宫」，到底说了什么？

François Chollet（Keras创始人，ARC-AGI挑战赛发起人）在讨论Agent行为模式时，用过一个非常精准的比喻：

"Current agents are essentially blind squirrels in a maze — they can only sense what's immediately in front of them, and they have no reliable way to know when they've hit a wall."

>

——François Chollet，关于LLM Agent局限性的讨论

"盲松鼠撞迷宫"——这个比喻值得慢慢拆解，因为它精准描述了代码Agent的3个结构性弱点：

弱点①：上下文窗口就是它的视野边界

Agent看不到迷宫全貌。它能看到的，只有当前上下文窗口里的内容——你的指令、它已经执行的步骤、工具返回的结果。

一个大型项目可能有几百个文件、几万行代码。Agent每次只能"看"其中一小块。它不知道自己没看到的部分里有什么，也不知道自己的修改会不会影响到那些它没看到的地方。

弱点②：工具调用结果是它唯一的"触觉"

盲松鼠怎么感知墙壁？靠碰撞。Agent怎么感知环境？靠工具调用的返回值。

它读一个文件，文件内容是它的感知。它执行一条命令，命令输出是它的感知。除此之外，它对环境一无所知。

如果工具返回了成功，它就认为成功了。如果工具返回了错误，它会尝试修复。但如果工具返回了一个"假成功"（比如测试没跑、lint没检查），它就真的以为自己做对了。

弱点③：没有你的显式确认，它不知道走错了

这是最致命的一点。

你发现Agent走错了，你可以叫停。但Agent自己不知道。它没有"这个方向不对"的直觉，只有"工具调用成功/失败"的信号。

如果你没有在Prompt里告诉它"遇到什么情况要停下来问我"，它就会一直走，走到任务结束，然后自信满满地说"完成了"。

---

第三章：3个立竿见影的Prompt改写思路

理解了盲松鼠的处境，改写Prompt的方向就清晰了：你不是在给助手下达任务，你是在给迷宫里的盲人设计一条有护栏的路。

思路1：把"目标"拆成"检查点"

问题所在： 你给了终点，没给路标。Agent会自己决定怎么走，而它的决定往往不是你想要的。 改写前（普通版）： 
帮我重构 src/utils/parser.js 这个模块，让代码更清晰。
改写后（Agent优化版）： 
任务分两个阶段执行，不要跳步：


阶段1（只读，不写）：


  • 读取 src/utils/parser.js 的完整内容
    • 

  • 告诉我：这个文件有多少行？有哪些导出函数？你认为哪些地方可以改进？
    • 

  • 等我确认后，再进入阶段2
    • 



阶段2（根据我的确认再执行）：


  • 按我指定的方向修改，每次只改一个函数
    • 

  • 每改完一个函数，告诉我改了什么，再继续下一个
    •
效果差异： 改写前，Agent可能直接重写整个文件。改写后，它必须先"汇报侦察结果"，你有机会在它动手前纠偏。

---

思路2：给Agent装"撞墙报警器"

问题所在： Agent撞墙了它不知道，你也不知道。等你发现的时候，它已经走了很远。 改写前（普通版）： 
帮我给这个项目加上 ESLint 配置，要符合我们团队的规范。
改写后（Agent优化版）： 
帮我给这个项目配置 ESLint。


在执行过程中，如果遇到以下任何情况，立刻停下来告诉我，不要自己决定：


  • 发现已有 .eslintrc 或类似配置文件
    • 

  • 不确定应该用哪个 extends 规则集
    • 

  • 需要修改 package.json 以外的配置文件
    • 

  • 安装依赖时发现版本冲突
    • 



完成后，用以下格式汇报：


✅ 已完成：[具体做了什么]


⚠️ 需要你确认：[如果有的话]


❌ 没有处理：[如果有跳过的事项，说明原因]
效果差异： 改写前，Agent可能发现已有配置文件，然后直接覆盖。改写后，它会停下来问你。那个汇报格式也很关键——它强迫Agent主动暴露自己没做的事。

---

思路3：用"环境约束"替代"意图描述"

问题所在： "理解我的风格""保持代码一致性"这类意图描述，对Agent来说几乎没有意义。它无法量化"风格"，只能猜测。 改写前（普通版）： 
帮我给旧项目加单元测试，要符合项目的测试风格。
改写后（Agent优化版）： 
帮我给 src/api/userService.js 加单元测试。


约束条件（严格遵守）：


  • 测试文件只能创建在 src/api/__tests__/ 目录下
    • 

  • 测试框架用 Jest，不要引入其他测试库
    • 

  • 参考已有测试文件 src/api/__tests__/authService.test.js 的写法风格
    • 

  • 每个测试文件不超过 150 行
    • 

  • 禁止修改被测试的源文件
    • 

  • 禁止新建除测试文件以外的任何文件
    • 



本次只处理 userService.js，其他文件下次再说。
效果差异： "符合项目的测试风格"是意图，Agent会自己猜。"参考 authService.test.js 的写法"是约束，Agent有明确的参照物。"禁止修改源文件"是护栏，防止它好心办坏事。

---

💡 想立刻验证这3个思路的效果？

>

文中所有Prompt示例都在 [api.884819.xyz](https://api.884819.xyz) 上跑通过——平台接入了 Claude Opus 4.6、GPT-5.2、Deepseek R1 等主流模型，支持长上下文，特别适合测试Agent类Prompt的差异。

>

新用户注册即送体验token，国产模型完全免费，不需要邮箱验证，直接上手对比改写前后的效果。

---

第四章：一张表看清两种Prompt的系统性差异

光靠例子可能还是容易忘。下面这张表，从4个维度帮你建立可复用的心智模型：

| 维度 | 普通ChatGPT Prompt | 代码Agent Prompt | | 信息颗粒度 | 描述最终目标即可，模型会补全细节 | 必须拆解成可验证的子步骤，每步有明确的完成标准 | | 反馈机制 | 你实时看到输出，随时追问纠偏 | 必须在Prompt里预设汇报格式和停止条件，否则Agent不会主动汇报 | | 权限边界 | 不需要，因为模型只输出文字，不执行操作 | 必须明确"能动哪些文件""禁止什么操作"，否则Agent会自行决定 | | 任务拆分 | 可以一次性描述复杂任务，模型会整体理解 | 必须分阶段，每个阶段结束要有确认点，防止错误累积 |

这张表的本质是：对话式AI是你的协作者，你们可以来回沟通；代码Agent是你部署出去的执行者，出发前你得把规则说清楚。

---

第五章：用一个真实场景走一遍完整链路

场景：让Agent帮一个旧项目加单元测试

这是最典型的Agent任务之一，也是最容易翻车的场景之一。

小白版Prompt（常见写法）

帮我给这个项目加单元测试，覆盖主要的业务逻辑。
实际会发生什么：

Agent开始扫描项目，发现有50多个文件，开始逐个分析，然后开始写测试文件——它可能会选错测试框架（项目用Jest，它装了Vitest），可能会修改源文件来"让代码更好测试"，可能会在根目录创建一堆你不想要的文件。最后给你一个"已完成"，但测试跑不起来，因为它没有运行过测试来验证。

套用3个思路改写后的版本

任务：给 src/services/orderService.js 加单元测试


【阶段1 - 侦察（只读，不写任何文件）】


1. 读取 src/services/orderService.js，列出所有导出的函数名和大致功能


2. 检查项目的 package.json，告诉我当前用的是什么测试框架


3. 查找现有测试文件（如果有），告诉我它们在哪个目录


4. 完成后等我确认，再进入阶段2



【阶段2 - 执行（等我说"开始"后才执行）】


约束：


  • 测试文件只能创建在 src/services/__tests__/ 目录（如果没有就创建这个目录）
    • 

  • 只用阶段1发现的现有测试框架，不安装新依赖
    • 

  • 禁止修改 src/services/orderService.js 本身
    • 

  • 每写完一个函数的测试，运行一次测试确认通过，再继续下一个
    • 

  • 如果某个测试跑不过，停下来告诉我原因，不要自己改源文件
    • 



【遇到以下情况立刻停下来问我】


  • 发现函数有复杂的外部依赖不知道怎么mock
    • 

  • 测试文件超过100行
    • 

  • 任何需要修改源文件才能测试的情况
    • 



【完成后的汇报格式】


✅ 已完成测试：[函数列表]


⚠️ 需要你决策：[如果有]


❌ 跳过未处理：[原因]


测试覆盖率：[运行测试后的实际数字]

执行差异

改写前的版本，Agent会自主决定测试哪些文件、用什么框架、把文件放在哪——每一个决策点都可能偏离你的期望，而你在它跑完之前完全不知道。

改写后的版本，Agent必须先"汇报侦察结果"，你确认框架、目录、现有测试风格都没问题之后，再开始写。每写完一个函数就跑一次测试，错误会立刻暴露，而不是积累到最后。

这就是"有护栏的路"和"开放式迷宫"的区别。

---

写在最后

回到fchollet的那个比喻：Agent是盲松鼠，在迷宫里靠触觉摸索。

但我想再往前推一步：Agent不是你的下属，是你部署在迷宫里的传感器。你的Prompt，是它唯一的地图。

地图画得好，它能精准到达你想要的地方。地图只有一个终点、没有路标、没有禁区标注，它就只能靠运气。

这3个思路——检查点拆分、撞墙报警、环境约束——本质上都是在做同一件事：把你脑子里的隐性知识，转化成Agent能感知的显性规则。

你不需要让Agent更聪明。你需要的是，给它一张更好的地图。

---

本文所有Prompt示例均可在 [api.884819.xyz](https://api.884819.xyz) 直接复制运行，新用户注册即送体验token，收藏备用。

---

下篇预告

说完了"怎么写Prompt"，下一个问题更棘手：

Agent执行到一半，你怎么知道它走对了？

大多数人在Agent跑任务时只会盯着进度条，但高手早就在Prompt里埋好了"自动体检"机制——不是等Agent跑完再看结果，而是在每一个关键节点都有信号告诉你"这步对了/错了"。

我们下篇会拆解「Agent中间状态监控」的完整方法论，以及3种最实用的"自动体检"Prompt模板。

下周见。

---

本文由8848AI原创，转载请注明出处。关注8848AI，带你从零开始学AI。

#AI教程 #代码Agent #Prompt技巧 #Claude #ChatGPT #8848AI #AI编程 #Agent开发