用途
no-comments 是一款代码注释清理技能,核心原则是:代码和测试是真正运行的内容,而注释是一种没人验证的声明。它把既定的注释规则应用到用户选定的范围,并在所有者批准一项正式提议后,才实际执行注释的删除与改写。
主要能力
- 确定范围:通过
/no-comments <files|diff>指定清理范围;不带参数时,范围为当前相对于基线分支的 diff。 - 全新审查者裁定:将范围交给另一模型(可通过 T3 delegate_task 调用)或新的子代理,逐条注释给出三种裁定之一:
delete:已过时,或只是复述代码本身已表达的内容;keep:需指出适用的 CORE 例外及证据;reshape:注释掩盖了自有代码中的意外情况,需指出应重命名、抽取或标注类型的精确符号,让代码自身表达该含义。
- 特殊情况处理:
- 注释与代码矛盾时,依据代码、调用方和测试确认真实行为;若注释陈述的是意图契约(公共文档注释,或与规格、测试名、DECISIONS 条目、issue 一致),则作为可能的缺陷上报,不得靠删注释或假定代码正确来解决。
- 约束性声明(如 IMPORTANT、do not remove、talk to X first)需追踪符号并查看其历史(git log、blame、DECISIONS):可验证且可编码的,提议改为测试、类型或 lint 后删除;可验证但不可编码的,作为例外保留;无法验证的,保留并列入清单交由所有者。
- 可执行注解与抑制(PHPDoc/PHPStan 类型、JSDoc 类型、装饰器、pragma、@ts-expect-error、eslint-disable、# type: ignore)会被工具读取,应保留;仅在提议给出替代方案且类型检查或 lint 通过后才移除。隐藏正确性或安全规则的抑制应标记出来,不得直接删除。
- 逐项核对:在提出任何提议前,使用者需核对每一项裁定,拒绝范围之外的编辑或理由错误的裁定,并检查每个保留理由。
- 一次正式提议:通过 workflow-specify 第 5 步(record.py offer create)生成一个提议,涵盖删除项、改写项以及将转为测试或 lint 的约束,并展示 record.py offer present 打印的记录,以其结尾的问题作为确认;用自己语言表述的提议无法获批,获批前不做任何改动。
- 无行为变更地应用:批准后执行删除与改写,随后运行测试和类型检查;删除注释不得改变行为,若改写会改变行为则报告而非执行。
- 报告:列出删除项、保留项及其例外、已执行的改写、转为测试或 lint 的约束,以及待办事项(可能的缺陷、未验证的约束、被拒绝的裁定)。
使用方式
调用 /no-comments <files|diff> 并指定范围;随后审查裁定、核对每项结论,再通过正式提议流程提交所有者批准,获批后执行并验证。
适用场景
适合在选定文件或 diff 范围内系统清理注释、把可编码的约束沉淀为测试或类型检查,并保持行为不变的开发流程。
限制
依赖 CORE 规则(位于 ../rule-maker/rules/CORE.md);需要所有者批准提议后才能改动;删除注释不得改变行为;无法验证的约束需保留并上报。