spec

name	spec
description	需求拆解与文档化——通过对话「澄清→拆解→文档化」把模糊需求拆为一文一规则、≤100 行/份、互不重叠的小规则 spec，落盘 .bb-spec/docs/spec/；启动即进入只读对齐、方案获批后才写；INDEX.md 汇总索引、GLOSSARY.md 术语权威源仅由本 skill 维护（合入 PRD 增量、按需增补多语言别名）、禁跨文档引用、每文档结尾必有可测试的具体例子。触发：/spec、整理需求、把功能写成 spec、需求拆解、PRD 出来后要拆规则。跳过：还没想清楚要解决什么问题（→/prd）、已有 spec 想改细节（→/revise）。

Spec 需求拆解与文档化

把模糊需求通过对话澄清 → 拆解 → 文档化，输出互不重叠、各自只讲一件事的"小规则"文档。

核心原则

1. 方案先对齐再落盘：启动即进入只读对齐阶段（禁止任何写盘），澄清与拆解全程只读，方案获用户明确批准后才写文档（❌ 澄清没结束就先建 spec 文件）
2. 一文一规则：每文档 ≤ 100 行，只描述一条独立逻辑/约束
3. 先澄清再写：禁止脑补，对话把假设和边界讲清楚
4. 必须举例：每文档结尾一个具体、可被测试的例子
5. 强制拆解：发现多个关注点时拆为多份文档
6. 按需加载结构：frontmatter name + description → INDEX.md 索引
7. 自主独立：每份自包含，禁止跨文档引用（无"详见/参见/复用 xxx.md"）
8. 语言跟随用户：正文用用户的工作语言（默认随对话语言），标识符/API 名/错误码保持英文
9. 纯净现态：spec 只描述当前系统行为，不携带变更历史或过渡标记；废弃规则直接删文件，git 是变更追溯的唯一来源
10. 术语单一权威源：${DOCS_DIR}/spec/GLOSSARY.md 登记全项目术语（英文锚点 + 可判定定义 + 多语言别名），仅 /spec 可写；谁使用、谁对齐、按需增补——只登记本次实际触及的术语，禁全量批量翻译；规则文档正文直接使用已登记术语，不写"见 GLOSSARY"；用户输入中混用的多语言写法（如同句出现「订单」与「注文」）一律经锚点归一理解，产出文档内同一术语只用当前工作语言的登记别名一种写法

---

工作流

步骤 03 在 plan 模式内（只读澄清对齐），步骤 410 在 plan 模式外（落盘 + 归档 PRD + commit）。

步骤 0a：进入 plan 模式

立即声明进入只读对齐阶段（本阶段禁止任何写盘）。后续 0~3 步全在只读态完成——读配置、盘点 PRD、递进澄清、冲突检测、拆解质检与方案展示，均不写盘。

步骤 0b：读取项目配置 + 盘点 PRD 与已有 spec

cat .bb-spec.yaml 2>/dev/null

有 base_dir → 用其值作为 bb-spec 根目录（如 base_dir: my/bb → spec 目录为 my/bb/docs/spec/）；文件不存在或无该字段 → 缺省 .bb-spec。${DOCS_DIR} = <base_dir>/docs，后续所有路径基于此值。

盘点待消费 PRD（PRD 由 /prd 头脑风暴产出，每个需求是一个目录：OVERVIEW.md + 一份或多份子需求文档，是本次需求的上游输入）：

ls ${DOCS_DIR}/prd/ 2>/dev/null | grep -v '^\.archive$'  # 活动 PRD；.archive/ 是已消费归档，跳过

• 不存在/为空 → 跳过
• 存在 → 列出活动 PRD 目录，用 question 工具 让用户选择是否以某个 PRD 目录作为本次需求输入。选定后先读 OVERVIEW.md 索引，再完整读取其全部子需求文档与 GLOSSARY.md 术语增量（如有）：
  • PRD 已明确的内容（目标 / 非目标 / 用户故事 / 用例 / 验收 / 验证路径）视为已澄清，步骤 1 不重复提问
  • PRD 的"开放问题"（OVERVIEW 全局 + 各子需求局部）并入下方待确认清单，随三类点一起请用户裁决
  • PRD 的 GLOSSARY.md 增量与权威源逐条比对：全新术语 / 新别名 → 记入合入队列（步骤 5 落盘）；定义与既有条目有出入 → 按冲突分析简报格式呈现请用户裁决
  • PRD 正文使用了权威源与增量均未登记的专有名词 → 不视为已澄清，并入待确认清单
  • 选定 PRD 在步骤 7 会被 git mv 到 ${DOCS_DIR}/prd/.archive/，与 spec 落盘同 commit
  • 步骤 10 完成简报标注来源 PRD 目录名（归档后路径）

cat ${DOCS_DIR}/spec/INDEX.md 2>/dev/null || ls ${DOCS_DIR}/spec/ 2>/dev/null
cat ${DOCS_DIR}/spec/GLOSSARY.md 2>/dev/null  # 术语权威源（锚点 + 定义 + 多语言别名）

• 不存在/为空 → 跳过，进入步骤 1
• 存在 → 完整读 INDEX.md，打开相关文档，识别三类点：
  • 冲突：新需求与既有规则互斥
  • 必须遵守：跨规则共享硬约束（如错误码格式、时间精度）
  • 待确认：重叠或边界模糊，需用户裁决（新增/修订/合并/放弃）
• 呈现三类清单给用户，用 question 工具 逐项收集裁决后再继续

代码 vs Spec 冲突检测：对每条新增/修改的规则，用 codegraph 或 grep 检查相关代码的实际行为。若代码行为与规则描述不一致，在三类清单中标注该冲突，并附冲突分析简报辅助用户判断：

### 冲突：<一句话描述>
| | 代码现状 | Spec 定义 |
|---|---|---|
| 行为 | <代码实际做了什么> | <spec 要求做什么> |
- 保留代码：<理由——如已上线验证、覆盖了 spec 遗漏的边界、性能更优>
- 遵循 Spec：<理由——如更贴合业务意图、更安全、当前代码是历史妥协>
- **建议**：<推荐方向> — <一句话理由>
- **代价**：<选该方向的改动范围与风险>

变更类型判定（修改或废弃已有 spec 时）：

• 修改：直接编辑原文件内容，不添加任何变更标记。Plan 阶段通过 git diff 读取具体内容差异
• 废弃：直接删除 spec 文件 + 从 INDEX.md 移除条目。Plan 阶段通过 git show main:<path> 读取旧内容生成清理计划

步骤 1：递进式澄清（核心环节，禁止脑补）

铁律：用户没明说的每个细节都是"未定项"，必须问出来——禁止用"常见做法/合理默认"替用户拍板。

已选定 PRD 时：先从 PRD（OVERVIEW + 各子需求文档）的用户故事、用例、验收、验证路径中提取各维度答案，只对 PRD 未覆盖的维度提问——这是 PRD 的价值兑现点，禁止重复问 PRD 已回答的问题。

能自查的不问：每个维度提问前，先查既有 spec 与相关代码能否自答——能自答的呈现"结论 + 依据（spec 条目 / 代码行为）"请用户确认或推翻，不开放式提问；自查结果与用户本次意图相左时，按步骤 0b 的冲突分析简报格式呈现请用户裁决。

术语锚定：澄清中触及的每个专有名词先对照 GLOSSARY——已登记 → 沿用其锚点与定义；未登记、或已登记但缺当前工作语言别名 → 并入待确认，与用户对齐定义/写法（禁自行翻译不经确认）后记入合入队列，随步骤 5 落盘。

怎么问：逐维度深挖，不要一次撒一堆问题。每轮锁定 1 个维度，问 1-3 个递进问题；用户回答后判断粒度——

• 还不够具体到能写成可验证的验收项 → 就着回答继续追问同一维度
• 够了 → 收口，切下一个维度

怎么呈现选项：每个问题给 1-3 个候选答案 + 标记推荐项，用户成本从"想答案"降到"判断接受 / 微调"。

• 选项名写具体行为，禁用抽象词（❌ "标准 / 灵活 / 简化" ✅ "refresh 失败时让用户重新登录"）
• 所有选项用同一组维度描述（行为 / 代价 / 适用场景），便于横向对比
• 推荐项前缀 ✅ + 一句根因式理由（为什么是它，不是它有什么优点）
• 两选项行为相近时显式写"差异仅在 X"

维度检查表（逐项过，保持领域无关——数据库 / 事务 / 语言专属约束由对应 skill 承担，不在此追问）：角色与场景 / 数据约束（类型·范围·必填·唯一）/ 边界（空·极值·越界）/ 并发与一致性 / 失败处理（错什么·怎么报·可否重试）/ 依赖（上下游·外部服务）。

收敛信号（满足即停手，避免过度追问）：

• 每个维度的回答都已具体到能写进 验收（输入 → 预期结果/报错）
• 用户对某维度明确说"不重要 / 按默认 / 不用管" → 记录决定，跳过
• 所有维度收口 → 澄清结束，进入步骤 2

步骤 2：判断是否需要拆解

多个独立逻辑（用"和/以及/还要/同时"连接的动词）→ 必须拆。

步骤 3：方案质检

拆解方案向用户展示之前，逐条自问：

1. 是否在解决根源问题：规则描述的是根本原因，还是在绕过表面症状？发现后者时主动提出更根源的规则定义
2. 有无更简单的表达：同等效果下能否用更少规则说清楚？能一条讲明白的不拆成两条
3. 是否值得定义：该规则是否已被语言/框架/工具天然保证？已保证的不写 spec
4. 是否可证伪：每条约束能写出"什么输入 → 什么结果"吗？写不出的（如"要健壮/高性能/友好"）就是空泛，重新定义或删除

质检通过后，展示拆解方案（文件名 + 一句话描述），明确请求用户批准（等待用户答复，不得自行视为已批准）。批准后进入步骤 4 落盘；驳回则在只读态调整后重新呈现。

步骤 4：产出文档

在 ${DOCS_DIR}/spec/ 下创建，强制按领域建子目录：<领域>/<动作>.md。

• 禁止扁平放置（如 <领域>-<动作>.md 或直接 <动作>.md 在根目录）
• 即便领域当前只有 1 条规则也建子目录，预留扩展位、避免后续重排
• <领域> 用 kebab-case，与 INDEX.md 分组标题一一对应

步骤 5：更新 INDEX.md 与 GLOSSARY.md

INDEX.md：每条一行：- [<name>](<路径>) — <description>。按领域分组（## <领域>），同领域字母序。

GLOSSARY.md：把合入队列（PRD 增量 + 澄清中登记的术语）写入 ${DOCS_DIR}/spec/GLOSSARY.md，不存在则按模板创建——全新术语加行、新别名并入既有行、定义修正按已裁决结论改写、本次废弃规则涉及的孤立术语（不再被任何 spec 使用）连行删除；所有定义冲突必须已在步骤 0b/1 经用户裁决，禁静默覆盖。合入队列为空则跳过。

步骤 6：跨文档一致性 review

新文档写完后，与所有相关 spec 比对：术语命名（对照 GLOSSARY.md 锚点与别名）/ 约束不矛盾 / 例子不冲突。

• 无冲突 → 告知用户
• 有冲突 → 列出，等用户决定改哪份（禁止自作主张改既有文档）

步骤 7：归档已消费 PRD

若步骤 0b 选定了 PRD，把整个 PRD 目录搬入 ${DOCS_DIR}/prd/.archive/——/prd 原则 7 已与本步骤构成消费契约：被消费的 PRD 必须落归档，让活动 PRD 与已归档 PRD 在目录层物理分离，新 agent 一眼可辨。

mkdir -p ${DOCS_DIR}/prd/.archive
git mv ${DOCS_DIR}/prd/<选定 PRD 目录> ${DOCS_DIR}/prd/.archive/

• git mv 保留文件历史并自动 stage，步骤 9 commit 时与 spec 落盘一并提交
• 未选定 PRD（步骤 0b 跳过）→ 本步骤跳过
• 同次消费多个 PRD 目录 → 逐个 git mv

步骤 8：自检

方案质检：

• 步骤 3 根源性质检已完成？每条规则在解决根源问题而非缓解症状？
• 无冗余规则——同等效果下已选最少规则数的拆法？
• 每条约束都可测（输入→预期），无"健壮/友好/高性能"类空泛词？约束与验收一一对应？

格式自检：

• 步骤 0a~3 全程只读，获用户明确批准后才落盘，未提前写文件？
• 步骤 0b 三类判定已完成并确认？
• 步骤 6 跨文档 review 已完成？
• 步骤 7 已消费 PRD 已 git mv 到 prd/.archive/（未消费 PRD 跳过）？
• frontmatter 含 name + description（≤ 80 字）？
• 正文 ≤ 100 行？只讲一件事？
• 有具体可验证例子？
• INDEX.md 已同步？
• GLOSSARY.md 已同步？（PRD 增量已合入、本次触及术语已登记、定义冲突均经用户裁决、废弃规则的孤立术语条目已删）
• 未引用其他 spec 文档？
• 所有新文件均放在 <领域>/ 子目录下，无扁平根目录文件？

步骤 9：本地 commit

自检通过后，把本次 spec 产出做一次本地 commit——下游 /plan 用 git diff main...HEAD 检测 spec 变更，spec 不提交则检测不到：

• 先 git branch --show-current 确认分支——在 main 上则跳过自动 commit，提示用户按 git-workflow 先建分支再继续
• 只提交本次涉及的文件（spec 文档 + INDEX.md + GLOSSARY.md + 步骤 7 的 PRD 归档 move）
• commit message 遵循仓库历史风格（先 git log --oneline -10 看一眼），不硬编码类型前缀
• 仅本地、不自动 push（推送门槛见 git-workflow：功能全完成 + 测试过 + 用户确认）

步骤 10：完成简报

自检通过后，向用户输出：

## Spec 完成简报

- 来源 PRD：<归档后路径 `prd/.archive/<目录名>`，未消费 PRD 则写"无">
- 产出：新增 N 条 / 修改 M 条 / 删除 K 条 spec
- 术语表：新增 X 条 / 新别名 Y 条 / 修改 Z 条 / 删除 K 条（无变更写"无"）
- 文件清单：
  - <新增/修改/删除> <路径> — <一句话描述>
- 冲突处理：<已解决 X 项 / 无冲突>
- 待解决：<问题列表，无则写"无">
- 下一步：建议运行 `/plan` 生成实施计划

---

单文档模板

---
name: <kebab-case，与文件名一致>
description: <一句话，≤ 80 字>
---

# <规则标题>

## 目的
<一句话。>

## 逻辑
<3-10 行核心逻辑。>

## 约束
<每条约束必须可测，且在「验收」里有对应项；禁止"健壮/友好/高性能"类无判定标准的表述。>
- <约束 1>
- <约束 2>

## 例子
<一个具体场景：输入、过程、预期结果。>

## 验收
- [ ] <可测试验收项 1>
- [ ] <可测试验收项 2>

INDEX.md 模板

# Spec 索引

> 每条一行。读者先扫此页判断相关性，再打开具体文件。

## <领域>

- [name](<领域>/<name>.md) — description

GLOSSARY.md 模板

# 术语表

> 全项目术语唯一权威源，仅 /spec 维护。跨语言 / 跨文档以英文锚点对齐；别名按需增补，只登记实际使用过的语言写法。

| 锚点 | 定义 | 别名 |
|---|---|---|
| order | 用户提交购买意图后生成的待履约交易单据 | 简体「订单」；繁體「訂單」；日本語「注文」 |