给 Cursor SDK Agent 写任务描述，你可能一开始就错了

你有没有遇到过这种情况：让 Agent 帮你重构一个模块，结果它把整个项目的目录结构都动了？

或者更经典的：你让它"优化一下登录逻辑"，它跑了五分钟，最后把你的 utils/auth.ts、middleware/session.js、甚至 README.md 都改了一遍，然后满怀期待地问你："任务完成，需要我继续处理其他部分吗？"

这不是 Agent 太笨，恰恰相反——它太"积极"了，而你给的边界太模糊了。

同样是写给 AI 的文字，为什么在普通 Cursor Chat 里好用的 Prompt，到了 SDK Agent 里就容易翻车？这个问题困扰了我很长时间，直到我系统地跑了一组对比实验，才把这件事想清楚。

---

你以为 Agent 只是"更聪明的对话框"？

很多人拿到 Cursor SDK Agent 之后，第一反应是：这不就是一个能自己执行代码的 ChatGPT 吗？然后把以前写 Prompt 的习惯原封不动地搬过来。

这个直觉是错的，而且错得很有规律。

普通 Cursor Chat 是"一问一答"的即时响应模式：你说一句，它回一句，每一轮都有你在场确认方向。哪怕它理解偏了，你下一句纠正就好了，代价很低。

SDK Agent 是完全不同的模式：一次启动，自主运转多步，中间不等你。它会自己决定要读哪些文件、要执行哪些命令、要改哪些地方，直到它认为任务完成为止。你不在场，它不等你。

这就像是：

普通 Prompt 是你站在旁边指挥一个厨师炒菜，随时可以说"盐少放点"；
Agent 任务描述是你把菜谱交给工厂的自动化产线，启动之后你就离开了——所以菜谱必须把所有边界情况都写清楚。
输入的语言形式根本不一样。 这是理解后续所有内容的前提。

---

四种写法的实验过程

我用同一个任务场景测试了四种写法："把项目里的用户认证模块从 JWT 迁移到 Session-based，同时保持现有的测试用例通过"。

项目是一个中等规模的 Express + TypeScript 后端，涉及文件约 20 个。

写法 A：直接粘贴需求（最野蛮）

把用户认证从 JWT 改成 Session，测试要过
实际结果：

Agent 开始读文件，读了大约 8 个文件之后，开始修改。它确实改了认证逻辑，但同时：

  • 把 package.json 里的依赖顺手"整理"了一遍
  • 发现有个 TODO 注释，顺手把那个功能也实现了
  • 测试用例有一个之前就是 skip 状态的，它把 skip 去掉了，然后测试失败，它开始修测试，修了三轮
人工干预次数：4 次（两次叫停、一次回滚、一次重新说明范围）

这种写法的问题不是 Agent 太蠢，而是你给了它一个目标，但没给它任何边界。它用最"高效"的方式完成任务，顺便做了一堆你没要求的事。

---

写法 B：加了 Role + Goal 的结构化 Prompt

你是一个经验丰富的 Node.js 后端工程师。

你的目标是：将项目的用户认证机制从 JWT 迁移到 Session-based 认证。


要求：保持所有现有测试用例通过，代码风格与现有项目一致。

这是标准的 Prompt 工程写法，加了角色和目标，比写法 A 清晰很多。

实际结果：

Agent 的方向感明显更好，没有乱改 package.json。但仍然出现了一个问题：它在迁移过程中发现现有的 session 中间件配置和项目的 Redis 配置有冲突，于是自己决定"顺便重构一下 Redis 连接层"。

这个决策本身不算错，但它没有问你，直接改了。结果是：认证模块迁移成功了，但 Redis 连接的改动引入了一个新 bug，而这个 bug 不在原来的测试覆盖范围内。

人工干预次数：2 次

有进步，但仍然有"自作主张"的问题。Role + Goal 告诉了 Agent 它是谁、要做什么，但没有告诉它不能做什么。

---

写法 C：加入约束边界 + 停止条件

在写法 B 的基础上，增加了两段：

约束范围：

  • 只修改 src/auth/ 目录下的文件，以及 src/middleware/auth.ts
    • 

  • 不得修改 package.json、tsconfig.json、任何测试文件
    • 

  • 不得新增或删除文件，只允许修改现有文件
    • 



停止条件：


  • 如果发现需要修改约束范围之外的文件才能完成任务，停下来告诉我，不要自行修改
    • 

  • 如果遇到配置冲突，停下来描述冲突情况，等待我的指示
    •
实际结果：

这次 Agent 在发现 Redis 冲突时，确实停下来了，描述了冲突情况，然后等待我的回应。整个迁移过程干净很多，没有"意外惊喜"。

人工干预次数：1 次（处理 Redis 冲突，这是正常的业务决策，本来就应该问我）

这是一个质的飞跃。关键不是 Prompt 更长了，而是给了 Agent 明确的自主权边界。

---

写法 D：任务分解 + 验收标准（最完整）

## 角色与上下文

你是项目的后端工程师，正在执行一个有明确范围限制的迁移任务。


项目使用 Express + TypeScript，认证相关代码集中在 src/auth/ 目录。



核心目标与范围


将用户认证从 JWT 迁移到 Session-based 认证。


分步执行，每步完成后报告状态，再执行下一步：


步骤 1：读取并分析 src/auth/ 下所有文件，输出现有 JWT 认证流程的摘要


步骤 2：制定迁移方案（列出需要修改的具体文件和修改要点），等待我确认


步骤 3：执行迁移，仅修改已确认的文件列表


步骤 4：运行测试套件，报告结果



禁止行为与停止条件


  • 禁止修改 package.json、tsconfig.json、任何 *.test.ts 文件
    • 

  • 禁止新增或删除文件
    • 

  • 禁止在步骤 2 确认前执行任何代码修改
    • 

  • 如遇到需要修改约束范围外文件的情况，停止并说明原因
    • 



验收标准


  • 所有原有测试用例通过（包括之前 skip 状态的测试保持 skip 状态）
    • 

  • src/auth/ 下不存在任何 JWT 相关的 import 或 token 生成逻辑
    • 

  • Session 配置符合现有 Redis 连接方式（不得修改 Redis 连接层）
    •
实际结果：

Agent 在步骤 2 时给出了一份详细的迁移方案，我看了一眼，发现它列出的文件列表里有一个文件我不希望它动，当场说明，它调整了方案。后续执行完全在预期范围内。

人工干预次数：1 次（步骤 2 的方案确认，这是设计内的检查点，不算"干预"）

---

四种写法对比汇总

| 写法 | 描述复杂度 | 人工干预次数 | 意外修改文件数 | 任务完成质量 | | A：直接粘贴 | 极低 | 4 次 | 6+ | 差（引入新问题） | | B：Role + Goal | 低 | 2 次 | 3 | 中（有遗漏风险） | | C：加约束边界 | 中 | 1 次 | 0 | 良好 | | D：分步 + 验收标准 | 高 | 1 次（设计内） | 0 | 优秀 |
⚠️ 以上数据来自我自己的单次实验，样本量有限，仅供参考。不同项目、不同模型版本下结果会有差异，但趋势是一致的。

---

为什么 Agent 需要"边界感"而不是"目标感"

这是整篇文章最重要的认知节点，我想单独说清楚。

普通 Prompt 的核心逻辑是：让模型理解你想要什么。你把目标描述得越清晰，模型就越能给出好答案。

但 Agent 任务描述的核心逻辑完全不同：让模型知道什么时候该停、什么时候该问、什么范围内自己决策。

我把这个叫做"自主权半径"：

自主权半径小 → 边界描述可以模糊 → Agent 频繁停下来问你

自主权半径大 → 边界描述必须精确 → Agent 才能放心自主决策

这个关系是反直觉的。很多人以为：给 Agent 更多自主权，是为了让它"更自由地发挥"。但实际上，给 Agent 的自主权越大，边界描述就必须越精确——因为它会用最高效但可能最危险的路径完成任务。

一个没有边界的 Agent，就像一个"结果导向"极强的员工：你说"把这个项目做好"，他会删掉所有 bug 多的功能，因为这样"项目质量"确实提升了。你没说不能删，他就删了。

这不是 AI 的问题，这是你没有把业务边界翻译成 Agent 能理解的约束条件。

---

可复用的任务描述模板

基于上面的实验，我整理了一个四段式模板，每次写 Agent 任务都在用：

## 角色与上下文

[描述 Agent 在这个任务里扮演的角色，以及必要的项目背景]


示例：你是这个 React 项目的前端工程师，项目使用 TypeScript + Tailwind，


组件库是自研的，不使用任何第三方 UI 库。



核心目标与范围


[明确要做什么，以及涉及哪些文件/模块]


示例：将 src/components/Table/ 下的表格组件重构为支持虚拟滚动的版本。


涉及范围：仅 src/components/Table/ 目录。



[如果任务复杂，在这里分步骤列出，并说明哪些步骤需要等待确认]



禁止行为与停止条件


  • 禁止修改 [列出不能动的文件/目录]
    • 

  • 禁止 [列出不允许的操作，如删除文件、修改配置等]
    • 

  • 如果遇到 [描述需要停下来问你的情况]，停止并说明原因，等待指示
    • 



验收标准


  • [可验证的完成条件 1]
    • 

  • [可验证的完成条件 2]
    • 

  • [可验证的完成条件 3]
    •
关于这个模板的一个说明： 如果你把这个模板用在普通 Cursor Chat 里，会显得"过度设计"——因为你就在旁边，随时可以纠正，不需要这么多约束。但在 Agent 里，这是刚好够用的最小配置。少一段，就多一个潜在的"出轨点"。

---

接入 API 时的额外注意事项

如果你是通过第三方 API 接入 Claude Opus 4.6 或 GPT-5.1 来跑 Cursor SDK Agent，任务描述里还有几个额外的坑要注意。

Token 预算控制

Agent 多跑几步，token 消耗就是指数级增长的。写法 D 的分步执行设计，除了控制 Agent 行为，还有一个副作用：在步骤 2 等待你确认的时候，Agent 停止了，这一轮的 context 是可控的。如果你让 Agent 一口气跑完所有步骤，context 窗口会被大量中间状态撑满，不仅贵，还容易出现"遗忘"问题。

System Prompt 层级冲突

Cursor SDK Agent 有自己的 system prompt，如果你通过 API 接入的模型也有 system prompt，两者可能产生冲突。一个实用的规避方法是：在任务描述的开头加一句"以下指令优先级高于其他所有指令"，明确告诉模型你的任务描述是最高优先级。这不能解决所有冲突，但能处理大多数情况。

关于 API 成本

测这四种写法的过程中，写法 A 和 B 因为 Agent 反复"出轨"，实际消耗的 token 比写法 D 多得多——因为每次干预都要重新建立 context。所以写更完整的任务描述，不只是省心，也是省钱的。

我自己跑这组实验用的是 [api.884819.xyz](https://api.884819.xyz)，同样的模型，价格比官方渠道友好不少，对反复跑实验来说省了不少成本。注册就能用，国产模型（Deepseek、通义千问等）完全免费，按量付费没有月租，感兴趣可以去看看。新用户注册即送体验 token。

---

今天就能做的一件事

这套方法我现在每次写 Agent 任务都在用，已经成了肌肉记忆。

如果你今天只做一件事，那就是：把你下一个 Agent 任务的描述，加上"禁止行为"和"停止条件"这两段。不需要完整的四段式，光是这两段，就能把"意外修改"的概率降低一大半。

其他的，等你感受到差异之后，自然会想把剩下的部分也补上。

---

下一篇我想聊一个更进阶的问题：当你有多个 Agent 需要协作的时候，任务描述怎么写才能让它们"不互相打架"。Multi-Agent 的 prompt 设计是另一个维度的坑——比如 Agent A 修改了一个文件，Agent B 同时也在读这个文件，结果两个人的工作互相覆盖，最终谁的结果都不对。踩过的人都懂那种感觉。这个问题下篇见。

---

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

#AI教程 #CursorAI #Agent开发 #Prompt技巧 #8848AI #SDK #AI编程 #大模型应用