用 WorkBuddy 开发程序避坑指南

把 WorkBuddy 当作"能写代码的执行方"来用，而不是"会自己想办法的工程师"。它能力足够，但它的默认行为和你的默认期待之间有十几处系统性偏差，每一处都要花钱、要时间，有的还会让判断失真。下面按"最容易致命 → 最容易忽略"排。

坑 1：让它自己定方案，它会顺手改判据

这是最贵的一个坑。它一旦拿到"看着办"的自由，就会自己定义"什么算完成"，然后在做不动的时候降低标准。

对策：方案和判据由你定，它只执行。判据写成可测量的硬条件——指标名、阈值、轮次、采样方式、环境门槛，一条不留口子。它提出"改测量口径"时，只允许改实现，不允许改测量。

真实案例：性能指标本来写的是 300ms，中途被一句"先按 200ms 看"带偏，后面它开始自己引用这个 200ms 当标准，还据此宣称"环境不合规"。

坑 2：它会自报"达标"，而数据经不起独立复算

自报很常见：几轮 PASS、附几个数字、结论"达标"。你只要自己跑一遍，就会发现轮次不够、样本被挑过、或者跑的是旧产物。

对策：

• 先核"产物时间晚于源码改动"（构建产物比源码新，才说明它真的重建过）；
• 再自己跑；判据只认自己跑出的原值与自行解包的文件字节；
• 它给的证据目录要能直接打开（脚本、原始结果 json、对照表）。

坑 3：它会"跑偏"——重跑已经结案的老任务

上下文一长，它会重跑很久以前的模块，或者把已通过的用例再跑一遍，然后告诉你"发现新问题"。这既烧钱又污染结论。

对策：

• 卡面上写死禁止项：不许重跑已结案的任务、不许私改验收脚本与断言；
• 要求每轮开头一行自证（本轮任务=<卡号> 依据=<指令编号>），跑偏能立刻发现；
• 发现跑偏就在一条指令里叫停，别讨论，别解释。

坑 4：它挂死时和"正在思考"长得很像

窗口没动静、日志不更新、进程还在——到底是在算，还是已经停了？搞错方向会付出最贵的代价（重启 + 重来）。

判活四件套（成本都很低）：

1. 工作区目录最近 30–60 分钟有无写入；
2. 它的数据目录日志 mtime；
3. 相关进程 CPU 增量（不是累计值，累计值随存活时间单调增长，永远"看起来在忙"）；
4. 磁盘剩余空间。

四项都静默、且窗口截帧字节数完全不变，才判定停摆。

坑 5：指望"自动叫醒"是幻想，靠文件和人

GUI 自动化这条路有三个硬边界：

• 目标窗口所在桌面不可见时，模拟键鼠、窗口消息、强制重绘全部无效，画面帧字节不会变一个字节；
• 弹窗类风险确认（"检测到批量删除，请选择"）对模拟输入经常无响应；
• 会话/权限会过期，切桌面会超时。

可靠链路是这两条：

• 文件信箱：把指令写成文件，它读文件执行——异步、可留痕、不依赖窗口焦点；
• 人来点一下：真发不进去时，请人在窗口输入框发一句话，比任何脚本都快。

自动化只做"提醒"，不做"代替人操作"。

坑 6：把聊天记录当项目管理台账

上下文会被压缩、会被截断、会话可能被归档。靠聊天记录记住"上张卡结论是什么"，迟早出事。

对策：三份文件就够——

• 任务卡：这一卡要做什么、判据、禁止项、时间盒；
• 验收结论：通过/有条件通过/不通过 + 关闭条件；
• 基线状态：当前提交号、提交数、工作树改动数、磁盘剩余、当前卡。

新会话第一件事是读这三份，不是读聊天。

坑 7：交付定义模糊，半成品会被当成完成

它理解的"完成"经常是"代码写完了"，而你要的是"可验收"。少了验证脚本、证据目录、验收报告，你就得回头再要一轮。

对策：卡面上写清交付物清单（例如：验证脚本、冒烟脚本、证据目录、验收报告），缺一不算交付。同时明确"不许预写下一卡"，避免它提前动手又被打回。

坑 8：并行子代理 ≠ 更快

让它"并行开两个子代理"看起来专业，实际常见结果是：两个子代理各读一遍项目、各自产出一半、没人合并，还互相覆盖文件。

对策：默认单线程；只有"互不依赖且都能一次成型"的两三块才并行，并且明确谁合并、合并顺序、冲突怎么办。

坑 9：性能类任务不给测量口径，必然吵架

"要快"这种判据没法执行。它要么挑有利样本，要么用无效证据申辩（例如拿各进程累计 CPU 分钟说明"环境被占用"）。

对策：卡面固定四件事——

• 指标定义（首屏可交互时间？首 DOM 变更？端到端？）；
• 轮次与稳定度规则（连续 N 轮全 PASS，其中至少 M 轮 ≤ 某值）；
• 每轮前置环境采样（CPU 均值/峰值、内存、磁盘），落成文件；
• 尖峰必须分段计时定位，不允许只报总数。

环境是否合格只认采样值，不认辩解。

坑 10：磁盘和备份，会在最关键时刻背刺你

构建产物、证据文件、源码快照都是大块头。磁盘写满时，写文件不是"报错"，而是直接把目标截成 0 字节——脚本被清空，且没有任何报错痕迹。

对策：

• 每轮巡查顺手看剩余空间，低于 1GB 视同阻断；
• 写文件后回读字节数，确认非 0；
• 清理只走白名单目录，证据/交接/历史/仓库这几类一律不动；批量删除类命令不要无人值守跑；
• 大文件备份到另一块盘，不要和构建共用一块。

坑 11：定时任务有平台下限，别指望分钟级

平台侧定时任务通常有最短间隔和数量限制（常见是 1 小时、单账号 1 个）。想要分钟级节奏，得靠系统计划任务。

对策：分层——平台定时管"每小时巡查"，系统计划任务管"3–5 分钟看守"，各自只做一件事，不要互相叠加轮询。

坑 12：每次踩坑不写进"长期口径"，就要付第二次学费

同一个坑重复踩，是这类协作最隐蔽的成本。今天发现"它会把已结案任务重跑"，明天换个卡又重演一遍。

对策：维护一份"长期口径"清单，每条一句话，写完就引用，不重复解释。新卡开工先读它。

附：一份可以抄的分工表

一句话总结

用 WorkBuddy 的正确姿势是：你把"什么算对"钉死，它负责"把活干完"；你负责"不信自报、只信自跑"，它负责"一次交齐、不跑偏"。 剩下的坑，基本都长在"边界没说清"这五个字上。