comment-cleanup

用途

comment-cleanup 用于清理源代码文件和 README 中的低价值文字注释，且不改变程序行为。其输出应是仅涉及注释的差异，范围限定为三种模式，其余内容一律不动。

对每条注释应用同一判断标准：它是否告诉读者一些无法从附近几行代码中获得的信息？能则保留（必要时缩短），不能则删除。

注释重复相邻代码：内容可从上下文几行推断出来，直接删除。典型迹象包括注释改写函数名、变量名或分支条件，预告下一行（如“# Loop over users”“// Return result”），或给首行已说明同一意思的代码块加标签。
注释叙述历史或被移除的功能：解释过去的状态、某次改动或某个 PR，这类内容应属于 PR 描述或版本控制。删除历史部分，保留读者仍需要的现在时事实。典型迹象包括“previously”“used to”“no longer”“now we”“after PR-...”“changed from”“was renamed”以及日期和作者名。
注释冗长：含有真实原因但夹杂叙事、轶事、重复或不需要的细节，压缩为保留原因的最短措辞。替换时只在周围代码或调用方表明目的时才写目的，绝不臆造目的；否则用更少文字保留原意。

每种语言的具体示例、边界情况和 README 规则见 references/patterns.md，应在会话首次编辑前阅读。

代码：注释之外的任何字符都不改，不重排格式、不调整缩进、不排序 import，也不做顺手修复。
文档字符串与文档注释：包括 Python docstring、JSDoc/TSDoc、Javadoc/KDoc 的 /** ... */、Rust 的 /// 和 //!、C# 与 Swift 的 ///、Doxygen 块、Go 中声明正上方的注释、Ruby 中 def/class 上方的 RDoc/YARD 注释、Elixir 的 @doc/@moduledoc。
机器可读注释：shebang、编码行、许可证与版权头、# noqa、# type: ignore、# pragma、// eslint-disable...、// @ts-...、//go:...、// nolint、#region、# fmt: off、# pylint:、// prettier-ignore、覆盖率标记。
解释为什么的注释：理由、带关联缺陷的临时方案、顺序或线程安全约束、安全说明、单位、非显而易见的不变量、警告。
带负责人、工单或具体下一步的 TODO/FIXME/HACK。
被注释掉的代码：不在范围内，留给人工处理。
生成、vendored 或第三方文件。

不确定某条注释是否值得保留时，保留它。漏删代价小，删掉不变量可能带来缺陷。

只检查请求明确指定的文件，不碰其他文件。

若请求未给范围（如“clean up the comments”），应先询问要检查哪些文件或目录，例如“src/ 下所有 Python 文件”“本 PR 中改动的文件”或“README.md 和 docs/”，不要默认整个仓库。

若请求给出范围（如“src/ 下所有 Python 文件”），用 git ls-files 展开为具体列表（例如 git ls-files 'src/*.py'，也会匹配嵌套目录），文件数超过约 50 个时先确认数量再开始。

若请求给出明确文件列表（如定时自动化任务），只检查这些文件，不要询问，也不要打开其他文件，除非需要读取某条注释引用的定义。

范围内若出现生成、vendored 和压缩文件，仍应跳过。

每个会话首次编辑前阅读一次 references/patterns.md。
完整阅读每个文件，将每条非文档注释分类为保留、删除（模式 1 或 2）或缩短（模式 3）。
只编辑注释行。删除整行注释时，一并删除仅为分隔它而存在的空行，其余间距不动。
在 git 仓库中，从仓库根目录运行 python3 <skill-dir>/scripts/verify_comment_only.py。该脚本会在注释之外出现未提交改动时报错（对 Python 还会捕获 docstring 编辑）。修复或还原（git checkout -- <path>）每个失败文件，直到脚本返回 0。
阅读验证器在 REVIEW 下列出的每个 README 的完整差异，还原任何改动命令、链接、代码块或含义的片段。
报告各模式删除或缩短的注释数量、未改动的文件，以及有意保留的可疑注释。