《Codex CLI》深度阅读系列

把Python项目交给AI前，
先准备好这套质量护栏

AI会写Python语法，却不会自动知道你的环境、工具链和完成标准。统一入口与单一质量门禁，才能阻止“差不多能用”的代码进入项目。

AI写一个Python函数通常很快，真正让团队返工的却是周围那圈小偏差：项目用统一包管理器，它直接执行另一套安装命令；仓库把配置集中在一个文件里，它又新建旧式配置；测试能通过，但类型检查失败，或者覆盖的只是当前实现而不是业务行为。每一处都不致命，累积起来却会持续侵蚀项目一致性。

问题不在于AI不会Python，而在于Python项目的规则太多是默认知识：版本、环境、依赖、格式、类型、测试、标记和覆盖率。人靠经验补齐，AI只能猜。要让它稳定工作，必须把这些隐性约定变成五层可执行护栏。

第一层：先固定环境和唯一工具入口

明确Python版本、包管理器、虚拟环境和依赖配置的唯一来源。安装依赖、运行脚本和执行测试都通过同一个项目入口，不允许临时绕开。这样开发者、AI和CI得到的是同一套解释器与依赖，而不是三种“在我机器上能跑”的环境。

还要写清哪些文件不能随意改：锁文件只有在依赖真的变化时更新，环境密钥不能进入仓库，不新建与现有配置重复的文件。环境一致是后面所有检查可信的前提；如果输入的运行环境都不同，测试结果就没有可比性。

第二层：先消灭格式和静态规则噪声

格式化和静态检查应该自动、快速、确定。它们负责导入顺序、无用变量、明显错误和风格一致性，让代码审查不再围绕机械问题反复争论。规则集中在项目配置里，由一个固定命令执行，不让AI临时挑选或跳过。

自动修复后仍要重新查看差异。工具可能重排大量代码，掩盖真正的功能修改；也可能触及任务范围之外的文件。质量护栏不是“命令跑过就算”，而是用确定工具降低噪声，再确认实际差异仍然最小。

第三层：用类型把接口假设提前暴露

Python在运行时才暴露很多类型问题，因此公共函数、服务边界和核心数据结构应有明确类型。重点不是给每个局部变量加注解，而是把可空值、返回结果、集合元素和跨模块协议说清楚，让错误在合并前出现。

同时限制无约束的通用类型。一个接口到处写成“任意值”，类型检查就只剩装饰。AI很擅长补齐语法化注解，但团队必须规定严格程度、允许的例外和数据模型位置，否则同一个项目会出现多套互不兼容的表达。

第四层：测试行为，不要复制当前实现

测试要覆盖正常、边界、异常和回归场景，并复用项目已有夹具与标记。新增测试如果只是把当前输出原样写进断言，只能证明代码今天这样运行，不能证明行为符合需求。先写清业务契约，再让测试对契约负责。

快单元测试适合每次修改后执行，集成与慢测试可以放到合并前或CI。覆盖率用于发现遗漏区域，但不能替代断言质量。比总百分比更重要的是：关键模块的分支是否被走到，失败路径是否真的触发，过去出现过的问题是否留下回归测试。

第五层：用一个命令定义“完成”

最后把格式、静态检查、类型检查、测试和覆盖率串成一个质量门禁，任何一步失败都返回明确错误并停止。AI在宣布完成前必须运行这一个入口，报告每一步结果以及未运行的检查。团队无需猜它到底挑了哪些命令。

项目规则里只需要写清四件事：环境怎么进入、检查怎么运行、测试与覆盖率标准是什么、什么结果才允许标记完成。规则不必复制整本Python手册，却必须让输出可验证。护栏的价值不是限制AI写代码，而是让它写出的代码天然走在团队同一条路上。