SuperAPI AI 工具集

requirements-gap-filler

编程与开发

查看项目

更新于 10-16 06:07

技能介绍

用途

requirements-gap-filler 是一个需求追溯(Requirements Traceability)技能。其目标是读取 requirements.md,扫描真实代码库,并双向比对需求与代码,找出全部四类差距:

  • 需求在代码中缺失(Missing)
  • 需求仅部分实现(Partial)
  • 代码中存在未写入需求的逻辑(Undocumented Logic)
  • 代码中存在未写入需求的业务规则(Undocumented Business Rule)

其理念是:需求必须反映现实;如果代码未实现某条需求,该需求必须被标记,而不是被静默保留;永不删除需求,只添加状态标记与差距说明;描述要具体,不能只说“部分实现”,而要说明具体缺哪一部分;代码是事实来源,代码中的内容优先于计划中的内容。

主要能力

该技能检测两个方向的差距:

方向一:需求 → 代码(需求是否被实现?)

  • ✅ IMPLEMENTED — 完全完成
  • ⚠️ PARTIAL — 部分位置完成,并非全部
  • ❌ MISSING — 完全未实现

方向二:代码 → 需求(代码行为是否被记录?)

  • 📝 UNDOCUMENTED LOGIC — 代码做了需求中未写的事
  • 📝 UNDOCUMENTED RULE — 代码中的业务规则从未被写下

使用方式

步骤 1 — 读取需求文件

询问用户需求文件路径(任意名称,如 requirements.md、specs.md、user-stories.md、feature-brief.txt、REQUIREMENTS.md 等)。若用户未提供路径,则自动检测常见需求文件名(requirements*.md、specs*.md、user-stories*.md、feature*.md、prd*.md 等,排除 node_modules、.git、bin 目录)。若找到多个文件,询问用户选择其一。将选定文件存为 {REQ_FILE} 变量。读取文件并检测格式(用户故事格式、编号列表格式、项目符号格式、RFC 风格、混合格式),解析每一条需求语句并记录行号。

步骤 2 — 扫描代码库

自动检测并扫描相关代码文件,无需询问用户:查找 AppService(业务逻辑)、DTO(验证规则)、实体(领域规则)、接口(契约覆盖)、验证器(如使用 FluentValidation)、测试(确认已实现行为)。

步骤 3 — 将每条需求追溯到代码

对每条需求,在代码库中搜索实现证据,并按规则分类为已实现、部分实现或缺失。部分实现的例子:邮箱唯一性在 CreateAsync 中检查但 UpdateAsync 中未检查;分页存在但未强制上限;Name 有过滤但 Email 没有;IsActive 在部分查询中使用但不一致。缺失的例子:电话格式验证无正则、无特性、无手动检查;完全找不到相关代码。

步骤 3B — 扫描代码中的未记录逻辑

反向查找从未写入需求的代码逻辑:从 AppService 提取所有业务逻辑(if 语句、验证检查、重复/存在性检查、throw 与错误返回、字符串转换、软删除/状态变更模式、级联或副作用逻辑);从 DTO 提取验证规则(DataAnnotation 特性、FluentValidation 规则);从实体提取领域规则(构造函数验证、领域事件)。对每条代码发现,检查需求中是否已存在,仅标记未被任何现有需求覆盖的发现。

步骤 4 — 构建内部差距报告

在更新文件前,构建覆盖两个方向的完整内部差距报告,包含统计与逐条明细。

步骤 5 — 生成差距报告 .md 文件

写入独立的差距报告文件,不修改 requirements.md。输出文件名格式为 {REQ_FILENAME}-gap-report-{YYYY-MM-DD}.md,输出位置与需求文件同一文件夹。报告格式包含:标题、生成日期、需求来源、检测到的文件格式、需求总数、代码发现总数、执行摘要表格(已实现/部分实现/缺失/未记录逻辑/未记录规则的数量与百分比)、整体健康度、方向一(需求 → 代码)的已实现与部分实现明细(含证据与修复建议)、方向二(代码 → 需求)的未记录发现明细。

适用场景

适用于需要验证需求文档与代码实现一致性的项目,例如在发布前检查需求覆盖情况、发现代码中未记录的业务规则、识别仅部分实现的需求。示例场景包括客户管理模块中邮箱唯一性、电话格式、软删除、分页上限等需求的追溯。

限制

资料未提供该技能的具体安装命令、支持的平台、收费或价格信息。资料中的代码示例为 C#/.NET 相关(AppService、DTO、实体、FluentValidation),但未明确说明是否仅支持该技术栈。