前阵子让一个 Agent 给五年前的 Django 项目补测试,目标是把订单模块的行覆盖率从百分之十二提到百分之六十。它第一轮写得挺像样:先摸底、再补核心模块、最后补边缘场景。跑到第二十八轮,中间发生了一次压缩。之后它重新打开 models.py,并且重新提出一个方案——「要不要先把测试框架从 unittest 换成 pytest」。

这个方案它在第七轮就已经否决过,理由是项目里有两百多个现成的 unittest 用例,迁移成本远超收益。

我去翻它的计划文件,上面只有两行:「步骤一:摸底;步骤二:补测试」。没有写为什么否决 pytest,也没有写当前补到哪个模块。

这件事让我彻底改变了对计划文件的看法。它的价值不在「规划」这个动作本身——模型不写计划也能想清楚下一步。它的价值在于:它是长任务里唯一一个不会被压缩改写的记忆载体。

一、压缩会吃掉意图

上一篇算过账,一个五十轮的任务,上下文会滚到二十多万 token,压缩不是可选项。而压缩的机制决定了它会优先丢掉什么。

摘要要的是「结论」,丢的是「过程」。哪些东西被归为过程?试错记录、讨论细节、以及否决理由。「我们评估过 pytest,决定不用」,在摘要里很容易被压成一句「测试框架保持不变」。下一轮模型读到这句话,只知道结论,不知道边界在哪,于是它会重新评估一遍——因为它不知道这个坑已经踩过了。

这就是长任务里最贵的失真:结论还在,约束没了。

对话历史天然不适合承担这个职责。它记录的是「谁在什么时候说了什么」,是一条流水;流水会被压缩、会被截断、会在注意力里被稀释。计划文件不一样,它是你主动写出去的一份契约,内容稳定,位置固定,需要时整段读回来。

这也解释了为什么 /AI/02/ 里把「写」排在四个动作的第一位。窗口是内存,文件是硬盘。计划文件就是把「这次任务要做什么、不做什么、做到哪了」从内存挪到硬盘,让压缩只影响过程,不影响意图。

一个很实用的判断标准:这条信息如果被摘要吃掉,任务会不会走回头路?会,就必须写进文件。目标、约束、验收标准、已排除方案,这四类几乎全部命中。

有人会问,一份 TODO.md 够不够。不够,而且差得很关键。待办清单能记录「还剩什么」,记录不了「为什么不做某个方案」和「做完的标准是什么」。前者防止走回头路,后者防止假完成,恰好是长任务最容易翻车的两个点。清单是给执行者看的,计划是给执行者和审查者共用的。

所以计划文件其实有三个读者。第一个是压缩后的模型自己,它靠这份文件恢复意图;第二个是可能接手的子 Agent 或下一次会话,它靠这份文件快速进入状态;第三个是人,出问题时你要能一眼看出它本来打算做什么、走到哪一步、为什么绕路。三个读者对详细程度的要求不一样,取交集就是「目标、约束、当前步骤、验收、已否决」这五项。

二、粒度:里程碑还是原子步骤

计划写到什么程度,是第一个要做的取舍。写太粗,模型执行时还是靠临场发挥;写太细,计划本身就变成了一份需要维护的代码。

粒度 一条计划长什么样 优点 代价 适合
里程碑式 补齐订单模块的单元测试 短、抗压缩、改起来便宜 模型要自己再拆,容易跑偏 探索性任务、边界不清
原子步骤式 为 calc_total 补三个用例:空车、单商品、折扣叠加 可验收、可并行、可追责 计划很长,容易过期 边界清楚、重复性任务
滚动式 只把当前里程碑拆到原子级,后面的保持粗粒度 兼顾两者 需要主动推进下一层 多数真实任务

过度规划的代价,我踩过三种,都很具体。

第一种是每轮都要重读计划。 一份两百行的计划,读一遍三四千 token,如果每轮都注入,五十轮就是十五到二十万——你为了管理上下文,先给自己造了一个上下文负担。计划越细,这个负担越重,最后挤掉的是真正用于推理的空间。

第二种是频繁改计划。 原子步骤写得越死,执行中越容易发现某一步不成立:文件结构和你以为的不一样、某个函数根本不存在、依赖的库版本不支持。每发现一次就得回去改计划,改计划本身又要花一轮。改得多了,模型会开始「顺手」扩大范围——它会把「这一步不成立」理解成「需要重新设计」,然后计划越改越大。

第三种是计划与实现脱节。 这是最隐蔽的。计划写得很细,但执行时模型发现实际路径不同,它不会回头改计划,而是直接按实际走。跑完二十轮,计划上还停在第三步,实际已经做到第九步。这时候计划不但没用,还有害——复盘时你没法判断它到底完成了什么。

所以我现在基本只用滚动式:当前这一步拆到能验收,后面的保持一句话。走完一步,再把下一步拆开。这样计划始终只有一页,改动的成本低,过期的影响也小。

这背后其实是个很朴素的原则:计划的详细程度应该随不确定性降低而提高。任务刚开始,你不知道代码长什么样,写细了全是错的;跑到第五步,结构清楚了,这时候再细化才有意义。

判断一个步骤该不该拆,我用的标准是「能不能用一到三轮做完」。一轮能做完的事,不必单独成步,写进当前步骤的备注就行;预计超过五轮还没法验收的,说明它其实是一个里程碑,里面还藏着几个子步骤。按这个标准,一份二十轮左右的任务,计划通常只有五到七个步骤,刚好一屏看完。

三、三种分解法

分解任务的方式不止一种,选错方式会让计划看起来很完整,执行起来处处别扭。拿「给旧项目补测试」这个任务举例,三种拆法出来的结果完全不同。

按交付物分解。 以最终要交出去的东西为单位:

  • 测试基线报告:覆盖率数字、可测性评估、阻塞项清单
  • 核心域模块的单元测试:订单金额、库存扣减、优惠计算
  • 边界与异常路径测试:空输入、超时、并发冲突
  • CI 接入:覆盖率门槛、失败即阻断

这种拆法的好处是每一项都有明确产物,验收时不用争论「算不算做完」。适合对外交付、需要分阶段汇报的场景。代价是交付物之间的依赖被隐藏了——四个交付物看起来可以并行,实际「补测试」依赖「基线报告」里的可测性结论,强行并行会返工。

按依赖链分解。 以「必须先有什么」为单位:

  • 确认测试能跑起来(现状:能跑,但缺 fixture)
  • 补 fixture 与 factory
  • 补纯函数测试(不碰数据库)
  • 补涉及数据库的测试
  • 接 CI 与覆盖率门槛

这种拆法顺序天然正确,不会出现「测试写完了发现跑不起来」。适合强依赖、步骤之间有硬前置的任务。代价是串行,前面卡住后面全等;而且它不关心每步产出多少价值,可能前四步做完覆盖率还是零。

按验证点分解。 以「怎么证明这一步对了」为单位:

  • 覆盖率工具能出报告(验证:coverage report 有输出且包含 order 目录)
  • 金额计算有测试且通过(验证:新增用例全绿,且能覆盖历史 bug)
  • 折扣叠加场景有测试(验证:故意改错折扣逻辑,测试必须变红)
  • 覆盖率到百分之六十(验证:CI 门槛通过)

这种拆法最抗「做完了」的主观判断,因为每一步的完成标准都是可执行的。它还有个副作用:写计划时就被迫想清楚怎么验证,很多含糊的需求在这一步就露馅了。代价是验证点难以穷举,非功能性要求(可读性、性能)很难写成判定条件。

实际用的时候不必三选一。我的习惯是:先用依赖链排出大顺序,再用交付物切分阶段,最后给每个阶段补验证点。三种拆法是三个视角,不是三套互斥的方案。

拆法 回答的问题 最适合 主要盲区
按交付物 最后交出什么 分阶段汇报、对外交付 隐藏依赖,容易并行返工
按依赖链 先做什么后做什么 强前置、环境搭建 串行慢,前期不产出价值
按验证点 怎么证明做对了 质量要求高、易假完成 难穷举,非功能要求难覆盖

组合使用时要注意一件事:三套拆法不能机械叠加,否则步骤会碎成一地。正确做法是让一套主导、另外两套做检查——依赖链定顺序,交付物检查每个阶段有没有可展示的产物,验证点检查每个阶段能不能判定。主次不分,计划就会变成一份谁都不想读的矩阵。

四、计划文件长什么样

模板不用复杂,但字段不能少。我用 YAML,因为它结构化、好解析,模型读起来也不费劲。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
goal: 把 order 模块行覆盖率从 12% 提到 60%
constraints:
- 不改生产代码行为,只允许提取函数
- 保留 unittest 风格,不引入 pytest
steps:
- id: S1
do: 建立覆盖率基线
accept: coverage report 生成,order/ 有具体行覆盖率数字
status: done
- id: S2
do: 为 calc_total 补 5 个用例
accept: 空车/单件/折扣/税/运费各一例,全部通过
status: doing
- id: S3
do: 补异常路径
accept: 非法输入返回明确错误,覆盖率提升 10 个点以上
status: todo
rejected:
- 迁移到 pytest: 200+ 存量用例,迁移成本大于收益
- mock 整个 ORM: 测试会失去对真实查询的验证
state:
round: 28
last_green: S1
blocked_by: null

逐个字段说清楚它们的职责。

goal 必须可度量。「提升测试质量」不是目标,「覆盖率从十二到六十」是。不可度量的目标会让后面所有验收标准失去锚点。

constraints 是负面清单。写「要做什么」的地方很多,写「不许做什么」的地方很少,而后者恰恰是长任务里最容易被压缩吃掉的部分。约束要具体到可执行:「不改生产代码行为」比「保持稳定」有用得多。

accept 是每一步的验收标准,必须能被程序或至少被一次明确的操作判定。这一条是整份计划的骨架,下一节单独讲。

rejected 是最容易被省略、也最值钱的字段。它记录的不只是「不做什么」,还有「为什么不」。开头那个故事里,如果第七轮就把「pytest 迁移成本大于收益」写进去,第二十八轮就不会重走一遍。

state 是压缩后的恢复锚点。轮次、最后一个通过的步骤、当前阻塞项,三个字段足够让模型在读回计划时知道自己站在哪。

有了模板,还要解决一个问题:每轮注入多少。整份计划注入,token 花销大;只注入目标,又丢了步骤上下文。我的做法是做一个「投影」:

1
2
3
4
5
6
7
8
9
def plan_brief(plan, limit=40):
cur = next(s for s in plan.steps if s.status != "done")
lines = [f"GOAL: {plan.goal}"]
lines += [f"CONSTRAINT: {c}" for c in plan.constraints]
lines.append(f"CURRENT {cur.id}: {cur.do}")
lines.append(f"ACCEPT: {cur.accept}")
lines.append(f"DONE: {[s.id for s in plan.steps if s.status == 'done']}")
lines += [f"REJECTED: {r}" for r in plan.rejected]
return "\n".join(lines[:limit])

投影只带四样东西:目标、约束、当前步骤及其验收标准、已完成与已否决。计划里其他步骤不注入,需要时让模型自己去读文件。这样既保住了意图,又把每轮的开销压到几百 token。

存放位置也有讲究。我一般放在仓库根目录,文件名固定为 PLAN.md,并且在 system prompt 里写明「长任务先读 PLAN.md」。固定路径是为了让模型不需要搜索就能找到,写进 system prompt 是为了让它在压缩之后仍然记得有这份文件。如果项目里同时有几个任务,就按任务名分文件,但当前任务的那份要有一个固定别名,否则模型每次都要猜该读哪个。

更新时机比内容更重要。三个时刻必须写:完成一步时改 status,发现新约束时补 constraints,否决一个方案时补 rejected。前两个是维持计划有效,第三个是防止重复犯错。最忌讳的是攒到最后一起改——攒的过程里模型可能已经忘了为什么要改,补上去的理由就成了事后编的。

五、什么时候重规划

计划一旦写下就容易变成教条,模型会努力让现实符合计划,而不是让计划符合现实。所以重规划不能靠模型自觉,要有明确的触发条件。

触发条件 典型信号 应该做什么
新信息推翻假设 发现依赖版本不支持、接口已废弃 把相关步骤标 blocked,重写受影响的部分
同一问题连续失败两次 同一个测试、同一个错误重复出现 停手,先写清两次分别为什么没成
范围变化 用户加需求、发现必须改生产代码 先改目标与约束,再改步骤
预算过半进度落后 轮数过半而完成步骤不足三成 砍范围或拆任务,不要硬跑

第一条的关键是「假设」这个词。计划本质上是一组假设:假设文件结构是这样、假设这个函数能复用、假设测试框架支持某个特性。执行就是验证假设的过程。假设被推翻不是失败,是正常的信息更新,但如果计划里没写清依赖了哪些假设,你就不知道哪一步该跟着改。

顺带说清一件事:重规划不等于推翻重来。多数情况下只需要改一两步,把受影响的步骤标 blocked、补一条新的、在 rejected 里记下旧路径为什么不通,其余部分保留。整份重写的成本很高,而且会把之前积累的有效判断一起丢掉。真正需要整份重写的只有一种情况:目标或核心约束变了,地基不成立了。

第二条我执行得比较严。同一个问题失败两次,第三次尝试大概率还是同一类思路的变体。这时候继续试是在赌运气,正确的动作是停下来写一段「两次分别是什么、差在哪、下一个假设是什么」。这段文字本身往往就能让模型换一条路。

第三条最容易被忽略。范围变化时,人的本能是「加一步」,而不是「改目标」。但目标和约束是计划的地基,地基变了还往上加步骤,整份计划就会自相矛盾。宁可推倒重写,也不要在旧目标上叠新需求。

第四条是预算纪律。过半轮数只完成三成步骤,说明要么步骤估得太大,要么中间有系统性阻塞。这时候继续按原计划跑,结果一定是预算耗尽在半路。砍范围不丢人,跑到一半没钱了才丢人。

重规划本身也要留痕。改计划时不要直接覆盖,旧步骤标成 dropped 并加一行原因,新步骤追加在后面。这样做有两个好处:模型在下一轮能读到「这个方向试过、为什么放弃」,人复盘时能看到任务是怎么偏移的。直接覆盖看起来干净,实际上把最有价值的决策过程删了,下一次遇到同样的岔路还会再走一遍。

六、计划必须和验证绑定

没有验收标准的步骤,不是步骤,是愿望。

「完成登录功能」无法判定。什么叫完成?接口能返回?前端能点?错误密码有提示?「登录接口对正确密码返回 200,且响应头包含 sessionid」可以判定。差别不在措辞,在于后者能让一个不参与开发的程序给出是或否。

我把验收标准分三级:

级别 判定方式 例子 可信度
程序可判定 测试、退出码、diff、lint pytest -k login 全绿 高
半自动 脚本产出,人看一眼 覆盖率报告数字达标 中
主观 只能由人或模型判断 代码「更清晰」 低

计划里的每一步至少要落到第二级,核心步骤尽量落到第一级。落到第三级的,要么改写成一个可观测的替代指标,要么承认它就是没法验收,单独标出来让人工确认。

写标准时有个很省事的技巧:尽量写成一条能直接执行的命令。「覆盖率达到百分之六十」可以变成 coverage report --fail-under=60;「接口没被改坏」可以变成 pytest tests/test_api.py。命令的好处是它不解释、不商量,跑完给一个退出码。写在计划里的验收标准越像命令,执行时的争议越少。

反过来,看到「验证功能正常」「确认没有副作用」这种标准,基本可以判定这一步没有真正被设计过。它们不是标准,是占位符,执行到这一步时模型会自己编一个宽松的判定,然后顺利通过。

这里有个顺序问题值得强调:验收标准必须在执行前写,不能执行后补。执行之后,模型看着自己产出的东西倒推标准,几乎总能找到一套说辞证明自己做完了。这不是它不诚实,是生成式模型的本能——给它一个结论,它能为你编出支撑理由。先写标准,等于先立好靶子再射箭。

这也是为什么我坚持把 accept 放在计划文件里,而不是放在 prompt 里。prompt 是每轮都会变的东西,计划文件是稳定的契约。标准写在稳定的地方,才不会被执行过程牵着走。

再补一个实操细节:验收失败时的处理要写进计划。是重试、是换方案、还是标记为已知失败继续往下走,三种选择对应完全不同的后续。不写清楚,模型会默认选第一种,然后在同一个点上反复撞。

七、三种反模式

写给人看的假计划。 格式漂亮,动词宏大——「优化架构」「提升健壮性」「完善测试体系」。这种计划的用途是让人类用户觉得靠谱,对执行毫无帮助。识别方法很简单:把每一步拿出来问「怎么证明它完成了」,答不上来就是假计划。假计划的危害不只是没用,它会挤占真计划的位置,让你以为规划这件事已经做过了。

无限细化。 把「读 models.py」都列成一步,计划写到两百行。这种计划的出发点是「消除所有不确定性」,但不确定性是消除不完的,你只是把它从执行阶段挪到了规划阶段。代价是每轮读计划花几千 token,改一次计划要重写一半,而且计划越细越容易在第一步就发现不成立,然后陷入改计划的循环。计划的作用是降低不确定性,不是消灭它。

计划与执行两张皮。 计划写在 PLAN.md,执行时模型根本不读,最后复盘发现实际做的和计划毫无关系。识别信号是计划里的 step id 从来没在思考文本里出现过。还可以做一个更量化的检查:任务结束时,比对 git diff 涉及的文件和计划步骤里提到的文件,重合度低于一半,说明计划基本是摆设。修复要靠机制:每轮注入当前步骤投影,完成一步强制更新 status,退出前用计划对一遍实际改动。光靠 prompt 里写一句「请遵循计划」是没用的。

这三种反模式有个共同根源:把计划当成一份文档,而不是一个运行时状态。文档写完就完了,状态要每轮读写、每步更新、退出时校验。只有后者才真的影响执行。

有个很快的自检:把计划文件单独发给一个不了解上下文的人,问他「现在做到哪、下一步做什么、怎么算做完」。他答得出来,说明这份计划是活的;答不出来,说明它只是写给你自己看的。

常见的坑

  • 计划写在对话里而不是文件里。 一次压缩就没了,而且模型不会告诉你它忘了。
  • 只写做什么,不写不做什么。 已否决的方案会被反复提出,每次都花几轮重新论证。
  • 验收标准用形容词。 「更健壮」「更清晰」无法判定,最后只能由模型自己宣布通过。
  • 计划一次写完不再更新。 过期计划比没有计划更危险,它会让模型朝一个作废的目标努力。
  • 一步塞三个交付物,只写一个验收标准。 另外两个会悄悄漏掉。
  • 把重规划当逃避执行的出口。 每次遇到困难就重写计划,本质是用规划的动作替代执行的痛苦。
  • 整份计划每轮全量注入。 计划越详细,挤占的执行空间越多,最后本末倒置。
  • 步骤之间没有依赖标注。 并行执行时才发现 B 依赖 A 的产物,返工重来。

检查清单

  • 目标一句话,带可度量的数字或明确产物。
  • 约束单独成段,写清「不许做什么」以及为什么。
  • 每一步都有能被程序或明确操作判定的 accept。
  • 已排除方案记录了理由,而不只是结论。
  • 当前状态包含轮次、最后通过的步骤、阻塞项。
  • 每轮只注入当前步骤投影,不全量读计划。
  • 完成一步立即更新 status,不攒到最后一起改。
  • 四种重规划触发有监控,尤其是「同一问题失败两次」。
  • 计划控制在一页内,细节折叠到子文件。
  • 压缩前确认计划已落盘,压缩后第一条消息重读计划。

计划文件这件事,说到底是在跟压缩抢记忆。模型会忘,摘要会丢,注意力会漂移,唯一稳定的是磁盘上那份你亲手写下的契约。

我现在的习惯是:任务开始先花两三轮写计划,写完先不急着执行,回头问一句「每一步怎么证明它完成了」。答不上来的步骤,要么改写成可判定的,要么删掉。这一步花的时间,通常在第一次压缩之后就能赚回来。

下一篇讲另一种放大能力的方式:当一个 Agent 的窗口装不下整个任务时,怎么把它拆给多个 Agent,以及为什么「多角色协作」往往是最不重要的那个理由。

系列大纲与全部篇目见:Agent 原理与开发。

延伸阅读