核心目标其实只有一句话：
不要让 spec 只是“生成代码前的说明书”，而要让它变成“代码进入主干前的协作闸门”。
如果按这个目标来设计，OpenSpec/SDD 想提前发现冲突，流程上至少要做五件事：
一、把开发流程从“先写 spec”改成“先过 spec gate”
很多团队虽然写了 spec，但实际流程还是：
- 开发者改 spec
- AI / 人写代码
- 本地测试
- 提代码 PR
- 合并时才发现冲突
这个流程里，spec 只是输入材料，不是治理节点。 要改成下面这种：
- 提交
spec change - 做影响分析
- 先过 spec review / spec gate
- 再基于已批准 spec 生成代码
- 代码 PR 必须绑定 spec 版本
- CI 校验“代码是否符合 spec、是否破坏共享契约”
- 合并主干
也就是说，代码 PR 前面要再插一个 spec PR。
二、把 spec 分层，不要所有人改同一层
如果所有人都在同一份大而全的规约里改，冲突永远提前不了，只会更早把文档搞乱。
推荐最少拆成 4 层：
| 层级 | 作用 | 谁负责 | 是否允许频繁改 |
|---|---|---|---|
| L1：核心领域规约 | 术语、核心对象、主状态机、全局不变量 | 架构/领域 owner | 否 |
| L2：模块规约 | 子域行为、模块边界、输入输出 | 模块 owner | 适中 |
| L3：接口契约 | API / event / schema / error code | 接口 owner | 谨慎 |
| L4：实现规约 | AI 生成约束、目录结构、测试要求、代码风格 | 开发者/小组 | 是 |
这样设计的目的，是把冲突区分成两类：
- 高价值冲突：术语、状态机、契约兼容性
- 低价值冲突：表述、实现细节、局部策略
你要尽量让高价值冲突在 L1/L2/L3 被拦住，而不是等到代码合并。
三、每次改 spec，必须附“影响分析”
这是最关键的一步。 如果没有 impact analysis，spec review 很容易流于“看起来合理”。
建议每个 spec change 都强制写这 6 项：
| 项目 | 必答内容 |
|---|---|
| 变更目的 | 为什么要改，不改会怎样 |
| 影响对象 | 影响哪些模块/服务/角色 |
| 兼容性 | 是否向后兼容，是否破坏已有调用 |
| 状态变化 | 是否影响状态机、流程顺序、事件语义 |
| 数据变化 | 是否新增/删除/重命名字段、枚举、错误码 |
| 迁移方案 | 老逻辑怎么过渡，灰度/回滚怎么做 |
这个动作的价值在于： 你不是在问“这条 spec 对不对”，而是在问：
它会不会和系统里其他已存在的假设打架。
这一步越扎实，冲突越容易在实现前暴露。
四、建立“Spec Review”角色，不要只做代码评审
要让冲突前移，评审对象必须从代码扩展到规约。
建议最少有这几个角色：
| 角色 | 关注点 |
|---|---|
| 业务 owner | 业务语义是否正确，例外规则是否闭合 |
| 模块 owner | 是否破坏模块职责边界 |
| 接口 owner | 是否破坏 API / event 契约 |
| 测试/质量 owner | 是否可验证、是否有验收样例 |
| 架构 owner | 是否引入全局不一致、重复概念、状态失配 |
注意一个关键点： Spec Review 不是看文档写得漂不漂亮，而是找“共享假设冲突”。
评审 checklist 可以固定成下面这组：
- 是否引入了新的术语，和已有术语是否重复/冲突
- 是否改动了状态机，旧路径是否还成立
- 是否新增了例外分支，是否影响全局规则
- 是否修改了共享字段/枚举/错误码
- 是否影响下游服务、前端、数据分析、运营逻辑
- 是否需要版本化、灰度、兼容层
五、代码 PR 必须绑定 spec 版本
这是连接 spec 和代码的关键手段。
每个代码 PR 至少要带上：
- 关联的 spec 文档 / spec change id
- 对应的 spec version
- 本次实现覆盖的 spec 范围
- 未覆盖项 / 偏差项说明
否则就会出现两个问题：
- spec 改了，但代码不是按这个版本实现的
- 代码改了，但没人知道它偏离了哪个规约
建议形成这样的规则：
没有绑定 spec 的代码 PR，不允许合并。
进一步一点：
如果代码行为和 spec 不一致，优先阻断合并，而不是事后补文档。
六、让 CI 校验“共享契约”，不是只跑单元测试
这是“提前发现冲突”真正落地的地方。 如果 CI 只验证本模块测试，那它只能发现局部问题，发现不了多人协作冲突。
至少建议上 4 类自动校验：
1. Schema / API diff 校验
检测：
- 字段删除
- 字段重命名
- required 变化
- 枚举值变更
- 响应结构变化
目的：防止“我本地都过了，但下游炸了”。
2. Event Contract 校验
如果你们有事件驱动架构，要校验：
- event name 是否变了
- payload 是否兼容
- 语义是否变化
- producer / consumer 假设是否一致
3. 状态机 / 业务不变量校验
例如：
- 订单不能从
INIT直接到REFUNDED - 已支付订单必须有支付凭证
- 已取消订单不能发货
这类规则一旦写成自动化检查，很多跨分支冲突会在合并前暴露。
4. Cross-module acceptance tests
不是只测单服务，而是测跨模块关键链路：
- 下单 -> 支付 -> 发货
- 提交申请 -> 审批 -> 回调
- 创建任务 -> 执行 -> 结果通知
多人并行时，最容易出问题的恰恰是这种链路级行为。
七、把“AI 生成代码”放在 spec 冻结之后，而不是之前
如果 OpenSpec 配 AI 生成代码，时序很重要。
不建议这样：
- 开发者先写一个 spec 草稿
- AI 立即生成实现
- 再看合不合适
更建议这样：
- 开发者提交 spec change
- spec review 通过
- spec version 冻结
- AI 基于冻结版本生成代码、测试、迁移脚本
- 代码 PR 只允许实现，不允许偷改语义
原因很简单：
- 草稿 spec 通常还带着个人理解偏差
- AI 会把这个偏差快速固化成代码
- 后面再改 spec，意味着代码也要重做
- 这会让团队误以为“AI 提速了”，但实际增加了返工
所以正确顺序是：
先冻结共享语义，再让 AI 放大执行效率。
八、建立“双主线合并”机制：spec 主线 + code 主线
这是流程设计里非常实用的一点。
主线 1：Spec Main
维护：
- 当前生效规约
- 版本历史
- 术语表
- 契约定义
- 状态机
- ADR / 变更记录
主线 2：Code Main
维护：
- 当前主干实现
- 测试
- 配置
- 迁移脚本
二者关系应该是：
- Spec Main 先于 Code Main
- Code Main 上的变更必须能追溯到某个已批准 spec version
这样做的好处是，当多人并行时，你能明确区分：
- 这是规约冲突
- 还是实现冲突
- 还是代码未跟上规约
否则所有问题最后都会混在代码 PR 里。
九、为冲突设计专门的“裁决机制”
多人并行时，最怕的不是有冲突，而是冲突没人裁决。
建议明确三类裁决规则：
| 冲突类型 | 谁裁决 | 裁决原则 |
|---|---|---|
| 业务语义冲突 | 业务 owner | 以统一业务口径为准 |
| 契约兼容性冲突 | 接口/平台 owner | 以兼容优先为准 |
| 领域边界冲突 | 架构 owner | 以边界清晰、职责单一为准 |
同时规定：
- 谁能改 L1 核心规约
- 什么变更必须升级版本
- 什么变更必须通知依赖方
- 哪些冲突不能在代码 PR 里“顺手解决”
这很重要。 因为很多团队真正的问题不是没流程，而是：
所有人都能提意见，但没人能拍板。
十、在 spec 里强制写“反例”和“禁止项”
这是很容易被忽略，但对 AI 特别有用的一点。
只写“应该怎么做”不够，还要写：
- 不允许什么状态转换
- 不允许哪些字段组合
- 不允许哪些兼容性破坏
- 不允许哪些默认推断
例如：
- 不允许删除已有 public 字段
- 不允许修改已发布 event 的语义
- 不允许跨模块直接读对方内部表
- 不允许将“失败可重试”默认推导成“无限重试”
这样做有两个好处：
- 人评审时更容易发现冲突
- AI 生成时更不容易“合理脑补”
十一、把冲突发现前移到“每日同步面”，而不是只靠 PR
只靠 PR 还是太晚。 建议在团队同步里增加一个很轻量的 spec 视角：
每日或每两日同步的最小模板
- 我改了哪条 spec
- 影响了哪些共享契约
- 需要谁关注
- 哪些点还没定
这样做不是为了开会，而是为了让并行开发里的“潜在碰撞面”尽早浮出来。
尤其适合：
- 多模块联动
- 状态机复杂
- schema 变更多
- AI 批量生成代码快于人类 review 的场景
十二、推荐你们团队可落地的一版最小流程
如果不想一下子搞太重，我建议先上一个 MVP 版流程：
阶段 1：提 spec change
开发者提交：
- 变更内容
- 影响分析
- 是否改接口/状态机/字段
阶段 2：小范围 spec review
由：
- 业务 owner
- 模块 owner
- 依赖方代表
做 15~30 分钟评审，先拍板语义。
阶段 3：冻结 spec version
通过后生成一个版本号，比如：
order-spec v1.12refund-contract v2.3
阶段 4：AI / 人实现
要求：
- 只能按冻结版本实现
- 偏离必须重新提 spec change
阶段 5：CI 自动检查
至少检查：
- schema diff
- contract compatibility
- 核心链路验收测试
阶段 6：代码 PR 合并
PR 模板里必须写：
- spec version
- 覆盖范围
- 偏差项
- 回滚方式
这是最小但有效的一套。
十三、一个最重要的原则
如果你只记一个原则，我建议记这个：
不要让“改 spec”成为个人行为，要让“批准 spec”成为团队行为。
因为多人并行时，真正需要共享的不是代码细节，而是：
- 术语
- 边界
- 契约
- 状态
- 不变量
这些东西如果不共享确认，AI 只会把各自的局部理解更快地编码出来。
十四、最后给你一个判断标准
如果你们团队做到下面这些，OpenSpec 才算真正开始“提前发现冲突”：
| 判断项 | 达标表现 |
|---|---|
| spec 是否先于代码评审 | 代码实现前先过 spec change |
| spec 是否有 owner | 核心规约有人裁决 |
| 是否有影响分析 | 每次变更都知道影响谁 |
| 是否做契约自动检查 | CI 能发现共享接口破坏 |
| PR 是否绑定 spec version | 代码与规约可追溯 |
| 是否有跨模块验收 | 不是只测单模块 |
| AI 是否基于冻结规约生成 | 不拿草稿直接生成主实现 |
如果这些都没有，那 OpenSpec 更多只是“提高单人开发效率”； 如果这些逐步建立起来，它才会变成“多人协作的冲突前哨”。
如果你愿意，我下一步可以直接给你补两份更实用的东西之一：
- 一份可直接套用的《OpenSpec 团队协作流程模板》
- 一份可直接放到仓库里的《spec change / code PR 模板》
如果你是想真落地，我更建议我直接给你第 2 份。
