AI 代码典型错误模式与技术债

一句话定义

AI 代码的七类高频错误模式——API 幻觉、旧版 API、风格漂移、重复造轮子、过度防御、死代码残留、测试凑答案——各有识别信号与处置动作，模式化识别比逐行怀疑高效得多。

为什么重要

审查 AI 代码最大的成本不是「读不懂」，而是「不知道该怀疑哪里」。错误模式库把零散的怀疑变成模式匹配：看到某类信号就启动对应的检查动作，10 分钟审查因此有了靶点。更重要的是长期视角：这些模式若不在生成端拦截（规则文件）与清单端过滤（kp-021），会以「每次一点点」的速度沉淀为技术债——重复实现、第二套风格、空转的防御层，最终拖慢整个团队。

前置知识

kp-021（五层审查清单——本节是它第三、四层的模式库支撑）。

核心概念

七类模式与识别信号：

1. API 幻觉：调用不存在的方法/参数。信号：IDE 红线、运行时 AttributeError。处置：核对官方文档，不存在则改用已有实现。
2. 旧版 API：语法正确但已被弃用的调用方式。信号：deprecation 警告、与仓库既有调用不一致。处置：以仓库内最新用法为准统一。
3. 风格漂移：引入仓库没有的第二套写法（另一种错误处理惯例、另一套命名风格）。信号：diff 里「不像本仓库」的代码段。处置：按仓库惯例重写，惯例不明则问维护者。
4. 重复造轮子：重新实现仓库已有的工具函数。信号：新增的 format/parse/retry 类函数。处置：grep 同义实现，复用或删除。
5. 过度防御：无意义的层层 try/except、对不可能为空的判空。信号：异常处理链深于业务层级。处置：削减到真实需要的防御，明确错误传播策略。
6. 死代码与残留：调试输出、注释掉的代码块、无引用的导出、遗留 TODO。信号：diff 中的 print/console.log、大段注释代码。处置：一律要求清除后合并。
7. 测试凑答案：断言与实现互相迁就、只测 happy path、断言弱。信号：对照 kp-012 弱断言清单。处置：回补边界用例。

原理与机制

这七类模式的共同根源是「概率生成没有仓库全局观」：模型逐 token 生成时，对「这个仓库已有什么、惯例是什么、版本是什么」只有局部与统计性的认识，于是按训练数据中的众数写法输出——众数可能与你的仓库不符（模式 2/3）、可能与你已有的实现重复（模式 4）、可能编造众数（模式 1）。防御因此分两层：生成端用规则文件注入仓库事实（版本、惯例、已有工具清单），审查端用模式信号快速定位。技术债的累积机制则是「单次无害」：每个模式单看都可接受，多轮迭代后相互叠加形成系统性的双倍维护面。

实例或案例

速查表（贴进评审模板）：

| 模式       | 秒级信号            | 动作           |
|-----------|--------------------|----------------|
| API幻觉    | IDE红线/AttributeError | 查文档改写      |
| 旧版API    | deprecation 警告    | 对齐仓库最新用法 |
| 风格漂移   | 「不像本仓库」的段落  | 按惯例重写      |
| 重复造轮子 | 新增工具函数         | grep 后复用     |
| 过度防御   | try/except 层层嵌套 | 削到真实需要     |
| 死代码     | print/注释块/TODO   | 清除后合并      |
| 测试凑答案 | 弱断言/只有happy path | 补边界用例     |

操作步骤（把模式库用于评审）：

1. 收到 diff 先扫模式信号（信号列），命中哪类做对应动作，不做全文件逐行怀疑。
2. 模式 3/4 高发的仓库，把「已有工具清单 + 惯例示例」写进规则文件，从生成端减量。
3. 每月盘点被打回最多的模式，针对性更新清单与规则。
4. 迁移/重构场景（kp-015）额外警惕模式 2 与 5——批量改动会放大它们。

排错清单：

• 模式 1 高频出现 → 模型知识截止早于你的依赖版本，提示中附上版本号与关键 API 签名。
• 模式 3 反复出现 → 惯例没有可执行描述；把惯例写成「示例 + 禁止项」而非形容词。
• 债务已经沉淀（两套风格并存）→ 立一项专项重构（走 kp-015 护栏），不要指望日常迭代顺带消化。

公式或模型

本节不适用：模式出现率可用「打回原因分布」粗测，但无跨团队可比的标准数值。

图示

本节不适用：速查表本身即最强形式，图示无增量。

直观类比

像老医生的鉴别诊断手册：不是对每个病人做全身扫描，而是看到指征就想起对应的病——模式信号是指征，处置动作是处方。

常见误区

• 逐行怀疑式审查：低效且仍会漏；按模式信号定位才是可扩展的审法。
• 只在审查端拦：生成端（规则文件注入事实）减量的收益远大于审查端捡漏。
• 把风格漂移当小事：第二套风格是复利债，两套惯例并存会使每个后来者的决策成本翻倍。

与其他知识点的关系

kp-021 的第三四层调用本节模式库；kp-015 的迁移场景是模式 2/5 的放大器。

自测题

要点：风格漂移、重复造轮子、过度防御——它们不影响当下运行，以维护面扩大为代价累积。

要点：在提示/规则文件中提供依赖版本与关键 API 签名，把「模型记忆」替换为「任务内事实」。

1. 七类模式中哪三类最可能沉淀为长期技术债？
2. 模式 1（API 幻觉）的生成端对策？

延伸阅读

本节不适用：错误模式库属实践归纳，建议团队在复盘中持续增补自有条目。