spec

name	spec
description	当用户要写需求规约/spec/需求文档，或 grill-me 审问完成后使用。只谈需求不谈技术，产出 spec.md。关键词：需求、规约、spec、规格、做什么、需求文档。

spec — 需求规约（做什么）

触发词

需求、规约、spec、规格、做什么、需求文档、需求规约、写需求

概述

把"想做成什么样"写成一份正儿八经的需求规约文档。只谈需求，不谈技术——别提 React、别提 Postgres，就讲这东西给谁用、能干啥、每个功能算"做完了"的标准是什么。

这是 SDD 四台阶的第 1 阶（specify）。产物存 .agents/specs/{feature}/spec.md，是后续 plan/tasks/implement 的对齐基准。

何时该用

• grill-me 审问完成，需求已澄清
• 用户直接给了较完整的需求描述，需要固化成文档
• 已有 spec 但需求有变，需要更新

工作流

1. 收集需求来源

• 若刚走过 grill-me：读 grill 产出的澄清摘要
• 若用户直接给需求：基于用户描述，必要时补 1-2 个澄清问题（用 grill-me 的"一次一问+给推荐"原则）
• 若已有 spec.md：读现有内容，确认要改哪部分

2. 生成 spec.md

在 .agents/specs/{feature}/spec.md 写入（feature 用 kebab-case 命名，如 team-kanban）：

# {功能名} 需求规约

## 目标
一句话：这个功能/项目要解决什么问题、给谁用。

## 完成态（Done）
靠岸那一刻就能判断的完成状态。不是"出去了转一圈"，而是"带回三船香料"。
- {具体到可观测的状态变化，如"用户登录后跳转首页，session 写入数据库"}

## 用户角色
- 角色 A：能做什么
- 角色 B：能做什么

## 功能清单
### 功能 1：{名称}
- 描述：做什么
- 完成标准（DoD）：怎样算做完了（可验证的具体条件）
- 边界：明确不做什么

### 功能 2：{名称}
- ...

## 证据与验收（Proof）
谁来清点货舱、怎么算数。每条验收必须是机器可判的命令，不是"看起来对了"。
- 验收命令：{如 `pytest tests/test_auth.py -v`，含断言数量}
- 基线数字：{当前测试数/覆盖率，验收后只许 ≥ 基线}
- 反向验证：{故意制造一次失败，贴变红输出，还原后贴全绿——凡是"坏了没人会知道"的检查都要}

## 反作弊（Anti-Cheat · Harness）
不许抢商船凑数。把偷懒路径一条条写明白，点名禁止具体姿势。
- **基线不可退**：测试数/覆盖率 ≥ 基线，skipped = 0
- **点名禁止**：`.skip` / `todo` / 放宽断言 / mock 被测对象 / 删测试 / `|| true`——全算失败
- **判卷标准冻结**：测试、验收脚本、CI 配置碰都不许碰
- **反向验证**：亲手制造一次失败证明报警器会响，贴输出
- **三道止损**：同一验收连败 3 次换项 / 结果比基线差回滚如实报告 / 量出数字对不上就停

## 边界（Bounds）
只许走这三条航线，其他海域不准进。粮食够吃三十天，第二十天没找到就掉头。
- 白名单路径：{只允许改哪些路径＋新建文件，其余只读}
- 时间盒：{如"最多烧 2 小时，烧完交目前最优"}
- 不新增：{不新增流程/权限/依赖，必须加的写 BLOCKED.md}

## 取舍（Trade）
风暴里保货还是保船。冲突时船长得知道保哪个。
- 优先级：{如"算得对 > 做得全 > 做得快"}
- 冲突处理：{两个要求打架时的让步顺序}

## 非功能需求
- 性能：如响应 < 200ms
- 兼容性：如支持 Win/Mac
- 安全：如密码加密

## 明确不做（Out of Scope）
- {本期不做的，避免范围蔓延}

## 待澄清（如有）
- {还没定死的点，标注默认值}

## 我替领导拍的板
没问出口的每个决定一行：问题 → 默认值（标"猜的"）｜猜错的代价。领导发出前可改；执行者按默认走，不停下来等。
- {问题 1}：{默认值}（猜的）｜{猜错的代价}
- {问题 2}：{默认值}（猜的）｜{猜错的代价}

Harness 融合：模板中的「完成态 / 证据与验收 / 反作弊 / 边界 / 取舍 / 我替领导拍的板」六节来自 dev/leader skill 的目标七问 + 五种死法心法。当通过 goal_engineering 入口进入时，这些节为必填；独立使用 spec skill 时按需填写。

3. 让用户停下来读一遍

这是整个流程里性价比最高的一次检查。现在花两分钟看 agent 有没有理解错，能省掉后面两小时返工。

把 spec.md 路径告诉用户，请用户过目并指出要改的地方。

4.（可选）触发 clarify 澄清含糊点

如果 spec 里有含糊、有歧义、用户没交代清的地方，主动揪出来问（沿用 grill-me 一次一问原则）。最好在 spec 出来、还没进 plan 之前跑。

典型要揪的含糊点：

• "任务可以分配给负责人" → 一个任务能分给多个人吗？没人认领算什么状态？
• "支持导出" → 导出什么格式？导出到哪？

5. 用户确认后，主动建议进 plan

spec.md 已对齐。下一步建议进入 plan 定技术方案（技术栈/架构/接口/数据模型）。要现在开始吗？

坑点清单（Gotchas）

• 混入技术决策：spec 里出现"用 React""用 Postgres"= 跑偏了。技术是 plan 的事。spec 只讲"要什么"，不讲"怎么做"。
• 完成标准模糊："支持登录"不算 DoD，"用户可用账号密码登录，失败有提示，成功跳首页"才算。
• 范围蔓延：没写"明确不做"，后期会无限加功能。
• 不存档：spec 只在对话里没存文件，下次会话就丢了。必须写 .agents/specs/{feature}/spec.md。
• 不让人读就往下走：agent 自己觉得对了不够，必须让用户过目。

关键规则

• 绝不在 spec 里写技术选型（框架/数据库/库）。
• 必须为每个功能写可验证的完成标准（DoD）。
• 必须写"明确不做"边界。
• 必须存到 .agents/specs/{feature}/spec.md。
• 必须让用户确认后才进 plan。

参考

• assets/spec_template.md — spec.md 空白模板
• 上游 skill：grill-me（需求澄清）
• 下游 skill：plan（技术方案）