Coding Agent 任务提示模板：把上下文写成约束

从一次翻车说起

我给 Coding Agent 下过一个看起来很清楚的指令：「给用户列表页加分页功能」。Agent 很快返回了改动——加了分页组件，改了 API 请求，甚至还顺手优化了 CSS。但审查时我发现：它把后端 API 的返回结构改了，上游服务正在用同一个接口，上游直接报错。

问题不在 Agent 能力不够，而在于我的提示缺少边界约束。我只说了「要做什么」，没说「不要碰什么」，也没告诉它验证标准是什么。

这不是个例。Anthropic 在上下文工程指南里提到一个核心观点：Agent 出错的根源，绝大多数时候不是推理能力不够，而是上下文质量不够——该给的信息没给，不该给的信息淹没了关键约束¹。Addy Osmani 在讨论 AI Agent 规格文档时也说，「上下文长度不等于上下文质量」，塞得越多，模型反而越容易丢失真正重要的东西²。

这篇文章分享一套我在用的任务提示模板。它的核心思路很简单：把上下文写成约束，而不是叙述。

为什么要把上下文写成约束

上下文工程的核心问题

Anthropic 把上下文工程定义为「策划有限上下文窗口内容的艺术和科学」¹。这里有两个关键词：有限、策划。

当前主流模型的上下文窗口看起来很大（200K tokens 甚至更多），但实际可用空间远没有数字上那么宽裕。Manus 团队在实践中发现，模型在上下文长度超过某个阈值后，性能会明显下降——即使窗口本身还装得下³。Sourcegraph 的工程团队把这个现象叫做「上下文腐蚀」（context rot）：往窗口里塞的 token 越多，模型对每条信息的注意力越弱⁴。

这意味着，给 Agent 的任务提示不是「信息越多越好」，而是要在有限空间里把最关键的信息以最强的信号传达出去。

从 Prompt Engineering 到 Context Engineering

2026 年行业内一个明显的共识转变是：单靠优化 Prompt 措辞已经不够了，重要的是系统性地管理 Agent 能看到的所有信息。Towards AI 有篇文章标题直接说「Prompt Engineering 已死，Context Engineering 才是真正有效的东西」⁵，说法有些绝对，但方向是对的。

对于 Coding Agent 的任务提示来说，这个转变意味着：

约束比叙述更有效的机制

模型处理自由叙述时，需要在大量文字中提取意图。而约束是已经提取好的结构化信息，模型可以直接执行。这类似于编程中的声明式和命令式——约束是声明式的「我要什么、不要什么」，叙述是命令式的「一步一步怎么做」。

Addy Osmani 提出的三级边界系统很实用²：

三个翻车案例

案例一：Agent 擅自扩大了改动范围

场景：我在做一个 Next.js 项目，让 Agent 给编辑器页面加一个工具栏按钮。

翻车：Agent 不仅加了按钮，还重写了工具栏的布局组件，改了三个相关页面的样式，甚至在 packages/ui/ 里新建了一个通用组件。它觉得「既然要加按钮，不如顺便重构一下」。

根因：我没有指定允许修改的目录范围和「非目标」，Agent 根据自己的判断扩散了范围。

修复方案：在提示中加入「相关路径」和「非目标」两个显式字段：

// ❌ 模糊的提示，Agent 会自行决定改动范围
在编辑器页面加一个「插入代码块」的按钮。

// ✅ 约束明确的提示，Agent 知道边界在哪
目标：在编辑器页面工具栏加一个「插入代码块」按钮。

非目标：
- 不改动工具栏布局
- 不新增通用 UI 组件
- 不修改其他页面

允许修改的路径：
- apps/src/features/editor/_components/toolbar.tsx
- apps/src/features/editor/_components/insert-code-button.tsx（新建）

项目约束：
- 新组件放在 _components/ 下，不放 packages/ui/
- 遵循现有 Button 组件的 props 风格

案例二：Agent 通过了测试但没有真正验证

场景：让 Agent 给一个 API 接口加参数校验。

翻车：Agent 写了校验逻辑，补了单元测试，测试全部通过。但上线后发现，校验逻辑只覆盖了正常输入，对空值、超长字符串、特殊字符这些边界情况没有处理。单元测试过了，集成测试挂了。

根因：我只说了「加参数校验」，没有指定验收标准——验证命令是什么、需要覆盖哪些场景、除了单元测试还要跑什么检查。

修复方案：在提示中加入「验收命令」和「风险检查项」：

// ❌ 只说目标，不说验证标准
给 /api/users 接口的 name 字段加参数校验。

// ✅ 目标 + 验收命令 + 风险检查
目标：给 /api/users 接口的 name 字段加参数校验。

验收命令（必须全部通过）：
1. pnpm typecheck
2. pnpm test -- --filter=users-api
3. pnpm lint

校验规则：
- name 不能为空字符串
- name 长度 1-100 字符
- name 只允许中英文、数字、下划线

风险检查：
- 确认不影响现有 GET /api/users 的行为
- 确认错误响应格式与项目其他接口一致（返回 { code, message }）
- 确认错误码使用项目统一的 4xxxx 格式

案例三：Agent 的项目风格与现有代码不一致

场景：让 Agent 在一个使用函数式组件 + Hooks 的项目里写一个新组件。

翻车：Agent 生成了一个正确的组件，但用了 class component 的写法。功能没问题，风格完全不对。审查时我还得手动改写。

根因：我没有告诉 Agent 项目的编码风格约束。模型训练数据里有大量 class component 的代码，如果没有明确约束，它可能按自己训练数据中权重更高的风格来写。

修复方案：把关键风格约束直接写在提示里，或者指向项目已有的配置文件：

// ❌ 不提风格，Agent 按训练数据默认风格输出
写一个 UserProfile 组件，显示用户头像和昵称。

// ✅ 风格约束写在提示里
目标：写一个 UserProfile 组件，显示用户头像和昵称。

项目约束：
- 使用函数式组件 + TypeScript，不用 class component
- 样式用 Tailwind CSS，不写自定义 CSS
- 组件放在 apps/src/components/ 目录
- Props 用 interface 定义，不用 type
- 导出方式：export function UserProfile()，不用 export default

参考现有组件：
- apps/src/components/UserAvatar.tsx（风格参照）

任务提示模板

把上面三个案例的经验汇总，我整理出以下模板结构。

完整模板

以下是我在用的完整模板，可以直接复制使用：

## 目标
[一句话描述用户可见的结果]
 
## 非目标
- [本次明确不处理的事项 1]
- [本次明确不处理的事项 2]
 
## 允许修改的路径
- [文件/目录 1]
- [文件/目录 2]
 
## 项目约束
- 编码风格：[框架、语言、样式方案]
- 目录规则：[新文件放哪里、测试放哪里]
- API 边界：[不改哪些接口、不改哪些公共模块]
- 参考文件：[列出风格参照的现有文件]
 
## 验收命令
1. [typecheck / lint 命令]
2. [test 命令 + 范围]
3. [build 命令]
 
## 风险提示
- [是否涉及数据迁移]
- [是否影响公开页面 / SEO]
- [是否涉及权限 / 鉴权]
- [是否有性能影响]
 
## 交付格式
完成后请说明：
- 改动了哪些文件，每个文件改了什么
- 验收命令的运行结果（附输出）
- 残余风险或需要人工确认的点

字段选择指南

不是每个任务都需要填完所有字段。下面是按任务复杂度的使用建议：

实践中的几个关键技巧

让 Agent 先复述计划

在正式实现之前，加一句「请先复述你的计划，包括会改动哪些文件、验证策略、以及你认为有风险的地方」。这一步能提前暴露理解偏差。

// ❌ 直接让 Agent 开始实现
实现用户注册功能。

// ✅ 先让 Agent 复述计划
实现用户注册功能。
在动手之前，请先说明：
1. 你打算改哪些文件
2. 你会运行哪些验证命令
3. 你觉得有哪些风险点
等我确认后再开始实现。

Anthropic 在上下文工程指南中建议用「多样化、典型的示例」来引导模型行为¹。让 Agent 复述计划本质上就是给模型一个机会来展示它理解的「典型执行路径」，如果理解有偏差，这时候修正成本最低。

按阶段拆任务，不要一次性给完

Sourcegraph 团队的实践是，把大任务拆成多个阶段，每个阶段有独立的上下文和验证标准⁴。这跟 Addy Osmani 提出的四阶段流程一致：规格 → 计划 → 任务拆分 → 实现²。

// ❌ 一次性给完所有需求
实现整个用户系统：注册、登录、找回密码、权限管理、用户头像上传。

// ✅ 分阶段推进
## 阶段 1：注册（当前任务）
目标：实现邮箱 + 密码注册。
非目标：登录、找回密码、权限、头像。
验收：注册接口返回 JWT，密码 bcrypt 加密，邮箱格式校验。

## 阶段 2：登录（阶段 1 完成后）
[下一阶段再给具体提示]

把验证命令写成可执行的

很多提示里会写「确保代码正确」或者「做好测试」。这种描述对 Agent 来说等于没说——它不知道「正确」的标准是什么，也不知道该跑哪些测试。

// ❌ 模糊的验证要求
确保改动没有问题。

// ✅ 具体、可执行的验收命令
验收命令（必须全部通过，请贴出运行结果）：
1. pnpm typecheck — 类型检查无报错
2. pnpm test -- apps/tests/users/ — 用户模块单测全通过
3. pnpm lint — 无新增 lint 警告
4. curl -s http://localhost:3000/api/users | jq '.data | length' — 返回数量与数据库一致

LangChain 在分析 Agent 上下文管理时提到，Claude Code 的「自动压缩」功能在上下文超过 95% 时会触发摘要⁶。如果你的验证命令太啰嗦，反而可能在压缩过程中丢失。保持验收命令简洁、可执行。

常见误区

检查清单

任务提示写完后，对照以下清单检查：

写提示之前

• 是否清楚用户可见的结果是什么
• 是否知道任务涉及哪些模块和文件
• 是否了解相邻功能（避免 Agent 误触）
• 是否确定了验收标准（什么算「完成」）

写提示时

• 目标是否用一句话说清楚
• 非目标是否列出了至少两项
• 允许修改的路径是否具体到文件或目录
• 项目约束是否包含风格和边界
• 验收命令是否可以直接复制运行
• 风险提示是否覆盖了数据、权限、SEO

批准后、实现前

• 是否让 Agent 复述了计划
• Agent 的计划是否与预期一致
• 是否有需要修正的理解偏差

实现完成后

• Agent 是否列出了所有改动的文件和改动内容
• 验收命令是否全部通过，结果是否附上
• 是否有残余风险或需要人工确认的点
• 改动范围是否超出允许路径

小结

给 Coding Agent 写提示，核心不在于措辞有多精巧，而在于约束是否足够明确。目标、非目标、路径、风格、验收、风险、交付——这七个维度覆盖到了，Agent 的出错率会明显下降。

这不是什么高深的方法论。本质上就是把「人跟人交接任务时应该说的事情」结构化地写给 Agent。区别只是 Agent 不会主动问你「边界在哪」，你得主动告诉它。

参考资料