51 lines
2.9 KiB
Markdown
51 lines
2.9 KiB
Markdown
# 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. 防需求偏移（必须）
|
||
- 未更新 `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]`
|