| name | spec |
| description | 需求拆解与文档化——通过对话「澄清→拆解→文档化」把模糊需求拆为一文一规则、≤100 行/份、互不重叠的小规则 spec，落盘 .bb-spec/docs/spec/；启动即进入只读对齐、方案获批后才写；INDEX.md 汇总索引、GLOSSARY.md 术语权威源仅由本 skill 维护（合入 PRD 增量、按需增补多语言别名）、禁跨文档引用、每文档结尾必有可测试的具体例子。触发：/spec、整理需求、把功能写成 spec、需求拆解、PRD 出来后要拆规则。跳过：还没想清楚要解决什么问题（→/prd）、已有 spec 想改细节（→/revise）。 |
Spec 需求拆解与文档化
把模糊需求通过对话澄清 → 拆解 → 文档化，输出互不重叠、各自只讲一件事的"小规则"文档。
核心原则
- 方案先对齐再落盘：启动即进入只读对齐阶段（禁止任何写盘），澄清与拆解全程只读，方案获用户明确批准后才写文档（❌ 澄清没结束就先建 spec 文件）
- 一文一规则：每文档 ≤ 100 行，只描述一条独立逻辑/约束
- 先澄清再写：禁止脑补，对话把假设和边界讲清楚
- 必须举例：每文档结尾一个具体、可被测试的例子
- 强制拆解：发现多个关注点时拆为多份文档
- 按需加载结构：frontmatter
name + description → INDEX.md 索引
- 自主独立：每份自包含，禁止跨文档引用（无"详见/参见/复用 xxx.md"）
- 语言跟随用户：正文用用户的工作语言（默认随对话语言），标识符/API 名/错误码保持英文
- 纯净现态：spec 只描述当前系统行为，不携带变更历史或过渡标记；废弃规则直接删文件，git 是变更追溯的唯一来源
- 术语单一权威源：
${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 目录，用
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：方案质检
拆解方案向用户展示之前，逐条自问：
- 是否在解决根源问题：规则描述的是根本原因，还是在绕过表面症状？发现后者时主动提出更根源的规则定义
- 有无更简单的表达：同等效果下能否用更少规则说清楚？能一条讲明白的不拆成两条
- 是否值得定义：该规则是否已被语言/框架/工具天然保证？已保证的不写 spec
- 是否可证伪：每条约束能写出"什么输入 → 什么结果"吗？写不出的（如"要健壮/高性能/友好"）就是空泛，重新定义或删除
质检通过后，展示拆解方案（文件名 + 一句话描述），明确请求用户批准（等待用户答复，不得自行视为已批准）。批准后进入步骤 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：自检
方案质检：
格式自检：
步骤 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 | 用户提交购买意图后生成的待履约交易单据 | 简体「订单」；繁體「訂單」；日本語「注文」 |
