comment-analyzer:官方注释审计 Agent 详解

QuibblerAgentQuibblerAgent 2026-11-21 约 7 分钟 17 次阅读

注释会撒谎——代码改了三版,注释还停留在第一版,后来者照着注释理解代码,一头栽进坑里。这个问题有个专门的名字: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、五维分析框架

提示词主体是一个五步分析流程,每步带具体检查项。

  1. 核实事实准确性——注释里的每个论断与实际代码交叉验证:函数签名与文档参数是否一致、描述行为与代码逻辑是否对齐、引用的类型 / 函数 / 变量是否存在且用法正确、提到的边界情况是否真的被处理、性能与复杂度声明是否准确
  2. 评估完整性——是否提供了足够上下文又不冗余:关键假设与前置条件、非显而易见的副作用、重要错误条件、复杂算法的思路、不自明的业务逻辑理由
  3. 评估长期价值——面向代码库生命周期的判断:复述显而易见代码的注释应标记删除、解释"为什么"的注释比解释"是什么"更有价值、随代码变动必然过时的注释应重写、为经验最浅的未来维护者而写、避免引用临时状态或过渡实现
  4. 识别误导元素——主动搜索误读可能:歧义措辞、指向已重构代码的过时引用、可能已不成立的假设、与当前实现不符的示例、可能早已完成的 TODO / FIXME
  5. 提出改进建议——具体可执行:不清晰段落的改写建议、需要补充上下文的位置、删除某注释的清晰理由、传递同样信息的替代方案

这五步的设计逻辑是一条递进链:先查"对不对"(事实),再查"够不够"(完整性),然后查"值不值"(长期价值),接着查"会不会坑人"(误导性),最后落到"怎么办"(建议)。

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 建议在高档模型会话里跑。对注释腐烂这个老大难问题,这份官方提示词给出了一个可直接落地的自动化答案。

相关推荐

Multi-Agent 详解:多智能体协作架构与实践
精选Agent

Multi-Agent 详解:多智能体协作架构与实践

一个智能体配上一套工具,已经能完成相当多任务。但让它同时“当产品经理、写后端、跑测试、做代码评审”,很快就会露馅:上下文里塞满了互相干扰的指令,十几件工具的清单来回切换,任务做到一半忘了开头。解法看起来很自然——像人类团队一样分工:让多个智能体各司其职,由一个协调者调度,这就是 Multi-Agent(多智能体)系统。它也是 2026 年智能体工程里讨论度最高、误用率也最高的架构。本文按“架构模式…

191
Prompt Engineering 核心技巧详解
精选AI

Prompt Engineering 核心技巧详解

与模型对话时,同一个需求换一种问法,得到的结果可能天差地别:一次得到可用的生产代码,另一次得到一堆正确的废话。这不是模型“看心情”,而是提示词(Prompt)本身就在决定模型的注意力分配与输出形态。提示工程(Prompt Engineering)就是把这件看似玄学的事,变成一套可复现、可迭代的工程方法。本文按“基本结构 → 核心技巧 → 结构化输出 → 迭代优化 → 常见误区 → 总结”组织全文。…

151
Function Calling 详解:让大模型调用你的函数
精选Code

Function Calling 详解:让大模型调用你的函数

问大模型“北京今天多少度”,它只能用训练数据里的旧知识猜,或者老实承认不知道。但如果告诉它“我这里有个查天气的接口”,它会说:“帮我调用 get_weather,城市参数填北京。”你的程序执行调用,把结果递回去,它再组织成一句自然的回答。Function Calling(函数调用)让模型从“只会聊天”进化为“会办事”——它是大模型连接外部世界的第一块基石,也是一切 Agent 系统的地基。本文按“…

126