用了 Coding Agent 一段时间。你大概遇到过这种情况：

任务交下去，Agent 跑了七八分钟，打开一看——方向错了。它写了一套认为「对」的实现，但就是和你想要的差了两三个关键决策。 你开始改需求、补说明、再跑一遍，又是十分钟出去了。

这个循环我经历过很多次直到我意识到：问题不在 Agent，而在我的任务描述。

Anthropic 最新发布的 Agentic Coding Trends 报告说明了一个让人有点难受的数字——开发者使用 AI 完成约 % 的工作量，但只能「完全委托」-% 的任务。大量时间被浪费在反复修正和重新跑 Agent 上。而更扎心的研究数据来自对 Coding Agent 失败案例的分析：% 的 agent 任务失败。根源在规划阶段，不是执行阶段。

换个角度Agent 跑偏。大多数时候是任务描述出了问题，不是模型能力不够。

做了十年服务端和架构，我最近把写任务描述这件事认真想了一遍。发现它和传统的需求分析有着高度的相似性——都是「先定约束，再谈实现」。摸了几个月下来出一套段式开头模板今天程序写一下。怎么说呢，

你的任务描述。可能少了这些东西

痛点：越是有经验的工程师，越容易在给 Coding Agent 布置任务时出问题。说起来，我们已经习惯了隐式传递信息——「加个使用者登录功能」背后暗藏技术栈、代码规范、数据库结构等上下文。但 Coding Agent 不是同事，它在没有明确说明时对这些上下文一无所知。

研究人员对 Coding Agent 失败案例做了归因分析。最常见的三个原因是：

1. 上下文不足Agent 看不到既有架构和程序约束，只能「合理猜测」，结果可能与你的期待相差甚远。
2. 样子。 话说回来，
3. 没有验收标准缺少「什么情况算成功」的明确定义。Agent 无法自我校验。

你可能觉得这三条都是废话。但我回顾自己写过的任务描述，发现这三条几乎从未同时满足过。

真正有趣的是数据：没有结构化规划时复杂 agent 任务的首次成功率大约是 %。加上结构化的任务说明文档后这个数字升到了 %——接近x 倍的提高。靠的不是换更好的模型，而是换更好的任务描述。

先定约束。再说实现——十年经验给我的根本原因

主要痛点：好的需求文档和烂需求文档最大的差距不在「写了什么功能」，而在「定义了哪些约束」。传统软件工程里有一套经典流程：先明确现有程序边界 → 定义非功能性需求→ 梳理隐式约束 → 最终才写功能实现。功能最易变，约束最难改，

I 将这个逻辑套在 Coding Agent 任务描述上后效果惊人。把 Coding Agent 想象成一个新来的外包工程师——水平很强、执行力极高，但对你的程序完全陌生。你会怎么布置任务，大概率会先讲现有架构、哪些地方动不得、哪些是历史包袱、哪些是团队规范…，接下来才说这次要做什么。

This is essence of **段式开头模板**: not “把任务说清楚”，而是“把约束交代清楚”。

段式任务开头模板

This template doesn’t make task longer;it makes *key* information appear at beginning. 每段都有不可替代的作用。

再看第一段，一句话任务定义

目的：

# 任务：为使用者中心服务新增 OAuth Google 登录功能
# 预期结果：使用者点击「Google 登录」后完成 OAuth 授权。在数据库中创建或关联使用者记录，# 返回 JWT token，整个流程无需重定向到外部页面。老实说，