SuperAPI AI 工具集

tech-spec

编程与开发

查看项目

更新于 11-06 09:09

技能介绍

tech-spec 是一个面向注解式项目的技术规格生成技能,核心目标是把代码与已配置的测试注解投影成一份可再生成的技术视图,同时避免形成第二个事实来源。

用途 该项目把“技术视图”定义为业务规格(Feature Spec)的派生结果:业务内容(用户故事、验收标准、业务规则、§1–§8 正文和 §8 测试用例)始终由业务规格拥有,本技能只负责把代码中的命令/查询处理器、事件消费者、后台任务、生产者、saga、outbox 以及配置的 TestSpec / TechnicalSpec 注解机械地整理为技术文档。生成内容带 DERIVED 横幅和再生成日期,不可手工编辑;当视图与代码不一致时以代码为准,重新生成即可。

主要能力

  • 生成:从代码树和测试注解派生 {TechRoot}/{Service}/{Component}.md 形式的技术视图,模板固定、来源锚定、逐件即时写入,并对整棵树保证幂等(源不变则重新生成差异为空)。
  • 审计:按请求执行陈旧性检查,对比代码/测试的修改时间或 git 状态与已有派生视图,只输出陈旧清单,不做任何修改。
  • 同步:原生配置下把测试对账路由给 $spec [mode=sync];在严格默认下报告 §8 测试用例与测试之间的漂移、仅路由的 CoveredBy: 或孤儿报告,不撰写内容。
  • 机械检测与路由:收割检测器只报告候选(如某不变量在至少两处被强制执行却没有业务规则引用),永不作为构建门禁或再生成前置条件。

使用方式 从项目根目录使用 Node.js 运行(node --version 探测环境),技能自带内置模块,无需安装第三方包,命令可在 Windows、macOS、Linux 上使用。主要调用为: node .claude/skills/tech-spec/scripts/generate-tech-specs.mjs 以及只读新鲜度与注解完整性检查: node .claude/skills/tech-spec/scripts/generate-tech-specs.mjs --check --optional 仅用于编排入口(例如 sync 运行器的 tech-spec-freshness 阶段)以便把缺失的 techSpecScan 契约记录为跳过,不能把跳过当作覆盖成功。执行前需先读取 docs/project-config.json,解析 specArtifacts、specRoots.technical.path 和 techSpecScan,确认模式与范围;配置缺失或格式错误不会被当作空成功,原生配置下的生成请求直接返回 UNSUPPORTED。工作流为 $investigate(定位组件)→ $tech-spec(投影视图)→ $changes-review → $watzup。

适用场景

  • 已有注解式代码与测试(TestSpec / TechnicalSpec)的项目,需要自动维护技术视图。
  • 需要检查技术文档是否过时、注解是否遗漏的审计场景。
  • 需要在严格默认下核对 §8 测试用例与测试覆盖关系、发现漂移的场景。

限制

  • 仅作为生成器,不撰写或评判任何业务内容,不输出 A–E 文件名,不在技术树中出现 US-/AC-/BR- 前缀内容。
  • 只写入 specRoots.technical.path,是唯一写入者;配置错误或技术根缺失时停止,不伪造组件。
  • 原生配置(native profile)不支持注解生成,只能路由到 $spec 同步。
  • 收割检测结果为报告,不是错误或构建门禁;不保证覆盖判断的绝对准确(存在误报与漏报)。
  • 具体收费、价格、平台支持范围等资料暂未提供。