SuperAPI AI 工具集

spec-writing

写作与研究

查看项目

更新于 10-16 06:15

技能介绍

用途:nlspec 是一份“最小跨度”的自然语言规格标准,旨在给出一个基础,使实现者结合材料与协作规则即可构建整个软件。跨度指:任何有能力的实现者无法自行决定的问题都已被回答;最小指:只回答这些问题,读者能在上下文中推导的内容一律省略。判断某决策是否应写入 nlspec 的标准是:它无法从已有内容推导出来,且两位有能力的读者会得出不同答案并影响 seam、claim、budget 或 exclusion。

主要能力与必需内容:概览与目标(意图、需求、设计原则);完成定义(必须演示的行为性 claims,分为 cell-local 与 integration,每个 seam 至少被一个 claim 覆盖,完成意味着应用真实运行并使用真实服务与密钥,mock 仅可用于 cell-local claims);排除项(明确不构建的内容);核心数据类型与算法(语言无关伪代码,仅公开格式给出精确语法);seams、cells、contracts;以及延迟决策(tripwire 清单,实现者遇到即上报而非即兴发挥)。

seams、cells 与 budgets:seams 将代码库划分为 cells,每个 cell 有明确职责、边界与 contract,内部实现可替换。seam 放置遵循 Parnas 测试:变更原因不同处才设 seam。每个 cell 有最大代码量 budget,机械可查,超限即停止上报。seam 完整性检查包括公共接口匹配 contract、外部不得越过 contract、每个 cell 不超预算、已路由 claims 得到演示,并报告公共接口变化与跨 cell 调用点增减。

权威与两个泵:nlspec 与代码是唯一持久权威,nlspec 持有意图,代码持有事实。只有两个通道写入 nlspec:规格缺陷上报(实现者不得修改 nlspec,遇到无法推导的决策即停止并提交缺陷,裁决后写入 nlspec 再继续)与催化转换器(代码中发现的测试用例可提升为 claims,仅接受行为性证据)。

产物层级:nlspec 永久维护、唯一权威;每 slice 技术规格仅存活一个 slice,随 PR 归档、不维护;代码与测试为事实,测试是候选 claims。路由测试:需永久遵守的内容进 nlspec,仅本 slice 的进 slice spec,代码中的不写下来。

比例原则:装置随变更影响范围伸缩。cell-local 变更走维护模式;单 cell 且影响 claim 的功能用最小 slice spec;跨 seam 或多 slice 才用完整 slice-design。任何对 seam、contract、claim、budget 或 exclusion 的变更,无论大小,都只能通过两个泵并经由 HITL 进入 nlspec。

风格:散文是规范契约,数据类型与顺序、优先级或边界模糊的算法用伪代码,不规定实现语言;新增重要公共概念或 contract 前需 HITL 批准。限制:资料未提供具体安装命令、平台、收费或价格信息。