---
name: spec-design
description: 基于实际代码与产品事实澄清新增或改变外部可见行为的需求。当用户提出新功能、公共 API、CLI、schema、用户流程变化，要求写 spec、梳理需求、挑战想法或定义验收契约，或者带来一句话需求、PRD、原型、Figma 链接或已有规格时使用。
---

# 需求规格设计

`spec-design` 在长程执行前帮助人类确认两件事：需求是否值得做，以及 Agent 理解的目标是否就是人真正想要的结果。它先调查事实，再通过苏格拉底式提问暴露假设与决策分支，最后按任务需要形成对话内或文件化的权威规格。

三类澄清产物各有边界：

| 阶段 | 负责内容 |
|---|---|
| `spec-design` | 为什么值得做、用户可观察的行为、范围和验收契约 |
| `arch-design` | 领域模型、模块边界、职责、接口、数据流和技术质量目标 |
| 计划与 `incremental-impl` | 实施步骤、完整实施单元、顺序和分发 |

## 什么时候使用

- 新功能、公共接口、命令行、数据格式或用户流程会新增或改变外部可见行为。
- 用户要求澄清需求、挑战一个想法、写规格或定义验收条件。
- 用户提供一句话需求、产品需求文档、原型、Figma 链接或已有规格，需要在实现前形成共同理解。

以下情况退出或转交：

- 外部行为不变，只调整内部结构、算法或依赖：按需要进入 `arch-design`、`code-simplify` 或计划阶段。
- 已有明确问题验证路径的缺陷：先走 `systematic-debugging`；若修复会引入新的产品决定，再返回本技能。
- 纯文档、纯配置或机械修改没有新的行为决定：直接进入相应工作。
- 价值门禁选择“暂缓”或“不做”：停止，不为完成流程制造规格或实现。

## 核心约束

1. **事实先于问题。** 需求是否明确不能依赖模型记忆、置信度或主观印象。先读取相关代码、现有行为、接口、测试、规则和产品资料。
2. **先判断价值。** 代码容易生成不代表需求值得实现；完整澄清前先通过有界门禁确认为什么现在值得投入。
3. **事实由 Agent 调查，决定由人确认。** 能从环境查明的内容不询问用户；事实无法决定的目标、范围、产品语义和取舍必须交给用户。
4. **批量解决独立决定，串行解决依赖决定。** 每轮最多提出三个前置决定已解决且彼此互不依赖的问题；运行时提问工具的上限更低时服从工具限制。依赖本轮答案的问题留到后续轮次。每个问题给出推荐答案、理由和主要后果，帮助用户思考，不替用户批准。
5. **共同理解是实施门禁。** 用户明确确认前，不进入架构、计划或实现；不能从沉默或话题延续推断批准。
6. **先沿用产品结构，再补充分项。** 原始产品需求描述或 PRD 已有清晰的产品功能结构时，规格沿用其业务章节；没有可用结构时，才按用户可感知的产品子功能组织，不用技术结构替代产品结构。

## 流程

### Phase A — 调查事实

1. 用 `git rev-parse --show-toplevel` 确认仓库根，读取适用于目标路径的 `AGENTS.md`、`CLAUDE.md` 和相关项目资料。根据任务选择事实源，不把任一入口文件当作所有场景的唯一事实。
2. 阅读与需求直接相关的代码、接口、测试、现有行为、近期变更、用户反馈、使用数据、故障记录和替代流程。用户给出的路径、提交、问题、原型、原始产品需求描述或 PRD 必须实际打开；同时辨认其中有业务意义的产品功能章节、层级和顺序，不能只提取一段总摘要。
3. 收集项目级 spec 规则：读取 `<仓库根>/docs/rules/spec/`，并从受影响路径向仓库根查找更近的 `docs/rules/spec/`；两层都适用时，子包级规则补充或收窄仓库规则，冲突时子包级优先。非 git 仓库回退到当前目录并从目标路径向上查找。没有相关规则时记录“无项目专属 spec 规则”。
4. 网页、Figma 或外部文档在当前运行时有可用工具时直接读取；无法访问时再请求截图、导出文件或关键内容，不把某一运行时的限制写成通用事实。
5. 区分已证实事实、合理推断和证据缺口。事实冲突或无法获得时明确指出，不用旧文档相互证明。

### Phase B — 判断价值并对齐目标

#### B1. 价值门禁

在展开完整需求决策树前，先帮助用户判断这件事是否值得投入。默认问一个价值问题，只有第一轮仍无法选择出口时追加第二个，最多两轮；用户可以随时直接选择出口。

每个价值问题必须同时包含：

- 已调查到的相关事实；
- 需要人决定的价值判断；
- Agent 的推荐答案和理由；
- “不做”或成本更低的替代思路。

问题优先检验：如果暂时不做，谁会继续遭遇什么问题；做到什么可观察结果，才足以证明它值得优先于不做、人工处理或更小方案。

价值门禁只能进入四个出口：

| 出口 | 后续动作 |
|---|---|
| 值得做 | 继续 B2 的需求对齐 |
| 先验证 | 定义单一假设、最低成本实验、继续信号和停止信号，不直接建设完整功能 |
| 暂缓 | 记录重新评估需要的证据或条件后停止 |
| 不做 | 停止规格和实现 |

安全、合规、严重故障和数据正确性等必做事项可以简化价值讨论，但仍要确认风险、影响和优先级。两轮后证据仍不足时，推荐“先验证”或“暂缓”，不继续无限讨论，也不默认进入完整实现。

#### B2. 苏格拉底式需求对齐

根据 Phase A 的事实建立会改变最终用户结果的决策依赖图。每轮找出前置决定已经解决的真实决定；同一轮只选择彼此互不依赖的问题，每轮最多三个，编号并一起提出。每个问题说明为什么需要决定，并给出推荐答案、理由和主要后果。

用户回答后，逐项检查每轮回答是否仍与原始目标一致，更新决策依赖图，再计算下一轮。依赖本轮其他答案的问题必须留到后续轮次；当前集合超过工具上限时，剩余的独立问题也顺延，不为凑满一轮提前询问尚未具备前置条件的问题。

对齐中出现新的事实缺口时，廉价事实由当前 Agent 直接调查；独立且耗时的调查可以交给内置子代理。调查中的事实视为尚未解决的前置条件，只阻塞依赖它的下游问题，不妨碍提出其他已经具备条件的问题。不存在会改变用户结果的真实决策分支时不提问，直接给出推荐，不制造候选或选择仪式。

至少明确：

- 目标用户、真实问题和期望结果；
- 用户可观察的行为、成功信号和失败语义；
- 范围、范围之外和重要兼容约束；
- 原始产品需求或 PRD 的功能结构，以及每个用户可感知产品子功能承接哪些来源条款；
- 仍存在的证据缺口及其归属。

涉及用户交互的叶子功能时，结合真实产品表面、用户任务和现有设计证据，使用尼尔森十大可用性启发式发现会改变用户结果的交互风险。它不是固定问卷、逐项清单或合规门禁；只澄清当前子功能实际命中的风险，并把确认结果写成交互设计、用户可观察行为和验收断言。无障碍、响应式和平台约束仍作为独立的横切要求处理，不用启发式原则替代。

生产级用户表面的交互设计必须包含本次新增或改变的具体文案，不能只写“展示提示”或“显示错误”。文案无论由客户端固定、服务端下发还是服务端配置，都属于产品规格；记录触发条件、用户最终看到的文本、动态变量和兜底。规格定义用户结果与必要的交付来源，接口字段、存储位置等技术结构留给架构或实施阶段，除非它们本身是公共契约。

用反事实检查判断是否已经对齐：如果两个独立且称职的 Agent 仍能依据当前要求产生明显不同的用户结果，并都合理声称满足需求，就继续澄清对应分支。

停止条件不是固定问题数或主观置信度，而是剩余未知项已经不会实质改变需求价值、目标、用户可观察行为、范围或验收契约。剩余的系统结构决定交给 `arch-design`，实施步骤交给计划阶段。

### Phase C — 形成权威规格

#### C1. 选择对话或文件

快速开发流程中，范围明确、无需跨会话或跨 Agent 交接的一句话需求，可以由当前对话中的用户确认作为权威规格，不强制生成文件。

出现以下任一情况时，需要文件化规格；未拆分时默认在 `docs/specs/<topic>/` 写 `spec.md` 与 `validation-contract.md`，拆分后的目录形态见下文：

- 有多个用户可观察结果，需要逐项追溯验收；
- 涉及公共接口、共享契约、跨模块行为或实质范围取舍；
- 需要跨会话、跨 Agent 或独立评审消费；
- 工作跨多个提交或拉取请求；
- 用户明确要求保存规格。

写文件前按需读取：

| 产物 | 模板 | 用途 |
|---|---|---|
| `spec.md` | `references/spec-template.md` | 保存价值、事实、行为、范围和已确认决定 |
| `validation-contract.md` | `references/validation-contract-template.md` | 保存可追溯的验收断言 |
| `umbrella.md` | `references/umbrella-template.md` | 仅在需求确实拆为多个独立子规范时保存共同范围、子规范清单、父子验收覆盖、依赖和生命周期 |

文件只保存确认后的结果，不记录冗长问答流水。不适用的可选章节直接删除，不用“无”填满模板。

需求没有拆成子规范时，`spec.md` 与 `validation-contract.md` 配套保存。需求拆成多个子规范时，总规范目录保存总 `spec.md` 与 `umbrella.md`；父级验收锚点写在总 `spec.md`，不另建总体验收契约。每个子规范在总规范目录下使用独立子目录，并在其中配套保存自己的 `spec.md` 与 `validation-contract.md`。

写入前先确定同一套产物骨架：

1. 原始产品需求描述或 PRD 已经按产品功能组织时，沿用有业务意义的章节名称、层级和顺序；用映射记录直接沿用、合并或拆分，不机械复制背景、修订记录和排期等非功能章节。多层结构中，非叶子章节只作为产品分组，只有叶子功能展开原始需求、用户可感知行为、适用的交互设计、范围边界和验收映射；不要让固定的规格内容标题占用或压平产品自身层级。
2. 没有可参考的前置产物或来源结构时，按用户可感知的产品子功能划分；每个分项都要有用户能够识别的触发场景和可观察结果。不能按后端模块、接口、数据表、类、文件或实施步骤划分产品需求。
3. 跨多个分项共同成立的产品目标、体验和规则放在总览；原始需求、分项行为、交互设计、范围边界和验收映射放在对应分项。每条原始需求都要能从来源定位到具体分项，不能只停留在总览。
4. 未拆分规格及每个子规范中的 `spec.md` 与 `validation-contract.md` 使用相同的产品分组、叶子功能名称和顺序；验收契约只在叶子功能下展开 VAL，不另建一套与产品结构无关的分类目录。

#### C2. 编写验收契约

每条 `VAL-<完整语义分类>-<NNN>` 表示一项需要证明的验收断言，不等于单个测试用例。分类使用完整、稳定的英文单词，不用项目自造缩写；编号后补充中文短标题，让人无需解码编号就能理解验收项。每项只保留：

- **验收要求**：单一含义的可观察结果；
- **验证方式**：适合证明它的证据类别，例如测试、运行探测、仓库检查或人工验证；
- **通过标准**：什么结果算通过。

具体测试运行器、驱动、测试函数、模拟方式和代码组织由 `test-driven-development` 结合 `docs/rules/test/` 与现有测试决定，不在验收契约维护一份具体工具链清单。

覆盖总览先按 `spec.md` 分项列出来源章节与 VAL 范围；断言正文再按同名分项归组。分类编号用于稳定引用，不用它取代用户能看懂的产品分项名称。

优先选择与断言风险匹配、且 Agent 能独立执行和观察结果的验收证据。可使用仓库检查、静态分析、单元测试、组件测试、契约测试、集成测试、HTTP 测试、界面自动化、运行探测或端到端验收；这些是开放示例，不是封闭清单。端到端验收用于证明依赖真实产品表面或跨层协作的代表性结果，不是每条 VAL 的默认方式，也不替代更直接、更便宜的分层证据。

- 客户端和前端工程中，当正确性依赖真实界面、系统权限或运行时集成时，至少保留一条代表性真实 UI 验收；可以使用现有 UI 自动化，或由 Agent 通过当前可用的 MCP/CLI 驱动模拟器、真机或浏览器。其余断言继续选择更直接的组件、状态、可访问性、集成或其他证据。
- 服务端 API 新增或改变接口行为时，至少保留一条 Agent 可执行的 HTTP 测试或接口端到端验收；可以由脚本直接请求，也可以通过真实客户端或前端页面触发并观察接口结果。协议形状、业务规则和内部协作仍可分别使用契约、单元或集成证据。
- 人工验收只作为 Agent 无法可靠观察结果时的例外。记录无法自动验收的原因、需要人判断的内容和操作入口，不用“人工确认”代替可执行路径。

规格阶段先写清每项断言需要证明什么；只有选择真实产品表面验收时，才补充需要驱动的表面、入口、关键操作和可观察结果。具体命令与测试组织交给 `test-driven-development` 根据当前工程能力确定，不虚构不存在的自动化设施。

#### C3. 拆分大需求

单份 `spec.md` 内先按来源产品结构或用户可感知子功能组织分项。只有当其中一个部分能够形成独立确认、独立验收且不误导总体目标的完整用户结果时，才进一步拆成单独的子规范。文件数、模块数、代码行数和实施手法不是需求拆分标准。

总需求拆成多个子规范时，总 `spec.md` 定义完整产品需求和父级验收锚点；`umbrella.md` 单独承担跨子规范协调，包括共同范围、完整用户结果清单、父子验收覆盖、真实依赖、状态和生命周期。子规范按可独立交付的完整用户结果划分，不要求与总 `spec.md` 的产品章节一一同构；只有存在真实交付依赖时才排序。每个子规范用自己的 `validation-contract.md` 展开所有适用的父级验收锚点。

工作没有跨多个拉取请求时，总规范写入 `docs/specs/<topic>/`，子规范写入它的 `<child-topic>/` 子目录。工作明确跨多个拉取请求时，先取得用户明确确认长期生命周期，再把总 `spec.md`、`umbrella.md`、子规范目录和适用的共同设计放入 `docs/long-running-specs/<topic>/`；开发期执行产物仍按仓库文档规则处理。子规范归档或晋升后同步更新 `umbrella.md` 中的实际链接。长期规范不能替代或绕过当前子拉取请求的待评审生命周期；全部子拉取请求结束后由人工决定长期规范的归档或晋升，执行时走 `documentation-management`，不直接移动文件。

### Phase D — 确认与交接

1. 检查规格是否建立在调查事实和项目规则上，价值判断有明确出口，产物结构能回溯原始产品需求或已按用户可感知子功能划分，适用的交互设计与具体文案已经落到叶子功能，行为与验收分项一致，未把产品决定静默留给下游。
2. 把对话内规格摘要或文件路径返回用户，突出需要确认的目标、范围、验收和仍有风险的假设，等待明确确认。收到修改意见就更新权威规格。
3. 用户确认后按工作流交接：技术结构不显然、需要重划边界或需要领域建模时先进入 `arch-design` 并取得人工确认；任务只有单一明确结果、没有未决的产品或架构决定、无需跨会话跟踪且无需多个完整实施单元时可以直接进入编码前准备；其余任务先由用户选择内置 Plan 或 `planning-with-files`，再进入实现。用户明确选择的 `goalify` 可以与任一计划载体组合。
4. 实现中发现新的产品语义、范围或用户结果歧义时返回本技能澄清并更新权威决定，不为维护既有草稿继续错误方向。

## 交接前检查

- [ ] 已调查可获得的事实，没有把可查信息问给用户。
- [ ] 已明确为什么值得做，或通过“先验证 / 暂缓 / 不做”合法退出。
- [ ] 每个问题都由真实决策触发，并给出推荐答案与主要后果。
- [ ] 同一轮的问题互不依赖；依赖本轮答案的问题已留到后续轮次。
- [ ] 目标、用户可观察行为、范围和验收契约没有多种合理解释。
- [ ] 规格先总后分；分项与原始产品需求或 PRD 的产品功能结构对齐，没有来源结构时按用户可感知的产品子功能划分。
- [ ] 涉及用户交互的叶子功能已写清交互设计；生产级表面本次新增或改变的具体文案及服务端下发内容已进入规格。
- [ ] 未拆分规格及各子规范中的 `spec.md` 与 `validation-contract.md` 使用相同的分项名称和顺序，每条原始需求都能落到具体分项。
- [ ] 产品决定、技术结构和实施步骤没有混在一起。
- [ ] 文件化规格只保存确认结果；一条 VAL 不被误当作一个测试用例。
- [ ] 用户已明确确认共同理解；沉默没有被当作批准。

## 和其他技能的关系

- `arch-design`：消费已确认的价值、行为和验收契约，澄清系统如何表达需求。
- `test-driven-development`：消费验收标准或 `validation-contract.md`，把每项断言展开成必要的失败证据和验证用例。
- `incremental-impl`：消费已确认的子规范与设计，把需求改动拆成完整、可验证的实施单元。
- `deep-review` 的 `spec-conformance`：以用户最新决定、对话内规格或文件化 VAL 为权威来源核对差异。