编写或编辑代码注释时，清理 AI 味注释并保留有价值注释

当 AI 编码代理需要新增、修改或审查代码注释时，用它过滤通用 AI slop 注释，保留真正解释 why 的注释，同时不改动代码。

适用场景

解决思路

1. 当任务涉及代码注释时，与 `antislop.md` 一起加载；核心文件提供 purpose test、three tiers、Delivery Gate，本技能提供注释特定深度。
2. 对每条注释按 Tell（模式）、Why（为何像 slop）、Fix（如何改）审查，并引用核心规则编号 R-XX。
3. 遵守范围护栏：只修改注释；绝不修改可执行代码、标识符、导入、格式、缩进、空白、控制流或逻辑；有疑问时保持代码不动。
4. 使用核心的 Delivery Gate 作为门禁，并运行文末的 Code Comment Checklist 作为注释特定补充。
5. 装饰性分隔符：将 banner 注释（重复字符、ALL CAPS 标签、框线标题，如 `// =======================`、`// -------- WORKFLOW --------`、`/* ---- ROUTES ---- */`）替换为单行纯文本；如果标签无信息则完全移除 (R-31)。
6. 重述显而易见：删除重复下一行或声明已显示内容的注释，例如 `// Initialize the variable` 在 `let count = 0` 上方、`// User class` 在 `class User {}` 上方、`// Validate user` 在 `function validateUser()` 上方、`const userAge = 25; // User age is 25`；保持代码行不变。
7. 工作流叙述：删除 `// Step 1: Validate input`、`// Step 2: Process request`、`// Step 3: Return response` 或 `// First...`、`// Next...`、`// Finally...` 等逐步叙述；如果流程确实难懂，应修复结构，而不是补注释。
8. 空标签：删除 `// Main logic`、`// Core logic`、`// Business logic`、`// Helper function`、`// Entry point`、`// Error handling`、`// Note: This is important.`、`// Important: Please read.` 等泛化标签，除非携带具体事实；例如 `// Note: retries happen only on 5xx` 可保留。
9. 模糊占位符：删除 `// TODO: Improve this`、`// Future improvements`、`// Additional optimization can be added here`、`// Add more validation` 等不说明任务的 TODO；仅当 TODO 指明具体任务且有足够上下文可执行时才保留。
10. 签名回声：简化或删除只重复签名的文档，例如 JSDoc 中重复 `@param price The price.` 和 `@returns Total price.`；保留解释业务规则、边界情况、假设、算法、限制、副作用、API 行为或安全影响的文档；绝不剥离真实文档。
11. 装饰性 emoji：将注释中的装饰性 emoji（如 `// ✅ Validation`、`// 🚀 Performance`）替换为纯英文，或如果标签无信息则删除。
12. 结束标记：删除只标记块结束的注释，如 `} // end if`、`# End of function`、`// End processOrder`；极少数情况下，结束标记确实有助于长文件时，仅保留在能防止混淆的位置，不作为习惯。
13. 过度解释的注释：将堆叠原因、上下文、历史的冗长注释削减到只保留约束；一行，最多两行，绝不超过三行；保留平台陷阱、静默失败、协议规则、性能成本；删除 issue number、版本历史、推理链。
14. 逐行叙述：每个逻辑块写一条简洁注释，而不是每行一条；如果该块不需要注释，则不写。
15. 生硬或大声措辞：写短句、句子大小写、自然开发者语气的注释，例如 `// Validate credentials before issuing a token.`；好的注释解释 why 而不是 what，并保持简短。
16. 保留列表：绝不移除解释业务逻辑与意图、架构决策、安全考虑、性能权衡、并发行为、协议细节、API 契约、变通方案、边界情况与假设、许可与法律声明的注释。
17. 保留示例：必须保留如 `// Stripe may retry webhook deliveries for up to three days.` 和 `// Ignore duplicate events using the event ID.`；注释有价值当它解释代码未展示的内容：原因、约束、非显而易见的行为。
18. 价值不等于长度：有价值说明可保留，但绝不说明可以多长；workaround 注释是一行关于 workaround，不是一段；上面的示例是两行因为两个事实真实，不是因为两行是目标；不要因为内容有价值就忽略长度审查。
19. 检查每条注释是否添加代码未展示的信息 (R-31)，答案必须为 yes。
20. 检查注释是否避免装饰性分隔符、ALL CAPS 横幅和框线标题，答案必须为 yes。
21. 检查注释是否避免重述显而易见的行、声明或签名，答案必须为 yes。
22. 检查注释是否避免逐步工作流叙述，答案必须为 yes。
23. 检查注释是否避免空标签和未指明任务的模糊 TODO，答案必须为 yes。
24. 检查注释是否避免装饰性 emoji 和结束标记，答案必须为 yes。
25. 检查注释密度是否每个逻辑块一条，而不是每行一条，答案必须为 yes。
26. 检查每条注释是否一行，或仅当第二行携带新事实时才两行，答案必须为 yes。
27. 检查剩余注释是否读起来简短、自然、句子大小写，答案必须为 yes。
28. 检查是否守住范围护栏：只改注释，代码未动，答案必须为 yes。

适用边界 · 注意事项

• 当任务需要修改可执行代码、标识符、导入、格式、缩进、空白、控制流或逻辑时，不适用；有疑问时保持代码不动。
• 不要删除解释业务逻辑、架构决策、安全、性能、并发、协议、API 契约、变通方案、边界情况、许可/法律等真实文档的注释。
• 如果控制流难以阅读，不要用注释掩盖，应调整代码结构。