specification

规范：对话才是产品

规范不是一份文档，而是利益相关者之间的一场对话，在对话中逐步建立共同理解——书面结果充其量只是对真实需求的有根据的猜测，直到现实作出最终裁决（Gorman）。价值在于规划，而不在于计划：跳过对话，让 Agent “编写规范”，就错过了全部重点。这项技能旨在促成对话——先与你交流，再由负责给出答案的人类彼此交流。

适用阶段：在 story-splitting、planning 之前，也在任何验收测试出现之前。它的输出会供这三者使用。

资源	在……时加载
spec-review-template.html	展示完成的地图，供负有责任的人类审核
references.md	核查本指南中介绍的实践的来源

---

约定

1. 先找到故事的归属位置。 询问这个故事存放在哪里——某个 issue、docs/stories/ 下的文件、工单，或团队已有的其他存放位置。这项技能产生的所有内容都要写回那个工件。如果它还没有归属位置，就询问应该放在哪里；绝不默默另创一套并行约定。
2. 每次只问一个问题。 绝不要一次列出一份问卷。说明其中的利害关系，并接受“暂且搁置”——搁置的问题要指定负责人和日期，绝不能不了了之。只有在仓库证据或已知权衡能支持建议答案时才提出建议；否则应中立地提问，并将任何暂定假设标明为假设，不要影响决策负责人的判断。
3. 把每个实质性假设都变成问题。 一旦发现自己正在决定人类从未提供的结果，就停下来询问。一个答案如果无法改变地图，那就不是一个真正的决策问题。
4. 地图是数据，不是散文。 在推进过程中逐步构建，并始终保持可见：

story:     <one line, in the words the human used>
rules:     # business policies / acceptance criteria
  - rule: <policy in domain language>
    examples:
      - <concrete: real values, real outcome — never a restatement of the rule>
    questions: # open assumptions attached to THIS rule (optional); parked items include owner and decision/review date
questions: # cross-cutting open assumptions; parked items include owner and decision/review date
acceptance criteria: # distilled from rules once examples stabilise
candidate terms:     # vocabulary the conversation coined or contested

5. 先挑战地图，再相信它。 对每条规则都要提出反例问题（“什么情况会导致这个示例得出不同结果？”），检查零、一个、多个的情况、边界，以及失败时会发生什么。只有一个示例的规则只是猜测；所有示例都一致的规则则是一项假设。
6. 通过地图的形态诊断进展。 问题占主导 → 尚未准备好开始构建；继续讨论，或指定负责人后搁置并停止。规则占主导（超过约 6 条规则）→ 范围太大；将地图交给 story-splitting。保持均衡，且每条规则都有具体示例 → 已准备就绪。

推荐流程：先起草，再由责任方评审

上面的 Agent 促成式对话会产出对共同理解的初稿。只有由对结果负责的人评审后，它才可供使用。评审人员应与工作相匹配：对于低风险的本地变更，单一负责人可能就足够；涉及共享、受监管、不可逆或跨学科行为时，则需要相关业务、开发、测试、安全、运维或设计视角。记录有意缺席的任何重要视角，并说明原因。

推荐流程，多轮进行：

1. 第 1 轮（由 Agent 促成）：与提出想法的人一起执行上述契约。将梳理出的内容写回故事工件，并据此生成评审页面（见下文）。
2. 第 2 轮（责任相关人员）：将评审页面交给负责人和与风险相关的人员。对于共享的产品行为，业务、开发、测试三方对话是很好的默认做法，但不应为了每个小任务都刻意举行仪式化流程。评审人员在页面上添加批注；分歧应转化为新问题，而不是被悄悄改掉。
3. 第 3 轮及后续（协调）：将他们的反馈作为答案和新的红卡带回 Agent 轮次。更新梳理结果和工件；重新生成页面。重复这一流程，直到某一轮不再产生新规则、不再修改示例，也不再出现新问题。
4. 然后拆分：将稳定后的梳理结果交给 story-splitting；每个子故事都继续携带其规则和示例——每条规则下的问题会合并到下游梳理流程所需的单一问题列表中——如果已安装验收测试外循环，这些示例就会成为其逐切片梳理的种子。

现实仍拥有最终决定权：在交付的切片验证之前，此处编写的验收标准都只是待验证的假设。如果现实与之不符，对话就会重新开启——这是此方法的特点，而不是规格的失败。

评审页面

对于第 2 轮，从 resources/spec-review-template.html 生成一个独立完整的页面：填写其 JSON 数据槽（替换所有双下划线 REVIEW_DATA 标记，并将字符串值中的每个 < 转义为反斜杠-u003c），写入临时目录，在本地打开，切勿提交生成的页面。将数据组织为共享同一套卡片引擎的各个部分：规则部分（每条规则一张卡片——规则作为卡片名称，具体示例作为纯文本，附带的问题放在高亮行中，原样的梳理条目可在下方折叠查看）、待处理问题部分（问题作为名称，负责人、决策/评审日期和背景作为纯文本），以及候选词汇部分（术语作为名称，一行释义作为纯文本）。每张卡片都可添加评论；复制反馈控件会将所有批注汇总为一个 Markdown 块，以便返回下一轮。此页面是对话工件，而非批准记录——每轮都可以随时重新生成。

词汇收集

规格讨论会不断创造词汇——这正是其价值的一半。对话中创造、质疑或以两种不同含义使用的每个术语，都应加入 candidate terms，并附上一行释义。如果已安装 ubiquitous-language 技能，则候选术语应逐一进入其五步语言协议（提取阶段收集候选词；只有协议才能批准术语）；如果未安装，候选词列表仍应随故事一起传递，确保命名讨论能在其他地方进行。

适用边界

情况	技能
模糊的决策树，尚无产出物，正在厘清选项	已安装时使用 grill-me；否则使用此技能的单问题流程
需要找出已有故事、计划或规范中的漏洞	find-gaps
已达成一致的地图过于庞大，需要拆分为子故事	story-splitting
将子故事转化为适合 PR 的计划	planning
行为和约束稳定后，对比库、工具、应用、服务、平台基础组件或定制实现	evaluate-existing-solutions
针对每个切片的可执行规范（已安装时）	acceptance-testing
为对话中出现的词汇命名（已安装时）	ubiquitous-language

验证清单

• 已询问故事产出物应存放在哪里，而非擅自假定；所有输出均已写回该产出物
• 每次只问一个问题；只有在证据或已知权衡足以支撑建议时，才提出建议
• 每条规则至少有一个具体示例（真实值、真实结果）
• 每条规则都经受住了反例挑战
• 搁置的问题均已指定负责人和决策／复审日期
• 已记录候选术语（并在已安装时转交给语言协议）
• 责任人已审阅页面；与风险相关的各方已参与，或已记录其缺席情况
• 反馈以回答或问题的形式返回，绝不通过静默编辑处理
• 已检查地图的整体形态：问题占比不过高，规则占比不过高，示例具体明确