楼主昨天 21:12

和 Claude Code 协作：开工前必须谈好的"任务契约"

复盘自己跑完一个真实任务后我才意识到：那些被我吹成"关键打断"的时刻，其实是我没在开工前把规则讲清楚。资深开发的省力，不在于少写代码，而在于少在中途纠偏。

背景：我上次干了一件什么事

先把场景交代清楚，否则后面的复盘读起来会一头雾水。

事情很简单：一份飞书 wiki 需要离线归档，但这份文档关掉了下载、PDF 导出、右键和文本选择，浏览器里只能"看"不能"拿"。我把这件事甩给 Claude Code，让它用浏览器自动化的方式抓下来，最终我希望得到的不只是一份本地 markdown，而是一个以后再遇到类似飞书文档可以一行命令复用的工具。

任务最终是做成了：抓到了完整正文、表格、图片，沉淀成了一个可复用的命令行工具和 skill。但过程中我打断过 AI 三次，每次都是"幸亏我盯着"才避免了产物跑偏。这篇文章就是关于这三次打断——以及为什么它们其实根本不该发生。

我踩的是流程坑

过程中那三次打断分别是：

第一次让它"先验证再固化 skill"——它已经准备开始写文档了，我才意识到脚本还没对真实文档跑过一遍完整流程
第二次让它"产物放项目里走 git，不要丢到全局目录"——它默认要把工具扔进 ~/.claude/skills/，那是 AI 的私域，不在我的工程视野里
第三次让它"做成通用方案，不要只针对这一份文档"——它一开始的代码里硬编码了我这份文档的特征，换一份就会失效

每一次打断都让产物变好了一点。但事后看，这三条规则没有任何一条是"过程中才能想到的"——它们全是开工前就应该写进第一条提示词的内容。中途纠偏的代价是：已经写了一半的代码要返工、AI 的思路要重置、上下文里塞满了无效尝试。

AI 写代码的速度比人快十倍，这意味着前期定义错了，浪费的成本也是十倍。

重做一次：开工前的"任务契约"模板

如果让我重新做这个任务，第一条提示词不会是"我给你一个飞书文档，你帮我抓下来"。我会用下面这个结构开场。这是一份契约，不是一份请求。


【目标】

  一句话说清要做什么，包括成功的可观测标准。



【产物形态】

  - 是一次性脚本，还是要沉淀为可复用工具/skill？

  - 文件落在哪个目录？是否需要 git 跟踪?

  - 谁会是后续的维护者(我/团队/未来的 AI)?



【范围与通用性】

  - 这次只处理这一个输入,还是要应对一类输入?

  - 哪些边界情况现在就要考虑,哪些可以暂不处理?



【约束】

  - 不能动的东西(我的本机配置、生产数据、共享凭证…)

  - 必须用的东西(独立 profile、指定依赖版本…)



【工作节奏】

  - 不要直接动手实现。先做 N 个独立探针验证可行性,把结论汇报给我。

  - 我确认方案后再进入实现。

  - 实现完成后必须对真实输入跑一遍并 diff 输出,通过后才能写文档/skill。

  - 所有产物最终落到 <path>,以可 git track 的方式组织。

把这五段写在第一条提示词里，前面那三次打断就一次都不会发生。

三条最容易被新手忽略的子项

1. 产物形态和归属，开工前就要钉死

不要等 AI 把脚本写完了才问"要不要做成 skill"。这种事先想清楚，AI 在实现时会顺手用更模块化的写法、加更合适的 CLI 接口、注释也会写在该写的位置。临时改产物形态意味着重写一遍。

同理"放哪里、谁管"也要前置。AI 默认会把东西放到它认为方便的地方（全局缓存、临时目录、用户主目录），这些位置通常不在你的 git 视野里。一旦堆积，半年后你会发现一堆"AI 帮我做过但我说不清在哪"的资产。

2. 工作节奏要显式写出来

我后来发现 Claude Code 对显式的工作节奏响应非常好：

"不要现在动手，先做探针" → 它会真的去做并行探针，而不是上来就写主干代码
"实现完成前不要写文档" → 它会忍住，先把脚本对真实输入跑通
"对真实输入跑绿之前不要声称完成" → 它会主动汇报验证证据，而不是"应该 OK 了"

但默认情况下它会按"最常见的工程动作"推进：写代码 → 写测试 → 写文档 → 收工。这个默认节奏对探索型任务是错的——探索型任务的正确节奏是：探针 → 定方案 → 实现 → 验证 → 固化。

3. 验证门禁要写成硬性条件

最容易被滥用的一句话是"差不多了"。AI 判定"差不多"的阈值经常低于资深开发的标准。

更可靠的做法是在契约里写硬门禁："对真实输入跑一遍，给我看输出的 wc / head / 关键字段统计，对比预期，超过 X% 误差就不算完成。" 把判定标准从主观语言换成可观测指标，AI 就没法蒙混过关，也不会再用"应该可以"这种话敷衍你。

一段话总结

和 Claude Code 协作的核心，不是写更漂亮的提示词，而是把工程纪律前置到第一句话里：目标、产物、归属、范围、约束、节奏、验证标准——开工前讲清楚，AI 才能贴着你的目标跑。

代码让 AI 写，规则我自己定。这两件事不能换，也不能拖到中途才补。

— 完 —