AI 总模仿代码库里的过时写法怎么办:先清坏样例,再用类型与测试让 AI 无法犯错

文章来源声明: 原文作者:ENCI; 来源站点:掘金; 原文链接:https://juejin.cn/post/7709358271694520329; 本文基于上述来源整理/加工,觅优补充点评,仅供技术学习交流。版权归原作者所有。
觅优短评

把模糊的规范升级为可执行的工程约束,配可直接挂 CI 的体检脚本,适合有历史包袱、正引入 AI 编码的团队落地。

> **核心结论**:AI 不是在「学坏」,是它把你的代码库当了教材——库里有多少旧写法,它就有多大概率抄旧写法。所以治理分两步:**先清掉坏样例**,把过时调用、临时补丁、复制粘贴、注释掉的死代码从「可抄样本」里移除;**再把约束下沉到代码**,用类型、封装、测试和 CI 门禁让错误写法写不出来、写出来编译不过、跑起来测试红。只清不锁,旧写法会长回来;只锁不清,你会被存量报错淹没。

目录

  1. 一句话结论

  2. AI 为什么会照着旧代码抄

  3. 坏样例的四种形态

  4. 只加规则为什么拦不住

  5. 第一步:把坏样例清出去

  6. 第二步:用类型封死错误写法

  7. 第三步:用测试与门禁封死退路

  8. 症状 → 原因 → 解法对照表

  9. 可直接运行的坏样例体检脚本

  10. 为什么必须先清后锁

  11. 边界:什么时候不用这么狠

  12. 一句话结论(The One-Line Conclusion)


AI 写代码时主要依据两样东西:预训练里见过的通用写法,和上下文里能读到的仓库现有写法。后者权重更高,因为它更「像」当前项目的风格。于是代码库里的每一处旧写法,都是给模型的一次示范。

治理顺序因此是固定的:先降低坏样例的密度,再提高坏写法的成本。前者解决「它抄什么」,后者解决「它抄了会怎样」。两件事都做,但顺序不能反——先锁后清,你会被存量报错逼着加一堆豁免,等于亲手把门禁关掉。

  1. AI 为什么会照着旧代码抄(Why Models Copy Legacy Code)

  • 训练目标是「下一个 token 最可能出现」,不是「最正确」。模仿(Imitation)是它的默认行为,不是 bug,也不是懒惰。
  • 上下文里的样例按「最近 + 最相似」加权。同一个文件第 40 行刚出现过 getJSON,第 400 行再写一次的概率,远高于它停下来翻文档的概率。
  • 数量分布决定结果:假设仓库里旧写法 30 处、新写法 3 处,模型照抄旧写法的朴素概率是 30/33≈0.90930/33 \approx 0.909。这不是模型笨,这是你给的样本分布。
  • 更隐蔽的一点:注释掉的死代码同样计入上下文。# old = requests.get(...) 在模型眼里和活代码一样,都是「这个项目就是这么写的」的证据。
  • 打个比方:你写的规范文档是「宪法」,仓库里那 300 处旧调用是「判例」,而 AI 是判例法系——它先看判例,实在找不到才翻宪法。
  1. 坏样例的四种形态(Four Shapes of Bad Examples)

形态长什么样为什么危险
Deprecated API(过时接口)调用已被替代的函数,如 `getJSON`新写法只在少数新文件里,旧写法才是多数派
Temporary Patch(临时补丁)`# FIXME 先这样,下周补`补丁自带「过期承诺」,会被当成范式继续复制
Copy-Paste Block(复制粘贴块)同一段逻辑的第 4 份拷贝改一份,剩下三份继续错,AI 还会抄那份没改的
Commented-Out Code(注释掉的死代码)`# old_impl = ...`它是最强的旧写法示范,而且不受 lint 管

四种形态的共同点:语法全部合法。审查时看不出错,跑起来才崩,这是它们比「编译错误」难治的地方。

  1. 只加规则为什么拦不住(Why Prompts Alone Fail)

  • 规则是软约束(Soft Constraint):写在 prompt、rules 文件、README 里,只改变概率,不改变可行性。模型完全可以读到「禁止使用 getJSON」,然后照写不误。
  • 规则会互相稀释:无关规则挂得越多,关键的那条越容易被淹没。而代码里的约束不会稀释——第 41 条 lint 规则和第 1 条一样,命中就报错。
  • 在项目越写越乱别急着改架构中我们讲过:目录乱不乱要先量化再动手。清理坏样例同理,先数、再删,不靠感觉。
  • 一句话区分:规则是提醒,编译器和测试是拒绝。提醒可以被忽略,拒绝不能。
  1. 第一步:把坏样例清出去(Purge the Bad Examples)

  • 先数后删。跑一次体检(§9 的脚本就能用),拿到三类清单:过时调用、补丁标记、重复块。没有清单就动手,结果通常是删了一半、剩下的一半更乱。
  • 按扩散速度排序,不按文件顺序。被引用次数最多的旧 API 排最前,因为它每被复制一次,成本就翻一倍。
  • 一个入口替代 N 个调用点。把旧调用全部收口到一个封装函数,再分文件替换。每替换一个文件就是一次可独立回滚的提交。
  • 补丁不留「无主」的。要么当场修掉,要么转成 issue 后删掉注释。留一个带日期的 FIXME 比留一个无主的 FIXME 好,最好的数量是零。
  • 死代码直接删。git 有历史,注释不提供额外信息,却持续污染上下文。
  • 示例代码和文档一起清。README、docs 里的示例是最强样例,在模型眼里的权重比业务代码更高。
  1. 第二步:用类型封死错误写法(Seal with Types)

  • 枚举代替字符串。把 mode: str 收成 Literal["fast", "safe"] 或 Enum,旧值写出来直接报错。AI 想抄 mode="legacy",类型检查先拦一次。
  • 参数对象代替散参。create(a, b, c, d) 改成 create(cfg: CreateConfig),旧的位置参数写法对不上就挂。
  • 返回类型收紧。dict 换成 dataclass,AI 想往里塞 payload["data"] 这类猜测式 key,会报属性不存在。
  • 私有化加唯一入口。模块内 _session 私有,对外只暴露 query_one()。想绕开封装直接执行 SQL,必须显式改私有成员,这一步足够让它犹豫。
  • 打个比方:类型系统是模具,不是说明书。说明书可以不看,模具不对零件根本出不来。
  1. 第三步:用测试与门禁封死退路(Seal with Tests and Gates)

  • 给新写法写一条会失败的测试(先红),再改实现(变绿)。这条测试从此就是捕鼠夹:以后谁抄回旧写法,CI 立刻红。
  • 门禁分三层:静态检查(type / lint)→ 单测 → 自定义规则(§9 脚本)。前两层本地跑保证速度,三层都在 CI 里跑保证落地。
  • 报错文案要能指导修改。不要只报「禁止调用 getJSON」,要报「不要用 getJSON,改用 request_json()」。模型读到报错会照做,读到 forbidden 只会换一种写法绕过去。
  • 不要给坏样例建 archive 目录。把旧实现挪到 legacy/ 并豁免检查,等于在仓库里保留一份「官方推荐的可抄样本」。这条反直觉,理由在 §10。
  • 门禁的价值不在拦人,在于拦概率。人看一遍就懂了,模型每次都要重新读一遍上下文。
  1. 症状 → 原因 → 解法对照表(Symptom-Cause-Fix)

症状原因解法
改好的接口,AI 下次又写成旧的旧调用点密度高于新写法清存量 + 收口到唯一入口
每个文件都在重复同一段逻辑没有可复用的抽象抽公共函数 + 重复块门禁
AI 反复写 `# TODO 后续补`补丁被当成了范式补丁零容忍,转 issue 后删注释
审查看不出错,跑起来才崩旧写法语法合法,只是语义过期弃用清单 + 报错文案给替代方案
门禁一开全红,只能批量 ignore先锁后清,存量没处理先清到零,再把阈值设成零容忍
  1. 可直接运行的坏样例体检脚本(Runnable Legacy Scanner)

下面这段脚本把三件事做成一次扫描:过时调用、临时补丁标记、重复函数体。命中任一项就返回退出码 1,可以直接挂到 CI。

"""代码库坏样例体检:过时调用 / 临时补丁标记 / 重复代码块,任一命中即退出码 1。"""
import ast, hashlib, pathlib, re, sys

DEPRECATED = {                                    # 过时写法 → 替代方案
    "getJSON": "改用 request_json()",
    "requests.get": "统一走 http_client.fetch()",
}
PATCH = re.compile(r"#.*\b(TODO|FIXME|HACK|TEMP)\b")    # 临时补丁标记


def dotted(node):                                 # 把调用点还原成点号全名
    parts = []
    while isinstance(node, ast.Attribute):         # a.b.get() 逐层拆到 a
        parts.append(node.attr)
        node = node.value
    if isinstance(node, ast.Name):
        parts.append(node.id)
        return ".".join(reversed(parts))
    return ""


def check(path):                                  # 单文件体检
    src = path.read_text(encoding="utf-8")
    tree = ast.parse(src)
    hits = []
    for node in ast.walk(tree):                    # 遍历所有调用点
        if isinstance(node, ast.Call) and dotted(node.func) in DEPRECATED:
            hits.append((path, node.lineno, "过时调用", dotted(node.func)))
    for lineno, line in enumerate(src.splitlines(), 1):
        mark = PATCH.search(line)                  # 逐行找补丁标记
        if mark:
            hits.append((path, lineno, "临时补丁", mark.group(1)))
    return hits, tree


def body_key(func):                                # 函数体归一化指纹
    body = [ast.dump(n) for n in func.body
            if not (isinstance(n, ast.Expr) and isinstance(n.value, ast.Constant))]
    return hashlib.md5("".join(body).encode()).hexdigest()


def main(root):                                    # 汇总报告并决定退出码
    files = sorted(p for p in pathlib.Path(root).rglob("*.py")
                   if ".venv" not in p.parts)
    all_hits, seen, dup = [], {}, []
    for path in files:
        hits, tree = check(path)
        all_hits += hits
        for node in ast.walk(tree):                 # 同体函数即视为复制粘贴
            if isinstance(node, ast.FunctionDef) and len(node.body) >= 3:
                key = body_key(node)
                if key in seen:
                    dup.append((seen[key], f"{path.as_posix()}:{node.name}"))
                else:
                    seen[key] = f"{path.as_posix()}:{node.name}"
    for path, lineno, kind, detail in all_hits:
        print(f"{path.as_posix()}:{lineno}  [{kind}] {detail}")
    for left, right in dup:
        print(f"重复函数体  {left}  ==  {right}")
    bad = len(all_hits) + len(dup)
    print(f"\n扫描 {len(files)} 个文件,过时/补丁 {len(all_hits)} 处,重复块 {len(dup)} 组")
    return 1 if bad else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else "."))

拿一个 4 文件的小目录(app/user.py 里有 2 处过时调用和 1 个 FIXME,app/report.py 有 1 个 HACK,app/order.py 与 app/user.py 各有一个同名同体的 normalize)跑 python scan_legacy.py app,实际输出是:

app/report.py:1  [临时补丁] HACK
app/user.py:5  [过时调用] requests.get
app/user.py:6  [过时调用] getJSON
app/user.py:5  [临时补丁] FIXME
重复函数体  app/order.py:normalize  ==  app/user.py:normalize

扫描 4 个文件,过时/补丁 4 处,重复块 1 组

退出码 1,在 CI 里就是一次失败。同一份脚本跑一个只剩干净模块的目录,输出「扫描 1 个文件,过时/补丁 0 处,重复块 0 组」,退出码 0。

局限也要说清:重复检测按函数体指纹比对,重构后语义等价但写法不同的逻辑识别不了;生产环境可以换成 jscpd 或 pylint 的 duplicate-code 检查,思路一样,精度更高。

  1. 为什么必须先清后锁(Order Matters)

多数团队会直接上 lint 和类型检查,不清旧代码。结果第一次跑,40 处旧调用全红。此时只有两个选项:全量修(等于先清,只是被逼着一次性做完),或者加 ignore。多数人选后者。

每加一条 ignore,AI 下次写旧写法就被豁免一次。40 条 ignore 就是 40 张通行证,门禁从「拒绝」退化成「提醒」——而你刚刚在 §4 说过,提醒拦不住模型。

顺序背后的经济学:清理是一次性成本,门禁是持续成本。先清,你能把阈值设成零容忍;先锁,你只能设成「不比昨天更差」,而后者对模型毫无约束力,因为它根本不看昨天。

存量确实太大时的折中方案是按目录设递减配额:新代码零容忍,老目录每周把配额乘 0.9,40 处起步,12 周后降到约 11 处(40×0.912≈11.340 \times 0.9^{12} \approx 11.3)。这是唯一能同时保住门禁强度和落地速度的做法。

  1. 边界:什么时候不用这么狠(Boundaries)

  • 一次性脚本、原型、临时数据清洗:不必上这套,约束成本高于收益。
  • 第三方 SDK 无法迁移:别硬删调用,用封装层隔离,门禁禁的是「直接调用」而不是「调用」。
  • 仓库小于 5k 行、团队 3 人以内:只做体检脚本这一件事,先让存量可见。
  • 别做成年度大扫除。一次清完,三个月又长回来;有效的是增量锁定——新代码零容忍,存量按配额递减,让「坏样例密度」单调下降。

只有当仓库里正确写法多于旧写法,AI 才会稳定抄对。所以先清、再锁,这两个动作隔一周做都行,顺序反了就得重来。

本专栏《AI 开发范式》聚焦 AI 协作下的代码组织、代码评审与工程约束,从目录结构一直讲到类型设计与 CI 门禁,每篇都配一段可直接运行的检查脚本,每周更新一篇。想按顺序读完,可在专栏页订阅。