SuperAPI AI 工具集

spec-mining

数据与分析

查看项目

更新于 10-15 19:54

技能介绍

用途:当系统缺少可用文档时,通过阅读真正运行的代码来提取规格,供重建服务、规划迁移或新人上手使用。核心纪律是把“观察到的”与“推断出的”分开,因为读者会据此行动,听起来自信的猜测比明确标注的空白更危险。

主要能力与做法:由外向内推进,先看入口点,再看路由,然后是背后的服务,最后是数据层;沿真实请求路径理解系统实际结构,它常与目录名暗示的结构不同。同时阅读测试,测试记录了预期行为和线上遇到的边界情况,通常比注释或 README 更诚实。还要阅读迁移历史,迁移有日期和顺序,能显示 schema 如何演变成当前形态——哪些列是在压力下加的、哪些被回填、哪些被重命名却从未删除,这往往是数据模型为何如此的唯一留存记录。每条观察都要引用证据,例如 src/auth/jwt.strategy.ts:42,没有位置读者无法核实,不可核实的断言会让逆向规格腐烂。

EARS 写法:用 EARS 把触发条件和状态强制写进句子,避免“系统验证令牌”这类隐藏时机的表述。模式包括:Ubiquitous(The system shall [action].)、Event(When [trigger], the system shall [action].)、State(While [state], the system shall [action].)、Conditional(While [state], when [trigger], shall …)、Optional(Where [feature enabled], shall …)。按领域编号以便引用,如 OBS-AUTH-001、OBS-USER-002,并附证据行号。

不确定项也是交付物:无法从代码确定的内容单独成节,写成问题而非猜测,例如什么触发状态转换、删除是否为软删除、某字段归哪个外部系统所有。这一节常是文档最有价值的部分,是维护者必须被询问的清单。

输出:保存到 specs/{project_name}_reverse_spec.md,结构与章节顺序见 references/specification-template.md。限制:资料未提供具体安装命令、平台支持、收费方式或效果数据。