66 lines
2.6 KiB
Markdown
66 lines
2.6 KiB
Markdown
|
# contracting.md（ai 必须遵守：契约成熟度与门禁规则）
|
|||
|
|
|
|||
|
|
本文件仅包含**编码智能体必须遵守**的契约约束与门禁规则（面向执行与校验）。
|
|||
|
|
|
|||
|
|
> 约定：若本文件与 `agents.md` 冲突，以 `agents.md` 为准；若本文件与 `spec/<module>/requirements.md` 或 OpenAPI 契约冲突，必须先修正文档再编码，禁止猜测。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 文件与字段硬约束
|
|||
|
|
|
|||
|
|
- 本模块的 OpenAPI 契约拆分为：
|
|||
|
|
- `openapi.provider.yaml`：本模块对外提供的 API（provider）
|
|||
|
|
- `openapi.deps.yaml`：本模块依赖的外部 API 契约（consumer 需求侧）
|
|||
|
|
|
|||
|
|
- 两份 OpenAPI 都必须在 `info` 下声明成熟度（全局标记，不按 operation 级）：
|
|||
|
|
- `info.x-contract-level: L0 | L1 | L2 | L3`
|
|||
|
|
|
|||
|
|
- provider 端接口（建议强制）：
|
|||
|
|
- `operationId` 必须存在且在同文件内唯一
|
|||
|
|
- 应通过 `x-requirements: [AC-...]` 或 requirements 的 traceability 表建立 AC 追踪
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 契约成熟度（L0-L3）最低要求
|
|||
|
|
|
|||
|
|
- **L0（占位/可 mock）**：允许 schema 粗粒度；仅用于并行启动与 mock。
|
|||
|
|
- **L1（可调用/可生成 sdk）**：关键请求/响应字段 required/optional 明确；基本状态码集合明确。
|
|||
|
|
- **L2（可验收/可契约测试）**：关键字段校验规则与错误语义稳定；可进行 provider-driven schema 校验。
|
|||
|
|
- **L3（可演进/可兼容治理）**：具备兼容策略与示例；可治理 breaking change。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. 细化路径（粗 → 细）执行规则
|
|||
|
|
|
|||
|
|
- 新增/调整 **AC** 会驱动契约细化；任何字段/错误语义/校验规则的新增，必须能追溯到某条 `AC-*`。
|
|||
|
|
- 当实现准备进入可合并状态（尤其是自动合并）时，必须先把 `openapi.provider.yaml` 提升到 **L2**。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. 门禁规则（软/硬）
|
|||
|
|
|
|||
|
|
### 4.1 feature 分支（软门禁）
|
|||
|
|
|
|||
|
|
允许：
|
|||
|
|
- 使用 `openapi.deps.yaml (L0/L1+)` 生成 mock/sdks，推进调用方开发。
|
|||
|
|
|
|||
|
|
禁止：
|
|||
|
|
- 未满足 `openapi.provider.yaml >= L2` 的情况下，将 provider 实现以“自动合并”方式进入 main。
|
|||
|
|
|
|||
|
|
### 4.2 main 分支（硬门禁）
|
|||
|
|
|
|||
|
|
满足以下条件前，禁止合并（或禁止自动合并）：
|
|||
|
|
- `openapi.provider.yaml >= L2`
|
|||
|
|
- 契约测试通过（响应符合 openapi schema）
|
|||
|
|
- openapi diff 检查通过（无未声明 breaking change）
|
|||
|
|
- 需求追踪检查通过（AC 引用未断裂）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. 最小检查清单（编码智能体自检）
|
|||
|
|
|
|||
|
|
- [ ] openapi 文件可解析
|
|||
|
|
- [ ] `info.x-contract-level`存在且为 L0-L3
|
|||
|
|
- [ ] provider: operationId 唯一
|
|||
|
|
- [ ] provider: 能追踪到 AC（x-requirements 或 traceability）
|