Spec Design

需求规格设计

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

三类澄清产物各有边界：

什么时候使用

• 新功能、公共接口、命令行、数据格式或用户流程会新增或改变外部可见行为。
• 用户要求澄清需求、挑战一个想法、写规格或定义验收条件。
• 用户提供一句话需求、产品需求文档、原型、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. 按实际疑点选择证据：行为查代码、接口或测试，价值与影响查用户反馈、数据、故障或替代流程，不要求收齐每类资料。用户指定的相关路径、提交、问题、原型或产品资料必须核实；辨认其中有业务意义的功能章节、层级和顺序。
3. 收集项目级 spec 规则：读取 <仓库根>/docs/rules/spec/，并从受影响路径向仓库根查找更近的 docs/rules/spec/；两层都适用时，子包级规则补充或收窄仓库规则，冲突时子包级优先。非 git 仓库回退到当前目录并从目标路径向上查找。没有相关规则时记录“无项目专属 spec 规则”。
4. 网页、Figma 或外部文档在当前运行时有可用工具时直接读取；无法访问时再请求截图、导出文件或关键内容，不把某一运行时的限制写成通用事实。
5. 区分已证实事实、合理推断和证据缺口。事实冲突或无法获得时明确指出，不用旧文档相互证明。

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

B1. 价值门禁

沿用已明确的价值与优先级；仅对调查后仍会改变目标或优先级的未决判断提问。只有第一轮仍无法选择出口时追加第二个问题，最多两轮；用户可直接选择出口。

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

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

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

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

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

B2. 苏格拉底式需求对齐

根据调查事实识别会改变用户结果的真实决定，按核心约束批量提问。每轮回答后核对原始目标，更新决定及其依赖；不存在实质分支时直接给出推荐，不制造选择仪式。

新的事实缺口由当前 Agent 调查；独立且耗时的调查可交给内置子代理。未查明的事实只阻塞依赖它的问题，其他独立决定继续推进。

至少明确：

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

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

生产级用户表面的交互设计必须包含本次新增或改变的具体文案，不能只写“展示提示”或“显示错误”。文案无论由客户端固定、服务端下发还是服务端配置，都属于产品规格；记录触发条件、用户最终看到的文本、动态变量和兜底。沿用既有风格的常规措辞由 Agent 先写草案，随规格一起审查，不逐句另开批准步骤；会改变产品承诺、操作后果或失败语义的文案仍由用户决定。接口字段、存储位置等技术结构留给架构或实施阶段，除非本身是公共契约。

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

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

Phase C — 形成权威规格

C1. 选择对话或文件

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

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

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

写文件前按需读取：

允许先保存明确标为“待确认”的草稿，未决产品问题集中列出，不能作为实施依据；确认后更新状态、记录确认来源并保留最终决定，不记录冗长问答流水。章节、来源映射与父子目录按上表模板编写，不适用的可选章节删除。

C2. 编写验收契约

每项验收断言写清可观察结果、适合证明它的证据类别和通过标准；一项断言不等于一个测试用例。按风险优先选择 Agent 可执行的直接证据，具体工具和测试组织交给 test-driven-development。

正确性依赖真实界面或运行时集成的客户端、前端变化，保留代表性真实界面验收；服务端接口行为变化，保留 Agent 可执行的请求验证。其余断言用更直接的分层证据，不默认逐项端到端验证。人工验收仅用于无法可靠自动观察的结果，写明原因、判断内容和操作入口。选择真实产品表面时写清入口、关键操作和可观察结果，不虚构自动化设施。

文件化时按 references/validation-contract-template.md 保持产品分项对应、稳定编号和断言格式。

C3. 拆分大需求

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

总 spec.md 保存完整产品需求和父级验收锚点，umbrella.md 协调子规范及验收覆盖。按 references/umbrella-template.md 编写父子映射和目录；每个子规范承接所有适用的父级验收锚点。

跨多个拉取请求且用户明确确认长期生命周期后，使用 docs/long-running-specs/<topic>/。长期规范不能绕过子拉取请求的待评审要求，全部子拉取请求结束后由人工决定归档或晋升。

C4. 验证结果的交接与生命周期

按 references/validation-results-template.md 在契约旁初始化未执行的覆盖记录，已有记录不重置；执行者每完成一个交付验证活动就填写，不记开发试跑。无文件化规格时仅在对话中汇报。

各子规范保存自己的结果，umbrella.md 仅索引。实际开展跨规范验收时才创建总主题结果，关联总规格锚点或已确认要求，不另造契约。

结果按拉取请求留存。进入待评审状态时，由 documentation-management 归档到对应 worklog，保留主题层级以避免同名覆盖，不晋升为架构文档；用户已明确结果去向时服从其决定。长期契约保留原位并索引归档结果，后续交付新建记录。迁移或删除来源时修复引用，必要时保留要求快照；归档后的复验继续记入当次归档。

Phase D — 确认与交接

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

和其他技能的关系

• arch-design：消费已确认的价值、行为和验收契约，澄清系统如何表达需求。
• test-driven-development：消费验收标准或 validation-contract.md，把每项断言展开成必要的失败证据和验证用例；只在形成交付证据时记录结果，不逐次记录开发试跑。
• incremental-impl：消费已确认的子规范与设计，把需求改动拆成完整、可验证的实施单元；核对并汇总各单元的验证结果。
• deep-review 的 spec-conformance：以用户最新决定、对话内规格或文件化 VAL 为权威来源核对差异，使用验证结果定位证据但不直接采信执行者结论。