给 Cursor Agent 写任务描述，别再用写 Prompt 的思路了

"它把我没让动的数据库层全重写了……"

这句话我在某个开发者群里看到的时候，忍不住笑出了声——不是因为幸灾乐祸，是因为我自己也经历过一模一样的事。

那次我让 Cursor Agent 帮我重构一个 API 模块，我的 Prompt 是这样写的：

"帮我重构 /src/api 下的用户认证模块，让代码更清晰一些。"

结果呢？Agent 花了三分钟，改了 17 个文件，把数据库连接层、中间件配置、甚至测试文件全动了一遍。我盯着那个 diff，感觉像是叫了个装修工来换个灯泡，回来发现他把承重墙也拆了。

这不是 Cursor 的 bug，这是我的问题。

---

为什么 Agent 任务描述需要单独对待？

在搞清楚怎么写之前，先得搞清楚一件事：你在和谁说话。

普通 Chat 模式下，你和 AI 是"对话"关系——你说一句，它回一句，你不满意可以立刻纠偏。整个过程是实时、交互、可中断的。

但 Cursor SDK Agent 不是这样工作的。它拿到你的任务描述之后，会自主拆解成子任务、调用工具（读文件、写文件、运行命令）、多步连续执行——中间不等你确认，也不会主动暂停问你"这样做对吗"。

这就像是你在给一个承包商打电话说"帮我把厨房翻新一下"，然后就挂了电话出门旅游。等你回来，发现他把你的整个房子按他的理解"翻新"了一遍。

问题不在承包商，在于你没说清楚。

对话型 Prompt 有三个致命缺陷，在 Agent 场景下会被成倍放大：

  • 意图模糊 → 跑偏：Chat 里模糊没关系，它会问你；Agent 里模糊，它会自己猜，然后猜错了你还不知道。
  • 边界不清 → 越权：没说"不能动哪里"，Agent 会按最大化理解你的需求去执行。
  • 无验收标准 → 死循环：Agent 不知道什么叫"完成了"，要么过度执行，要么反复确认拖死你。

明白了这个，再来看四种写法的实测差异就清楚多了。

---

4 种写法实测对比

我用同一个任务场景测试了四种写法："帮我重构 /src/api/auth.js 这个用户认证模块"，模型调用走的是 [api.884819.xyz](https://api.884819.xyz)（兼容 OpenAI 格式，支持多模型切换，方便横向对比不同模型的表现——如果你也想自己跑实验，注册即可用）。

---

写法① 普通聊天式 Prompt（最常见踩坑）

帮我重构 /src/api/auth.js 这个用户认证模块，让代码更清晰一些。
实际输出： Agent 改了 auth.js 本体，同时顺手修改了引用它的 middleware.js、routes/user.js，还新建了一个 auth.test.js。共改动 4 个文件，新增 1 个文件。 出轨指数： ⭐⭐⭐⭐（4/5，高危） 一句话点评： "更清晰一些"这四个字，给了 Agent 无限的发挥空间。

---

写法② 加了角色和背景，但没有约束（进阶踩坑）

你是一个资深 Node.js 工程师，熟悉 Express 框架和 JWT 认证。

我们的项目是一个中型 SaaS 应用，代码质量要求较高。


请帮我重构 /src/api/auth.js 这个用户认证模块，让它更易维护、更符合最佳实践。
实际输出： 这次 Agent 更"自信"了。它不仅重构了 auth.js，还主动把 JWT 工具函数提取到了 /src/utils/jwt.js（这个文件之前不存在），并更新了所有引用路径。改动 6 个文件，新增 2 个文件。 出轨指数： ⭐⭐⭐⭐⭐（5/5，最危险） 一句话点评： 给了角色设定之后，Agent 更有"主人翁精神"了——但这种主人翁精神在没有边界约束的情况下，是灾难性的。
⚠️ 反面案例记录：这个写法是我见过最多人觉得"写得很好"但翻车最惨的。加了专业角色 + 项目背景，感觉很完整，实际上给 Agent 的自主权更大了，反而比写法①更容易越权。

---

写法③ 结构化任务描述（目标+范围+禁止项+验收标准）

## 任务目标

重构 /src/api/auth.js 中的用户认证逻辑，提升代码可读性。



操作范围


  • 仅修改 /src/api/auth.js 这一个文件
    • 

  • 不得新建文件
    • 

  • 不得修改任何其他文件
    • 



禁止事项


  • 不要修改函数签名和对外接口
    • 

  • 不要引入新的依赖包
    • 

  • 不要修改注释语言（保持中文注释）
    • 



验收标准


  • 原有的所有函数名和参数不变
    • 

  • 代码行数减少或持平
    • 

  • 每个函数有明确的单一职责
    •
实际输出： Agent 只改了 auth.js 一个文件，函数签名全部保留，代码从 187 行缩减到 142 行。中途没有发起一次确认请求。 出轨指数： ⭐⭐（2/5，基本可控） 一句话点评： 结构化之后效果立竿见影，这个写法在实测中比写法①减少了约 70% 的中途确认打断（实测估算，样本为同类任务 10 次执行）。

---

写法④ 分阶段委托式描述（最稳定，推荐）

## 背景

/src/api/auth.js 是用户认证核心模块，目前代码耦合度较高，


单个函数超过 50 行，难以维护。



本次任务（仅执行阶段一）

阶段一：分析并报告

  • 读取 /src/api/auth.js
    • 

  • 列出所有函数名、行数、主要职责
    • 

  • 指出耦合度最高的 2-3 处
    • 

  • 输出分析报告，等待我确认后再进行修改
    • 



明确边界


  • 本次任务不做任何修改，只做分析
    • 

  • 不读取其他文件
    • 

  • 报告用中文输出
    • 



完成标志


输出分析报告后，询问我："是否确认进入阶段二（实际重构）？"
实际输出： Agent 输出了一份清晰的分析报告，列出了 8 个函数的职责分布，标注了 3 处耦合问题，然后停下来等待确认。没有做任何修改。 出轨指数： ⭐（1/5，极度稳定） 一句话点评： 把大任务切成"分析→确认→执行"的阶段，每个阶段都有明确的完成标志，Agent 不再需要"猜"你想要什么。

---

四种写法综合评分表

| 写法 | 出轨频率 | 完成质量 | 需要人工干预次数 | 综合推荐度 | | ①聊天式 | 高 | 不可控 | 多 | ❌ 不推荐 | | ②角色+背景 | 极高 | 不可控 | 极多 | ❌❌ 最危险 | | ③结构化 | 低 | 较好 | 少 | ✅ 可用 | | ④分阶段委托 | 极低 | 高 | 按需 | ✅✅ 首选 |

---

最优写法的模板拆解

把写法④的逻辑提炼出来，是一个五段式结构，每段都有不可替代的作用：

五段式任务描述模板（填空版）

## 背景

[用1-3句话说明：这个文件/模块是做什么的，当前存在什么问题]



本次任务目标


[明确说明：这次只做什么，不做什么]


[如果是大任务，标注"仅执行阶段X"]



操作范围


  • 可以修改：[列出具体文件路径]
    • 

  • 不得修改：[列出禁止触碰的文件/目录]
    • 

  • 不得新建文件（除非明确允许）
    • 



执行约束


  • [约束1：如"不引入新依赖"]
    • 

  • [约束2：如"保持函数签名不变"]
    • 

  • [约束3：如"注释保持中文"]
    • 



完成标志


[描述任务完成的可验证状态]


[如需分阶段，写明"完成后询问是否进入下一阶段"，而不是自动继续]
每个模块为什么不能省？
  • 省掉"背景"：Agent 缺乏上下文，容易按最宽泛的理解执行。
  • 省掉"范围"：这是最常见的翻车点。没有边界，Agent 会按需要扩展范围。
  • 省掉"执行约束"：细节层面的越权——改了你不想改的函数签名、引入了你不想要的库。
  • 省掉"完成标志"：Agent 不知道何时停，要么过度执行，要么在不该停的地方停下来问你。
💡 核心心智模型：写 Agent 任务描述，就像写一份工程需求文档。你需要告诉它"做什么"，更需要告诉它"不做什么"和"怎么算做完了"。

---

两个场景的完整示例

场景 A：代码重构任务（技术向）

普通写法： 
帮我把 /src/services/payment.js 重构一下，现在逻辑太乱了。
最优写法： 
## 背景

/src/services/payment.js 是支付处理核心服务，目前约 320 行，


包含订单创建、支付回调、退款三个主要流程，三者代码混在一起，


维护时经常误改。



本次任务（阶段一：只做分析）


读取 /src/services/payment.js，输出以下内容：


1. 三个主要流程各占多少行


2. 函数之间的调用关系图（文字版）


3. 你认为最适合首先拆分的部分，及理由



操作范围


  • 只读取 /src/services/payment.js
    • 

  • 不读取其他文件
    • 

  • 本阶段不做任何修改
    • 



执行约束


  • 分析报告用中文输出
    • 

  • 不要给出修改建议，只做现状描述
    • 



完成标志


输出分析报告后，停止并问我："是否进入阶段二？"

---

场景 B：自动化文档生成任务（非技术向）

普通写法： 
帮我根据代码生成 API 文档。
最优写法： 
## 背景

我需要为 /src/api/routes/ 目录下的接口生成 Markdown 格式的 API 文档，


供前端开发者参考，他们不需要看代码细节，只需要知道接口地址、


请求方法、参数和返回格式。



本次任务


读取 /src/api/routes/user.js，生成该文件中所有接口的文档。



输出要求


  • 格式：Markdown
    • 

  • 每个接口包含：接口路径、HTTP 方法、请求参数（名称/类型/是否必填）、返回示例
    • 

  • 不包含：代码实现细节、数据库相关信息
    • 

  • 输出到对话框，不要写入文件
    • 



操作范围


  • 只读取 /src/api/routes/user.js
    • 

  • 不读取其他文件
    • 

  • 不写入或修改任何文件
    • 



完成标志


输出文档内容后，询问我是否需要处理其他路由文件。

两个场景的核心逻辑是一样的：把你脑子里的隐含假设，全部显式化地写出来。 你觉得"这还用说吗"的部分，恰恰是 Agent 最容易猜错的部分。

---

今天就能用的行动

这不是玄学，是工程思维迁移到 Prompt 里的结果。

软件工程里有一个概念叫"防御性编程"——你不能假设调用方会按你期望的方式使用你的代码，所以你要在函数里做边界检查、异常处理。

写 Agent 任务描述是一样的道理：你不能假设 Agent 会按你期望的方式理解你的意图，所以你要在描述里做边界声明、约束列举、验收定义。

今天可以做的一件事：找一个你最近打算交给 Cursor Agent 的任务，用五段式模板重新写一遍任务描述，对比一下执行结果。大概率你会发现，Agent 的"理解力"并没有变，变的是你给它的信息质量。

当你开始用工程师写需求文档的思维去写 Agent 任务描述，你会发现 Agent 其实已经足够聪明——它缺的从来不是智能，是你给它的那份"工作说明书"。

---

下一个问题我正在测：Agent 的 System Prompt 和任务描述能不能分开管理？ 如果把"角色设定"和"单次任务"拆开写，稳定性会不会更高——初步结果有点出乎意料，下篇见。

---

本文由8848AI原创，转载请注明出处。关注8848AI，带你从零开始学AI。 新用户注册即送体验token，国产模型（Deepseek/千问等）完全免费，没有月租，按量付费。👉 [api.884819.xyz](https://api.884819.xyz)

#Cursor #AI编程 #Agent开发 #Prompt技巧 #AI工具 #代码重构 #8848AI #开发者工具