Vibe Coding 方法论 · 第 4 节

注释三要素与代码保护

AI 写的注释多是功能复述，三个月后回来看代码，想不起当初为什么这样实现。这一节给注释立结构，也给「删代码」立规矩。页面里有两个可动手的演示。

问题在哪

代码只能表达「做了什么」。为什么存在、为什么这样实现、调用时要注意什么，这些信息只有写进注释才能跨时间留存。「写好注释」四个字 AI 执行不了，必须给出固定结构和示例。

三要素结构

背景

这个函数为了解决什么业务问题、在什么场景下被调用。没有背景，读代码的人只能看到实现，看不到它为什么存在。

设计意图

为什么这样实现，选择这种方案的理由，以及放弃了哪些备选方案。git log 里找不到这些，注释是唯一载体。

关键约束

调用方须知：副作用、依赖关系、边界条件等非显而易见的注意点。少了这条，下一个调用者就会踩坑。

交互演示一 · 同一个函数，两种注释

点击切换同一个 merge_chat_history 函数的两种注释写法，对比它们留下的信息量。

chat/history.py
          背景设计意图关键约束
        
def merge_chat_history(existing: list, incoming: list) -> list:
    """
    合并两个聊天记录列表，返回合并后的结果。
    """
    ...
def merge_chat_history(existing: list, incoming: list) -> list:
    """
    背景：前端每次会话恢复时会带上本地缓存的历史消息，
    但服务端也保留了一份持久化记录，两者可能因网络中断出现分叉。
    设计意图：以服务端记录为权威，仅追加本地独有的消息，
    不做全量替换，避免覆盖掉服务端已有的 AI 回复元数据。
    约束：incoming 中 role=system 的消息一律丢弃，不合并入结果。
    """
    ...

这条注释复述了函数名，读一眼代码就能得到同样的信息。三个月后想知道「为什么以服务端为权威」「为什么丢弃 system 消息」，什么线索都没有。

交互演示二 · 删不删，你来判

三个真实情景，判断 AI 应该怎么做。点选项即时判定，并给出对应的规则依据。

情景 1 · AI 在重构时发现一段兼容旧数据格式的代码，它觉得「看起来没用」，想顺手删掉。

情景 2 · 重构后实现方式变了，原有的「设计意图」注释已经和代码对不上了。

情景 3 · AI 觉得 fetch 比 axios 更轻量，想把项目里的 axios 换成 fetch，顺手改掉 package.json。

已答对 0 / 3 题

两条保护规则

注释保护

重构时禁止以「注释太长」「代码自解释」「顺便清理」为由删除背景和设计意图注释。实现变了导致注释不准确时，必须同步更新内容。判断标准只有一条：未来接手的人，没有这条注释还能理解当初为什么这样做吗？

代码删除声明

删除任何已有功能代码前，必须明确告知用户并说明理由，禁止以「顺手清理」「看起来没用」为由静默删除。认为某段代码该移除时，先标注 // TODO: 建议移除 - 原因：xxx，拿到许可再删。

配套规范 · 错误处理

禁止空 catch。所有 try/catch 和错误分支必须有实质性处理：日志记录 + 用户可见的错误提示，或合理的降级逻辑。仅 console.log(e)、pass、// ignore 都属于静默吞错，一律不允许。

本节要点

注释的使命是留存代码无法表达的决策信息。三要素结构让 AI 写得出来，保护规则让它删不掉，两者配合才能跨越时间。

素材来源：本节内容整理自开源仓库 itshen/xs_vibe_rules 的 rule-opensource.mdc 第七章「代码组织与规范」。