开场：AI 遇到报错的第一反应是猜

AI 遇到报错的第一反应是猜一个原因改改看，不行再猜一个。这一节立最核心的一条规矩：禁止猜测性修复。

一句话速览：禁止猜测性修复，修复前回答三个问题，改完声明影响范围。

一、核心条款

禁止猜测性修复。 无法确认根因时，必须先通过 Log、断点或测试脚本验证假设，禁止「试着改一下看看」。后端在终端打详细日志，前端在浏览器 Console 打日志，无论什么问题，第一步都是加 Log。

二、同一个 Bug，两条修法

Bug 现场：聊天输入框在中文输入法下，用户按回车确认候选词时，半截拼音被当成消息直接发了出去。

猜测性修复（❌）

• 第 1 轮：可能是发送按钮重复绑定事件，去掉一个监听试试 → 问题依旧
• 第 2 轮：可能是没做防抖，加 300ms 防抖 → 没修好，还多了发送延迟的新问题
• 第 3 轮：把 keydown 换成 keyup，顺便重写事件处理 → 仍然误发送

战绩：3 轮 · 改动 47 行 · Bug 仍在。 三轮下来事件处理逻辑被改得认不出来，原始现场也没了。

先 Log 再改（✅）

加日志、看证据、定位根因（最终指向 isComposing 未判断，详见环境事实那节）。加 Log 的 2 分钟，买断的是猜错三轮的返工和被掩盖的根因。

三、修复前三问自查

修 Bug 前必须回答三个问题：

1. 这个 Bug 所在的功能，完整业务流程是什么？
2. 修改这里会影响哪些其他模块？
3. 是否有其他地方存在同类问题？

三问全部答完，才开始修复。

四、交付线 · 两道硬性检查

禁止 Mock 绕过真实 AI 接口： 凡涉及 AI 模型调用的功能，交付前必须确认接口真的能访问。用户没给 API Key 时必须停下来要，禁止硬编码假响应或本地模拟绕过真实调用。Key 到位后先发一次测试请求验证可用性，再继续开发。

单元测试不过，不得交付： 核心业务逻辑、API 接口、数据处理函数、边界条件都要覆盖。测试文件统一放 tests/，命名 test_{模块名}.py，Python 项目用 pytest。调试用的临时脚本，用完自行删除。

本节要点

证据先行。 修复后用 ⚡ 影响范围：XXX、YYY、ZZZ 的格式声明影响面，交付前过真实接口和单元测试两道线。