SuperAPI AI 工具集

no-comments

编程与开发

查看项目

更新于 10-16 02:10

技能介绍

用途

no-comments 是一个面向代码审查场景的智能体技能,目标是在审查被编辑过的代码时,将注释数量降到最低。其立场是:注释会撒谎,叙述、横幅、被注释掉的死代码、权宜之计的说教都可能腐坏,不是今天就是以后。技能适用于被编辑过的代码文件的审查环节。

审查范围

技能使用调用者提供的文件或 diff 作为范围;若未提供,则使用相对基线分支的当前 diff,其中包含已暂存、未暂存和未跟踪的文件。

主要能力

  • 将审查委托给一个全新的、只读的子智能体,并传递范围与相关说明。如果没有可用的新审查者,则直接审查,并披露该审查并非独立进行。审查者只报告,从不编辑文件。
  • 维护一份注释“保留白名单”,只有满足白名单例外且证明其适用于仍在运行的代码时,注释才会被保留。
  • 对不在白名单中的抑制,识别其规则,建议删除该抑制,并以 MUST KILL 标记被抑制的符号,同时给出满足规则所需的具体改动。
  • 对解释我们自身代码中令人惊讶行为的注释,建议删除,并以 MUST KILL 标记精确符号,附上使之无需文字即显而易见的改名、抽取、类型或重新设计。
  • 结束时要求报告列出范围内每一条注释和抑制,标注为删除候选(含精确位置)、带一行证据的 MUST KILL 标记,或带保护例外的保留项。要求不虚构内容,且不越出范围。

保留白名单

只有以下注释可被保留:

  1. 法律或许可证头部。
  2. 由外部依赖、平台、供应商或协议强制的、我们无法重塑的非显而易见行为。
  3. 规则有误、过于学究或仅涉及风格的 lint 抑制。
  4. 定义公共 API 契约的文档注释。
  5. 解释代码无法表达的约束的 issue 或 RFC 链接。
  6. 指明刻意简化之上限与升级路径的注释。

保留注释需要证明其例外适用于仍在运行的代码。IMPORTANT、do not remove、too risky、fine for now 以及冗长辩解都被视为主张,而非证明。需要阅读附近代码并追踪被指名的符号或调用。技能明确要求:不得缩短或改写任何未通过保留白名单的注释。

使用方式

技能依据审查者的报告,按以下步骤执行:

  1. 对照代码校验每条发现。拒绝范围之外的发现、受保留白名单保护的删除、没有证据的主张,以及理由错误的 MUST KILL 标记。如果报告遗漏范围内任何注释或抑制,则拒绝该报告。被拒绝的审查重跑一次,并指明每项失败;若重跑仍被拒绝,则停止并将审查报告为失败。
  2. 删除所有被接受的删除候选,但声称我们代码中约束的注释除外,这些由第 4 步处理。
  3. 对每个 MUST KILL 标记,实施范围内最小的根因修复,例如删除死路径、移除未用参数、使用真实 API,或执行该标记所指名的改动。不扩大范围。若原因超出范围,则只做范围内最小的安全修复,并将其余部分报告为未完成工作。
  4. 对声称我们代码中约束的每个删除候选,提供范围内最廉价的类型、运行时检查、测试或 CI lint 方案并等待批准。若获批准,编码该约束并删除注释;否则保留注释并报告该未强制执行的约束。
  5. 对每一条被保留的注释(法律或许可证头部除外)应用 unslop。

结束报告

完成后报告删除数量、带证据的保留注释、重跑情况、修复、编码情况、未强制执行的约束及其他未完成工作。

适用场景与限制

该技能面向代码审查与被编辑代码文件的清理流程,属于编程与开发范畴。资料中未提供其支持的具体平台、安装命令、配置方式、价格或收费信息,这些暂未提供。