146 lines
5.2 KiB
Markdown
146 lines
5.2 KiB
Markdown
|
# contracting-guide.md（给人看的：契约治理与落地指南）
|
|||
|
|
|
|||
|
|
本文档面向人类（架构/平台/DevOps/测试/协作负责人），用于说明如何将契约成熟度与门禁策略落地到实际工程中。
|
|||
|
|
|
|||
|
|
> 编码智能体必须遵守的硬规则见项目根目录 `agents.md` 与 `spec/contracting.md`。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 目标
|
|||
|
|
|
|||
|
|
- 降低 AI 开发过程中的需求偏移（通过可执行门禁约束）
|
|||
|
|
- 支持多窗口并行：调用方先行、提供方后补实现
|
|||
|
|
- 降低跨模块联调成本：契约成为单一可信源（SSOT）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. OpenAPI 拆分与职责
|
|||
|
|
|
|||
|
|
- `openapi.provider.yaml`
|
|||
|
|
- 描述“本模块对外提供什么能力”
|
|||
|
|
- 由提供方维护并对其实现负责
|
|||
|
|
|
|||
|
|
- `openapi.deps.yaml`
|
|||
|
|
- 描述“本模块依赖外部什么能力”（调用方需求侧契约）
|
|||
|
|
- 由调用方先起草（draft），用于生成 mock / sdk
|
|||
|
|
- 提供方后续可认领实现或提出映射/替代方案
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. 契约成熟度（L0-L3）如何在团队中使用
|
|||
|
|
|
|||
|
|
建议把 `info.x-contract-level` 当作“里程碑标签”，在代码评审/门禁中用于决策，而不是装饰。
|
|||
|
|
|
|||
|
|
- L0：允许快速并行启动（mock 驱动）
|
|||
|
|
- L1：允许调用方完成主流程开发（sdk/调用可稳定）
|
|||
|
|
- L2：允许提供方实现进入可合并门槛（契约测试可跑）
|
|||
|
|
- L3：允许进入兼容治理与长期演进阶段（deprecate / examples / changelog）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. 门禁落地点（实现建议）
|
|||
|
|
|
|||
|
|
> 裸 git 场景下，推荐以服务端 hooks 作为最终防线。
|
|||
|
|
|
|||
|
|
### 4.1 git hooks
|
|||
|
|
|
|||
|
|
- 本地 hooks（可选）：`pre-commit` / `pre-push`
|
|||
|
|
- 目的：快速反馈，减少无效 push
|
|||
|
|
- 注意：可被跳过，不能作为最终门禁
|
|||
|
|
|
|||
|
|
- 服务端 hooks（推荐）：
|
|||
|
|
- `pre-receive` / `update`
|
|||
|
|
- 用于 main 分支硬门禁：不符合规则直接拒绝
|
|||
|
|
- `post-receive`
|
|||
|
|
- 触发构建、测试、契约校验
|
|||
|
|
- 通过后执行自动合并（若你们实现了 auto-merge 流程）
|
|||
|
|
|
|||
|
|
### 4.2 构建阶段（mvn verify）
|
|||
|
|
|
|||
|
|
建议在构建阶段串联以下检查：
|
|||
|
|
- openapi 解析与 lint
|
|||
|
|
- openapi diff（breaking change 检测）
|
|||
|
|
- provider 契约校验（响应符合 schema）
|
|||
|
|
- 需求追踪校验（AC 引用未断裂）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. 推荐的软/硬门禁策略
|
|||
|
|
|
|||
|
|
- feature 分支：软门禁
|
|||
|
|
- 允许并行推进、允许契约处于 L0/L1
|
|||
|
|
- 但不允许自动合并进入 main
|
|||
|
|
|
|||
|
|
- main 分支：硬门禁
|
|||
|
|
- 至少要求 provider 达到 L2
|
|||
|
|
- 契约测试与 diff 检查必须通过
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. Git Cadence（提交节奏）与 Hooks 门禁（落地建议）
|
|||
|
|
|
|||
|
|
本节用于将 `agents.md` 中的“提交与同步（Git Cadence）”规则落到工程实现（裸 Git/中央仓库）。
|
|||
|
|
|
|||
|
|
### 6.1 提交节奏（建议与约束）
|
|||
|
|
|
|||
|
|
- **提交粒度（推荐与 `agents.md` 一致）**：
|
|||
|
|
- `spec/<module>/` 下的规范文件变更必须**单独 commit**（Spec-only commit），不要与实现代码混在同一提交。
|
|||
|
|
- 实现代码按 `spec/<module>/tasks.md` 的**子任务完成**为粒度提交。
|
|||
|
|
|
|||
|
|
- **必须提交的触发点**（满足任一，且必须通过最小自测）：
|
|||
|
|
- 任何 `spec/<module>/` 规范文件发生变更。
|
|||
|
|
- 任一 `spec/<module>/tasks.md` 子任务完成（从 ⏳/🔄 → ✅）。
|
|||
|
|
- 触发 `docs/session-handoff-protocol.md` 的阈值并准备会话接续前。
|
|||
|
|
|
|||
|
|
- **最小自测（与 `agents.md` 对齐）**：
|
|||
|
|
- 能编译/构建通过。
|
|||
|
|
- 单元测试通过。
|
|||
|
|
- 至少一条契约校验或接口冒烟通过（与本次变更相关）。
|
|||
|
|
|
|||
|
|
- **提交信息要求**：
|
|||
|
|
- commit message 必须包含 `[AC-...]`，便于需求追踪与门禁脚本校验。
|
|||
|
|
|
|||
|
|
### 6.2 hooks 分层：feature 软门禁 / main 硬门禁
|
|||
|
|
|
|||
|
|
> 原则：feature 分支尽量给快速反馈；main 分支必须可验收、可回滚、可自动合并。
|
|||
|
|
|
|||
|
|
#### 6.2.1 feature 分支（软门禁）
|
|||
|
|
|
|||
|
|
建议做（可在本地 `pre-commit/pre-push` 或服务端提示性检查）：
|
|||
|
|
- commit message 包含 `[AC-...]`
|
|||
|
|
- OpenAPI 变更时：
|
|||
|
|
- YAML 可解析
|
|||
|
|
- `info.x-contract-level` 存在且为 L0-L3
|
|||
|
|
- provider: `operationId` 唯一
|
|||
|
|
|
|||
|
|
允许：
|
|||
|
|
- `openapi.deps.yaml` 处于 L0/L1，用于 Mock/SDK 并行开发。
|
|||
|
|
- provider 实现处于 L0/L1（但仅限 feature，不得进入 main 的自动合并路径）。
|
|||
|
|
|
|||
|
|
#### 6.2.2 main 分支（硬门禁）
|
|||
|
|
|
|||
|
|
建议在服务端 `pre-receive/update` 中强制：
|
|||
|
|
- Provider 契约成熟度门槛：`openapi.provider.yaml >= L2`
|
|||
|
|
- 契约测试通过（Provider 响应符合 OpenAPI schema）
|
|||
|
|
- OpenAPI diff 检查通过（无未声明 breaking change）
|
|||
|
|
- 需求追踪检查通过（AC 引用未断裂）
|
|||
|
|
|
|||
|
|
### 6.3 推荐的实现位置（裸 Git）
|
|||
|
|
|
|||
|
|
- **服务端 hooks（最终防线）**：
|
|||
|
|
- `pre-receive` / `update`：拒绝不符合 main 硬门禁的 push
|
|||
|
|
- `post-receive`：触发构建/测试/契约校验/（可选）自动合并流程
|
|||
|
|
|
|||
|
|
> 注：具体脚本实现（如何解析 OpenAPI、如何做 diff、如何跑契约测试）属于工程实现细节，建议以仓库内脚本（如 `scripts/`）承载，并在 CI/构建中复用。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. 检查清单（适合做成脚本/CI step）
|
|||
|
|
|
|||
|
|
- OpenAPI 可解析
|
|||
|
|
- `info.x-contract-level` 存在且合法
|
|||
|
|
- provider operationId 唯一
|
|||
|
|
- AC 追踪一致性（x-requirements 或 traceability 表）
|
|||
|
|
- 合并门槛：provider >= L2
|
|||
|
|
- breaking change 检测：无未声明破坏性变更
|