先写契约再写代码:多 agent 协作里的接口设计

多个 agent 并行写同一个仓库时,冲突往往不是能力问题而是契约缺失。本文给出契约该包含的五项内容、写契约的具体模板,以及一次因契约模糊导致返工的复盘。

目录
  1. 一、为什么"口头约定"必然失败
  2. 二、契约必须包含的五项
  3. 三、目录结构:把"写作用域"写成硬边界
  4. 四、数据格式:字段级定义,不是"大概这样"
  5. 五、命名规则:slug 是唯一键,必须定死
  6. 六、验收命令:把"完成"变成可执行判断
  7. 七、冲突处理:写清楚"卡住了怎么办"
  8. 八、一次因契约模糊导致的返工
  9. 九、契约的维护成本
  10. 十、契约该多长
  11. 结论
  12. 下一步

多 agent 同时写一个仓库,最常见的失败不是"某个 agent 能力不行",而是它们对同一件事有不同理解。一个用 ### 当标题,一个用 ##;一个把日期写成 2026-11-20,一个写 2026/11/20。单独看都对,合起来就是灾难。

解法不是加强沟通,而是先写一份谁都不能改的契约文件。这篇文章讲契约该写什么、怎么写,以及不写的代价。

一、为什么"口头约定"必然失败

agent 之间没有共享的短期记忆。你在给 A 的提示词里说"用 UTF-8",A 记住了;但 B 的上下文里没有这句话。

更糟的是能力越强越危险:强模型会"合理补全"你没说清的部分,而两个模型补全的方向往往不同。

我当时以为:把需求写详细一点就够了。 实际是:详细的需求描述解决不了"两个人对同一句话的理解差异",只有可校验的契约能解决。

区别在于:需求是"你要做什么",契约是"做成什么样才算合格"。前者靠理解,后者靠检查。

二、契约必须包含的五项

我现在的契约文件固定含五块:

项作用不写会怎样
目录结构谁的写作用域在哪互相覆盖文件
数据格式front matter 字段与取值构建器解析失败
命名规则文件名/slug/编号URL 冲突、slug 重复
验收命令怎么判断"做完了"各自以为自己完成
冲突处理遇到契约没覆盖的情况怎么办各自发明规则

下面用真实例子逐项展开。

三、目录结构:把"写作用域"写成硬边界

光写目录树不够,必须指定谁写哪里:

text
content/
├── workbuddy/   # writer-a 独占
├── dsh/         # writer-b 独占
├── review/      # writer-c
├── pitfalls/    # writer-c
└── method/      # writer-c

配套的硬性纪律要写进契约正文,且用"不要"这种否定句:

text
1. 只写你任务 write_scopes 里的路径,绝不碰别人的目录。
2. 不要修改 docs/ 下的契约文件,遇到契约冲突就在完成说明里写出来。
3. 不要执行 git 命令,不要部署。

注意第 3 条的价值:git 和部署是跨越所有写作用域的全局操作。两个 agent 同时 git add 会互相干扰,同时 deploy 会上线半成品。这类操作必须由单一角色独占。

四、数据格式:字段级定义,不是"大概这样"

反例(真实踩过):

yaml
# 契约只说"有 front matter",没说字段
---
title: 我的文章
date: 2026/11/20
tags: Harness, 自动化
---

这份 front matter 有四个问题:日期格式错、tags 不是数组、少了 category、summary 缺失。构建器会崩,但报错信息可能只指向第一行。

正例是字段级定义:

yaml
---
title: "标题,不带书名号,18~34 字"
date: 2026-11-20          # YYYY-MM-DD,必填
category: workbuddy       # 必须是 workbuddy|dsh|review|pitfalls|method 之一
tags: ["Harness", "自动化"]  # 2~5 个,中文或英文,不加 #
summary: "一句话摘要,40~80 字"
draft: false              # 可选,默认 false
---

三处细节值得学:

  • 给了字数区间(18~34 字、40~80 字),不是"简洁"
  • category 用枚举,直接堵死拼写错误
  • 说明了反例("不带书名号"、"不加 #"),因为这两条最容易犯

五、命名规则:slug 是唯一键,必须定死

text
文件名即 slug:NNN-kebab-case-slug.md,如 001-harness-first-run.md
构建器去掉 NNN- 得到 slug
每篇 slug 全局唯一,用英文小写连字符
编号按大类内顺序:workbuddy 001-008,dsh 001-009,review 001-004...

"编号按大类内顺序"这条特别重要。如果没有它,三个 agent 会各自从 001 编号,然后出现三个 001。虽然 slug 不同不算冲突,但归档页排序会乱。

六、验收命令:把"完成"变成可执行判断

这是最容易被漏掉的一项。多数契约写了"要做什么",没写"怎么证明做完了"。

我的写法是给可运行的检查:

bash
# 硬性验收(写进契约,写手自己跑)
- npm run build 从零构建成功,零报错
- 每篇文章生成独立 HTML,含 title/description/canonical/OG
- 站内链接全部可点通(构建器校验并输出断链报告)
- 移动端 375px 宽无横向滚动

注意第一条的"从零":rm -rf public && npm run build 和增量构建结果可能不同,契约必须指定是哪种。

还有一条针对内容的死规定:

text
无法核实的数字必须显式标注(待核实),不得编造具体版本号/日期/金额。

这条的价值不是"提高质量",而是给 agent 一个合法的退路。不给退路,模型就会为了"完成任务"编一个数出来。

七、冲突处理:写清楚"卡住了怎么办"

契约不可能覆盖一切。必须提前规定:

text
遇到契约冲突就在完成说明里写出来,不要自行发挥。
不要修改 docs/ 下的契约文件。

两句:上报,不自行解决;不越权修改规则。

对应的执行细节也要写,比如怎么上报:

text
完成后必须自检并在完成说明里列出:
写了哪些文件、字数控、你确认过的事实。

八、一次因契约模糊导致的返工

真实情况(我方视角):

契约里写了"每篇 1200~2200 字(中文字符计),不少于 1100 字",但没定义**"字"怎么数**——是包含代码块,还是只算正文汉字?

结果:我按"含代码块的总字符数"估算,觉得 4000 字符够了;实际上纯汉字只有 1350 左右,勉强压线。如果契约要求"不含代码块的汉字数 ≥1500",我会全部不合格。

修法是把度量方式也写进契约,并给一条能自己跑的检查:

bash
# 数纯汉字,剔除 front matter 与代码块
python -c "
import sys, re
t = open(sys.argv[1], encoding='utf-8').read()
t = re.sub(r'^---.*?---', '', t, flags=re.S)
t = re.sub(r'```.*?```', '', t, flags=re.S)
print(len(re.findall(r'[\u4e00-\u9fff]', t)))
" content/review/001-cli-coding-agents.md

教训:契约里每个数字,都要配一条能算出这个数字的命令。

九、契约的维护成本

写完契约会多花时间,值不值?

环节无契约有契约
启动快慢(要读契约)
并行阶段快快
合并阶段大量返工少量修正
整体不可预测可预测

关键在"合并阶段"。3 个 agent 并行,无契约时合并要重写 30%~50% 的内容;有契约时通常只修格式细节。

十、契约该多长

我的经验:一页到两页 A4。太短盖不住关键决策,太长没人读完。

判断标准:一个新来的 agent 读完契约,能不能在不问任何问题的情况下产出格式正确的产物?能,就够了。至于内容质量,那是提示词和模型的事,不该塞进契约。

结论

三句话:

  1. 契约解决的是"一致性",不是"质量"。 别指望靠契约让内容变好。
  2. 每个数字配一条可执行检查。 否则就是主观判断,等于没写。
  3. 写清"卡住怎么办"。 给 agent 合法的退路,比逼它硬猜安全得多。

下一步

下次要多个 agent 并行干活前,花 20 分钟写这五项。然后做一次小规模试跑(每人写 1 篇),检查合并阶段的实际冲突量。冲突多的项,就是契约里没写清的那一项。