# agents.md（ai 编码硬规则，必须遵守）

## 0. 开始编码前（必须）
- 必须已读取（路径格式：`spec/<module>/...`）：
  - `spec/contracting.md`（契约硬规则）
  - `spec/<module>/requirements.md`（当前模块需求）
  - `spec/<module>/openapi.provider.yaml`（本模块提供）
  - `spec/<module>/openapi.deps.yaml`（本模块依赖，如存在）
- **长会话/复杂任务接续**：若当前任务满足 `docs/session-handoff-protocol.md` 中的触发条件，**必须**先读取并持续更新 `docs/progress/{module}-{feature}-progress.md`。
- 若上述任一文档缺失、冲突或内容不明确：
  - **禁止开始实现**
  - 必须在 `spec/<module>/tasks.md` 记录“待澄清”并停止

## 1. 提交与同步（Git Cadence，必须）
- **提交粒度**：
  - `spec/<module>/` 下的规范文件变更必须**单独 commit**（不得与实现代码混在同一 commit）。
  - 实现代码按 `spec/<module>/tasks.md` 的**子任务完成**为粒度提交。
- **提交触发点**（满足任一且必须通过“最小自测”）：
  - 任何 `spec/<module>/` 规范文件发生变更。
  - 任一 `spec/<module>/tasks.md` 子任务完成（从 ⏳/🔄 → ✅）。
  - 触发 `docs/session-handoff-protocol.md` 阈值并准备会话接续前。
- **最小自测（必须）**：
  - 能编译/构建通过。
  - 单元测试通过。
  - 至少一条契约校验或接口冒烟通过（与本次变更相关）。
- **提交质量（必须）**：
  - **严禁**提交编译不通过或未通过最小自测的代码（不允许 checkpoint commit）。
  - commit message 必须包含关联的验收标准 ID：`feat/fix: <desc> [AC-...]`。

## 2. 接口契约与代码对齐（必须）
- OpenAPI 文件必须声明全局成熟度：`info.x-contract-level: L0|L1|L2|L3`。
- **契约升级同步校验**：当 `openapi.provider.yaml` 提升到 L2（或补充 required/enum/format 等约束）后，必须同步补齐代码校验：
  - 更新 DTO/Controller 的校验注解（如 `@Valid`, `@NotBlank`, `@NotNull`）。
  - 补充至少 1 条针对该契约约束的测试用例。
- **Provider 合并门槛**：`openapi.provider.yaml` **< L2** 时，禁止将实现代码自动合并到 main。
- **Consumer 并行规则**：允许在 feature 分支基于 `openapi.deps.yaml` 的 **L0/L1** 级别进行并行开发（Mock/SDK/页面流），无需等待提供方实现。

## 3. 自动合并门槛（全通过才允许）
- 单元测试通过。
- 契约测试通过（Provider 响应符合 OpenAPI Schema，满足 L2 要求）。
- OpenAPI Diff 检查通过（无未声明 breaking change）。
- 需求追踪检查通过（AC 引用未断裂，且符合 `spec/contracting.md` 的自检清单）。

## 4. 分支与提交规范
- 分支：`feature/<AC-ID>-desc` 或 `fix/<AC-ID>-desc`
- commit：`feat/fix: <desc> [AC-ID]`