调试与交付检查：先定位再改码

操作步骤

1. AI 遇到报错常会猜一个原因改改看

   AI 遇到报错常会猜一个原因改改看，失败再猜一个，这会掩盖真正根因并制造新问题。规则要求无论前后端，第一步都是加日志：后端在终端打详细日志，前端在浏览器 Console 打日志。加 Log 的少量成本能买断多轮猜测的返工。

2. 修复前必须回答三问

   修复前必须回答三问：这个 Bug 所在功能的完整业务流程是什么；修改这里会影响哪些其他模块；是否有其他地方存在同类问题。三问帮助定位链路断点、理解上下游依赖、把同一坑一次性修干净。修复后还要用'⚡ 影响范围：XXX、YYY、ZZZ'的格式声明影响面，让人知道该回归测试哪些地方。

3. 交付前有两道硬性检查

   交付前检查真实依赖与测试：模型接口等外部能力必须用获准的 secrets 配置并实际验证；缺少凭据时应说明阻塞，不能硬编码假响应绕过。核心逻辑、接口、数据处理和边界条件要有自动化测试。以 Python/pytest 项目为例，测试可放在 tests/ 并遵循项目命名约定；其他技术栈以仓库规范为准。

完成检查

• 为什么禁止 Mock 绕过真实 AI 接口： 因为假响应会让开发看起来完成，实际上真实调用路径从未被验证，交付后用户一用就出问题。用户没给 Key 时必须停下来索取，Key 到位后要先发一次测试请求确认可用。

• 影响范围声明和修复内容有什么区别： 修复内容说明改了什么，影响范围声明告诉团队哪些已有功能可能受这次修改波及，用于决定对哪些模块做回归测试，防止按下一处问题又冒出另一处。