ai-robot-core/agents.md

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

## 0. 开始编码前（必须）
- 必须已读取（路径格式：`spec/<module>/...`）：
  - `spec/contracting.md`（契约硬规则）
  - `spec/<module>/requirements.md`（当前模块需求）
  - `spec/<module>/openapi.provider.yaml`（本模块提供）
  - `spec/<module>/openapi.deps.yaml`（本模块依赖，如存在）
- **版本化迭代规则**（CRITICAL）：
  - 读取 `requirements.md` 的 frontmatter，识别 `active_version` 字段（如 `”0.6.0-0.7.0”`）
  - **仅关注活跃版本的 AC**：历史版本（折叠在 `<details>` 中）的 AC 可跳过，不影响当前实现
  - 在代码注释、测试用例、commit message 中引用的 AC 编号，必须在活跃版本范围内
  - 若需要追加新需求，按 `docs/spec-product-zh.md` 第 4 节”版本化迭代规则”执行
- **长会话/复杂任务接续**：若当前任务满足 `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. 防需求偏移（必须）
- 未更新 `spec/<module>/requirements.md` 前，**禁止**改变业务规则、验收口径或用户可见行为。
- 代码/测试/提交必须可追溯到验收标准：
  - controller/endpoint 注释（或 `@Operation` 描述）必须包含 `[AC-...]`
  - 测试类名或测试用例名必须包含 `[AC-...]`
  - commit message 必须包含 `[AC-...]`

## 2. 接口契约与成熟度（必须，细则见 `spec/contracting.md`）
- OpenAPI 文件必须声明全局成熟度：`info.x-contract-level: L0|L1|L2|L3`。
- **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]`