注释三要素与代码保护：让 AI 写出能跨时间的注释

开场：注释的使命是留存代码无法表达的决策信息

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

一句话速览：背景、设计意图、关键约束缺一不可；禁止静默删除代码与依赖。

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

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

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

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

# chat/history.py
def merge_chat_history(existing: list, incoming: list) -> list:
    """
    合并两个聊天记录列表，返回合并后的结果。
    """
    ...

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

三要素注释则要补上：背景（两处聊天记录合并时，以服务端数据为权威来源）、设计意图（丢弃 incoming 中与 existing 冲突的 system 消息，避免上下文污染）、关键约束（调用方必须传入已按时间排序的列表）。

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

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

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

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