Anthropic官方反例：用六字段任务简报替代"修复登录Bug"

打开Claude Code最佳实践页面，看"在提示中提供具体上下文"下面的那张表。最后一行的"Before"列写着："fix the login bug"。

"After"则长得多："用户反馈会话超时后登录失败。检查src/auth/中的认证流程，尤其是token刷新。先写一个能复现问题的失败测试，然后修复它。"它点名了症状、排查位置，以及"修好"的标准。

那个"Before"版本，每个人都打过。Agent自己划范围、自己决定什么时候算完。你拿到一个diff，得反向工程它做了什么，能不能合并还要靠你从未见过的判断。

解决方案是一份包含六个字段的简短简报。每个字段都关掉了Agent原本要靠猜来填补的一个缺口。

三家厂商，同一份清单

做这些Agent的厂商在自己的文档里说的是一回事。

Anthropic的指南说要"引用具体文件、说明约束、指向示例模式"，并且把最有用的规格描述为"点名涉及的文件和接口、说明什么不在范围内、以端到端验证步骤收尾"。

OpenAI的Codex提示指南说，有用的提示"点名你想要的行为、指向相关代码或复现步骤、保留重要约束、说明如何验证改动"。

GitHub针对Copilot编码Agent的指引列出了理想任务的要素：清晰的问题描述、"关于好方案是什么样子的完整验收标准"，以及"哪些文件需要改动的方向"。

把这些并排放，你就得到了那六个字段。顺序没那么重要，关键是六个都要有。

这三家厂商的文档之所以能收敛到同一份清单，是因为它们面对的是同一个底层机制：编码Agent本质上是一个在巨大动作空间里做决策的循环系统，它每一步都要选择读哪个文件、改哪一行、何时停止。提示的真正作用不是"描述任务"，而是收缩这个动作空间——把无限可能的仓库探索收窄成一条可预测的路径。

值得注意的是，CLAUDE.md、AGENTS.md 和 Codex 指南虽然出自竞争厂商，却都把"验收标准"和"范围边界"列为核心要素。这说明问题不是某家模型的缺陷，而是任务委托（task delegation）这一行为的固有结构：任何执行者——无论人或Agent——在缺少明确目标、边界和停止条件时，都会用自己的默认假设去填补空白。人会用会议追问来澄清，Agent则只能沉默地猜。

六个字段：差与好对照

我们全程使用Anthropic表格里的登录Bug作为例子，放在一个TypeScript仓库里。

一、目标

差：修复登录Bug。

好：会话超时的用户重新登录时收到401。修复后，超时用户首次尝试即可登录成功。

为什么能改变行为：Agent需要一个它能识别的停止点。"修复Bug"没有停止点。症状加上"修好的样子"给了它一个，这正是Anthropic表格里"描述症状"那一行的含义。

这里的核心概念是停止点（stopping condition）。Agent不像人类那样有"做得差不多了"的直觉，它的循环需要一个可判定的终止信号。当提示只说"修复Bug"时，模型会用自己训练中习得的"看起来完成"的标准来收尾——而这个标准往往和你实际想要的不一致。

把"症状"和"修好的样子"分开写，其实是在给Agent提供两样东西：一个用于定位问题的观测描述（超时用户收到401），以及一个用于判断结束的目标状态（首次尝试即成功）。这种"现状 vs 目标"的写法也常见于测试驱动开发的验收标准、SRE的故障工单模板，以及产品需求文档里的用户故事——它们解决的都是同一个问题：让执行者知道"完成"不靠感觉，而靠可核对的事实。

二、范围内的文件

差：不写。Agent会grep整个仓库，读到所有匹配"login"的东西。

好：从src/auth/session.ts和src/auth/refresh.ts开始。新测试放在tests/auth/。

原因：Agent读的每个文件都占上下文窗口，Anthropic的文档说性能"随着窗口填满而下降"。指向正确的文件能把这笔预算省给修复本身。它还告诉Agent你预期diff出现在哪里，这样出现在别处的改动对双方都会很显眼。

三、范围外

差：不写，或者写保持干净。

好：不要碰登录UI、公共API形态、package.json或lockfile。不要重排你不改的文件。如果修复看起来需要动这些，停下来告诉我。

原因：Agent会顺手修它注意到的东西。重命名一个helper或整理一段import，会把两文件的修复变成对周边一切的review。Codex自己的Bug修复示例里就有一行"不要改变API形态"。"停下来告诉我"给了Agent一个合法动作，而不是悄悄扩大改动范围。

四、约束

差：写好代码。

好：保持最小修复。先写一个能复现超时的失败测试，再修。不加新依赖。遵循src/auth/refresh.ts里已有的刷新模式。

原因：约束决定Agent怎么走到终点。"保持最小修复，如果可行则添加回归测试"来自OpenAI的示例提示，Anthropic的示例则说"避免mock"、"只用代码库已有的库从头构建"。"写好代码"什么都没约束住，因为Agent本来就觉得自己在写好代码。

五、完成检查

差：确保它能跑。

好：完成意味着npm test -- tests/auth通过，且npm run lint退出码为0。告诉我做完之前先跑这两个。

原因：用Anthropic的话说，"Claude在工作看起来完成时就停下。没有它能运行的检查，'看起来完成'就是唯一可用的信号，你就成了验证循环"。一个有通过或失败结果的命令，让Agent自己跑、读结果、重试。如果只加一个字段，就加这个。

"用户成为验证循环"这句话背后是一个具体的工程经济学问题：Agent每轮对话都要重新读取上下文、重建对任务的理解，而人类审查者需要反向工程diff、判断改动是否可接受。如果Agent自己不能运行检查，这个昂贵的循环只能由人承担，且每轮都重复。

一个可运行的命令（如 npm test）改变了成本结构：Agent可以在无人干预的情况下跑测试、读输出、失败则重试，把"验证"这一步骤内化成自动循环。这也是为什么该字段在六项中最重要——其他五项减少的是Agent犯错的方向性概率，只有这一项能把错误在Agent这一侧直接拦截。业界把这种模式称为 self-verification loop（自验证循环），它与"给Agent一个可执行的反馈信号"是同一个意思。

六、回报什么

差：不写。你会得到一段欢快的文字说Bug修好了。

好：完成后回复：一句话说明根因，你改了哪些文件，你运行了哪些命令及其结果，以及你注意到但没有改的东西。

原因：同一份Anthropic指南说要让Agent"展示证据而不是声称成功"，因为"审查证据比自己重跑验证更快"。OpenAI的版本是"报告命令和结果"。Agent在范围外发现的问题以列表形式回来，你可以分诊，diff也保持在你要求的规模。

完整简报模板

保留这些标题，Agent会把它们当作结构来读。

GOAL
<哪里坏了，修好是什么样>

IN SCOPE
<要读和改的文件或目录>

OUT OF SCOPE
<不要碰什么；需要时停下来问>

CONSTRAINTS
<遵循的模式、依赖、测试优先、规模>

DONE WHEN
<说完成之前必须通过的命令>

REPORT BACK
<你最终消息必须包含什么>

把登录Bug填进去：

GOAL
会话超时的用户重新登录时收到401。
修复后，超时用户首次尝试即登录成功。

IN SCOPE
src/auth/session.ts, src/auth/refresh.ts,
新测试放在tests/auth/。

OUT OF SCOPE
登录UI、公共API形态、package.json、
lockfile。不要重排其他文件。
如果修复需要动这些，停下来问。

CONSTRAINTS
最小修复。先失败测试，再修复。
不加新依赖。遵循src/auth/refresh.ts里的模式。

DONE WHEN
npm test -- tests/auth通过。
npm run lint退出码为0。

REPORT BACK
一句话说明根因。改了哪些文件。
运行了哪些命令及其结果。
注意到但没有改的东西。

登录Bug特有的内容大多集中在目标和路径里。范围外列表、约束风格和回报行几乎可以原封不动地搬到下一个任务。

简报做不到的事

简报是一个请求。Anthropic的文档划清了CLAUDE.md里的指令（"建议性"）和hooks（"确定性，保证动作发生"）之间的界限。OUT OF SCOPE字段同理。没有什么能阻止Agent越界，所以你得检查。

Agent回报后两个便宜的检查：

**建议性（advisory）与确定性（deterministic）指令**的区别是理解这节的关键。写在提示或 CLAUDE.md 里的内容，最终仍是模型输入的一部分，模型可以选择遵循或忽略；而 hooks、CI检查、分支保护规则是在模型之外执行的代码，无论模型怎么想都会触发。Anthropic文档用这两个词，正是要提醒使用者：**不要把可验证的规则寄托在提示词上，而是要寄存在执行层**。

这也是软件工程里"策略 vs 机制"的老原则在Agent时代的重演。提示词是策略——它表达意图；hooks和git检查是机制——它强制结果。有效的Agent工作流需要两者配合：用简报表达意图，用自动化执行边界。仅靠前者，边界形同虚设；仅有后者，Agent会因缺乏引导而在动作空间里乱撞。
# 这个分支碰了哪些文件？
git diff --stat main...HEAD

# lockfile变了吗？
git diff --name-only main...HEAD -- package-lock.json

让Agent在自己的分支或worktree上运行，范围失误就留在了那个分支上。至于完成检查，Claude Code自己的Stop hook可以阻止一轮对话结束，直到你的脚本通过，用不用Hermes都行。

还有两个限制。每份简报里都一样的行（你的测试运行器、lint命令、风格规则）属于CLAUDE.md（Claude Code）或AGENTS.md（Codex），Agent每次会话都会读。简报是给每个任务变化的内容用的。另外，不是每个任务都需要六个字段。Anthropic的指南说，如果你"能用一句话描述diff"，就可以跳过计划。修一个typo是一句话。一个跨两个文件加一个测试的登录Bug不是。