用途
Melech Smart Comments 是一个面向 AI 编码代理的技能，目标是让代理在读写代码注释时保留代码意图。它把注释视为“离代码最近的规格层”，也是人类向模型传递约束、警告和意图的最廉价、最高信号的方式。技能的核心关切是：代理往往不了解代码背后的历史事故，无法仅凭代码形状识别“地雷”，因此需要一套明确规则来指导注释的撰写与保留。
主要能力
技能从两个方向规范代理行为。
第一，规定何时应当写注释。技能列出四类应当写内联注释的情形：
- 地雷：代码看起来错误、冗余或可移除，但实际上不是。需要说明原因，例如过去的缺陷、顺序约束或外部系统的怪癖，让下一位读者知道触碰它的代价。
- 非显而易见的 WHY：当所选方案优于看起来更干净的替代方案时，说明权衡。例如“可以做 X，但在负载下会出现 Y”这类信息是承重的，缺少它下一位读者就会去尝试 X。
- 隐藏的不变量与契约：类型、命名或局部函数体无法体现的隐式假设，例如调用之间的顺序、幂等性保证、调用方必须预先设置的状态、必须一起填充的字段。
- 绕过方案：外部系统的缺陷、竞态条件、临时版本锁定、polyfill、等待上游修复的 hack。若存在相关 issue，应链接或指明。
第二，规定何时不应写注释。技能明确禁止以下情形：
- 叙述代码已经表达的内容，且标识符已说明清楚。例如在 counter++ 上方写“递增计数器”属于噪音。
- 引用当前任务、工单、PR、作者或评审轮次。这些内容属于提交信息或 PR 描述，留在代码中会腐化。
- 横幅、分节分隔线，或对函数签名的复述。
- 描述代码本身在重构中能可靠延续的意图——如果一次重命名就让注释变错，说明该注释本就冗余。
技能还给出撰写要求：注释应内联，直接位于所保护代码的上方或旁边，而非文件顶部、外部文档或提交信息中；应简短，以约束或警告开头，不要铺垫；在关键处使用祈使语气，例如“不要重排——必须在 X 之前运行”优于“这在 X 之前运行”；应点明代价，例如“移除此提前返回会重新打开我们修复过的 N+1”优于“重要的提前返回”；应闭合推理缺口，给出足够的因果链，让不熟悉的读者能回答“什么改动会违反它、什么会坏掉”，而“竞态”“安全问题”“数据泄露”这类标签本身不构成解释；篇幅尽量控制在三行左右，用最短的注释保留原因，若需要显著更长，应让代码本身表达更多约束。
使用方式
技能以规则文本的形式提供给 AI 编码代理，代理在生成或修改代码注释时遵循这些规则。技能本身不提供安装命令或运行接口，具体接入方式暂未提供。
适用场景
适用于使用 AI 代理进行代码维护、重构、审查和功能开发的场景，尤其是需要长期维护、注释承载历史决策的代码库。技能帮助减少注释腐化、避免代理静默删除有价值的注释，并让新注释真正传递约束而非复述代码。
限制
技能是一套行为准则，不提供自动化检测或强制机制，效果取决于代理是否遵循。它不涉及具体编程语言或框架，也不提供平台支持、收费或价格信息，这些内容暂未提供。