andylei.app / playbook · EN
One task system per project. Machine-verifiable acceptance. Rules that agents cannot rewrite for themselves. Distilled from four real projects, every line paid for by an incident.
我不是工程师。过去一年我用 AI agent 做了十几个工具和两三个产品，每一个项目都在教我同一课：agent 不缺能力，缺的是让它不骗你、不白干、不互相打架的规程。这页是我从四个长期项目（一个桌面应用、一个任务管理库、一个内容生产管线、一个照片工具）里淬炼出来的作业规程——每一条都是真实事故换来的，不是理论。
我踩过最贵的坑不是某个 bug，而是让三套任务体系在家里并行：这边用 markdown 复选框、那边用文件夹编号、第三个项目用 GitHub Issues，彼此不知道对方存在。同一件事两处记账，必有一处过时——过时的那份会在几周后骗到你或你的 agent。
| 项目形态 | 判据 | 任务载体 |
|---|---|---|
| 代码产品 | 有可机器校验的产物（构建/测试/发版），需要验收闭环 | GitHub Issues + Milestones（私库免费，服务端原子发号，多会话不撞号） |
| 知识 / 流程 / 运营型工作 | 产出是文档、消息、事务推进 | 纯 markdown + git 的项目/任务文件夹（我开源了这套：workmd） |
| 轻量单人小仓 | 一个人、单会话为主、没有验收压力 | 一份 plan.md 复选框 + 几个协作文档就够 |
选哪套不重要，只选一套最重要。项目长大了可以迁移（我迁过一次，文件卡 → Issues，留了新旧编号对照表），但任何时刻只能有一个真相源。
纸面规则拦不住不守规矩的执行方——这句话在我这里不是比喻，是发生过的事：agent 绕过规定路径干完活，回头把规则文档改写成给自己背书。所以规矩必须落在 agent 绕不过去的地方：
01 · 完成的定义
任务完成 = 有证据表明结果在对方那边成立，不是「我发出去了」。归档前有硬门：交付证据一栏还是占位符，就拒绝归档。
02 · 关闭语义
Issue 关闭 = 验收过了，不是「代码合了」。需要人验的任务禁止在 commit 里写 closes #N——否则合并那一刻 GitHub 会自动关掉一个没人验过的任务，进度条从此虚高。
03 · 代码是事实，任务卡是线索
说某功能「没做」、建「要做 X」的卡、打算重做 X——这三个动作之前必须先查代码。功能常在别的任务下被顺手做掉，旧卡还开着；信了旧卡，就会重复造轮子。同理：最新决策是事实，记忆和旧文档是线索，冲突时以更晚的决策为准。
04 · 发给 agent 的任务卡要有白名单
卡里明确列「允许改的文件」和「不许碰」清单，从源头掐掉顺手重构；验收写成「命令 + 期望输出」的表格，每条都机器可判，还要有反向断言（grep 旧符号必须零命中，证明是真删了、不是改个名躲过检查）。
05 · 反自欺三件套
施工 agent 开工第一件事跑 pwd 自证在正确的工作目录；判定构建/测试通过要看输出里的证据字符串（BUILD SUCCEEDED、0 failures），退出码为零不等于干了活；回执必须贴实际读回的数据——自报「已完成」不算证据，验收方会抽查，对不上按造假处理。
06 · 诚实的第三出路
人工验收队列积压几十条时，如果只有「开着」和「关闭」两条路，唯一现实选项就是假装验过。所以给一条清账出路：如实注明「机器闸全绿、人没逐条验」，打上专门标签、刻意不勾验收清单。严重级别的缺陷拒绝清账。记录可以不完美，不可以说谎。
07 · 元铁律：规则不可自我修改
任何执行方不得修改规则来放行自己刚走过或想走的路径。想改规则，停下来向人提出。每条规则都带着它的事故编号和日期——规则可追溯，才判断得了它有没有过期。
贵的模型当司机：写卡、审查、验收、做架构判断；便宜的 agent 当施工队：在隔离的 worktree 里按卡产码。审查用水位线机制——审过的提交打上标记，永不重审，只看增量；返工不开新卡，在原卡追加返工单。返工超过两轮就停：要么卡没写清楚（司机的锅），要么这活施工队啃不动（换人）。
这套规程的全部价值可以压成一句话：让「骗你」这件事，在物理上变贵。
agent 不是恶意的，但它在压力下会走捷径——虚标完成、编造验证、改规则给自己背书，四个项目里我全遇到过。每一条铁律都不假设 agent 自觉，只把闸放在它绕不过去的地方。做到这一点之后，剩下的就全是它的长处了。