用 claude code 自动生成代码注释的最佳实践争议

过去六个月，我在三个项目里深度使用了 Claude Code 的自动注释功能。第一次是在一个支付系统的重构项目里，第二次是在一个 SaaS 平台的组件库迭代中，第三次是带一个五人团队从零搭建新的数据中台。

三次体验下来，我得出了一个让很多人不舒服的结论：自动生成注释这项功能，在它最被吹捧的那些场景里，恰恰是最危险的存在。

不是因为技术不行。恰恰相反，Claude Code 生成注释的能力强到让人害怕，它能在一秒内给一个 300 行的类写完 JSDoc，格式规范、措辞流畅，甚至连参数类型推导都准确无误。但正是这种“丝滑”的表象，掩盖了它最深层的问题。

上周我在 Code Review 时看到一段代码，注释写得堪称教科书级别：

/**

处理订单状态流转

@param orderId 订单ID

@param targetStatus 目标状态

@returns 处理结果

*/

async function processOrderStatus(orderId: string, targetStatus: OrderStatus): Promise<ProcessResult> {

// 验证订单存在

const order = await validateOrder(orderId);

// 检查状态转换是否合法

checkStatusTransition(order.currentStatus, targetStatus);

// 执行状态更新

const result = await updateOrderStatus(orderId, targetStatus);

// 返回处理结果

return result;

}

看似完美，对吧？但真正的问题是什么？这段注释什么都没告诉你。 它没有告诉你 validateOrder 可能会抛出三种不同的异常；没有告诉你 checkStatusTransition 里埋了一个反直觉的边界条件（已退款订单在特定时间窗口内可以逆向流转）；更没有告诉你为什么这个函数被设计成可重入的，以及它和上层的幂等性方案是怎么配合的。

这就是问题的核心：Claude Code 生成的注释，本质上是对代码结构的“翻译”，而不是对设计意图的“解释”。

而目前市面上的绝大多数“最佳实践”文章，都在教你如何让它翻译得更精准、更快、更规范。却很少有人告诉你：翻译得越好，掩盖的问题越深。

一、先谈核心结论：自动注释不是没价值,而是价值被放错了位置

在展开所有争议之前，我必须先把我的核心判断说清楚。

Claude Code 自动生成注释这件事，真正的问题不是“能不能用”，而是“在什么层级上用它”。当前业界的主流做法是：把所有代码都扔给 AI，让它生成尽可能完整的注释。这种做法，恰恰是把 AI 用在了它最不擅长的层级上。

我的判断框架是这样的，我把它叫 “注释的三层价值模型”：

第一层：结构描述层。 这是 AI 擅长的。例如：这个函数叫什么、接收什么参数、返回什么类型、类之间的继承关系。这些信息，代码本身已经表达得很清楚了，注释只是做了一次“翻译”。Claude Code 在这个层级上的准确率可以做到 90% 以上，而且速度极快。

第二层：行为说明层。 这是 AI 能胜任但需要监督的。例如：这个函数里面做了哪些步骤、调用了哪些关键方法、有哪些重要的条件分支。AI 可以准确描述“代码做了什么”，但经常会遗漏“为什么选择这样做”和“什么情况下不这样做”。在这个层级上，Claude Code 的准确率大概在 60%-70%，取决于代码的复杂度。

第三层：决策与约束层。 这是 AI 目前基本无法胜任的。例如：为什么这个模块要设计成观察者模式而不是发布订阅、为什么这个字段的类型是 string 而不是枚举、为什么这个定时任务被设置在凌晨三点而不是业务低峰期、为什么这个边界条件被特意保留。这些信息，是代码里没有的，它们存在于开发者的脑子里、PRD 的讨论记录里、线上的事故复盘里。Claude Code 在这个层级上的准确率，乐观估计也不到 15%。

而真正有价值的注释，恰恰在第三层。

所以我的第一个核心结论是：如果你用 Claude Code 来生成大量第一层和第二层的注释，你会得到一份看起来很漂亮但信息密度极低的文档；如果你指望它帮你处理第三层的注释，你不仅会失望，还可能因为“看起来很靠谱”的假象而忽略真正重要的信息缺失。

这不是 Claude Code 的问题。这是当前大语言模型（包括 Claude 4.5 Opus）在代码理解范式上的根本局限：它们是基于 token 序列预测完成训练的，可以完美地“看到”代码的结构，但无法真正“理解”代码背后的上下文、组织记忆、和隐含的工程权衡。

二、背景：为什么“自动注释”突然变成了热点

要真正理解这个争议，我们得先回到 2024 年底到 2025 年初这个时间节点。

Anthropic 在 2024 年 10 月正式推出了 Claude Code，一个基于 Claude 模型的命令行编程助手。相比 GitHub Copilot 那种“在 IDE 里补全代码”的模式，Claude Code 的做法激进得多：它直接接管了终端，可以读文件、写文件、执行命令、管理 Git。

这让“自动生成注释”这件事从“锦上添花的小功能”突然变成了“可以批量化、规模化操作的工程实践”。以前你用 Copilot 写注释，是一行一行补全；现在你用 Claude Code，是一个指令下去，整个项目的注释都被补齐了。

这件事的热度，本质上是三个趋势的叠加：

趋势一：AI 编程从“辅助”到“代理”的范式转移。 Claude Code 代表的不是更强的自动补全，而是“让 AI 独立完成一个完整工程任务”的可能性。自动注释，是这个范式转移里最容易出效果、也最容易被过度使用的一个场景。

趋势二：技术债的量化管理开始流行。 越来越多的团队在用 SonarQube、CodeClimate 这类工具给代码质量打分，而“注释覆盖率”经常被当作一个硬指标来考核。这就产生了一个强烈的动机：用 AI 快速提升这个指标。但它解决的到底是质量问题，还是指标问题？

趋势三：大语言模型在代码理解上的突破给很多人造成了错觉。 Claude 4.5 Sonnet 和后来的 Opus 在 HumanEval、SWE-bench 这些基准测试上的表现确实惊艳。但很多人混淆了“能写代码”和“能理解代码”这两个概念。写代码是一个生成任务，理解代码（并写出真正有用的注释）是一个需要深层推理和组织知识的认知任务。

这三个趋势交织在一起，催生了一个奇特的现象：整个行业在热烈讨论“最佳实践”，但很少有人停下来问一句：我们到底在最佳实践什么？

我在今年三月份参与了一个开源项目的注释规范化讨论。那个项目的核心维护者直接用 Claude Code 给整个代码库跑了一遍注释生成，然后提交了一个包含 4000 多行注释变更的 PR。他的理由是：“先把注释覆盖率拉到 80% 以上，后面再慢慢改”。

这件事的结果是什么？三个月后，有开发者发现：一个关键模块里的注释明确写着“此方法在单线程环境下安全”，但实际上那段代码在多线程环境里跑了一年没出过问题，注释反而制造了不必要的恐慌。这个例子不是孤例，它代表了一个系统性的问题：自动生成的注释，正在把“不确定的猜测”变成“看起来确定的事实”。

三、争议的本质：五大误区正在同时发生

我在前面铺垫了这么多，就是为了现在能拆得足够深。过去半年我在不同场合（技术播客、闭门讨论、客户咨询）里反复讨论这个话题，发现争议并不是围绕某一个点展开的，而是同时发生在五个维度上。

这五个误区，不是平行并列的，而是一个逐渐深化的链条。如果你只是掉进了前两个误区，你可能做出来的注释“只是没用”；如果你五个全中了，那你很可能在用 AI 系统性地破坏团队的代码认知。

我用一个表格先把它们列清楚，然后逐个拆解：

误区一：效率幻觉，“它生成只要 3 秒，我省了一下午”

这是最常见、也最容易反驳的误区。但反驳它需要一个完整的成本模型，而不是一句话的结论。

我先讲一个我自己的实测数据。在今年一月份那个支付系统重构项目里，我专门做了一次对比实验。我选了三个复杂度不同的模块：

• 模块 A：交易流水模型层（低复杂度）。主要是一些 POJO/DTO 类，字段多但逻辑简单，CRUD 为主。代码量大约 800 行。
• 模块 B：对账引擎（中复杂度）。包含一些核心算法，但业务逻辑清晰，代码量大约 1200 行。
• 模块 C：退款状态机（高复杂度）。多线程、事务嵌套、补偿逻辑、状态流转的边界条件极其复杂，代码量大约 600 行。

我分别记录了“让 Claude Code 生成注释的时间”、“我审查这些注释的时间”、“我修改/补充注释的时间”。结果如下：

看到了吗？在所有情况下，“生成”这个动作的时间成本都可以忽略不计。真正的成本在“审查”和“修改”上。

对于模块 A（低复杂度），总耗时 11 分钟，我自己写可能只需要 15-20 分钟，省了一点，但没有数量级的差异。

对于模块 B（中复杂度），总耗时 40 分钟，我自己写如果一个一个认真琢磨，大概需要 60-80 分钟。看起来省了将近一半，对吧？但注意，这个比较是“AI 生成+我审查修改”和“我自己从头写”的对比。如果我只是选那些真正需要注释的核心方法手工写，可能只需要 30 分钟，而且质量更高。

对于模块 C（高复杂度），总耗时 99 分钟。好，问题来了：我自己给这个退款状态机写注释，需要多久？答案是：如果是我自己写（我熟悉这个业务），大概也是 90-120 分钟。但是，我写的注释会包含那些关键的决策信息；而 AI 生成的注释，我在审查和修改时，实际上是在逆向理解一段我并不完全熟悉的代码（这是我接手的遗留代码），这个过程的认知负荷，远大于我自己写。

所以我的结论是：“效率提升”只有在低复杂度、高重复度的代码（POJO、DTO、DAO 接口、简单工具方法）上成立。对于任何包含业务逻辑的代码，净效率提升要么不明显，要么是负的。而这个“负效率”，往往以“知识没有被真正消化”的形式隐性存在，不会在你的工时统计里显示出来。

误区二：准确率崇拜，“它写的都是对的啊”

这个误区比效率幻觉更危险。因为效率问题只是“浪费时间”，准确率问题直接关系到“引入错误”。

我需要先定义清楚什么叫“准确”。我说的不是“语法正确”，是“语义正确”。语法正确意味着：注释和代码不矛盾，你看注释去看代码，能找到对应的实现。语义正确意味着：注释准确地描述了这段代码的设计意图、适用场景、和边界条件。

Claude Code 的语法正确率确实很高，我估测在 85%-95% 之间。但语义正确率？取决于你拿什么标准来衡量。

我来给几个我实际遇到的例子，按严重程度分三级：

轻度：废话型准确。 它说的都是对的，但毫无信息量。比如 // 获取用户信息 放在一个 getUserInfo 方法上面。这是对的，但没有增加任何信息。这种注释本身不带来危害，但它占用了阅读者的注意力，让你在扫描代码时不得不消耗认知资源去判断“这条注释有没有信息”。

中度：片面正确。 它说了一部分，但漏了关键的另一部分。比如这段代码：

def calculate_discount(user, order_amount):
根据用户等级计算折扣

discount_rate = get_user_discount(user.level)

订单金额超过500应用额外折扣

if order_amount > 500:

discount_rate += 0.05

return order_amount * (1 - discount_rate)

AI 生成的注释看起来没问题，对吧？但它漏掉了什么？它没有告诉你：get_user_discount 可能返回 None（如果用户的等级数据是脏数据），也没有告诉你“额外折扣”的叠加逻辑是不是幂等的（如果多次调用会不会一直叠加），更没有告诉你为什么阈值是 500 而不是其他数字，以及这个阈值和营销规则引擎的关系是什么。

这些都是“正确但不完整”的注释。对于后来维护这段代码的人来说，它们提供了虚假的安全感，让人以为看懂了，但其实最要害的东西一个都没看到。

重度：事实性错误。 这是最可怕的，但发生的概率比你想象的高。我举一个让我后背发凉的例子。

在我们的支付系统里，有一个处理退款回调的方法。Claude Code 生成的注释里有一句：// 退款成功后，订单状态流转为 REFUNDED。

但实际上，这段代码的逻辑是：只有在全额退款的情况下，订单状态才流转为 REFUNDED；部分退款时，订单状态保持 PARTIAL_REFUND，同时触发一个异步任务去重新计算分账。

AI 看到了 updateStatus(REFUNDED) 这一行，就推断“退款成功后状态变为 REFUNDED”。但它没有看到上面还有一个 if 分支，在 isPartialRefund 为 true 的情况下根本不会走到这一行。

这个例子让我意识到一个关键规律：Claude Code 在生成注释时，倾向于对代码的“主路径”进行描述，而系统性忽略异常路径、补偿逻辑、和边界条件分支。 这是由 transformer 架构的注意力机制决定的：在主路径上的代码占据了主要的 token 序列，异常分支在训练数据的分布里也是低频模式。

误区三：规范一致性错觉，“全项目注释风格终于统一了”

这个误区最容易被技术管理者拥抱。因为管理者天然关注“规范”和“一致性”。当一个工具可以瞬间让整个项目的注释风格统一（都是 JSDoc 格式、都是相同的缩进、相同的标签顺序），这看起来像是工程能力的巨大进步。

但我必须说：统一了注释的格式，和统一了注释的质量，是两件完全不相干的事。而且前者往往会制造后者的假象。

让我讲一个真实的团队冲突场景。今年四月，我带的数据中台团队在制定注释规范时，产生了一次很激烈的讨论。我们的前端组长是 TypeScript 和 JSDoc 的坚定拥护者，他提出：所有函数必须使用 JSDoc 格式注释，包括 @param、@returns、@throws 标签。他的理由是：这样 IDE 的类型提示会更友好，而且 Claude Code 可以一键生成。

后端组长则反对。他说了一段话我至今记得很清楚：“Claude Code 生成的 JSDoc，对于 getUserById 这种函数来说是完美的。但我们现在数据库里 40% 的查询都是多表联查加子查询加窗口函数，它生成的 @param 描述是 userId: 用户ID，这对我来说没有任何价值。我真正需要写清楚的是：为什么这个查询用了 LEFT JOIN 而不是 INNER JOIN，为什么子查询的过滤条件是在 JOIN 之后而不是之前，以及这个查询的执行计划在数据量增长到千万级以后会怎么变。这些东西，JSDoc 装不下，Claude Code 也生成不了。”

那次讨论之后，我们做了一个决定：把注释分成两级。一级注释（对外接口、公共方法）使用严格的 JSDoc 格式，可以由 Claude Code 生成框架然后人工填充关键信息；二级注释（内部实现、复杂逻辑）不强制格式，但强制内容，必须包含“为什么这样写”和“什么情况下会出问题”。

这个分级策略执行了两个月之后，效果超出了我的预期。让我用一张表来对比：

看到了吗？“注释覆盖率”这个指标的升高，和“开发者真正理解代码”之间，可能是负相关的。 因为覆盖率越高，意味着越多的“废话注释”和“片面注释”被塞进了代码库，它们不仅没有帮助理解，反而稀释了那些真正有价值的注释。

这个发现让我重新定义了“注释规范”：好的注释规范，不是追求“所有地方都有同一格式的注释”，而是“在真正需要注释的地方，有足够深度的注释，并且这些注释的格式让它容易被找到和理解”。

误区四：知识外化陷阱，这一条最不容易察觉，但后果最深远

这是我整个文章最想讲清楚的一个点。因为它触及了编程活动最本质的东西，但它又非常容易被忽略。

让我先问一个问题：你写注释，是为了让别人看懂，还是为了让自己真的懂了？

大多数人的回答是“让别人看懂”。这个回答没错，但它忽略了注释的一个隐藏功能：写注释的过程，是一个强制你自己深度思考的过程。

当你在写 // 这里不能使用缓存，因为上游系统是准实时的，允许最大 3 秒的延迟，但缓存刷新周期是 30 秒 的时候，你不是在“翻译”代码，你是在整理和验证自己的思维。你在问自己：我真的理解这段代码的约束条件吗？我有没有把所有的边界情况都考虑过？我有没有做出过为了性能牺牲一致性的决策，并且清楚地知道这个决策的代价？

这个过程，我称之为 “注释的认知闭环” ：理解 → 组织 → 表达 → 审视 → 修正理解。

当你把这个过程外包给 Claude Code，你跳过了最关键的“组织”和“表达”环节。你看着 AI 生成的那段流畅的注释，大脑会产生一个错觉：“哦，这个我懂了。” 但实际上，你是被 AI 的表达流畅度给骗了，你以为你懂了，其实你只是读懂了 AI 写的字面意思。

这不是我凭空臆想出来的。认知科学里有一个概念叫 “流畅性启发”（fluency heuristic）：人类倾向于认为，容易处理的信息就是正确或可信的。AI 生成的注释，因为语言流畅、格式规范、措辞专业，会触发这种认知偏差。

我在团队里做过一个非正式的观察实验。我让两个开发者分别接手一个他们不熟悉的模块：

• 开发者 A：自己阅读代码，自己写注释（花了一整天）。
• 开发者 B：让 Claude Code 生成注释，然后阅读理解这些注释（花了三个小时）。

一周后，我分别问他们两个关于那个模块的关键设计决策的问题。开发者 A 能准确回答 80% 的问题，开发者 B 只能回答 40%。 这不是智商或能力的差异，两个开发者都是高级工程师。这纯粹是认知过程的差异：A 通过“被迫思考和表达”建立起了对代码的深层心智模型；B 只是“消费”了 AI 生成的文本，没有经历那个认知闭环。

而且更麻烦的是，B 对自己知识水平的信心反而更高。当我问“你对这个模块的理解程度打几分”的时候，A 打了 6 分，B 打了 8 分。实际表现和自评信心的倒挂，是知识外化陷阱最典型的副产物。

误区五：所有权稀释，“注释不是我写的，我不用对它负责”

这是五个误区里最偏“组织行为学”的一个，但在工程实践中的影响绝对不小。

当注释是由开发者在理解代码的过程中亲手写的，有一种隐性的心理契约：“这段注释代表了我对这段代码的承诺。” 如果后来发现有错，我有义务去修正它，因为它是“我的表达”。

但当注释是 AI 生成的，这个心理契约就瓦解了。开发者会觉得：“这不是我写的，我只是没有发现它有问题”或者“这是工具生成的，它本来就不保证完全正确”。这种心态会导致一个结果：注释进入代码库之后，就不再被维护。

我观察到一个非常具体的现象。在我们的代码库里，有一段人工写的注释长这样：

// 注意：这里的重试次数设置为 3 而不是 5，
// 因为在弱网环境下（用户侧的移动网络 RTT > 2s 的占比约 15%），

// 超过 3 次重试会导致用户等待时间超过产品定义的最大容忍时长（7 秒）。

// 这个数字是和产品组、客户端组对齐过的，修改前请同步到跨端文档。

这段注释，是那个开发者花了 15 分钟写的。他查了监控数据、找了产品文档、确认了对齐机制。这段注释的价值，远超它字面上写的那些信息，它告诉你：“这个数字背后有一套跨团队的决策机制，不要随意改动。”

现在想象一下，如果这段注释是 Claude Code 生成的，它会写成什么样？

// 设置重试次数为3，最大重试次数
private static final int MAX_RETRIES = 3;

看出来了吗？AI 生成的注释删掉了所有非显而易见的上下文信息，把一段承载了跨团队共识和工程权衡的注释，简化成了一句对代码的重复描述。 这不是补充信息，这是删除信息。

而一旦这种低信息密度的注释大量进入代码库，开发者会产生一种心态：“注释都是工具生成的，没什么可看的，还是直接读代码吧。” 这种心态一旦形成，那些残存的、真正有价值的人工注释也会被连带忽略。

这就是所有权稀释的完整链条：AI 生成注释 → 开发者不对它负责 → 注释质量持续劣化 → 开发者不再信任注释 → 所有注释都被忽略。

四、深水区：什么时候 Claude Code 自动注释确实好用

我必须声明，我不是在否定这个功能。我是在说，这个功能被系统性地用错了地方。在这一节，我想认真讨论一下：哪些场景下，Claude Code 自动注释确实是正收益的。

我的判断基于一个核心逻辑：注释的信息增量和代码的复杂度成反比时，自动注释有效；成正比时，自动注释危险。

说人话版本：代码越简单、越像样板文件、越不需要设计思考，自动注释的信息增量就越高（因为人工写也写不出什么花来）。代码越复杂、越涉及深层决策、越依赖上下文，自动注释的信息增量就越低甚至为负。

基于这个逻辑，我划分出四个有效场景：

除此之外，我还发现了一个很多人没注意到的有效用法：用 Claude Code 来生成“注释的草稿”，然后人工进行“重写”而不是“修改”。

这听起来像是一个文字游戏，但实践中差异很大。当你进入“修改模式”时，你的注意力集中在“这个注释哪里不对，我要改掉它”，你的认知过程是纠错。当你进入“重写模式”时，你先把 AI 的注释看一遍，然后关掉它，自己写一遍，最后再打开 AI 版对比一下，你的认知过程是重新理解并表达。

重写模式花的时间比修改模式多大概 30%-50%，但它带来的理解深度提升，在我们的非正式对比里是 2 倍以上。

五、行动指南：在不同情况下如何取舍

到目前为止，这篇文章停在了“争议是什么”和“为什么会有这些争议”上。接下来，我要给出一个可以在团队里直接落地的决策框架。

第一步：对你的代码库做一次“注释价值分级”

不要想着“所有代码都要有高质量的注释”，这既不现实，也不合理。更好的做法是，把代码分成三级，每一级对注释有不同的要求：

A 级（高价值注释区域）：

• 核心业务逻辑（状态机、事务流程、规则引擎）
• 复杂算法（非标准实现、带优化的数据结构）
• 跨模块的契约接口（对外暴露的 API、消息队列的消息体）
• 历史上出过 bug 的代码段（标上为什么出 bug、为什么这样修）
• 注释要求：必须包含“为什么”和“边界条件”，不允许仅由 AI 生成，AI 只能作为草稿工具

B 级（中等价值注释区域）：

• 内部服务方法（有一定逻辑但不涉及核心业务）
• 配置类和常量定义（需要说明取值来源和变更影响）
• 复杂的数据查询（多表关联、子查询、聚合）
• 注释要求：可先由 AI 生成框架，然后人工补充关键信息。审查时间不短于生成时间的 3 倍

C 级（低价值注释区域）：

• DTO、POJO、VO
• 简单的 getter/setter
• 框架强约束下的样板代码
• 单元测试（仅限测试意图描述，不需要解释测试逻辑）
• 注释要求：可由 AI 全量生成，抽样审查即可

这个分级不是一成不变的。一个模块如果经历了重构、或变成了性能瓶颈、或频繁出 bug，它应该从 B 级或 C 级提升到 A 级。

第二步：为 Claude Code 注释建立“三必须审查清单”

不管你的团队多信任 AI，对于任何进入 A 级和 B 级区域的 AI 生成注释，必须通过以下三条检查：

必须检查一：“这句注释删掉以后，还有别的信息源能告诉我它说了什么吗？”

• 如果答案是“能”，代码本身就能说明白，那这句注释就是冗余的。
• 如果答案是“不能”，说明注释确实承载了代码之外的信息，那就要检查这个信息是否准确。

必须检查二：“如果这段代码在未来被修改了，这个注释会跟着被更新吗？”

• 这不是让你预测未来，而是让你审视：这个注释和代码之间的耦合程度。如果注释写得太具体（比如：// 循环遍历前100个元素），那么未来代码改成遍历 200 个时，注释必然会变成错误信息。好的注释应该描述设计意图（比如：// 只处理当前页的数据，避免一次加载全部导致 OOM），而不是实现细节。

必须检查三：“如果一个入职三个月的新人看到这段注释，他能理解这段代码为什么这么写吗？”

• 这是最终的可用性测试。如果新人只能理解“代码做了什么”，但理解不了“为什么这么做”、“当时有什么限制条件”、“改这里可能影响什么”，那这个注释是失败的。

在实际操作中，我们把这三点做成了一个简单的 Code Review 检查项。任何包含 AI 生成注释的 PR，Reviewer 必须对 A/B 级区域的注释逐一过这三条。

第三步：建立“注释所有权”的团队规范

这一点是组织层面的，不是技术层面的，但它比前两步都重要。

规范一：任何进入代码库的注释，必须有一个人类作者对它负责。 如果注释是 AI 生成的，那么审查并确认这段注释的开发者，就是它的“作者”。未来如果发现注释有误，追溯的是这个审查者，不是 AI。

规范二：不允许“先让 AI 生成，以后有空再改”。 这是一个极其常见的陷阱。在我们的团队规范里，未经过人工确认的 AI 注释，不允许被合入主干分支。我们宁愿一个模块暂时没有注释，也不愿它有一堆“看起来很好但可能有问题”的 AI 注释。因为后者的危害更大，它制造了虚假的安全感，而且一旦入库，修复它的优先级永远排不上。

规范三：Code Review 中，对注释的审查时间不应少于对代码的审查时间。 这个规范一开始推行时会遇到阻力，因为开发者习惯性地只审查“代码逻辑是否正确”。但你要让团队明白：代码是给机器执行的，注释是给人的认知框架。一个错误的认知框架，比一个逻辑 bug 更难被发现，也更容易引发连锁性的决策失误。

第四步：定期做“注释健康度检测”

不要等到出了问题才去审视注释。我建议每个季度做一次注释健康度检测，包含以下几个动作：

1. 随机抽取 20 个 A 级区域的注释，检查它们是否仍然准确。 代码在迭代，但注释往往不跟着更新。这个抽取能给你一个“注释腐化率”的快照指标。如果腐化率超过 20%，说明团队的注释文化有问题。
2. 找一个没有接触过这个模块的开发者，让他只靠注释来理解代码（不看实现），然后问他几个关键的设计意图问题。 这能直接测试注释的信息承载能力。如果答对率低于 60%，说明注释的信息密度严重不足。
3. 检查 AI 生成注释的比例趋势。 不是说你有了这个数据就要设上限，而是要观察：AI 注释比例是否在持续上升？如果上升的同时，团队对代码的理解深度（可以从 bug 率、事故复盘中的“我不知道这里会这样”出现频率来间接衡量）在下降，那就是一个需要干预的信号。

六、更远的争议：自动注释正在改变“什么是好代码”的标准

我在写这篇文章的过程中，发现这个争议其实比“怎么用 Claude Code 生成注释”更深。它指向了一个更根本的问题：当 AI 可以自动生成注释的时候，“代码的可读性”这件事的评判标准是否需要改变？

过去二十年，软件工程里有一条铁律：好的代码是自解释的，注释是代码表达力不够时的补充。 像 Clean Code 那本书里，Robert Martin 花了大量篇幅论证“注释是失败的信号”，如果你需要写注释来解释代码在做什么，说明你的代码写得不够清晰。

这个观点在 AI 出现之前，基本上是行业共识（虽然也有争议，但基调如此）。但现在，当 AI 可以在一秒内给你生成一整套注释，这个共识开始动摇了。

动摇的原因不是“AI 注释写得好”，而是“写注释的成本降到了几乎为零”。当一件事的成本降到零，人们的行为就会发生变化，即使这件事的价值存疑。

我观察到的一个现象是：越来越多的代码库开始“注释泛滥”。 开发者不再努力让代码本身可读（因为那要花时间重构），而是直接用 AI 给难以阅读的代码贴上一层“注释膏药”。代码依然难读，但看起来“被注释覆盖了”。

这让我想起医学里的一个概念：症状治疗 vs 病因治疗。 代码难读是“病因”，缺乏注释是“症状”。AI 自动注释让你可以轻松治疗症状，但这可能让你延迟或放弃治疗病因，即重构代码让它本身更清晰。

这件事的长期后果是什么？我担心会出现一种我称之为 “注释依赖型代码” 的模式：代码本身写得晦涩难懂（变量名随意、函数职责混乱、控制流复杂），但因为有一层 AI 生成的注释，开发者被迫“先读注释再读代码”来理解逻辑。而这层注释本身又可能不准确，于是一个二手的、可能错误的理解，成为了团队对这段代码的集体认知。

这远比“没有注释”更可怕。因为“没有注释”至少会迫使你去读代码，而“有注释但可能错误”会让你带着偏见去读代码，你看到的不是代码实际在做什么，而是注释告诉你代码应该做什么。

七、我的真实实践：如何在三个项目中调整策略

我不想让这篇文章停留在理论和判断上。这一节我会讲三个真实的项目经历，分别对应我在开头提到的支付系统重构、SaaS 组件库、和数据中台。每个项目我在“自动注释”这件事上踩了不同的坑，也做了不同的策略调整。

项目一：支付系统重构，高复杂度的教训

这个项目是我第一次大规模使用 Claude Code 做注释生成。当时的背景是：一个跑了三年的支付系统，代码质量参差不齐，原团队有 60% 的人离职了，留下来的代码大部分缺乏注释。新团队接手后，迫切需要一个“代码理解”的加速方案。

我的初始方案是：用 Claude Code 对整个代码库做一次全量注释生成，然后新团队基于这些注释来学习系统。我当时的逻辑是：“即使注释不完美，也比什么都没有强。”

结果：这个方案只执行了两周就被叫停了。

叫停的原因是我发现了一个致命的问题。那段退款状态机的代码，AI 生成的注释里明确写着“退款申请提交后，等待审核”。但实际逻辑是：小额退款（< 100 元）自动审核通过，大额退款需要人工审核。这个“隐性规则”在代码里是通过一个配置中心动态读取的，没有写在状态机的硬编码逻辑里。Claude Code 看不到配置中心的动态规则，它只能基于状态机本身的代码来生成注释。

结果是什么？一个新加入的开发者，基于这段注释的理解，在做另一个模块时复用了这个“等待审核”的假设，写出了一个逻辑漏洞：他以为所有退款都需要等待审核，于是给一个不需要审核的自动退款流程加了一个不必要的等待环节，导致用户体验下降。

这件事之后，我做了三个调整：

1. 对核心业务模块，禁用“全量自动注释”。 改用“按需生成草稿+人工重写”的模式。开发者自己先读代码，遇到不理解的段落，让 Claude Code 解释（不是生成注释，而是用对话方式提问），然后基于自己的理解写注释。
2. 建立“已知隐性规则文档”并让 AI 参与维护。 我们把那些“代码里没有但实际存在的规则”整理成文档，然后在提示 Claude Code 时明确告诉它：“这些规则在代码中不可见，请勿对它们做任何假设。” 这个做法显著降低了 AI 的“脑补式错误”。
3. 把 Claude Code 的角色从“注释生成器”调整为“注释审查器”。 开发者写完注释后，让 Claude Code 读代码+注释，然后问它：“这段注释有什么可能误导人的地方？” AI 在挑错这件事上，比在创作这件事上，可靠得多。

项目二：SaaS 组件库，中等复杂度的折中方案

这个项目的代码大部分是 UI 组件，逻辑复杂度中等偏下，但组合复杂度很高，一个表格组件可能组合十几个子组件。

在这个项目里，我采用了一个更精细的策略：

• 对外文档注释：AI 生成框架，人工填充。 组件的 Props、Events、Slots 这些接口注释，用 AI 生成格式和类型描述，然后人工补充“什么时候用这个 prop”、“什么情况下这个事件不会触发”等上下文信息。
• 内部实现注释：只在关键节点使用 AI。 我不让 AI 给每一行代码生成注释，而是让它帮我识别“哪些地方需要注释”，即代码中最可能让维护者困惑的部分，然后我只给这些部分生成注释草稿。
• 复杂交互逻辑：人工写注释，AI 做可读性检查。 比如拖拽排序的核心算法，我自己写注释解释为什么要在 mousedown 和 mousemove 之间设置一个 requestAnimationFrame 的缓冲。写完后让 AI 读一遍，问它：“你能理解我为什么这么做吗？” 如果 AI 的回答偏离了我的本意，说明我的注释表达还不够清晰。

这个项目跑下来，我的感受很复杂。一方面，AI 确实帮团队节省了大量“给简单组件写格式化注释”的时间；另一方面，我发现在“让我更理解这段代码”这件事上，AI 提供的帮助远比“让它帮我写注释”大得多。

项目三：数据中台，从零开始的最佳实践落地

这个项目是我目前最满意的实践。因为是从零开始，我可以在写第一行代码之前就定好“注释策略”，而不是在一个已经有技术债的代码库上打补丁。

这个项目的注释策略核心是 “禁止 AI 独立生成任何注释”。你没看错，是“禁止”。但这个“禁止”不是说不用 AI，而是说 AI 永远不能作为注释的最终决策者。

具体流程是这样的：

1. 开发者在完成一个模块的代码后，先把代码提交到分支。
2. 在提 PR 之前，开发者自己写注释。 这个阶段不允许使用 AI，必须是自己理解了代码之后写出来的。
3. 注释写完后，用 Claude Code 做“注释审查”。 具体做法是：给出代码+注释，问 AI 三个问题：

• “这段注释中，哪些信息是代码本身已经能看出来的？”（识别冗余）
• “这段注释中，哪些地方可能让一个不熟悉业务的人产生误解？”（识别歧义）
• “这段代码里，有没有什么重要的信息或边界条件，在注释里完全没有提到？”（识别遗漏）

1. 根据 AI 的反馈调整注释。
2. 在 PR 的 Code Review 环节，Reviewer 会对照 AI 的反馈，检查开发者是否合理处理了这些提示。

这个流程听起来很繁琐，但实际上，因为 AI 在第三步给出的反馈通常非常精准，开发者在第四步的修改量并不大。关键是，这个流程强制保证了“开发者必须自己完成认知闭环”，他们不能跳过“理解并表达”的环节。

项目跑了两个多月，我观察到的几个现象：

• AI 在“识别遗漏”这件事上的表现远超预期。 它会捕捉到很多开发者在写注释时下意识忽略的边界条件，比如：“这个查询在数据量为零时会返回什么？”、“如果上游服务超时，这个降级逻辑的触发条件是什么？” 这些问题驱动开发者去重新审视自己的代码，有时候真的会发现一些疏漏。
• 开发者对 AI 反馈的接受度，从最初的不耐烦变成了主动期待。 这种转变大概发生在执行这个流程的第三周。一开始大家觉得“又多了一个检查项，好烦”，但当他们连续几次从 AI 的反馈中发现真正有价值的信息后，态度就变了。
• 代码库的“注释可读性”显著高于前两个项目。 因为每一段注释都是由人写的，有人的语气和思考痕迹，而不是那种千篇一律的 AI 腔。新成员加入时说：“读你们的注释，像是在和写这段代码的人对话。” 这恰恰是我想要的效果。

八、最后的总结：在 AI 时代重新定义“好的注释”

这篇文章写到这里，已经超过了我最初规划的长度。但我觉得有必要，因为这个话题触及的东西太深了。

让我用三句话来总结我的核心观点：

第一句：Claude Code 自动生成注释这件事，真正的价值不在于“省时间”，而在于“让你更清楚地知道自己不知道什么”。 当 AI 生成的注释暴露出它没有理解到的边界条件、设计意图、和隐式约束时，这恰恰是它对你最大的帮助，它强制你去审视：我自己是不是也没意识到这些？

第二句：在 AI 时代，“好的注释”的标准应该从“描述代码”转向“承载决策”。 既然 AI 可以轻易完成结构描述和行为说明，人类写的注释就必须做 AI 做不到的事：解释为什么、交代上下文、标明边界条件、记录已知的坑。

第三句：别把注释当成代码的附属品，把它当成团队知识的存储器。 注释不是写给机器看的，是写给未来的你、你的同事、接手你代码的陌生人看的。它的质量，直接决定了你的团队在知识传承这件事上是“滚雪球”还是“狗熊掰棒子”。

我想用我们团队现在贴在 Code Review 看板上的一段话来结束这篇文章：

“如果三年后，一个完全不知道这段代码背景的工程师，在凌晨三点处理线上事故时翻到了你的注释，他能通过这段注释做出正确的判断吗？如果你不确定，那这段注释还不够好。”

这个标准在 AI 出现之前就已经存在，在 AI 出现之后变得更加重要。因为 AI 可以让“看起来够好”的注释充斥整个代码库，但只有人，才能真正写出“在关键时刻救命”的注释。

下一步，我建议你这样做：

1. 今天就做一次“注释审计”。 随机翻开你代码库里的 10 个文件，看看那些由 AI 生成的注释。用我前面的“三必须审查清单”过一遍。你可能会惊讶地发现，你一直以为“有注释就行”的那些地方，其实什么都没说出来。
2. 在你的团队里发起一次讨论：我们为什么要写注释？ 不是让大家吐槽“注释没用”或者“注释很重要”，而是真正去对齐：什么情况下需要注释、什么样的注释是有价值的、AI 在这个流程里应该扮演什么角色。这个讨论本身，比任何“最佳实践文档”都更有用。
3. 从小范围开始尝试“分级注释策略”。 不要一下子推到整个团队。选一个模块，按照我在第五节提出的 A/B/C 三级分类，试运行两周。看看“对高价值区域投入更多人工注释精力”这件事，是不是真的能带来代码理解质量的提升。如果能，再扩大范围。
4. 最重要的是：不要因为 AI 能做，就放弃自己理解代码的责任。 Claude Code 是一个极其强大的工具，但它不能替你思考。每一次你让 AI 帮你“写注释”的时候，问自己一句：“我是在用它来补充我的理解，还是在用它来替代我的理解？” 如果是后者，停下来，先去读懂那段代码。