AI 简明手册注释三要素与代码保护
目标
注释必须包含背景、设计意图和关键约束三要素，让 AI 按固定结构写明白代码无法表达的决策信息；同时要保护注释不被随意删除，禁止静默删除任何已有功能代码。
操作步骤
AI 默认写的注释多是功能复述
AI 默认写的注释多是功能复述，读代码就能获得同样信息。三要素注释要求写清：这个函数解决什么业务问题、在什么场景下被调用；为什么这样实现、放弃了哪些备选方案；调用方必须知道的副作用、依赖关系和边界条件。设计意图往往无法从 git log 中找到，注释是唯一载体。
保护注释与已有功能
两条保护规则要求：重构时不能以'注释太长'、'代码自解释'或'顺手清理'为由删除背景和设计意图注释，若实现改变导致注释不准，应同步更新内容，使其继续说明现在为什么这样做；删除任何已有功能代码前必须告知用户并说明理由，先标注'// TODO: 建议移除 - 原因:xxx'，获得许可后再删。
配套的错误处理规则禁止空 catch
配套的错误处理规则禁止空 catch：所有 try/catch 和错误分支必须有日志记录加用户可见提示，或合理的降级逻辑，仅 console.log、pass 或 ignore 都属于静默吞错。
完成检查
为什么 git log 替代不了设计意图注释： git log 记录的是改动历史，不解释为什么要选某个方案、放弃了哪些备选。后来的人看到代码只能知道做了什么，无法理解决策背景，这些信息只有注释能留存。
注释和代码不一致时应该怎么处理： 应该同步更新注释内容，让它继续说明现在为什么这样做。注释不是为了保留旧决定，而是为了帮助未来接手的人理解当前实现的原因，不准确的注释本身也会误导。