# AI 编码规格包入门套件

在让 AI 编码工具实现功能之前，先用这套文件把模糊需求变成可评审输入：

- `spec.md`
- `tasks.md`
- `acceptance-criteria.md`
- `evidence.md`

建议把这些文件放在 issue、PR 或仓库的变更目录里。评审者能拒绝范围漂移，QA 能直接写测试，这个规格包才算准备好。

---

## 1. spec.md

```md
# 功能规格：<功能名称>

负责人：
状态：草稿 | 待评审 | 已批准
最近更新：

## 背景
- 哪个系统、用户或工作流会变化？
- 当前行为是什么？
- 为什么现在需要改？

## 目标
- 变更上线后应该出现什么行为？

## 非目标
- 这次工作明确不改什么？
- 哪些相邻功能、重构或策略决策不在范围内？

## 需求
1. 系统必须...
2. 用户必须能够...
3. 现有行为必须继续...

## 边界情况
- 空输入或缺失输入：
- 权限或角色不匹配：
- 重试、重复请求或幂等：
- 旧客户端或旧数据状态：

## 约束
- 允许修改的文件或服务：
- 公开 API 或数据库契约：
- 性能、安全、隐私或灰度约束：

## 未决问题
- [ ] 问题：
  负责人：
  必须在什么时间前解决：
```

---

## 2. tasks.md

```md
# 任务拆解：<功能名称>

## 任务 1：<小实现切片>
允许修改：
- 

对应验收标准：
- AC-1：

必须证据：
- 测试：
- 日志、截图、fixture 或指标：

## 范围保护
实现不能：
- 
- 
```

---

## 3. acceptance-criteria.md

```md
# 验收标准：<功能名称>

## AC-1：正常路径
Given
When
Then

证据：
- 

## AC-2：无效或阻断状态
Given
When
Then

证据：
- 

## AC-3：保留现有行为
Given
When
Then

证据：
- 

## AC-4：回滚或失败路径
Given
When
Then

证据：
- 
```

---

## 4. evidence.md

```md
# 证据清单：<功能名称>

## 自动化检查
- [ ] 单元测试：
- [ ] 集成或契约测试：
- [ ] 回归测试：
- [ ] typecheck、lint 或 build 命令：

## 人工检查
- [ ] 截图或录屏：
- [ ] QA 评审：
- [ ] 产品负责人评审：
- [ ] 可访问性或移动端检查：

## 发布证据
- [ ] feature flag 或回滚开关：
- [ ] 日志查询或指标：
- [ ] 监控负责人：
- [ ] 支持或运维说明：

## 评审决策
是否可以合并：是 / 否
评审人：
原因：
后续事项：
```