SuperAPI AI 工具集

validate-docs

通用与其它

查看项目

更新于 10-16 07:18

技能介绍

validate-docs 用于校验代码注释质量与 TODO/FIXME 格式。它先解析目标目录:优先从 CLAUDE.md 的 Project Structure 提取源码目录,缺失时用 Glob 匹配常见源文件扩展名并以顶层目录为目标,仍无则标记为 SHALLOW。默认排除 node_modules/、.git/、dist/、build/、coverage/,并排除生成代码(.generated.、.g.dart、.freezed.dart)。

主要能力:检查 TODO/FIXME 是否为 TODO(@assignee, YYYY-MM): description 形式,缺少负责人或期限会告警;检查 HACK 是否带移除条件或日期(YYYY、vN、#issue-number);统计 WHY、CONSTRAINT、DEPENDS、SECURITY、PERF、MIGRATION 各前缀使用次数;用英文模式匹配疑似自明注释(如 // increment i),仅列为 suspected items,不作 FAIL。

使用时会先输出目标解析结果和 Findings 验证矩阵,生成文档质量报告后持久化到 .ww-w-ai/standards/validate-docs/:latest.json、latest.md,并将 JSON 归档到 history/{timestamp}.json。latest.md 使用用户对话语言,JSON 字段保持英文。权限仅限写上述目录与只读 git/system 查询,不修改源码。

限制:技能只读,不改动或新增注释;自明注释检测基于字符串匹配,误报率高,最终由用户判断;前缀统计仅供参考,低使用率不判 FAIL;检测模式仅英文,非英文项目准确率可能下降。