给 Agent 的任务书要当代码来维护

2026-08-25

我给自己的一批内容页写过一份写作规格，用来派活给子代理：这批页面要写成什么样、哪些字段必填、哪些话不许说。写完第一版的时候我以为这件事就算结了——规格是一次性成本，往后每次派活把它甩过去就行。

后来我翻自己的提交记录，发现这份规格前前后后被改过好几轮。而且没有一轮是润色措辞，全是加约束。这篇复盘的就是这几轮修订：它们分别是被什么逼出来的，我手上的记录能把发现过程还原到哪一步，以及最后我把规格这个东西的定位改成了什么。这是我自己那条产线上的事，别处未必这样。

现象：改了不止一次，每次都是加约束

按提交记录，几次修订大致是这样：

一次是给结构化字段定规矩——字段里只认事实，取舍判断放到正文里去写，字段本身不许做主观筛选。

一次是给规格新增了一节「读者画像」——这批页面面向做实施和售前的人，不都是程序员，技术细节要降权。

一次是把散在各处的通用写作要求抽出来，单独做成一份简报。

还有一次是往那份简报里补了一条：遇到已经过期的事实该怎么处理，给出方法规则，而不是留给写的人自己发挥。

这四条摆在一起看，第一感觉是我这份规格写得不行，第一版漏得厉害。但真正让我改变做法的不是这个结论，而是我发现这几次修订的触发方式完全一样。

当时是怎么发现的：记录到哪一步，我说到哪一步

先把记录的边界交代清楚：这几次修订分别是在哪一次交付之后加进去的、当时具体是哪一句话让我觉得不对劲，我没有留下记录。手上能确认的只有提交本身——什么时候改的、改的是哪一节、以及提交信息里写下的那句理由。所以下面这一段是从修订内容反推的，我把它标出来，不是当天的现场记录。

反推的依据是这几条约束的措辞：它们的针对性都强得不像是坐在桌前想出来的。「结构化字段里只认事实、取舍放到正文去写」不是一条通用写作原则，它精确到了某一个字段的某一种用错方式；「读者是做实施和售前的人、不都是程序员、技术细节要降权」也不是泛泛的读者意识，它指名道姓圈定了一批人。通用原则可以凭空想，这种一句话堵一个具体口子的话凭空想不出来——它只可能是照着某一份已经交回来的产物写的。

也就是说，发现的方向是从产物倒推到规格，不是重读规格发现它有洞。这个区别不是文字游戏。规格重读多少遍也很难读出洞来，因为写规格和读规格的是同一个脑子，你能想到的都已经写进去了；能把洞照出来的只有一份不符合预期、但你又指不出它违反了哪一条的产物。

方向清楚了，接下来该修哪一层就有了判据。我从这几次修订里带走的是这一条：

觉得交回来的东西不对时，先去规格里搜这条要求的原话。搜得到，是执行问题，重派或者把提示说清楚；搜不到，是规格问题，先补规格再重派。

这个动作很便宜，一次搜索的事，但它决定了接下来修的是哪一层。把规格问题当执行问题处理的代价是：你会在这一次派活的提示里临时补一句话，这句话跟着这一次派活一起消失，下一批换个执行者，同一个坑原样再踩一遍。代理不会替你记住上一次口头补过什么，没写进规格的东西，对下一个执行者就等于不存在。

为什么规格不可能一次写全

想通那个动作之后，第二个问题就顶上来了：为什么我第一版写不全？我是认真写的，写的时候也逐条想过。

我的解释是：规格里的每一条约束，本质上是某一次失败留下来的化石。没翻过的车，你想不到要写。「字段里不许做取舍」这句话，在撞见这件事真的发生之前是想不出来的——因为在我自己的默认认知里，字段就是照抄，这个前提太理所当然，理所当然到不会被写下来。而写规格这件事的困难恰恰全在这里：你要写下来的，正是那些你觉得不用写的东西。

所以第一版规格不全不是失职，是必然。真正的失职是发现了洞、当场绕过去了、却没有回写进规格。

顺带说一句，这个规律在别的地方我也撞见过。我给内容做过一道自动质量门，那道门上线之后被修过不止一次，改的全是误报而不是漏报——它命中的是模板自带的合规声明、是规范强制要求写的否定句、是代码示例里的数字。误报的代价不是多花时间去核，是执行的人开始整体忽略这道门，那门就等于不存在了。修误报同样是一次翻车回写一条判据的过程，只不过回写的对象从任务书换成了检查规则。

改成了什么：把规格当代码维护

我最后落到三条做法上。

第一，每条约束都带着它的来历。 规格里新加一条限制，我会在提交信息里写清楚它是被什么逼出来的。这样做的直接好处是，半年后想删掉某条看起来啰嗦的约束时，我能查到它当初挡住的是什么，而不是凭当下的心情判断它多余。约束是有成本的——规格越长越没人认真读——所以能不能删，得有依据。

第二，共性约束沉淀到一处，单次派活只描述差异。 这就是抽出独立简报的那次修订，它带来一个我事先没料到的附带收益：派活的提示可以大幅精简。原先每次派活我都得把一整套通用要求重述一遍，重述就会走样，走样出来的差异我自己都不容易察觉。抽出来之后，通用的那份是稳定的、可以单独修订的，单次任务的提示只写这一篇跟别的篇有什么不同。任务书这才真正有了「公共库」和「调用点」的分别。

第三，连我自己的流程错误也记进去。 有一条提交记的就是我作为主导者犯的错——凭猜测给出了一个域名，而不是去核实。这条本可以不留痕迹，因为犯错和改错的是同一个人，改掉也就没了。它被记下来的意义在于：规格的可信度来自它连自己的错都记。在我看来，一份只记录执行方怎么犯错的规格，读起来更像甩锅文档；一份连主导者自己怎么翻车都写在里面的规格，约束才立得住。

同一批修订里还有一条相关的：核实结果按等级记录——直接核实、第三方交叉核实、未核实，而不是「核过 / 没核过」这种二值。未核实的要显式列出来并且禁止推测，不能留白让下游自己填。留白是最危险的，因为下游看到空着，多半会顺手补一个看起来合理的答案。

可迁移的判断

如果这一段经历只能带走一句话，我会带走这句：给 Agent 的任务书，要当代码来维护，不能当需求说明书来写。

需求说明书的心理模型是「写完就固定了，往后照着执行」。代码的心理模型是「它一直在改，每次改都有理由，改动是有版本的，谁在什么时候为什么改都查得到」。任务书属于后者。它跟代码一样，会在真实输入面前暴露出没考虑到的分支；跟代码一样，修 bug 的正确方式是补一个分支而不是在调用点绕过去。

再具体一点，就是三条判据：

交回来的东西不对时，先搜规格里有没有这条要求的原话，据此决定修哪一层；
每次翻车都必须回写进规格，绕过去了不算修完，因为绕过去的东西不会跟着规格传给下一个执行者；
通用约束单独成篇、单次派活只描述差异，共性沉淀一次，往后每次派活都省一次重述。

从零把规格想全是不可能的。但每次翻车之后必须回写，否则同一个坑一定会踩第二次——而且第二次踩的时候，你多半已经忘了第一次是怎么爬出来的。

这篇写的是我自己那套流程里的一次实际情况，不是通行做法。你的场景、工具和团队规模不同，结论未必适用，判断方式可能比结论更值得拿走。