yonathan-boop/Claude

antislop-code

反废料：AI 编码代理规则。代码注释技能

属于 antislop 系统的一部分。请与 antislop.md（核心规则）一起阅读。此技能专门过滤那些看起来像 AI 生成的通用注释（装饰性的、复述显而易见内容的、生硬的、喧闹的），同时保留携带真实信息的注释。它通过编号引用核心规则，且从不重复或重新编号。当任务涉及编写或编辑代码注释时，请加载此技能。

如何使用此技能

• 当任务涉及代码注释时，请与 antislop.md 一起加载。核心规则包含机制（目的测试、三层模型、交付门控）；此技能包含注释相关的具体细节。
• 每个条目都具有相同的结构：识别（模式描述）、原因（为什么这被认为是废料）、修复（应该怎么做），并引用核心规则编号（如 R-XX）。
• **范围护栏：**此技能仅修改注释。绝对不修改可执行代码、标识符、导入语句、格式、缩进、空白字符、控制流或逻辑。如有疑问，请保持代码原样。
• 核心规则中的“交付门控”仍然是总门控。本文件末尾的“代码注释检查清单”是其针对注释的补充，需要一起执行。

无价值的注释

装饰性分隔符

• **识别：**由重复字符、全大写标签或围绕部分名称的方框绘制组成的横幅注释：围绕 Authentication 的 // =======================、// -------- WORKFLOW --------、或 /* ---- ROUTES ---- */ 标题。
• **原因：**装饰本身就成了信息。用 = 或 - 包裹的标签暗示“这是 AI 写的”，没有增加任何信息，并且全大写看起来像是在喊叫。
• **修复：**替换为单行纯文本，或者如果标签本身没有增加任何信息，则直接删除（R-31）。

复述显而易见的内容

• **识别：**重复下一行代码或声明所展示内容的注释，例如在 let count = 0 上方的 // 初始化变量、class User {} 上方的 // User 类、function validateUser() 上方的 // 验证用户、或者 const userAge = 25; // 用户年龄是 25。
• **原因：**它增加了阅读负担但没有任何价值。代码已经表达了这些信息；注释只是重复了一遍。
• **修复：**删除注释，保持代码行不变。

流程叙述

• **识别：**逐步叙述流程的注释，例如 // 步骤 1：验证输入、// 步骤 2：处理请求、// 步骤 3：返回响应，或者 // 首先...、// 接着...、// 最后...。
• **原因：**控制流在代码本身中可见。对它们进行编号看起来像一个检查清单，而不是解释。
• **修复：**删除。如果流程确实难以理解，那是结构问题，而不是缺少注释的问题。

空标签

• **识别：**没有实质信息的通用标签：// 主要逻辑、// 核心逻辑、// 业务逻辑、// 辅助函数、// 入口点、// 错误处理，或者 // 注意：这很重要。 / // 重要：请阅读。
• **原因：**标签命名了一个类别，而非一个事实。“主要逻辑”告诉读者的信息并不能从代码中推断出来。
• **修复：**删除，除非该标签包含具体信息。“注意：仅在 5xx 错误时重试”有保留价值；“注意：这很重要”没有。

模糊的占位符

• **识别：**承诺未来工作但没有说明具体内容的注释：// TODO：改进此处、// 未来改进、// 可以在此处添加更多优化、// 添加更多验证。
• **原因：**模糊的 TODO 是噪音。它命名了一种感觉（这可以更好），而不是一个任务（做什么，以及为什么）。
• **修复：**删除。仅当 TODO 命名了一个具体的任务，并提供了足够的上下文来执行时，才保留它。

签名回声

• **识别：**仅复述函数签名的文档，例如一个 JSDoc 块，其中重复了 @param price 价格。 和 @returns 总价。，而函数的名称和参数已经表达了所有这些信息。
• **原因：**重复签名的文档增加了篇幅，但没有增进理解。读者没有学到任何新东西。
• **修复：**简化或删除回声。保留解释业务规则、边界情况、假设、算法、限制、副作用、API 行为或安全影响的文档。绝不删除真正的文档。

装饰性 Emoji

• **识别：**在注释中用作装饰的 emoji，例如 // ✅ 验证 或 // 🚀 性能。
• **原因：**在代码中，emoji 是视觉噪音，并且特定集合（✅、🚀、🔒）是 AI 的默认词汇。
• **修复：**替换为纯英文文本，或者如果标签本身没有增加价值则删除。

结束标记

• **识别：**仅用于标记代码块结束的注释，例如 } // 结束 if、# 函数结束 或 // 结束 processOrder。
• **原因：**右花括号已经结束了代码块。标记的存在是出于习惯，而非需要。
• **修复：**删除。在极少数情况下，如果结束标记确实有助于长文件的阅读，请仅在可能引起混淆的地方保留它，而不是作为一种习惯。

应该如何写注释

过度解释的注释

• **识别：**一条注释写了多行，围绕一个一行就能说清楚的事实堆砌了原因、上下文和历史：一个四行的代码块解释了某个存根位于 PATH 上、哪个版本引入了该变通方案、以及之前什么东西出了问题。每个句子都是真实的。长度本身就暴露了问题。
• **原因：**人类会留下笔记，而生成器则会撰写案例。将一行事实填充成一段文字，构建一个“因为 X，所以 Y，因此 Z”的推理链，或者引用 issue 编号和修复它的版本，都是和其他 AI 模式一样的赘述，它们会把起关键作用的一行信息淹没在无用的信息之下。
• **修复：**只保留约束条件：一行，最多两行，永远不要三行。保留平台陷阱、静默失败、协议规则、性能代价。删去 issue 编号、版本历史和推理链。

逐行叙述

• **识别：**每一条琐碎语句上都有注释，逐行叙述代码的执行过程：// 初始化 count，然后 // 循环 items，然后 // 获取 item，然后 // 递增，然后 // 返回结果。
• **原因：**当每一行都有注释时，就没有任何注释是重要的。读者必须检查每一条才能找到真正有意义的那一条。
• **修复：**每个逻辑块写一条简洁的注释，而不是每行写一条。如果某个块不需要注释，就一条也别写。

生硬或喧闹的措辞

• **识别：**听起来很正式、冗长或是在喊叫的注释：“此函数负责在继续认证过程之前验证所提供的凭据是否有效”，或者全大写的 // MAIN LOGIC。
• **原因：**正式和喧闹的措辞读起来像是生成的文本，而不像工程师给下一个人留下的笔记。
• **修复：**用自然的开发者语言写简短的、句子大小写的行：// 在签发令牌前验证凭据。 好的注释解释“为什么”，而不是“是什么”，并且保持简短。

不是禁止（请保留这些）

永远不要删除解释以下内容的注释：

• 业务逻辑和意图
• 架构决策
• 安全考量
• 性能权衡
• 并发行为
• 协议细节
• API 契约
• 变通方案
• 边界情况和假设
• 许可和法律声明

必须保留的示例：

// Stripe 可能会在最多三天内重试 webhook 交付。
// 使用事件 ID 忽略重复事件。

当一条注释解释了代码本身未展示的内容：理由、约束、非显而易见的行为时，它就有保留的价值。

有价值决定什么可以保留，但绝不规定它能写多长。一个变通方案笔记是关于该变通方案的一行字，而不是一段话。上面的例子是两行，因为有两个事实是真实的，而不是因为两行是目标。这个列表是一条评论能够侥幸通过本不该通过审查的最常见原因：内容有实际价值，所以其长度就被忽略了。价值不等于长度。

代码注释检查清单

当任务涉及注释时，请将此清单与核心规则的“交付门控”一起执行。所有答案必须为是：

• 每条注释是否都增加了代码本身未展示的信息？（R-31）
• 注释是否避免了装饰性分隔符、全大写横幅和方框绘制的标题？
• 注释是否避免了复述显而易见的代码行、声明或签名？
• 注释是否避免了逐步的流程叙述？
• 注释是否避免了没有具体任务的空标签和模糊 TODO？
• 注释是否避免了装饰性 emoji 和结束标记？
• 注释密度是否保持在每个逻辑块一条，而不是每条代码行一条？
• 每条注释是否只有一行，或者仅当第二行包含新的事实时才为两行？
• 保留下来的注释是否简短、自然，并使用句子大小写？
• 是否严格遵守了范围护栏：仅修改了注释，代码保持原样？