结论先行:多任务并行时,派单信息放对话里 = 必然丢失。写成文件,任务才有完整的上下文载体。

说明书完整模板

每个任务一个文件,放在 .zcode/tasks/<id>-<slug>.md。下面是一份可以直接抄走的完整模板:

# T12:给调度查询接口加 Redis 缓存

## 背景
运单列表查询高峰期 DB 压力大;运营确认查询条件组合固定,适合加短 TTL 缓存。
为什么是现在:本迭代性能专项已排期。

## 文件清单
- service/QueryService.java:80-140(主查询逻辑)
- resources/mapper/QueryMapper.xml:40-70(SQL,仅加提示不改动语义)
- 新增 service/CacheKeyBuilder.java

## 边界
- 清单外文件一律不改;公共常量、枚举、mapper XML 若必须动,写进未决问题区
- 不引入新依赖
- 不顺手重构清单内文件的其他问题

## DoD
./gradlew clean build -x test   # 期望 exit 0
回归请求返回结构与改造前一致(对照一份留存样本)

## 未决问题区
(执行中发现的清单外问题写这里,不擅自扩大改动;返回时由主模型统一决策)

五段各司其职:背景回答"为什么",清单回答"改哪里",边界回答"不许碰哪里",DoD 回答"怎么算完",未决问题区回答"拿不准的怎么办"。

模板本身也是活文档。每次任务收尾的复盘里发现新的共性缺口——环境启动方式、公共文件依赖提示、测试数据准备——就固化成模板的默认段,让下一份说明书自动带上。模板的演进速度决定同类错误的重发率:缺口停在个例里就会重发,进了模板就消失。

各段的常见写法错误

常见写法后果应该写成
“优化查询性能”无验收口径DoD 写具体命令 + 期望退出码
“相关文件都改一下”边界失控,改动蔓延清单带行号区间,边界段明令禁止
不写边界段coder 动了公共文件,并行任务互相踩明确"清单外一律不改"
口头补充上下文换个 agent 或重派就丢一切信息落进说明书文件
“尽量快点完成”没有判定权写成可判定的 DoD

背景段最常被当成废话省略,其实它影响执行者的取舍。知道"这是为高峰期降 DB 压力",coder 在缓存键设计和过期策略上就会往高峰场景偏;不知道,它可能按最通用的方式实现,功能对但意图错。背景是五段里唯一解释动机的,删掉它,执行者只剩"做什么",没有"为谁做"。

最容易被忽视的是边界段。不写边界,执行 agent 遇到清单外的问题会自己动手——它不知道那个公共文件被另外两个任务依赖着。边界段是唯一一段"不写也不影响正常情况下的产出"的内容,所以总是被省略;而它恰恰决定了出事时的损失大小。

派单只给一句话

执行 .zcode/tasks/T12-redis-cache.md,完成后回报退出码

重派只改说明书,不重发长篇指令。说明书是唯一事实源,对话只是触发器。这个约束在并行场景价值最大:三份说明书同时派三个 agent,主模型的对话里不需要为任何一个任务保留大段上下文,派完即忘,收单时只看退出码。

这一句话里有两个要件:说明书的路径,和回报的要求——“完成后回报退出码”。缺了路径,agent 靠对话猜任务;缺了回报要求,收单时要靠追问。除此之外不派任何内容:任何跟任务细节相关的话,都该写进说明书而不是对话——对话里的话是给这一次的,说明书里的话是给所有次的。

为什么有效

  • 上下文完整:执行 agent 只读文件就能自洽工作,不依赖主模型对话史
  • 可并行:三个任务三份说明书,同时派三个 agent 互不干扰
  • 可审计:任务改了什么、边界怎么划的,事后翻文件就知道
  • 防蔓延:未决问题区把"顺手改一下"的冲动收拢到主模型统一决策

再补一条不那么显眼的:可重派。说明书写对了,重派成本是一句话;说明书有缺口,重派成本是改一段。整个重派回路都围绕文件转,对话史从头到尾没有参与——这意味着重派不挑执行者,换一个 agent 也能拿到同样的信息。

根子上是载体的区别。对话是易失的、线性的、只属于一个会话的;文件是持久的、可寻址的、谁都能读的。把任务从前者搬到后者,它才第一次具备被并行消费、被重派、被审计的能力——这三件事没有一个能靠聊天记录做到。

重派协议

重派 = 只改说明书 + 原样再派。改动要落在对应段落:缺环境信息补 DoD 段,边界划错了改边界段,而不是在对话里追加解释。追加解释等于退回对话驱动——下一个 agent 或者重开 session 后,那段解释就不存在了。

未决问题区是重派协议的安全阀:执行 agent 把"发现公共常量需要加一个枚举值"写进未决问题区然后收工,主模型批量处理所有任务的未决问题——可能合并成一次公共文件改动,避免三个并行任务各改各的。这个设计把"执行者的判断力"用在了发现问题,把"改不改"的决定权收回到了主模型。

重派还要有上限。同一任务重派三次仍在失败,问题多半不在说明书也不在 coder,而在任务本身没拆好——边界里混了两个正交改动,或者 DoD 依赖了不稳定的条件。这时候的升级动作是回炉重新拆任务,而不是第四次重派;重派次数是拆分质量的温度计。

真实场景

边界段成为必填项是一次事故换来的。三个并行任务里,一个 coder 发现某公共枚举缺一个状态值,没写未决问题区,直接改了——从它单任务的视角看完全合理。但另一个并行任务也改了这个枚举,合并时状态值冲突,排查花了小半天。复盘发现那份说明书没写边界段,coder 根本不知道这个枚举还有别的任务在依赖。当时的权衡是:补边界段会让每份说明书多几行、拆任务多花几分钟,早期我嫌啰嗦;事故之后我认为这几行是全文件性价比最高的内容。做得更好的做法:主模型拆任务时就应该主动扫一遍"哪些公共文件被多个任务共用",把它们逐个写进各说明书边界段——这一步几分钟,而事故成本是半天,这笔账在派单前就该算清楚。补一个当时的观察:出事故的那份说明书,恰好是三份里唯一赶工写的——并行窗口的压力最先压掉的恰恰是边界段。后来我把"说明书齐套检查"做成派单前的固定动作,赶工时也不许跳,正是针对这个规律。

检查清单

  • 每份说明书五段齐全:背景/文件清单/边界/DoD/未决问题区
  • 文件清单带行号区间,清单外文件在边界段点名
  • DoD 是可跑的命令,不是形容词
  • 派单一句话,指向说明书路径
  • 重派只改说明书文件,不在对话里追加解释
  • 并行任务共用到的公共文件,已写进每份说明书边界段
  • 收单时核对退出码与改动文件集合,再关任务