在微服务中，接口定义常位于独立契约仓，业务仓依赖 CI 生成的 SDK 或 protobuf 产物。Agent 最容易犯的错误是：
- 修改业务调用，却没有先修改契约；
- 直接手改业务仓里的生成文件；
- 假设远端 CI 已经生成新版本；
- 在依赖未更新时继续编写大量下游代码；
- 编译失败后把问题归因于环境。
这类任务不能只靠“记得先改接口”，应设置硬暂停点。
flowchart TD
A[更新契约仓主分支] --> B[创建契约功能分支]
B --> C[修改源定义并本地提交]
C --> D{用户确认提交内容}
D -->|通过| E[推送并创建 PR/MR]
D -->|暂缓| T[下游保留 TODO]
E --> F{远端 CI 生成产物完成?}
F -->|是| G[业务仓更新依赖并重新生成/vendor]
F -->|否| T
G --> H[确认生成文件确由工具更新]
H --> I[实现下游业务代码]
展示：
- 源定义 diff；
- 兼容性判断；
- commit SHA；
- 将创建的目标分支和 PR/MR。
用户确认后才推送。
不能根据时间推测 CI 完成。应查询流水线状态，并让用户确认可消费的版本已经生成。
只有此时，业务仓才能执行依赖更新和生成命令。
契约变更至少检查：
- 是否删除或重命名已有字段；
- 字段编号是否复用；
- 枚举默认值和未知值处理；
- 新字段在旧客户端中的默认行为；
- RPC 超时、错误语义和幂等性是否变化；
- 所有调用方是否能独立升级；
- 数据库或消息中的历史数据能否被新版本读取。
兼容性结论应以功能分支相对主分支的完整变更为准。
- 生成文件只由官方工具或仓库既有命令产生；
- 不通过手工编辑制造“临时可编译”；
- 更新依赖后检查 lockfile、module 文件和生成目录的真实 diff；
- 不相关的大范围生成变化应停止并排查工具版本；
- 若暂时跳过契约流程，下游只实现不依赖新类型的部分，并留下明确 TODO。
契约流程的关键不是自动运行更多命令，而是把“未完成上一步就禁止进入下一步”写成 Agent 无法忽略的硬规则。这是多仓 Skill 比普通操作文档更有价值的典型场景。