AI 写代码已经是主流了。但很多团队面临同一个问题：AI 生成的代码"能跑"，但不"好"——有 bug、不安全、不符合规范、不可维护。
问题不完全出在 AI 上，更多出在工程体系上：没有对 AI 生成代码做质量把关，就像没有代码审查一样危险。本文梳理一套让 AI 代码生成更可靠的工程方法。
问题诊断：AI 代码的典型缺陷
先了解 AI 代码最容易出现什么问题：
1. 安全漏洞
- SQL 注入（没有参数化查询）
- 未验证的用户输入
- 硬编码密钥
- 不安全的文件操作路径
2. 错误处理缺失
- 裸露的 try/except: pass
- 不处理网络超时
- 忽略边界条件（空列表、None 值）
3. 不符合项目规范
- 命名风格不一致
- 没有类型注解
- 缺少文档注释
- 不符合项目的日志格式
4. 性能问题
- N+1 查询
- 在循环里做网络调用
- 不必要的全量数据加载
方案一：Prompt 工程层面的质量提升
系统级约束
不要每次都在对话里重复要求，用系统 Prompt 或规则文件设定全局约束：
# .cursorrules（Cursor IDE 规则文件）
# 或 CLAUDE.md / AGENTS.md
## 代码质量要求
### Python 规范
- 所有函数必须有类型注解和 docstring
- 使用具体异常类，不允许裸露的 except: 或 except Exception: pass
- 数据库查询必须参数化，禁止字符串拼接 SQL
- 所有外部 API 调用必须有超时设置（默认 30s）
- 使用 structlog 进行结构化日志，禁止 print()
### 安全要求
- 不得硬编码任何密钥、密码、token
- 所有用户输入在使用前必须验证
- 文件路径操作必须使用 Path 对象和白名单验证
### 错误处理
- 写明每个函数可能抛出的异常类型
- 网络操作统一使用项目内的 retry 装饰器
## 当前项目技术栈
- Python 3.12, FastAPI, SQLAlchemy 2.0
- 测试框架: pytest + pytest-asyncio
- 类型检查: mypy (strict mode)
结构化代码请求
不要模糊地说"写一个用户认证功能"，而是提供上下文结构：
## 任务
实现用户登录 API 接口
## 接口规范
- POST /api/auth/login
- 输入: {"email": str, "password": str}
- 成功返回: {"access_token": str, "token_type": "bearer", "expires_in": int}
- 失败: 401 错误
## 约束
- 密码必须 bcrypt 验证（不是明文对比）
- 连续失败 5 次锁定账号 15 分钟（需要 Redis）
- 成功/失败都要记录日志（包含 IP，不含密码）
- access_token 用 JWT，有效期 24 小时
## 已有上下文
- User 模型在 models/user.py 中已定义
- Redis 客户端在 core/cache.py: redis_client
- JWT 工具函数在 core/security.py: create_access_token
请生成：
1. 路由函数
2. 认证服务类
3. 对应的单元测试
方案二：自动化静态分析流水线
构建 AI 代码的专项检查清单
# code_quality_checker.py
import subprocess
import re
from pathlib import Path
from typing import List, Dict
class AICodeQualityChecker:
"""专门针对 AI 生成代码的质量检查"""
def check_file(self, filepath: str) -> Dict:
path = Path(filepath)
code = path.read_text(encoding="utf-8")
issues = []
# 1. 安全检查
issues.extend(self._check_security(code, filepath))
# 2. 错误处理检查
issues.extend(self._check_error_handling(code))
# 3. 类型注解检查
issues.extend(self._check_type_annotations(code))
# 4. 运行 mypy
issues.extend(self._run_mypy(filepath))
# 5. 运行 bandit（安全扫描）
issues.extend(self._run_bandit(filepath))
return {
"file": filepath,
"issues": issues,
"severity_counts": self._count_by_severity(issues),
"pass": not any(i["severity"] == "ERROR" for i in issues),
}
def _check_security(self, code: str, filepath: str) -> List[Dict]:
issues = []
lines = code.split('\n')
patterns = [
(r'password\s*=\s*["\'][^"\']+["\']', "ERROR", "硬编码密码"),
(r'api_key\s*=\s*["\'][^"\']+["\']', "ERROR", "硬编码 API Key"),
(r'secret\s*=\s*["\'][^"\']+["\']', "ERROR", "硬编码 Secret"),
(r'f["\'].*SELECT.*{', "ERROR", "可能的 SQL 注入（f-string 拼接 SQL）"),
(r'eval\s*\(', "ERROR", "危险的 eval() 使用"),
(r'exec\s*\(', "WARNING", "危险的 exec() 使用"),
(r'os\.system\s*\(', "WARNING", "使用 os.system，建议用 subprocess"),
]
for i, line in enumerate(lines, 1):
for pattern, severity, desc in patterns:
if re.search(pattern, line, re.IGNORECASE):
issues.append({
"line": i,
"severity": severity,
"type": "security",
"description": desc,
"code": line.strip(),
})
return issues
def _check_error_handling(self, code: str) -> List[Dict]:
issues = []
lines = code.split('\n')
for i, line in enumerate(lines, 1):
stripped = line.strip()
# 裸露的 except
if re.match(r'^except\s*:', stripped):
issues.append({
"line": i,
"severity": "ERROR",
"type": "error_handling",
"description": "裸露的 except: 会捕获所有异常包括 KeyboardInterrupt，请指定异常类型",
})
# except Exception: pass 或类似
if re.match(r'^except\s+Exception.*:\s*$', stripped):
next_line = lines[i].strip() if i < len(lines) else ""
if next_line == "pass":
issues.append({
"line": i,
"severity": "ERROR",
"type": "error_handling",
"description": "except Exception: pass 吞掉了所有异常，调试时极难发现问题",
})
# 没有超时的 requests 调用
if 'requests.get(' in stripped or 'requests.post(' in stripped:
if 'timeout' not in stripped:
issues.append({
"line": i,
"severity": "WARNING",
"type": "reliability",
"description": "HTTP 请求缺少 timeout 参数，可能导致永久阻塞",
})
return issues
def _check_type_annotations(self, code: str) -> List[Dict]:
issues = []
# 检查没有返回类型注解的函数
func_without_return_type = re.findall(
r'def\s+(\w+)\s*\([^)]*\)\s*(?!->)',
code
)
for func_name in func_without_return_type:
if not func_name.startswith('_') or func_name.startswith('__'):
continue # 允许私有方法没有注解
issues.append({
"severity": "WARNING",
"type": "type_annotation",
"description": f"函数 {func_name} 缺少返回类型注解",
})
return issues
def _run_bandit(self, filepath: str) -> List[Dict]:
"""运行 bandit 安全扫描"""
try:
result = subprocess.run(
["bandit", "-f", "json", filepath],
capture_output=True, text=True
)
import json
data = json.loads(result.stdout)
issues = []
for r in data.get("results", []):
issues.append({
"line": r["line_number"],
"severity": r["issue_severity"],
"type": "bandit",
"description": f"{r['issue_text']} (CWE: {r.get('issue_cwe', {}).get('id', 'N/A')})",
})
return issues
except Exception:
return []
def _run_mypy(self, filepath: str) -> List[Dict]:
"""运行 mypy 类型检查"""
try:
result = subprocess.run(
["mypy", "--ignore-missing-imports", filepath],
capture_output=True, text=True
)
issues = []
for line in result.stdout.split('\n'):
if ': error:' in line:
parts = line.split(':')
if len(parts) >= 3:
issues.append({
"line": int(parts[1]) if parts[1].isdigit() else 0,
"severity": "ERROR",
"type": "mypy",
"description": ':'.join(parts[2:]).strip(),
})
return issues
except Exception:
return []
def _count_by_severity(self, issues: List[Dict]) -> Dict:
from collections import Counter
return Counter(i["severity"] for i in issues)
集成到 CI/CD
# .github/workflows/ai-code-quality.yml
name: AI Code Quality Gate
on: [pull_request]
jobs:
quality-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: 安装检查工具
run: |
pip install bandit mypy ruff
- name: 获取 AI 生成的文件
id: ai_files
run: |
# 通过 PR 标签或文件注释标识 AI 生成的文件
git diff --name-only HEAD~1 HEAD | grep '\.py$' > changed_files.txt
echo "files=$(cat changed_files.txt | tr '\n' ' ')" >> $GITHUB_OUTPUT
- name: 运行安全扫描
run: |
bandit -r . -f json -o bandit_report.json || true
python -c "
import json
data = json.load(open('bandit_report.json'))
high_issues = [r for r in data['results'] if r['issue_severity'] == 'HIGH']
if high_issues:
print(f'发现 {len(high_issues)} 个高危安全问题！')
for i in high_issues:
print(f' Line {i[\"line_number\"]}: {i[\"issue_text\"]}')
exit(1)
print('安全扫描通过')
"
- name: 运行类型检查
run: |
mypy --ignore-missing-imports src/ || true
方案三：AI Review AI
用另一个 LLM 来 Review AI 生成的代码：
async def ai_code_review(
code: str,
context: str = "",
severity_threshold: str = "WARNING"
) -> dict:
"""让 LLM Review 代码"""
review_prompt = f"""你是一个严格的代码审查专家。请审查以下代码，重点关注：
1. **安全漏洞**：SQL注入、XSS、权限绕过、硬编码密钥等
2. **错误处理**：是否正确处理所有异常情况？
3. **并发安全**：是否有竞态条件？
4. **性能问题**：N+1查询、大量数据加载、内存泄漏
5. **逻辑错误**：边界条件、空值处理、业务逻辑
6. **可维护性**：命名清晰度、函数大小、复杂度
{f"业务上下文：{context}" if context else ""}
代码：
```python
{code}
以 JSON 格式返回审查结果： {{ "overall_score": 0-100, "approved": true/false, "issues": [ {{ "severity": "ERROR/WARNING/INFO", "category": "security/performance/logic/style", "line_range": "1-5 或 null", "description": "问题描述", "suggestion": "建议修改方式", "code_fix": "修改后的代码片段（可选）" }} ], "summary": "一句话总结" }}"""
resp = await async_client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": review_prompt}],
temperature=0,
response_format={"type": "json_object"},
)
result = json.loads(resp.choices[0].message.content)
# 过滤低于阈值的问题
severity_order = {"ERROR": 3, "WARNING": 2, "INFO": 1}
min_severity = severity_order.get(severity_threshold, 1)
result["issues"] = [
i for i in result["issues"]
if severity_order.get(i["severity"], 0) >= min_severity
]
return result
---
## 代码生成的完整工作流
把以上方法整合成一个完整工作流：
- 提供详细规格（Prompt 层质量提升） ↓
- AI 生成代码 ↓
- 静态分析（Bandit + Mypy + 自定义规则） ↓ 发现 ERROR 级别问题？ ↓ Yes → 反馈给 AI 修复 → 回到步骤2
- AI Code Review（LLM 审查） ↓ 发现重大问题？ ↓ Yes → 反馈给 AI 修复 → 回到步骤2
- 人工 Review（最终确认） ↓
- 运行测试 ↓
- 合并
---
## 实际效果
根据团队实践经验，引入这套体系后：
- 安全漏洞（SQL 注入、硬编码密钥）：几乎降为零
- 缺少错误处理的问题：减少 80%
- Code Review 时间：减少约 40%（AI 先做一轮过滤）
- 生产 Bug 率：降低约 30%
最重要的是，开发者的注意力从"找低级问题"转向"评估设计合理性"，Review 质量反而提高了。
---
## 总结
让 AI 代码更可靠，不是单点技术问题，是工程体系问题：
1. **约束前置**：用 `.cursorrules` 等文件把规范嵌入 AI 生成过程
2. **自动检查**：静态分析、安全扫描作为 CI 门禁
3. **AI Review AI**：用强模型审查弱模型的输出
4. **人工最终确认**：AI 做减法，人做判断
"AI 写代码"和"AI 写好代码"之间，差的是这套工程体系。
