SuperAPI AI 工具集

specification-first

编程与开发

查看项目

更新于 10-16 07:23

技能介绍

用途:在编写实现代码之前,先撰写规格说明,并把它作为事实来源;代码是为了满足规格而生成,而非相反。技能说明指出,行为规格定义系统“做什么”,代码实现“怎么做”,没有规格就是在猜。

何时使用:开发新功能或模块、创建 API 端点、构建数据管道、任何具有明确输入输出的系统,以及用户提出“给我构建 X”时都属强制使用。例外情况需与人类确认:配置变更、行为明确的一行缺陷修复、文档更新。

入口流程:实现前依次完成——识别输入、定义预期输出、约束边界与限制、考虑边界情况(空值、null、最大值、并发)、确定验收标准、撰写规格文档、获得用户确认,之后才开始实现。

规格模板结构:目的(一句话说明用途与存在理由)、输入表(名称、类型、是否必填、约束、默认值)、输出表(场景、返回内容、结构形状)、行为(标准路径分步说明,含状态变更与副作用)、边界情况表(空输入、最大长度、并发访问等及其预期行为)、验收标准(可测试、具体的清单)、明确排除项(YAGNI)。

与测试优先的关系:规格的验收标准直接映射为测试用例,每条标准至少生成一个测试;若无法从某条标准推导出测试,说明该标准过于模糊,需细化规格。流程为:规格 -> 测试 -> 代码 -> 按规格验证。

规格深度分级:Minimal 适用于简单、行为明显的功能(目的+输入+输出+3 条验收标准);Standard 适用于多数功能(完整模板);Exhaustive 适用于复杂系统、公开 API、多租户(完整模板加时序图、状态机、错误分类)。按复杂度调整规格规模。

限制与护栏:禁止在规格获批前开始实现、禁止不引用规格标准就写测试、禁止行为变更不更新规格、禁止未按验收标准验证就交付、禁止推迟边界情况、禁止实现完成后再补写规格。必须做到:写代码前取得规格批准、验收标准与测试用例一一对应、需求变化时更新规格、声明完成前验证全部标准通过、写明明确不构建的内容。技能说明要求实现时须调用配套技能 godmode:test-first。资料未提供该技能的收费与平台信息。