# ClickVibe Issue 契约:可自动开发的 issue 写法

> 配套 [product-blueprint.md](product-blueprint.md) §"自动化边界"。目标:让 issue 能被 ClickVibe **自动选取 → 自动开发 → 自动 review**,同时不加重提 issue 的负担。

## 核心原则

**三个环节,各只需一个必读项:**

| 环节 | 必读项 | 缺了会怎样 |
|---|---|---|
| 自动选取 | **依赖**(Blocked by #NN / 无) | 可能选了被阻塞的 issue |
| 自动开发 | **目标**(做什么) | agent 自己脑补,风险最大 |
| 自动 review | **验收标准**(可判定 check) | 没有判据,通过/失败靠猜 |

## 最小集合(3 项必填)

日常 issue 只需三行:

```markdown
## 目标
一句话说明要做什么。

## 验收标准
- [ ] 一条可判定的检查(能明确说"通过/不通过"的行为或测试)

## 依赖
无  或  Blocked by #NN
```

**30 秒可提一个可自动开发的 issue。**

## 可选增强(有则更好,缺了不卡)

| 项 | 何时值得写 | 缺失后果 |
|---|---|---|
| **约束/边界** | 有明确"不要做 X"的边界 | agent 可能多做,review 能兜住(风险中) |
| **入口** | 测试/运行命令特殊,agent 找不到 | agent 自己读 package.json/README,慢但不卡 |

```markdown
## 约束
不要改动 X 模块;不要自动重发非幂等消息。

## 入口
运行 `pnpm test` 验证;本地起 `go run ./cmd/afu` 复现。
```

## 分级模板

按 issue 复杂度选择,不必每次都写全:

```
简单(一行):  目标一句 + 验收一条
  "给欢迎语加重试,失败 3 次后标记 failed。验收:重试次数可配且日志可见。"

标准(三行):  目标 + 验收 + 依赖
  简单版 + "依赖:无"

完整(复杂):  目标 + 验收 + 依赖 + 约束 + 入口(必要时加 关联/问题/非目标)
  参考 afu #103 的全格式(关联/问题/目标/实现要求/验收标准/非目标)。
```

## 验收标准怎么写才"可自动判定"

- ✅ 好:行为或测试,机器/agent 能验证
  `- [ ] 重试 3 次后状态标记为 failed 且日志输出原因码`
- ❌ 模糊:无法判定
  `- [ ] 功能正常` / `- [ ] 处理好各种情况`

## 机器可读约定(自动选取用)

- **依赖**:固定写 `依赖: 无` 或 `依赖: Blocked by #NN`(多依赖逗号分隔),不要散在正文
- **状态 label**(可选):`ready` / `blocked` / `wip` 帮助自动选取跳过非 ready
- 验收标准统一用 `- [ ]` checklist,ClickVibe 以"全勾 = 通过"为 review 判据

## ClickVibe 侧的支持(待实现)

- 提 issue 时给出**最小模板引导**(三个空:目标/验收/依赖)
- 自动选取前**校验契约**:缺依赖或验收 → 提示补齐,不硬选
- review 时以验收 checklist 为判据,非空泛判断