AI 写 Python 代码总翻车？我靠这 3 条工程约定把开发效率拉满

上周我翻自己半年前写的Python学习项目，看着满屏风格不统一的工具函数、零散的注释、改了三次还没跑通的日期处理逻辑，突然意识到：之前用AI编码助手改代码的效率，全浪费在了反复对齐上下文和修低级错误上。
后来我把踩过的坑整理成了3条项目级的工程约定，再也没出现过AI理解错需求、生成的代码风格混乱的问题，开发效率直接提升了近40%。今天就把这些经验和具体案例分享出来。

第一条约定：给AI固定的上下文模板，告别反复解释背景

最开始用AI改代码的时候，我每次提问都要从头说一遍项目背景、当前模块的功能、依赖的第三方库，经常AI理解错需求，生成的代码要么不符合现有逻辑，要么和项目其他部分的风格冲突。
最典型的一次是改一个日期格式化函数，我之前已经写过类似的逻辑，但是AI完全没参考现有代码，重新写了一个用time模块的实现，和我项目里统一用datetime模块的约定冲突，我前前后后改了三次才对齐需求。
后来我定了一个固定的上下文输入模板，每次让AI改代码前，必须先贴当前模块的头部注释，包含4个核心信息：模块的核心功能、依赖的外部库、核心输入输出、项目已有的约束（比如统一用datetime处理日期、错误码要统一用枚举定义等）。
按这个模板调整之后，之前那个日期格式化函数的修改，AI一次就给出了符合要求的实现，还额外加了非法日期输入的异常处理，省了近半小时的沟通成本。

第二条约定：提前定好代码片段规范，减少AI的随机发挥

AI生成的代码最大的问题就是随机性太强：同一个功能的代码，每次问的风格都不一样，有的加类型提示有的不加，有的写异常处理有的直接裸写逻辑，后期重构的时候特别麻烦。
我之前需要写一个Excel数据解析的工具函数，第一次问AI生成的代码没有处理空单元格的情况，第二次问加了处理但是类型提示乱七八糟，第三次才符合要求，光是写这个函数就花了快一个小时。
后来我定了项目级的代码片段规范，所有AI生成的工具函数必须满足3个要求：必须加完整的类型提示、必须包含至少一个单测用例的注释占位、公共函数必须加标准格式的docstring。我把这个规范写在了项目的README里，每次提问前都会把规范片段贴到上下文里。
按这个规范生成的代码，不仅风格统一，而且可以直接复用。后来这个Excel解析函数直接被我用到了数据统计和报表生成两个模块里，连单测的框架都直接复用了，省了至少2小时的开发时间。

第三条踩坑经验：AI生成的代码必须过静态检查，不能直接上线

很多人用AI写代码会直接拿来用，我之前也踩过这个坑：有一次AI帮我写用户输入的校验函数，我扫了一眼逻辑没问题就直接用到项目里了，后来跑静态检查的时候才发现，AI没有过滤特殊字符，存在潜在的安全风险，要是上线了可能会被注入攻击。
后来我定了死规则：所有AI生成的代码，必须先跑ruff（代码规范检查）和mypy（类型检查），涉及用户输入、文件操作、数据库操作的逻辑，必须人工review之后才能合并到主分支。自打定了这个规则之后，我再也没出现过因为AI生成的代码导致的低级错误。

写在最后

很多人觉得AI编码助手是“偷懒工具”，但其实用对了反而能大幅提升开发效率，核心就是把AI当成“刚入职的新人”，给它明确的规则和上下文，而不是让它自由发挥。
给大家总结3个可以立刻落地的方法：

1. 给AI建立固定的上下文输入模板，把项目级的约定提前写进模板里，减少每次的解释成本；
2. 哪怕是个人小项目，也提前定好简单的代码规范，写入项目的公共文档里，降低AI输出的随机性；
3. 永远不要完全信任AI生成的代码，静态检查+人工review是底线，尤其是涉及业务逻辑和安全相关的代码。