核心结论 :AI 不是在「学坏」,是它把你的代码库当了教材------库里有多少旧写法,它就有多大概率抄旧写法。所以治理分两步:先清掉坏样例 ,把过时调用、临时补丁、复制粘贴、注释掉的死代码从「可抄样本」里移除;再把约束下沉到代码,用类型、封装、测试和 CI 门禁让错误写法写不出来、写出来编译不过、跑起来测试红。只清不锁,旧写法会长回来;只锁不清,你会被存量报错淹没。
目录
- 一句话结论
- AI 为什么会照着旧代码抄
- 坏样例的四种形态
- 只加规则为什么拦不住
- 第一步:把坏样例清出去
- 第二步:用类型封死错误写法
- 第三步:用测试与门禁封死退路
- 症状 → 原因 → 解法对照表
- 可直接运行的坏样例体检脚本
- 为什么必须先清后锁
- 边界:什么时候不用这么狠
1. 一句话结论(The One-Line Conclusion)
AI 写代码时主要依据两样东西:预训练里见过的通用写法,和上下文里能读到的仓库现有写法。后者权重更高,因为它更「像」当前项目的风格。于是代码库里的每一处旧写法,都是给模型的一次示范。
治理顺序因此是固定的:先降低坏样例的密度,再提高坏写法的成本。前者解决「它抄什么」,后者解决「它抄了会怎样」。两件事都做,但顺序不能反------先锁后清,你会被存量报错逼着加一堆豁免,等于亲手把门禁关掉。
2. AI 为什么会照着旧代码抄(Why Models Copy Legacy Code)
- 训练目标是「下一个 token 最可能出现」,不是「最正确」。模仿(Imitation)是它的默认行为,不是 bug,也不是懒惰。
- 上下文里的样例按「最近 + 最相似」加权。同一个文件第 40 行刚出现过
getJSON,第 400 行再写一次的概率,远高于它停下来翻文档的概率。 - 数量分布决定结果:假设仓库里旧写法 30 处、新写法 3 处,模型照抄旧写法的朴素概率是 30/33≈0.909。这不是模型笨,这是你给的样本分布。
- 更隐蔽的一点:注释掉的死代码同样计入上下文。
# old = requests.get(...)在模型眼里和活代码一样,都是「这个项目就是这么写的」的证据。 - 打个比方:你写的规范文档是「宪法」,仓库里那 300 处旧调用是「判例」,而 AI 是判例法系------它先看判例,实在找不到才翻宪法。
3. 坏样例的四种形态(Four Shapes of Bad Examples)
| 形态 | 长什么样 | 为什么危险 |
|---|---|---|
| Deprecated API(过时接口) | 调用已被替代的函数,如 getJSON |
新写法只在少数新文件里,旧写法才是多数派 |
| Temporary Patch(临时补丁) | # FIXME 先这样,下周补 |
补丁自带「过期承诺」,会被当成范式继续复制 |
| Copy-Paste Block(复制粘贴块) | 同一段逻辑的第 4 份拷贝 | 改一份,剩下三份继续错,AI 还会抄那份没改的 |
| Commented-Out Code(注释掉的死代码) | # old_impl = ... |
它是最强的旧写法示范,而且不受 lint 管 |
四种形态的共同点:语法全部合法。审查时看不出错,跑起来才崩,这是它们比「编译错误」难治的地方。
4. 只加规则为什么拦不住(Why Prompts Alone Fail)
- 规则是软约束(Soft Constraint):写在 prompt、rules 文件、README 里,只改变概率,不改变可行性。模型完全可以读到「禁止使用 getJSON」,然后照写不误。
- 规则会互相稀释:无关规则挂得越多,关键的那条越容易被淹没。而代码里的约束不会稀释------第 41 条 lint 规则和第 1 条一样,命中就报错。
- 在项目越写越乱别急着改架构中我们讲过:目录乱不乱要先量化再动手。清理坏样例同理,先数、再删,不靠感觉。
- 一句话区分:规则是提醒,编译器和测试是拒绝。提醒可以被忽略,拒绝不能。
5. 第一步:把坏样例清出去(Purge the Bad Examples)
- 先数后删。跑一次体检(§9 的脚本就能用),拿到三类清单:过时调用、补丁标记、重复块。没有清单就动手,结果通常是删了一半、剩下的一半更乱。
- 按扩散速度排序,不按文件顺序。被引用次数最多的旧 API 排最前,因为它每被复制一次,成本就翻一倍。
- 一个入口替代 N 个调用点。把旧调用全部收口到一个封装函数,再分文件替换。每替换一个文件就是一次可独立回滚的提交。
- 补丁不留「无主」的。要么当场修掉,要么转成 issue 后删掉注释。留一个带日期的 FIXME 比留一个无主的 FIXME 好,最好的数量是零。
- 死代码直接删。git 有历史,注释不提供额外信息,却持续污染上下文。
- 示例代码和文档一起清。README、docs 里的示例是最强样例,在模型眼里的权重比业务代码更高。
6. 第二步:用类型封死错误写法(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,必须显式改私有成员,这一步足够让它犹豫。 - 打个比方:类型系统是模具,不是说明书。说明书可以不看,模具不对零件根本出不来。
7. 第三步:用测试与门禁封死退路(Seal with Tests and Gates)
- 给新写法写一条会失败的测试(先红),再改实现(变绿)。这条测试从此就是捕鼠夹:以后谁抄回旧写法,CI 立刻红。
- 门禁分三层:静态检查(type / lint)→ 单测 → 自定义规则(§9 脚本)。前两层本地跑保证速度,三层都在 CI 里跑保证落地。
- 报错文案要能指导修改。不要只报「禁止调用 getJSON」,要报「不要用 getJSON,改用 request_json()」。模型读到报错会照做,读到
forbidden只会换一种写法绕过去。 - 不要给坏样例建 archive 目录。把旧实现挪到
legacy/并豁免检查,等于在仓库里保留一份「官方推荐的可抄样本」。这条反直觉,理由在 §10。 - 门禁的价值不在拦人,在于拦概率。人看一遍就懂了,模型每次都要重新读一遍上下文。
8. 症状 → 原因 → 解法对照表(Symptom-Cause-Fix)
| 症状 | 原因 | 解法 |
|---|---|---|
| 改好的接口,AI 下次又写成旧的 | 旧调用点密度高于新写法 | 清存量 + 收口到唯一入口 |
| 每个文件都在重复同一段逻辑 | 没有可复用的抽象 | 抽公共函数 + 重复块门禁 |
AI 反复写 # TODO 后续补 |
补丁被当成了范式 | 补丁零容忍,转 issue 后删注释 |
| 审查看不出错,跑起来才崩 | 旧写法语法合法,只是语义过期 | 弃用清单 + 报错文案给替代方案 |
| 门禁一开全红,只能批量 ignore | 先锁后清,存量没处理 | 先清到零,再把阈值设成零容忍 |
9. 可直接运行的坏样例体检脚本(Runnable Legacy Scanner)
下面这段脚本把三件事做成一次扫描:过时调用、临时补丁标记、重复函数体。命中任一项就返回退出码 1,可以直接挂到 CI。
python
"""代码库坏样例体检:过时调用 / 临时补丁标记 / 重复代码块,任一命中即退出码 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,实际输出是:
text
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 检查,思路一样,精度更高。
10. 为什么必须先清后锁(Order Matters)
多数团队会直接上 lint 和类型检查,不清旧代码。结果第一次跑,40 处旧调用全红。此时只有两个选项:全量修(等于先清,只是被逼着一次性做完),或者加 ignore。多数人选后者。
每加一条 ignore,AI 下次写旧写法就被豁免一次。40 条 ignore 就是 40 张通行证,门禁从「拒绝」退化成「提醒」------而你刚刚在 §4 说过,提醒拦不住模型。
顺序背后的经济学:清理是一次性成本,门禁是持续成本。先清,你能把阈值设成零容忍;先锁,你只能设成「不比昨天更差」,而后者对模型毫无约束力,因为它根本不看昨天。
存量确实太大时的折中方案是按目录设递减配额:新代码零容忍,老目录每周把配额乘 0.9,40 处起步,12 周后降到约 11 处( 40×0.912≈11.3)。这是唯一能同时保住门禁强度和落地速度的做法。
11. 边界:什么时候不用这么狠(Boundaries)
- 一次性脚本、原型、临时数据清洗:不必上这套,约束成本高于收益。
- 第三方 SDK 无法迁移:别硬删调用,用封装层隔离,门禁禁的是「直接调用」而不是「调用」。
- 仓库小于 5k 行、团队 3 人以内:只做体检脚本这一件事,先让存量可见。
- 别做成年度大扫除。一次清完,三个月又长回来;有效的是增量锁定------新代码零容忍,存量按配额递减,让「坏样例密度」单调下降。
只有当仓库里正确写法多于旧写法,AI 才会稳定抄对。所以先清、再锁,这两个动作隔一周做都行,顺序反了就得重来。
本专栏《AI 开发范式》聚焦 AI 协作下的代码组织、代码评审与工程约束,从目录结构一直讲到类型设计与 CI 门禁,每篇都配一段可直接运行的检查脚本,每周更新一篇。想按顺序读完,可在专栏页订阅。