SuperAPI AI 工具集

specification

智能体与模型

查看项目

更新于 10-16 11:29

技能介绍

规格:对话本身就是产物

规格不是一份文档,而是利益相关者之间建立共识的对话;书面结果至多是关于真实需求的合理猜测,需要现实来投最后一票。价值在于“做计划”这件事,而不是计划本身——让智能体跳过对话直接“写规格”会错过全部要点。本技能的目的就是强制进行对话:先与你对话,再在掌握答案的人之间对话。

位置

位于 story-splitting、planning 以及任何验收测试之前,其输出会喂给这三者。

契约

  1. 先找到故事的“家”。询问这个故事放在哪里——issue、docs/stories/ 下的文件、工单,或团队已有任何存放位置。本技能产出的一切都写回该载体。若尚无存放位置,询问应该放在哪里;绝不悄悄另创一套并行惯例。
  2. 一次只问一个问题。绝不做问卷。说明利害关系,并接受“先搁置”——搁置的问题要指定负责人和日期,绝不允许沉默。只有在仓库证据或已知取舍支持时才推荐答案;否则中立提问,并把任何试探性假设明确标为假设,避免锚定决策者。
  3. 每个实质性假设都变成问题。一旦发现自己正在替人决定他从未给出的结论,就停下来问。如果答案不会改变地图,那它就不是真正的决策问题。
  4. 地图是数据,不是散文。边对话边构建并保持可见:
story:     <一行,用对方使用的措辞>
rules:     # 业务策略 / 验收标准
  - rule: <用领域语言表达的策略>
    examples:
      - <具体:真实取值、真实结果——绝不重复规则本身>
    questions: # 附着在此规则上的未决假设(可选);搁置项含负责人与决策/复核日期
questions: # 跨切面的未决假设;搁置项含负责人与决策/复核日期
acceptance criteria: # 示例稳定后从规则中提炼
candidate terms:     # 对话中创造或争议的词汇
  1. 先质疑地图再信任它。对每条规则追问:反例问题(“要怎样这个示例才会得出不同结果?”)、零–一–多、边界,以及失败时会发生什么。只有一条示例的规则是猜测;示例全都一致的规则是假设。
  2. 把地图的形状当作诊断。问题占主导 → 尚不适合开工,继续谈,或指定负责人搁置后停止。规则占主导(超过约 6 条)→ 太大,交给 story-splitting。每条规则都有具体示例、整体平衡 → 就绪。

推荐路径:先草案,再责任人评审

智能体主导的对话产出共识的初稿,只有对结果负责的人评审后才可用。评审范围要与工作匹配:低风险的本地改动,唯一负责人可能就够;共享、受监管、不可逆或跨学科的行为需要受影响的业务、开发、测试、安全、运维或设计视角。记录任何有意缺席的重要视角及原因。

多轮推荐流程:

  1. 第 1 轮(智能体主持):与提出想法的人运行上述契约。把地图写回故事载体,据此生成评审页。
  2. 第 2 轮(责任人):评审页交给负责人和风险相关视角。三人组对话(业务、开发、测试)是共享产品行为的强默认,但不必为每个小任务制造仪式。评审者在页面上批注;分歧变成新问题,而不是默默修改。
  3. 第 3 轮及以后(对齐):反馈作为答案和新问题回到智能体轮次。更新地图和载体,重新生成页面。重复直到某一轮不再产生新规则、不改变示例、不产生新问题。
  4. 然后拆分:稳定的地图交给 story-splitting;每个子故事带上自己的规则与示例——每条规则的问题摊平进下游映射所期望的统一问题列表;若安装了验收测试外循环,这些示例成为其按切片映射的种子。

现实仍有最终决定权:此处写下的验收标准在已交付切片确认之前都只是假设。现实不同意时,对话重新开启——这是方法的特点,不是规格的失败。

评审页

第 2 轮时,从 resources/spec-review-template.html 生成一个自包含页面:填入 JSON 数据槽(替换所有出现的双下划线 REVIEW_DATA 标记,字符串值中每个 < 转义为 \u003c),写入临时目录,本地打开,绝不提交生成的页面。数据结构为共享同一卡片引擎的若干区:Rules 区(每条规则一张卡——规则作为卡名,具体示例作为纯文本,附着的问句放在高亮行,逐字地图条目折叠在下方)、Parked questions 区(问题作为名称,负责人 + 决策/复核日期 + 背景作为纯文本)、Candidate vocabulary 区(术语作为名称,一行释义作为纯文本)。每张卡都可评论;复制反馈控件把所有批注组装成一个 markdown 块,回到下一轮。此页面是对话产物,不是批准记录——每轮都可自由重新生成。

词汇捕获

规格对话不断创造词汇,这本身就是一半价值。对话中发明、有争议或出现两种用法的每个术语,都放入 candidate terms 并附一行释义。若安装了 ubiquitous-language 技能,候选词逐个进入其五步语言协议(提取只收集候选,只有协议才接纳);若未安装,候选列表仍随故事同行,让命名对话在别处发生。

边界

情形 技能
模糊的决策树,尚无载体,需定夺选择 已安装则 grill-me;否则用本技能的单问题协议
已有故事/计划/规格需要挑漏洞 find-gaps
达成的地图太大,需切成子故事 story-splitting
把子故事转成 PR 规模的计划 planning
行为与约束稳定后比较库、工具、应用、服务、平台原语或定制实现 evaluate-existing-solutions
按切片的可执行规格(若已安装) acceptance-testing
为对话产生的词汇命名(若已安装) ubiquitous-language

核对清单

  • [ ] 询问过故事载体的归属而非假定;所有产出写回其中
  • [ ] 问题一次一个;仅在证据或已知取舍支持时给出推荐
  • [ ] 每条规则至少有一个具体示例(真实取值、真实结果)
  • [ ] 每条规则都经受住反例挑战
  • [ ] 搁置问题都有负责人和决策/复核日期
  • [ ] 已捕获候选术语(并在已安装时路由到语言协议)
  • [ ] 责任人评审了页面;风险相关视角加入或记录了其缺席
  • [ ] 反馈以答案/问题形式返回,绝不作为默默修改
  • [ ] 检查过地图形状:非问题主导、非规则主导,示例具体