SuperAPI AI 工具集

speckit-review-comments

编程与开发

查看项目

更新于 10-16 03:11

技能介绍

用途:审查代码注释的准确性与长期价值,防止注释腐化带来的技术债。它会以将来接手代码的开发者视角,判断每条注释是否真实、必要、清晰。

主要能力:核对注释与实现是否一致,包括函数签名与文档参数、返回类型、描述行为与代码逻辑、引用的类型/函数/变量、提到的边界情况、性能或复杂度说法;评估完整性,如关键假设与前置条件、非显而易见的副作用、重要错误条件、复杂算法思路、非自明的业务逻辑理由;评估长期价值,标记仅复述代码的注释,优先保留解释“为什么”而非“做什么”的注释;识别误导因素,如歧义表述、对已重构代码的过时引用、可能不再成立的假设、与实现不符的示例、可能已解决的 TODO/FIXME;最后给出可操作改进建议,包括改写、补充上下文、删除理由与替代表达方式。

输出结构:摘要、严重问题(位置 file:line、问题、建议)、改进机会(位置、现状、建议)、建议删除的注释(位置、理由)、正面示例。

使用方式:若用户给出文件列表或获取文件的明确指令,按其执行;否则必须用 --json 执行 .specify/scripts/bash/detect-changed-files.sh 检测变更文件,不要用 git 命令或其他方式自行判断。该脚本会自动选择模式:A(功能分支)从合并基点将当前分支与默认分支 main/master 比较,并含暂存与未暂存变更;B(工作目录)无功能分支时回退到暂存与未暂存变更。JSON 输出包含 branch、default_branch、mode、changed_files。脚本所在目录可能不在版本控制内或被搜索索引隐藏,仍需定位并执行。

适用场景:提交前或评审中检查注释质量,尤其适合长期维护的代码库。

限制:仅分析与反馈,不直接修改代码或注释,属建议性角色;其他未提供的细节暂未提供。