注释会撒谎——代码改了三版,注释还停留在第一版,后来者照着注释理解代码,一头栽进坑里。这个问题有个专门的名字:comment rot(注释腐烂)。pr-review-toolkit 插件里的 comment-analyzer Agent 就是冲它来的:以"健康的怀疑主义"逐条核对注释与代码的事实一致性,评估完整性与长期价值,专防文档性技术债。本文按"定位 → 分析框架 → 输出契约 → 提示词工艺 → 总结"拆解这份官方 Agent 定义。
1、定位:注释守护者
comment-analyzer 的系统提示词开篇即定调:"meticulous code comment analyzer……以健康的怀疑主义对待每一条注释,理解不准确或过时的注释会制造随时间复利的技术债"。
它的使命被一句话锚定——保护代码库免于注释腐烂,确保每条注释都提供真实价值并随代码演进保持准确。分析视角也很讲究:站在数月或数年后初次接触这段代码、且没有原始实现上下文的开发者立场看注释。这个视角选择直接决定了它所有的判断标准。
frontmatter 三要素值得注意:model: inherit(跟随宿主模型,不额外指定)、color: green(终端 UI 标识色)、description 里塞了四个触发场景(生成文档注释后、PR 定稿前、存量注释排查、注释准确性验证)——description 就是 Agent 的路由依据,写得越具体,宿主调度的准确率越高。
2、五维分析框架
提示词主体是一个五步分析流程,每步带具体检查项。
- 核实事实准确性——注释里的每个论断与实际代码交叉验证:函数签名与文档参数是否一致、描述行为与代码逻辑是否对齐、引用的类型 / 函数 / 变量是否存在且用法正确、提到的边界情况是否真的被处理、性能与复杂度声明是否准确
- 评估完整性——是否提供了足够上下文又不冗余:关键假设与前置条件、非显而易见的副作用、重要错误条件、复杂算法的思路、不自明的业务逻辑理由
- 评估长期价值——面向代码库生命周期的判断:复述显而易见代码的注释应标记删除、解释"为什么"的注释比解释"是什么"更有价值、随代码变动必然过时的注释应重写、为经验最浅的未来维护者而写、避免引用临时状态或过渡实现
- 识别误导元素——主动搜索误读可能:歧义措辞、指向已重构代码的过时引用、可能已不成立的假设、与当前实现不符的示例、可能早已完成的 TODO / FIXME
- 提出改进建议——具体可执行:不清晰段落的改写建议、需要补充上下文的位置、删除某注释的清晰理由、传递同样信息的替代方案
这五步的设计逻辑是一条递进链:先查"对不对"(事实),再查"够不够"(完整性),然后查"值不值"(长期价值),接着查"会不会坑人"(误导性),最后落到"怎么办"(建议)。
3、输出契约与边界
提示词规定了严格的输出结构,四段式分类报告:
| 板块 | 内容 | 判定标准 |
|---|---|---|
| Summary | 分析范围与结论概览 | — |
| Critical Issues | 事实错误或严重误导的注释 | 位置 / 问题 / 修复建议 |
| Improvement Opportunities | 可增强的注释 | 位置 / 现状 / 改进方式 |
| Recommended Removals | 无价值或制造混乱的注释 | 位置 / 移除理由 |
| Positive Findings | 值得作为范本的好注释 | 有则列出 |
这个"问题分级 + 正面示范"的结构设计有讲究:不只挑错,还树立好注释的标杆,让报告兼具诊断与教育功能。
边界约束同样明确,提示词结尾用大写强调:"You analyze and provide feedback only. Do not modify code or comments directly. Your role is advisory."——只分析、只建议、不改代码,纯顾问角色。这个设计与 Claude Code 的子代理机制配合:Agent 在隔离上下文里跑完分析,报告交回主会话,由人或主 Agent 决定改不改。
4、提示词工艺
作为一份官方系统提示词,它展示了几处值得借鉴的写法。
场景化触发。提示词内嵌"Three representative scenarios":用户主动检查新写文档、助手生成文档后的主动自检、PR 打开前的 diff 注释清扫——每个场景都是一段完整对话情境,宿主模型据此判断何时派活。把"何时用我"写进 Agent 正文而非只写在 description,是双保险。
价值观前置。"健康的怀疑主义""注释腐烂会复利""为最不了解上下文的人而写"——这些原则性表述先于流程出现,让模型在框架未覆盖的边界情况里也能顺着价值观做判断。相比纯规则清单,价值观 + 流程的组合泛化性更好。
可操作的反面清单。不说"注释要写好",而是列出具体的坏味道:复述显而易见的代码、引用临时状态、TODO 可能已完成、示例与实现不符——每一条都是模型可以直接对号入座的检测项。
5、总结
comment-analyzer 是 Claude Code 官方 pr-review-toolkit 插件中的注释审计 Agent:以五维框架(事实准确性 / 完整性 / 长期价值 / 误导性 / 改进建议)逐条核查注释,以"未来维护者视角"评判价值,输出四段式分级报告并附正面示范;只建议、不修改的纯顾问边界保证了它在评审流程中的安全位置。
它的适用场景很清晰:写完文档注释后自检、PR 合入前扫一遍 diff 里新增或改动的注释、存量代码的注释健康度排查。用法上,装好 pr-review-toolkit 插件后无需手动调用——在 PR 评审语境里 Claude Code 会按 description 自动派发,也可以直接说"用 comment-analyzer 检查这批新注释"。值得注意的是:它默认英文输出且检查项偏向 docstring 风格文档注释,中文注释项目可能需要在自己的 CLAUDE.md 里补充本地约定;model: inherit 意味着分析质量跟随宿主模型档位,重要 PR 建议在高档模型会话里跑。对注释腐烂这个老大难问题,这份官方提示词给出了一个可直接落地的自动化答案。


