Ai编码总则

AI编码总则

AI 生成代码的基本准则与红线

---

基本准则

规则：AI 生成的代码与人工编写的代码适用同一套工程标准，不因”AI 生成”而降低要求。所有 AI 产出必须经过人工审阅、测试验证后方可合入。

[Requirement] AI 生成的每一段代码，必须有明确的人类负责人（Owner），由其承担最终质量责任。

[Requirement] AI 只在”理解了上下文和约束”的前提下生成代码；上下文不足时必须先提问，不得臆造。

[Standard] AI 生成代码遵循”先理解、后生成、再自检”的三步流程，每步缺一不可。

三步流程

1. 理解（Understand）：确认需求、约束、现有代码结构
2. 生成（Generate）：按规范输出代码、注释、测试
3. 自检（Self-check）：编译/运行/静态检查通过后再提交

示例：

# AI 自检清单（生成代码后必须逐项确认）
□ 代码可编译/无语法错误
□ 符合团队编码规范（命名、格式、分层）
□ 没有引入未使用的导入和变量
□ 边界条件已处理（空值、越界、异常）
□ 配套的单元测试已生成或说明为何不需要
□ 无硬编码的密钥、Token、连接串

反模式：

• AI 生成代码后直接提交，不做任何检查
• 上下文不明确时，AI 自行”猜测”业务逻辑
• 认为”AI 生成的代码天然正确”，跳过 Code Review

---

红线清单

规则：以下行为属于绝对禁止项（Red Line），一旦触发必须立即阻断并人工介入。

[Requirement] 红线项无例外，任何场景下均不得由 AI 自动执行。

红线行为表

编号	红线行为	说明	后果
R1	硬编码密钥/凭证	代码中出现 API Key、密码、Token、私钥	安全泄露，立即回滚
R2	未经审查直接合并到主干	AI 生成的代码未经人工 Review 合入 main/master	质量失控，回滚
R3	执行不可逆的破坏性操作	删库、删生产数据、强制覆盖远端分支	数据丢失，安全事故
R4	修改权限/鉴权相关代码	绕过鉴权、关闭安全校验、放宽权限	安全漏洞，回滚
R5	引入未审计的第三方依赖	新增 npm/pip/maven 包未经过安全扫描	供应链攻击风险
R6	生成可执行的敏感数据操作	导出生产数据、批量修改用户数据	数据合规风险
R7	伪造测试结果	跳过测试、Mock 掉被测逻辑、假绿	质量造假，回滚

示例：

# 红线 R1：硬编码密钥（禁止）
api_key = "sk-abc123def456ghi789"
client = OpenAI(api_key=api_key)
 
# 正确：从环境变量读取
import os
api_key = os.environ["OPENAI_API_KEY"]
client = OpenAI(api_key=api_key)

反模式：

• AI 自动运行 git push --force origin main
• AI 在代码里写死数据库密码”方便调试”
• AI 为了让测试通过，把断言改成 assert True
• AI 直接 pip install some-package 不做安全校验

---

质量要求

规则：AI 生成代码的质量标准不低于人工编写，必须在可读性、健壮性、可测试性三个维度达标。

[Requirement] AI 生成的代码必须通过项目已有的全部静态检查（lint、format、type-check），不得为通过而 disable 检查规则。

[Standard] 新增函数必须有 docstring 或注释说明”做什么、入参、返回值、异常”；复杂逻辑必须有行内注释。

[Standard] 新增公共函数/方法必须配套单元测试，覆盖率不低于团队既有基线。

[Suggestion] 函数长度控制在 50 行以内，圈复杂度不超过 10，超过必须拆分。

质量维度检查清单

维度	检查项	工具
可读性	命名清晰、无魔法值、注释充分	人工 Review
规范性	符合 lint/format/type-check	ESLint / Black / mypy
健壮性	边界处理、异常捕获、空值判断	单元测试
可测试性	无全局状态、依赖可注入、纯函数优先	人工 Review
性能	无明显 N+1、无死循环、合理使用缓存	性能测试 / Code Review

示例：

# 质量达标示例
def get_user_by_id(user_id: int) -> Optional[User]:
    """根据 ID 查询用户。
 
    Args:
        user_id: 用户 ID，必须为正整数。
 
    Returns:
        查到返回 User 对象，查不到返回 None。
 
    Raises:
        ValueError: user_id 非法时抛出。
    """
    if user_id <= 0:
        raise ValueError(f"user_id 必须为正整数，当前值: {user_id}")
    return user_repo.find_by_id(user_id)

反模式：

# 质量不达标：无注释、无类型、无边界处理
def get_user(id):
    return db.query("select * from users where id=" + str(id))

---

安全要求

规则：AI 生成的代码必须通过安全基线检查，重点防范注入、越权、敏感数据泄露三类风险。

[Requirement] 所有数据库操作必须使用参数化查询，禁止字符串拼接 SQL。

[Requirement] 所有外部输入（HTTP 参数、文件内容、消息体）必须经过校验后再使用。

[Requirement] 日志中不得输出敏感信息（密码、Token、身份证、手机号原文）。

[Standard] 用户输入直接拼接进命令执行、模板渲染、HTML 输出时，必须做转义/净化。

[Caution] AI 生成的正则表达式必须检查 ReDoS 风险（灾难性回溯）。

安全红线速查

风险类型	禁止做法	正确做法
SQL 注入	字符串拼接 SQL	参数化查询 / ORM
XSS	直接输出用户输入到 HTML	转义 / CSP / 模板自动转义
命令注入	os.system(user_input)	白名单参数 / subprocess 列表传参
越权	不校验资源归属	每次操作校验 owner_id == current_user.id
敏感泄露	日志打印请求体原文	脱敏后打印

示例：

# SQL 注入防护：参数化查询（正确）
def get_user_by_email(email: str) -> Optional[User]:
    return db.execute(
        "SELECT * FROM users WHERE email = :email",
        {"email": email}
    ).first()
 
# 禁止：字符串拼接（红线）
# return db.execute(f"SELECT * FROM users WHERE email = '{email}'").first()

反模式：

• AI 生成 eval(user_input) 或 exec(user_input)
• AI 在日志里 logger.info(f"用户请求: {request.body}") 打印含密码的请求体
• AI 生成的文件上传接口不校验文件类型和大小

---

验收标准

规则：AI 生成代码的合入验收，必须经过”自动化检查 + 人工 Review”两道关卡，缺一不可。

[Requirement] 合入前必须通过：编译通过、lint 通过、单元测试通过、安全扫描通过。

[Requirement] 人工 Code Review 必须覆盖：业务逻辑正确性、边界条件、异常处理、可读性。

[Standard] AI 生成的代码在 PR 描述中必须标注”AI 辅助生成”，并附上使用的 Prompt 和上下文范围。

[Suggestion] 对 AI 生成的核心业务逻辑，额外增加一次”反向测试”（故意构造异常输入验证健壮性）。

验收流水线

AI 生成代码
    │
    ▼
┌─────────────────────┐
│ 1. 本地自检          │  编译 / lint / 单测 / 安全扫描
│    （AI 自动执行）    │  全部通过才进入下一步
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│ 2. 提交 PR           │  标注 AI 生成、附 Prompt 摘要
│    （人类确认后提交） │
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│ 3. CI 流水线         │  重复执行全部检查 + 集成测试
│    （自动化）         │  失败则打回
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│ 4. 人工 Code Review  │  逻辑、边界、安全、可读性
│    （至少 1 人）      │  通过方可合并
└─────────────────────┘
    │
    ▼
  合入主干

示例：

PR 描述模板（AI 生成代码专用）

## 变更说明
本次变更由 AI 辅助生成，实现：用户注册接口

## AI 使用信息
- 工具：GitHub Copilot
- 上下文范围：src/services/user.py、src/schemas/user.py
- Prompt 摘要："实现用户注册，校验邮箱唯一性，发送欢迎邮件"

## 自检结果
- ✅ 编译通过
- ✅ ruff check 通过
- ✅ 单元测试 3/3 通过
- ✅ 安全扫描无高危

## 需要 Reviewer 重点关注
1. 邮箱唯一性校验的并发安全性
2. 欢迎邮件发送失败时的事务处理

反模式：

• AI 生成代码后，人类不看就点 Approve
• PR 描述只写”AI 生成”，不说明上下文和自检结果
• 跳过 CI 直接合入