用途
Smart Comments 是一个 AI 编码智能体技能，用于规范智能体如何撰写新的行内注释，以及如何处理代码中已有的注释。该技能的出发点是一个观察：智能体往往是代码的第一个读者，但不像人类同事那样经历过导致某段代码长成现在样子的历史事故，也无法仅凭代码形态嗅出隐藏的陷阱。因此，注释被定位为离代码最近的规格层，需要在生成和维护时被严肃对待。
主要能力
该技能按决策规则组织，主要覆盖两类判断。
何时撰写注释
当满足以下任一条件时，才写行内注释；否则不写：
- 代码陷阱：代码看起来错误、冗余或可删除，但实际上不是。需要说明原因，例如过去的 bug、顺序约束或外部系统的怪癖，使下一个读者（人或智能体）知道改动它的代价。
- 非显而易见的 WHY：当所选方案是在看起来更简洁的替代方案之间被选中时，说明取舍。例如“可以做 X，但在负载下会发生 Y”，这类信息是承重的，缺少它下一个读者会尝试 X。
- 隐藏的不变量与契约：类型、名称或局部函数体无法体现的隐式假设，包括调用之间的顺序、幂等性保证、调用方必须先设置的状态、必须一起填充的字段。
- 临时规避方案：外部系统的 bug、竞态条件、临时的版本锁定、polyfill、等待上游修复的 hack。若存在对应 issue，应链接或指明。
何时不写注释
以下情况不应写注释：
- 只是叙述代码在做什么，且标识符已经说明了。例如在 counter++ 上方写“increment counter”属于噪音。
- 引用当前任务、工单、PR、作者或评审轮次。这些内容属于提交信息或 PR 描述，写在代码里会腐化。
- 横幅、章节分隔线，或对函数签名的重述。
- 描述那些代码自身在重构中能可靠携带的意图——如果一次重命名就让注释变错，那这条注释本就是冗余的。
- 如果 WHY 从函数名和参数就明显可见，注释不值得占用空间。
使用方式
撰写规范
- 行内：直接写在所保护代码的上方或旁边，而不是文件顶部、外部文档或提交信息里。
- 简短：先给约束或警告，不要铺垫。
- 必要时用祈使句：优先写“不要重排——必须在 X 之前运行”，而不是“这在 X 之前运行”。
- 点明代价：写“移除这个提前返回会重新打开我们修过的 N+1”，优于写“重要的提前返回”。
- 如果一条注释需要超过约三行，通常说明代码本身有问题；应改代码，而不是改注释。
尊重已有注释
这是该技能存在的核心原因。
- 在证明相反之前，把每一条已有注释都当作承重的。无论是人还是过去的智能体，都曾为留下它付出代价，应假定这一代价是真实的。
- 除非注释所描述的代码同时被删除，否则不要在重构中删除注释。移动代码不构成丢弃其注释的理由。
- “看起来冗余”不足以作为删除的理由。注释可能是过去某次事故仅存的痕迹，而代码本身不再提示这一点。
- 如果注释看起来过时或错误，应在回复中向用户指出，而不是静默修复或删除。只有用户能确认注释是否仍反映现实。
- 永远不要仅为改变语气或措辞而重写注释。如果它读起来像警告，就保持它是警告。
校准示例
反面示例（叙述代码已说明的内容）：
Increment the retry counter
retries += 1
正面示例（点明陷阱）：
Do not switch to exponential backoff here; upstream rate-limits on burst, not on average.
retries += 1
反面示例（会在下次重构中腐化）：
// Added in PR #4821 by @alice to handle the new billing webhook if (event.type === "invoice.paid") { ... }
正面示例（保留 WHY）：
// Stripe fires invoice.paid before invoice.finalized for auto-advancing subs; handle both orderings. if (event.type === "invoice.paid") { ... }
反面示例（装饰性，无信号）：
// ---------- Helpers ----------
正面示例（编码隐藏契约）：
// Caller must hold s.mu. Returns the unwrapped value; safe only until the next Set(). func (s *state) peek() T { ... }
适用场景
该技能明确其触发时机为：编写、编辑、重构代码时，以及对已有注释做判断时。它适用于任何需要在代码中留下或维护判断依据的场景，尤其是包含历史事故、隐式顺序、外部系统怪癖或临时规避方案的代码库。
限制
- 该技能本身是一套写作与决策规范，不提供自动检测注释是否过时的能力；过时与否最终需要用户确认。
- 是否删除或修改注释的最终决定权在用户手中，技能要求智能体在不确定时保留并询问，而非自行处置。
- 该技能不涉及具体编程语言或编辑器的语法限制，其规则以行内注释的通用形式描述。
- 关于该技能是否收费、是否有价格方案、支持哪些模型或平台，资料中暂未提供。