发帖
雷达卡
引言
AI编码工具在生成可运行的Python代码方面表现得越来越出色。它们能在几分钟内构建完整应用程序、实现复杂算法。然而，AI生成的代码往往难以维护。
如果你使用过Claude Code、GitHub Copilot或Cursor的智能体模式等工具，大概率有过这样的经历：AI帮你快速交付了可运行的代码，但后续代价随之而来。几周后，你可能需要重构一个臃肿的函数，只为弄明白它的工作原理。
问题不在于AI写的代码质量差——虽然有时确实如此——而在于AI的优化目标是“即时可用”和完成提示词中的需求，而你需要的是长期具备可读性和可维护性的代码。本文将聚焦Python专属策略，教你弥合这一差距。
避免空白画布陷阱
开发者最大的误区是让AI从零开始写代码。AI智能体在有约束和指导的情况下表现最佳。
在撰写第一个提示词前，亲自搭建项目基础框架。这包括确定项目结构、安装核心库、实现几个可运行的示例，以此定下调性。这看似事倍功半，却能让AI生成的代码更贴合应用需求。
先手动实现几个功能。如果构建API，就亲自完成一个完整端点的开发，融入你期望的所有模式：依赖注入、规范的错误处理、数据库访问和数据验证。这将成为参考实现范例。
例如，你手动编写了第一个端点：
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.orm import Session
router = APIRouter()
# 假设get_db和User模型已在其他地方定义
async def get_user(user_id: int, db: Session = Depends(get_db)):
user = db.query(User).filter(User.id == user_id).first()
if not user:
raise HTTPException(status_code=404, detail="用户不存在")
return user
当AI看到这个模式后，就能理解你如何处理依赖、查询数据库以及应对记录缺失的情况。
项目结构亦是如此。自行创建目录、配置导入语句、搭建测试框架。架构决策不应由AI来做。
让Python类型系统发挥核心作用
Python的动态类型具有灵活性，但当AI生成代码时，这种灵活性反而会成为隐患。要将类型提示作为应用代码中必不可少的防护措施，而非可有可无的补充。
严格的类型检查能在AI代码进入生产环境前发现问题。当要求每个函数签名都包含类型提示，并以严格模式运行mypy时，AI就无法走捷径——不能返回模糊类型，也不能接收可能是字符串或列表的参数。
更重要的是，严格类型能倒逼更优的设计。例如，AI生成接收data: dict参数的函数时，可能会对字典内容做出多种假设；但当函数要求接收data: UserCreateRequest（其中UserCreateRequest是Pydantic模型）时，AI的解读就唯一确定了。
推荐写法（约束AI生成正确代码）：
from pydantic import BaseModel, EmailStr
class UserCreateRequest(BaseModel):
name: str
email: EmailStr
age: int
class UserResponse(BaseModel):
id: int
name: str
email: EmailStr
def process_user(data: UserCreateRequest) -> UserResponse:
pass
不推荐写法：
def process_user(data: dict) -> dict:
pass
使用强制契约的库：SQLAlchemy 2.0（带类型检查模型）和FastAPI（带响应模型）都是极佳选择。这些不仅是最佳实践，更是约束AI不偏离轨道的准则。
将mypy设置为严格模式，并要求必须通过类型检查。当AI生成的代码未通过检查时，让它迭代优化直至合格。这种自动反馈循环比任何提示词工程都能生成更优代码。
创建指导AI的文档
大多数项目都有开发者视而不见的文档。对于AI智能体，你需要它真正会用到的文档——比如包含指导原则的README.md文件。也就是说，用一个文件明确具体的规则。
在项目根目录创建CLAUDE.md或AGENTS.md文件，无需过长，聚焦项目特有规则而非通用Python最佳实践。
AI指导文档应明确：
项目结构及不同类型代码的存放位置
常见任务对应的库选择
需遵循的特定模式（指向示例文件）
明确禁止的模式
测试要求
以下是AGENTS.md文件示例：
项目指导原则
结构
/src/api - FastAPI路由
/src/services - 业务逻辑
/src/models - SQLAlchemy模型
/src/schemas - Pydantic模型
模式
所有服务类继承自BaseService（见src/services/base.py）
所有数据库访问通过仓储模式实现（见src/repositories/）
所有外部依赖使用依赖注入
标准
所有函数必须添加类型提示
使用Google风格的文档字符串
函数代码不超过50行
提交前运行
mypy --strict和ruff check
禁止项
禁止使用裸露的except子句
禁止使用type: ignore注释
禁止使用可变默认参数
禁止使用全局状态
关键在于具体化。不要只说“遵循最佳实践”，要指向演示该模式的确切文件；不要只说“正确处理错误”，要展示你期望的错误处理模式。
撰写指向示例的提示词
通用提示词生成通用代码，而引用现有代码库的具体提示词能生成更易维护的代码。
不要让AI“添加认证功能”，而是结合现有模式逐步引导实现。以下是指向示例的提示词示例：
在src/services/auth_service.py中实现JWT认证，遵循src/services/user_service.py中UserService的结构。使用bcrypt进行密码哈希（已包含在requirements.txt中）。 在src/api/dependencies.py中添加认证依赖，遵循get_db的模式。 在src/schemas/auth.py中创建Pydantic模型，参考user.py的写法。 在tests/test_auth_service.py中编写pytest测试，使用conftest.py中的夹具。
”
注意，每个指令都指向现有文件或模式。你不是让AI搭建架构，而是让它在新功能中应用已有规则。
AI生成代码后，对照现有模式审核：是否采用相同的依赖注入方式？错误处理是否一致？导入语句的组织是否统一？若不一致，指出差异并要求其对齐现有模式。
实现前先规划
AI智能体速度快，但如果追求速度而牺牲结构，反而会降低实用性。在生成代码前，使用规划模式或要求AI输出实现方案。
规划步骤能迫使AI思考依赖关系和结构，也让你有机会在实现前发现架构问题——比如循环依赖或冗余服务。
要求AI提供包含以下内容的方案：
需创建或修改的文件
组件间的依赖关系
将遵循的现有模式
所需的测试内容
像审核设计文档一样审阅方案：确认AI理解项目结构、使用正确的库、没有重复造轮子。
方案可行就让AI执行，不可行则先修正方案再生成代码。修正糟糕的方案比修复劣质代码更容易。
让AI生成真正有价值的测试
AI擅长快速编写测试，但除非你明确“有价值”的定义，否则它很难生成实用的测试。
AI默认只会测试正常流程，这种测试仅验证一切顺利时代码能运行——而这恰恰是不需要测试的场景。
明确测试要求。每个功能都需覆盖：
正常流程测试
验证错误测试（检查无效输入的处理情况）
边界案例测试（空值、None、临界值等）
错误处理测试（数据库故障、外部服务故障等）
将现有测试文件作为示例提供给AI。若你已有良好的测试模式，AI也能生成实用测试；若暂无，先手动编写几个示例。
系统化验证输出结果
AI生成代码后，不要只检查是否能运行，需对照清单逐一验证。
验证清单可包含以下问题：
是否通过mypy严格模式检查？
是否遵循现有代码模式？
所有函数是否都不超过50行？
测试是否覆盖边界案例和错误场景？
所有函数是否都添加了类型提示？
是否正确使用指定库？
尽可能自动化验证。设置预提交钩子，自动运行mypy、Ruff和pytest。AI生成的代码若未通过这些检查，禁止提交。
对于无法自动化的部分，审阅足够多的AI代码后，你会发现常见的反模式——比如函数职责过多、错误处理吞噬异常、验证逻辑与业务逻辑混杂等。
实现实用工作流
下面整合前文所述内容，形成一套实用工作流：
启动新项目后，先搭建结构、选择并安装库、编写几个示例功能；创建CLAUDE.md文档明确指导原则，编写具体的Pydantic模型。
要求AI实现新功能时，撰写指向示例的详细提示词；AI生成方案后，审阅并批准；AI生成代码后，运行类型检查和测试；所有检查通过后，对照模式审核代码；确认一致后提交。
一个手动编写需1小时的功能，按此流程从提示词到提交可能仅需15分钟。更重要的是，生成的代码更易维护——因为它遵循了你设定的模式。
后续功能的开发速度会更快，因为AI有了更多学习示例；代码一致性也会逐步提升，因为每个新功能都在强化现有模式。
总结
随着AI编码工具的实用性日益凸显，开发者或数据从业者的工作内容正在转变。你将减少代码编写时间，更多投入到以下工作中：
设计系统并选择架构
创建模式的参考实现
制定约束条件和指导原则
审阅AI输出并维持质量标准
最重要的技能不再是快速写代码，而是设计能约束AI生成可维护代码的系统，懂得哪些实践具有可扩展性、哪些会产生技术债务。希望本文对你有所帮助，即便你不使用Python编程。欢迎分享你对保持AI生成Python代码可维护性的其他见解，继续探索吧！
作者简介
巴拉·普里娅·C（Bala Priya C）是来自印度的开发者兼技术作家，热衷于探索数学、编程、数据科学与内容创作的交叉领域。她的兴趣和专长包括DevOps、数据科学和自然语言处理，喜欢阅读、写作、编码和喝咖啡！目前，她致力于通过编写教程、操作指南、观点文章等，向开发者社区分享知识，同时创作优质的资源综述和编码教程。
推荐学习书籍 《CDA一级教材》适合CDA一级考生备考，也适合业务及数据分析岗位的从业者提升自我。完整电子版已上线CDA网校，累计已有10万+在读~ !
京公网安备 11010802022788号
