contract-first

契约优先（Contract-First / Consumer-Driven Contracts）

多端并行开发的项目（前端 + 后端，或再加多个服务），最容易炸在"连接"那一刻：

后端把 userName 改成 user_name，忘了通知前端。两边各自"自测通过"，一集成——白屏。两份文档各自为真，合起来是假的。

契约优先把接口当成一份唯一真相源（CONTRACT.md）：所有数据接口只定义一次，各端照它各做各的，谁都不许私自偏离。它和 living-docs-governance 是姊妹篇——那套防"项目文档"漂移，这套防"端与端之间的接口"漂移。

学名：这套就是 消费者驱动契约（Consumer-Driven Contracts, CDC）/ 契约测试（contract testing）。"消费方需求先行"=CDC 核心；"后端写返回符合契约的测试"=提供者验证（provider verification）；标杆工具是 Pact，契约规格常用 OpenAPI/Swagger。

什么时候启用

• 项目分前端 + 后端（或多个服务），且各端可能并行开发。
• 接口字段老对不上：userName vs user_name、类型不符、枚举值不一致。
• 某端为渲染一个页面要调 5 个接口拼数据。
• 某端改了接口忘了通知别人，集成时才发现。

不要用在只有单端、不存在跨端集成的项目上——那时退化成单层，用 living-docs-governance 即可。接口少、单人、不会漂移时也别上，过度工程化。

两种协作模式（关键：选对你的现实）

这套契约协作有两种落地方式，纪律一致、组织方式不同：

模式 A — 单会话多 agent（中心化派活）

一个支持多 agent 的会话里，契约拥有者派出前端 / 后端（及更多服务工人）并行干活，最后由它集成对账。Claude Code 可使用 contract-director、frontend-dev、backend-dev；Codex 可由当前 agent 持有契约并使用内置 worker，任务提示中明确端别、文件所有权和“只读契约”的边界。适合一人一个会话内推进、需要实时编排时。

模式 B — 多终端各自跑（去中心化，契约当异步媒介）⭐ 更贴近真实团队

终端1 跑前端、终端2 跑后端、终端N 跑某个服务，各端完全独立、上下文隔离，没有一个活的主任在线派活。协调的唯一媒介就是那份 CONTRACT.md 文件：

• "主任"在这里退化成"契约拥有者"——就是定契约、有权改契约那个人/终端（很可能是你本人或某个指定终端），不是实时调度器。
• 各端要改接口时，不存在"喊一个在线 agent"，而是提一条"契约变更请求"：写进约定位置（如 CONTRACT.md 顶部的"待定变更"区，或 PROJECT_LOG.md 追加一条 contract-request），由契约拥有者评估后更新契约，各端再各自重新拉取对齐。
• 适合双终端/多终端、多人、跨时区——这才是大多数真实前后端团队的样子。

两种模式的铁律完全相同：接口只在 CONTRACT.md 定义一次；各端只读不改；要改接口必须先改契约，绝不在实现里私自偏离。

宿主适配：Claude Code 的 /contract 与自定义 agents 是交互适配层；Codex / ChatGPT 直接调用 $contract-first 并由当前 agent 执行同一流程。没有可用子 agent 时退化为顺序执行，不得因此跳过契约前置、提供方验证或集成对账。

三条核心纪律

1. 契约是唯一真相源，只有一个拥有者，且分两层

CONTRACT.md 分两层写，别单层平铺（借 GitHub Spec Kit 的 constitution + specify 思路）：

• 契约宪法层（文件顶部，很少变，所有接口共享的铁律）：字段命名规范（统一 camelCase 还是 snake_case）、类型铁律（19 位商品 ID 必须 string、金额 number 保留 2 位、状态用枚举）、版本策略、"实现偏离即报错"的硬规则。
• 具体契约层（每个接口一段）：本接口的方法 + 路径、字段表、错误码。

具体契约必须服从契约宪法。所有接口只在 CONTRACT.md 定义一次，各端只读；改契约的权力归契约拥有者（模式 A 是 director，模式 B 是指定的人/终端）。要改接口 → 提契约变更请求 → 拥有者改契约 → 各端再对齐。绝不在实现里单方偏离契约——这是头号集成杀手。