Agent 工作单：给 AI 一张可验收的任务卡

一句 prompt 只能描述愿望。工作单必须同时定义目标、事实、边界、输入、输出、验证和停止条件。

一、为什么一句 prompt 不够

“迁移 GMV 清洗链路”包含至少四类完全不同的工作：还原旧逻辑、设计新契约、实现平台模块、验证新旧口径。如果把它们塞进一个会话，模型会一边猜事实、一边改结构、一边给自己的实现补测试，最后很难判断错在口径、设计还是代码。

工作单的作用是控制信息密度：每个执行上下文只拿到完成当前任务所需的事实，同时清楚知道哪些事情不能做。

二、工作单的八个字段

字段	必须回答的问题	防止的失效
目标	本单结束时新增什么可验证能力	做了很多但没有闭环
已知事实	哪些结论已经由代码、SQL 或业务确认	把猜测当事实
输入	要读哪些文件、表、接口和上游产物	重复造轮子
输出	要改哪些文件、生成哪些文档或测试	产物不可检查
允许范围	可以改哪些模块	跨边界“顺手优化”
禁止事项	哪些行为即使更快也不能做	负面约束被忽略
验收标准	哪些命令和场景必须通过	只有 happy path
汇报格式	最终要说明什么	人无法快速审查

任务卡不是越长越好。判断标准是：一个新会话只读这张单和引用材料，能否开始；一个审查者只读规格、diff 和测试，能否判断是否完成。

三、拆分粒度

一张合格工作单应满足 INVEST 的工程化版本：

• 独立：依赖稳定契约，而不是另一张单尚未完成的中间状态；
• 可评审：结果可以单独阅读、运行或对照；
• 单一职责：证据梳理、契约设计、平台实现、总控实现、验证不要混在一起；
• 范围受控：预计修改的模块和文件集合清晰；
• 可停止：发现事实不足或契约冲突时，返回问题，不继续猜。

“一次只实现一个平台执行器”通常比“一次迁移九个平台”更容易审查；但“一个函数一张单”又会让上下文重建成本超过实现成本。粒度要按风险、耦合和可验收性决定。

四、生态店铺 GMV 迁移的四张工作单

工作单 1：还原旧链路证据

【目标】
从历史文档、任务定义、SQL 和调用关系中，产出九平台口径矩阵与调用链图。

【输入】
- 历史迁移文档与现有说明
- Kettle/调度任务定义
- 相关 SQL、Mapper、存储过程和目标表

【输出】
- 平台 → 源表 → 日期字段 → 销售/退款规则 → 类目/部门规则 → 目标表
- 已证实 / 文档说明 / 待确认 三类标记
- 无法从代码判断的业务问题清单

【禁止事项】
- 不修改代码和数据库
- 不根据字段名猜业务含义
- 不把九个平台强行归并为同一口径

【验收】
- 每个平台都有可追溯证据位置
- 每个待确认项都说明影响范围

工作单 2：实现单个平台执行器

【目标】
按已确认口径迁移一个平台，符合统一 PlatformExecutor 契约。

【已知事实】
- 输入、输出、错误契约已经冻结
- 该平台的源表、日期、销售、退款和归属规则已经确认

【允许范围】
- 当前平台 service / mapper / model / test
- 必要的执行器注册

【禁止事项】
- 不修改其他平台
- 不在总控中加入当前平台特殊分支
- 不改变共享契约和旧业务口径
- 不绕过目标表白名单

【验收】
- save=false 无写入副作用
- save=true 返回读取/写入行数和耗时
- 平台异常按契约上抛并留痕
- 平台单测与回归通过

工作单 3：实现总控编排

【目标】
组织平台选择、日期校验、失败策略、结果聚合和汇总门禁。

【输入】
- PlatformExecutor 稳定契约
- GmvTargetTableProperties 白名单
- GmvGenerateAllResult 输出模型

【禁止事项】
- 总控不直接访问平台 Mapper
- 总控不承载平台销售/退款特殊规则
- 任一平台失败时不得刷新完整汇总
- preview 模式不得删除、插入或刷新汇总

【验收】
- 未知平台、无效日期、非白名单目标表均在执行前拒绝
- continueOnError=true/false 两条失败路径均有测试
- 全部成功才触发汇总刷新

工作单 4：独立验证与新旧核对

【目标】
验证实现符合规格，并记录新旧链路在同范围下的差异。

【输入】
- 冻结规格
- 代码 diff
- 测试报告
- 可用于核对的日期范围与平台样本

【禁止事项】
- 不为让测试通过而弱化断言
- 不用实现会话的解释替代证据
- 不把“功能可运行”写成“口径已一致”

【验收】
- 规格规则逐条映射到测试或人工检查
- 输出行数、销售额、退款额、关键维度差异
- 无法解释的差异进入待确认清单

五、统一汇报格式

Agent 完成后只按以下结构汇报：

1. 完成了什么
2. 修改了哪些文件 / 生成了哪些证据
3. 做了哪些关键判断，依据是什么
4. 跑了哪些验证，结果是什么
5. 仍有哪些风险、假设或待确认项
6. 是否触碰禁止事项（应为否；如发生必须说明）

这会强迫执行者把“代码已写”转成“结果可审”，也让人可以快速决定接受、返工还是补充信息。

六、四种反模式

反模式	表现	后果
巨型单	一张单覆盖九平台、总控、测试和文档	约束稀释，审查困难
碎片单	每个函数单独发任务	编排开销大于产出
无禁区	只写要做什么，不写不能做什么	模型为最短路径跨边界
自写自审	同一上下文实现并宣布完成	原假设被带入验证

工作单不是形式主义。它真正控制的是决策权：AI 可以决定局部实现方式，不能擅自改变业务口径、系统边界和验收标准。

七、本章小结

• 一张工作单解决一个可独立验收的问题，并显式声明停止条件。
• 证据梳理、平台实现、总控编排、独立验证使用不同上下文，避免猜测扩散。
• 禁止事项与验收标准和目标同等重要；模型不会自动推断负面约束。
• GMV 迁移的最终证据不只是代码和测试，还包括新旧同范围核对与差异解释。

下一章 多 Agent 编排，讨论这些工作单什么时候串行、什么时候并行，以及如何保持独立审查。