AI代码助手系列·第3讲:注释与日志规范,别让 AI 在日志里埋雷

痛点：注释啰嗦、日志混乱，还可能泄密

AI 代码助手有个坏习惯：喜欢给每行都加注释。「给 discount 赋值」「返回结果」这种注释，对阅读毫无帮助，纯粹是噪声。更麻烦的是日志——不同人、不同模型写出来的日志格式五花八门，级别乱用，线上出问题翻半天日志拼不出一条完整链路。

最危险的不是乱，而是日志不规范就是雷。AI 为了「方便调试」，很顺手就把密码、Token、身份证号、手机号原样打印出来。这些日志一旦进了检索系统或被导出，就是实打实的数据泄露。注释和日志看似小事，实则是 AI 代码里最容易埋雷的地方。

方法：Rules 把注释边界和日志模板写清楚

第一件事是给 AI 划清注释的边界。在 Rules 里明确：复杂逻辑、业务规则、算法思路必须注释，因为这些是后人最需要知道的；简单赋值、自解释的代码不要注释——变量名本身说清楚了，再写一遍纯属冗余。配上正反例效果最好：

### Do ✅ 计算折扣时需考虑 VIP 等级差异 ### Don't ❌ 给 discount 赋值

第二件事是格式统一才查得动。在 Rules 里写死日志模板：[时间戳][日志级别][模块名][TraceID] 消息内容。每条日志都带链路 ID，一次请求的完整调用链就能串起来，出问题顺着 TraceID 一把捞全。

实践：日志四级用法与敏感信息禁打清单

日志级别最容易被混用，直接写进 Rules：

• DEBUG
  调试细节，生产环境必须关闭，只在本地排查用
• INFO
  业务流转关键节点，如「订单创建成功」
• WARN
  可恢复的异常，不影响主流程但要留意
• ERROR
  需要人工介入的严重异常，必须告警

同时划出敏感字段一个都不能打的禁打清单：password、token、secret、idCard、phone 这类字段，任何日志里都不许出现原文。光靠自觉没用，在 CI 里增加日志安全扫描，自动检测 log 语句里有没有敏感字段，命中就阻断合入。

落地还有个小技巧：每个模块入口打一行脱敏后的参数摘要，出口打一行处理结果摘要，一来一回形成完整链路。这里的关键是两道防线缺一不可——Rules 禁打清单让 AI 从源头上不打，CI 扫描给偷懒和漏网兜底。

收束

注释和日志规范，本质是给 AI 立「不乱说话」的规矩：注释写在刀刃上，日志打得有章法。Rules 前置约束，CI 后置扫描，中间再靠入口出口的摘要串起链路。下一讲进入工程章——Spec 模式入门，聊聊怎么让 AI 按「合同」干活，而不是凭感觉乱发挥。