Vibe Coding Agent 共享接口冻结：先定合同再并行实现

两个 Agent 同时实现 profile 功能时，最容易冻结的是一句自然语言：“返回用户资料和错误信息。”前端据此把 error 当字符串，后端却返回带 code 的对象；测试 Agent 又根据旧讨论允许缺失 displayName。每个局部实现都自洽，只有组合时才暴露三套合同。

Vibe Coding 中的接口冻结不是提前设计全部架构，而是在任务分叉前固定最小公共面。它承接 API 合同与请求响应示例 的业务语义，但更强调多个执行者在同一时间窗口内消费同一个 revision。冻结之后可以并行写实现，不能各自继续“顺手优化”共享字段。

先找出真正的共享接口

共享接口不只等于 HTTP API。任何被两个任务独立读取和写入的边界都应纳入候选：

• 请求、响应、错误码和认证前提；
• 事件 topic、payload、顺序与重复语义；
• 数据库迁移后暴露给应用的字段约束；
• 公共 TypeScript 类型、CLI 参数、环境变量；
• 生成器输入、文件布局和测试 fixture；
• UI 与浏览器测试约定的可观察状态。

不要把内部函数的每个参数都提升成冻结合同。判断标准是：消费者能否在不读取生产者实现的前提下独立工作；若能，双方需要一个显式边界。若消费者必须依赖某个内部调用顺序，先确认那是业务约束还是应该消除的偶然耦合。

冻结包必须能被机器检查

一份 InterfaceFreeze.v1 至少包含接口 ID、revision、适用范围、canonical schema 摘要、正反样例、错误语义、兼容策略、生产者和消费者列表。OpenAPI 可以描述 HTTP 操作及请求响应表面，JSON Schema Validation 可表达类型、必填、取值等结构约束；二者仍不能替你决定对象级授权、事务原子性和事件幂等。

interface: profile.update
revision: 3
canonical: contracts/profile-update.openapi.yaml
successExample: fixtures/profile-update-200.json
errorExamples:
  - fixtures/profile-update-401.json
  - fixtures/profile-update-422.json
semantics:
  displayName: trimmed Unicode text, 1..80 code points
  unauthorized: no row or audit-success event is written
consumers:
  - web-settings
  - api-contract-tests

正例只证明某个输入允许，反例才划出边界。至少覆盖缺失字段、未知字段、错误身份和旧版本消费者。结构化 validator 通过并不代表语义完成；集成合同边界测试应从真实入口检查生产者和消费者是否对同一状态得出同一解释。

表示层和语义层分别冻结

只冻结一个 TypeScript interface 很危险，因为类型会在编译后消失，也可能没有覆盖网络和持久化输入。反过来，只冻结 JSON Schema 也不够：string 无法表达“规范化后仍唯一”，200 也不能说明审计事件是否已可靠提交。

为每个字段写三层事实：表示形式、业务含义、失败行为。删除字段时还要记录兼容窗口。Protocol Buffers 的官方最佳实践要求不要重用已删除字段编号，并建议保留删除的名称；这类规则体现了同一个原则：共享表示一旦被消费者观察，不能把旧标识当作空位随意再利用。

Agent 改 API 的契约兼容门处理接口变更能否进入代码库；冻结包则是并行工作开始时的共同输入。前者是接受门，后者是协作基线，两者不能用一份“最新类型文件”含糊代替。

冻结后按 revision 工作

每个子任务在上下文中记录 interfaceId + revision + digest，生成夹具和 mock 也绑定同一组合。生产者 Agent 不得在实现过程中独自改 canonical 文件；消费者若发现合同无法实现，提交一条带反例的 change request，而不是在本地增加兼容分支。

变更流程应是：暂停受影响节点的提交资格，说明旧合同哪里不可满足，更新 schema 与样例，列出受影响消费者，重新运行合同检查，产生 revision+1，再明确哪些已有工作可复用。未受影响的调查可继续，但任何基于旧字段形状的绿色测试都标为 stale。

工具结果 Schema 演进给出了 producer 与活跃 consumer 的兼容矩阵。代码任务也需要列真实消费者，不能只问“新 schema 是否合法”。一个未被搜索到的移动客户端、脚本或文档生成器，可能决定本次变更只能做 additive 演进。

集成前做双向接受

生产者提交“我按 schema 返回了”不够，消费者提交“mock 下能渲染”也不够。先用 canonical 正反夹具分别驱动双方，再跑至少一条不经过 mock 的跨边界用例；同时确认错误路径没有多余副作用。生成客户端则从冻结源重新生成，检查没有手工漂移。

冻结完成的判据不是文件被标成 read-only，而是任一实现选择都能追到当前 revision，任一合同改变都触发受影响任务重新接受，最终集成不需要猜测哪一方的局部约定优先。这样共享接口成为并行的起点，而不是并行结束后的冲突现场。

延伸阅读

• API 合同与请求响应示例
• Agent 改 API 的契约兼容门
• 集成合同边界测试
• 工具结果 Schema 演进