先写契约再写代码:多 agent 协作里的接口设计
多个 agent 并行写同一个仓库时,冲突往往不是能力问题而是契约缺失。本文给出契约该包含的五项内容、写契约的具体模板,以及一次因契约模糊导致返工的复盘。
目录
多 agent 同时写一个仓库,最常见的失败不是"某个 agent 能力不行",而是它们对同一件事有不同理解。一个用 ### 当标题,一个用 ##;一个把日期写成 2026-11-20,一个写 2026/11/20。单独看都对,合起来就是灾难。
解法不是加强沟通,而是先写一份谁都不能改的契约文件。这篇文章讲契约该写什么、怎么写,以及不写的代价。
一、为什么"口头约定"必然失败
agent 之间没有共享的短期记忆。你在给 A 的提示词里说"用 UTF-8",A 记住了;但 B 的上下文里没有这句话。
更糟的是能力越强越危险:强模型会"合理补全"你没说清的部分,而两个模型补全的方向往往不同。
我当时以为:把需求写详细一点就够了。 实际是:详细的需求描述解决不了"两个人对同一句话的理解差异",只有可校验的契约能解决。
区别在于:需求是"你要做什么",契约是"做成什么样才算合格"。前者靠理解,后者靠检查。
二、契约必须包含的五项
我现在的契约文件固定含五块:
| 项 | 作用 | 不写会怎样 |
|---|---|---|
| 目录结构 | 谁的写作用域在哪 | 互相覆盖文件 |
| 数据格式 | front matter 字段与取值 | 构建器解析失败 |
| 命名规则 | 文件名/slug/编号 | URL 冲突、slug 重复 |
| 验收命令 | 怎么判断"做完了" | 各自以为自己完成 |
| 冲突处理 | 遇到契约没覆盖的情况怎么办 | 各自发明规则 |
下面用真实例子逐项展开。
三、目录结构:把"写作用域"写成硬边界
光写目录树不够,必须指定谁写哪里:
content/
├── workbuddy/ # writer-a 独占
├── dsh/ # writer-b 独占
├── review/ # writer-c
├── pitfalls/ # writer-c
└── method/ # writer-c配套的硬性纪律要写进契约正文,且用"不要"这种否定句:
1. 只写你任务 write_scopes 里的路径,绝不碰别人的目录。
2. 不要修改 docs/ 下的契约文件,遇到契约冲突就在完成说明里写出来。
3. 不要执行 git 命令,不要部署。注意第 3 条的价值:git 和部署是跨越所有写作用域的全局操作。两个 agent 同时 git add 会互相干扰,同时 deploy 会上线半成品。这类操作必须由单一角色独占。
四、数据格式:字段级定义,不是"大概这样"
反例(真实踩过):
# 契约只说"有 front matter",没说字段
---
title: 我的文章
date: 2026/11/20
tags: Harness, 自动化
---这份 front matter 有四个问题:日期格式错、tags 不是数组、少了 category、summary 缺失。构建器会崩,但报错信息可能只指向第一行。
正例是字段级定义:
---
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 是唯一键,必须定死
文件名即 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 不同不算冲突,但归档页排序会乱。
六、验收命令:把"完成"变成可执行判断
这是最容易被漏掉的一项。多数契约写了"要做什么",没写"怎么证明做完了"。
我的写法是给可运行的检查:
# 硬性验收(写进契约,写手自己跑)
- npm run build 从零构建成功,零报错
- 每篇文章生成独立 HTML,含 title/description/canonical/OG
- 站内链接全部可点通(构建器校验并输出断链报告)
- 移动端 375px 宽无横向滚动注意第一条的"从零":rm -rf public && npm run build 和增量构建结果可能不同,契约必须指定是哪种。
还有一条针对内容的死规定:
无法核实的数字必须显式标注(待核实),不得编造具体版本号/日期/金额。这条的价值不是"提高质量",而是给 agent 一个合法的退路。不给退路,模型就会为了"完成任务"编一个数出来。
七、冲突处理:写清楚"卡住了怎么办"
契约不可能覆盖一切。必须提前规定:
遇到契约冲突就在完成说明里写出来,不要自行发挥。
不要修改 docs/ 下的契约文件。两句:上报,不自行解决;不越权修改规则。
对应的执行细节也要写,比如怎么上报:
完成后必须自检并在完成说明里列出:
写了哪些文件、字数控、你确认过的事实。八、一次因契约模糊导致的返工
真实情况(我方视角):
契约里写了"每篇 1200~2200 字(中文字符计),不少于 1100 字",但没定义**"字"怎么数**——是包含代码块,还是只算正文汉字?
结果:我按"含代码块的总字符数"估算,觉得 4000 字符够了;实际上纯汉字只有 1350 左右,勉强压线。如果契约要求"不含代码块的汉字数 ≥1500",我会全部不合格。
修法是把度量方式也写进契约,并给一条能自己跑的检查:
# 数纯汉字,剔除 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 读完契约,能不能在不问任何问题的情况下产出格式正确的产物?能,就够了。至于内容质量,那是提示词和模型的事,不该塞进契约。
结论
三句话:
- 契约解决的是"一致性",不是"质量"。 别指望靠契约让内容变好。
- 每个数字配一条可执行检查。 否则就是主观判断,等于没写。
- 写清"卡住怎么办"。 给 agent 合法的退路,比逼它硬猜安全得多。
下一步
下次要多个 agent 并行干活前,花 20 分钟写这五项。然后做一次小规模试跑(每人写 1 篇),检查合并阶段的实际冲突量。冲突多的项,就是契约里没写清的那一项。