该技能用于对照源码实际行为检查注释,并在同一次运行中修复已确认的不一致或噪声。核心限制是只允许编辑注释,绝不为了迁就注释而改动可执行代码。\n\n使用方式:接受零个或多个文件或目录路径;无参数时使用当前仓库根目录,路径按当前工作目录解析,无法读取的路径会被报告。它会发现 JavaScript、JSX、TypeScript、TSX 和 Go 源文件,默认排除测试、testdata、fixtures、快照、stories,以及 generated、vendor、依赖、覆盖率、缓存和构建输出目录,还包括压缩后的 JavaScript 和生成的 Go 文件。显式指定的测试文件或目录只覆盖测试排除规则。可用时借助仓库感知的发现方式(如 git ls-files 或 rg --files)。\n\n分析将文件拆分为约十个的非重叠批次,可委托只读子代理并行处理。对行、块和文档注释,结合相邻代码、引用符号、调用方、配置和仓库历史进行分类:STALE(描述的行为已不存在)、ORPHANED(引用已不存在的符号、路径、标志或概念)、MISLEADING(暗示的行为与实际实现有实质不同)、REDUNDANT(仅复述自解释代码、不含意图或约束)。风格偏好、措辞不完美、有价值的理由说明或不确定情况不作为发现报告。\n\n对 Go 中含行为语义的注释(//go:*、//line、//nolint、构建约束、cgo 前导、go:embed、包注释、导出符号文档、并发与所有权约定等)需按程序行为处理,不得仅因相邻声明明显而判为冗余。\n\n修复前会汇总去重并重新打开每个候选位置验证行号与证据,无法验证的发现会被丢弃;干净结果有效,不应以低置信度发现填充。修复采用最小的仅注释改动,行为相关的 Go 注释只有在语义明确时才修改,否则保持原样并报告未修复。所有写入在主执行上下文完成,不委托写入。修改后会重新检查并与实现核对,运行最窄范围且能证明文件有效的格式化、lint、类型检查、测试、构建或 Go 工具验证。\n\n报告按固定结构输出:修复数量表、按分类列出的修复明细、验证命令与结果、未修复和未复查项;空分类可省略。若全部复查且无发现,则以无确认问题开头;若存在未复查文件,以“Review incomplete”开头;若有确认但无法安全修复的问题,以“Comments partially fixed”开头。分类标识、路径、行号、命令、指令和引用的注释文本需保持原样。
stale-comments-audit
编程与开发
更新于 10-16 03:16