AI写了90%的代码，谁来守住底线——31万行重构的约束实践

# .cursorrules — 项目级 AI Coding 约束
# 此文件会被 AI 编码工具在每次生成时自动注入上下文

project:
  name: "order-service"
  language: "python"
  framework: "fastapi"

architecture:
  layers:
    - name: "api"
      path: "src/api/"
      rule: "只做参数校验和路由，不包含业务逻辑"
    - name: "service"
      path: "src/service/"
      rule: "业务逻辑层，禁止直接操作数据库"
    - name: "repo"
      path: "src/repo/"
      rule: "数据访问层，禁止引用 service 层"
  dependency_direction: "api → service → repo，禁止反向依赖"

naming:
  function: "snake_case，动词开头，如 get_order_by_id"
  class: "PascalCase，名词，如 OrderService"
  variable: "snake_case，禁止驼峰混用"
  constant: "UPPER_SNAKE_CASE"
  # 同一概念的统一命名映射，AI 必须遵守
  concept_map:
    user_id: ["user_id", "userId", "uid"]  # 禁止使用后两个变体
    order_id: ["order_id", "orderId", "oid"]  # 禁止使用后两个变体

prohibited_patterns:
  - "禁止在 api 层写 SQL 查询"
  - "禁止用 print 替代 logger"
  - "禁止硬编码配置值，必须从 settings 读取"
  - "禁止 catch 所有异常后静默忽略"
  - "禁止在循环内做数据库查询（N+1 问题）"

error_handling:
  framework: "fastapi.HTTPException"
  format:
    status_code: "HTTP 状态码"
    detail: "面向调用方的错误描述"
    internal_code: "内部错误码，格式 ERR_{MODULE}_{NUMBER}"

SOP: 统一命名重构
├── Step 1: 扫描变体
│   输入: concept_map + 项目源码
│   输出: 变体清单 (文件路径 + 行号 + 当前命名)
│   验证: 变体数量 > 0 才继续
│
├── Step 2: 执行替换
│   输入: 变体清单 + 目标命名
│   输出: 替换后的文件 diff
│   验证: diff 中只有命名变更，无逻辑变更
│
├── Step 3: 回归测试
│   输入: 替换后的代码
│   输出: 测试报告
│   验证: 全部通过，无新增失败
│
├── Step 4: Rule 更新
│   输入: 本次统一的概念
│   输出: 更新后的 concept_map
│   验证: concept_map 包含新概念条目

# refactor_prompt.py — 生成重构 prompt 的辅助脚本
# 用法: python refactor_prompt.py --concept user_id --target user_id

import argparse
import json

def build_prompt(concept: str, target_name: str, variants_file: str) -> str:
    """根据 concept_map 和扫描结果，生成精确的重构 prompt"""

    with open(variants_file) as f:
        variants = json.load(f)

    # 只取当前概念的变体
    items = [v for v in variants if v["concept"] == concept]

    prompt = f"""你正在执行一个命名统一重构任务，严格约束如下：

1. 只修改命名，不修改任何逻辑、注释或格式
2. 将以下变体统一为 `{target_name}`：
{json.dumps(items, indent=2, ensure_ascii=False)}
3. 修改后运行: pytest tests/ -x --tb=short
4. 如果测试失败，回滚所有变更并报告失败原因
5. 输出变更文件列表和每个文件的 diff 摘要

禁止行为：
- 禁止重构之外的任何改动
- 禁止删除或新增代码行
- 禁止修改 import 顺序
"""
    return prompt

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--concept", required=True)
    parser.add_argument("--target", required=True)
    parser.add_argument("--variants-file", default="variants.json")
    args = parser.parse_args()

    prompt = build_prompt(args.concept, args.target, args.variants_file)
    print(prompt)

# Step 1: 扫描命名变体（可以用 grep + AI 辅助分析）
grep -rn "userId\|uid" src/ --include="*.py" | python scan_variants.py > variants.json

# Step 2: 生成重构 prompt
python refactor_prompt.py --concept user_id --target user_id --variants-file variants.json

# Step 3: 将 prompt 交给 AI 执行，人工审核 diff
git diff --stat  # 只看变更范围
git diff         # 逐行确认只有命名变更

# Step 4: 运行回归测试
pytest tests/ -x --tb=short

# .github/workflows/pre-pr-check.yml
# AI 生成代码的 Pre-PR 结构性检查

name: Pre-PR Structural Check

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  architecture-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # 检查跨层依赖：api 层禁止直接 import repo 层
      - name: Cross-layer dependency check
        run: |
          violations=0
          # api 层不应直接引用 repo 层
          for f in src/api/*.py; do
            if grep -n "from src.repo" "$f"; then
              violations=$((violations + 1))
              echo "::error file=$f::API layer directly imports repo layer"
            fi
          done
          if [ $violations -gt 0 ]; then
            echo "Found $violations cross-layer violations"
            exit 1
          fi

      # 检查命名变体：禁止 concept_map 中标记的变体出现
      - name: Naming convention check
        run: |
          violations=0
          # 禁止 userId 和 uid 变体
          for variant in userId uid; do
            matches=$(grep -rn "$variant" src/ --include="*.py" | wc -l)
            if [ $matches -gt 0 ]; then
              violations=$((violations + matches))
              echo "::warning::Found $matches occurrences of prohibited variant '$variant'"
            fi
          done
          # 禁止 oid 和 orderId 变体
          for variant in orderId oid; do
            matches=$(grep -rn "$variant" src/ --include="*.py" | wc -l)
            if [ $matches -gt 0 ]; then
              violations=$((violations + matches))
              echo "::warning::Found $matches occurrences of prohibited variant '$variant'"
            fi
          done
          if [ $violations -gt 0 ]; then
            echo "Found $violations naming violations"
            exit 1
          fi

      # 检查硬编码配置值
      - name: Hardcoded config check
        run: |
          # 搜索常见的硬编码模式
          hardcoded=$(grep -rn "localhost:5432\|localhost:6379\|hardcoded_password" src/ --include="*.py" | wc -l)
          if [ $hardcoded -gt 0 ]; then
            echo "::error::Found $hardcoded hardcoded config values"
            exit 1
          fi

      # 检查 N+1 查询模式（循环内数据库调用）
      - name: N+1 query pattern check
        run: |
          # 简化检测：for/while 循环体内出现 session.query 或 db.query
          violations=0
          for f in src/api/*.py src/service/*.py; do
            if python -c "
import ast, sys
tree = ast.parse(open('$f').read())
for node in ast.walk(tree):
    if isinstance(node, (ast.For, ast.While)):
                    for child in ast.walk(node):
                        if isinstance(child, ast.Call):
                            func = child.func
                            if isinstance(func, ast.Attribute) and func.attr in ('query', 'execute', 'fetchone', 'fetchall'):
                                print(f'$f:line {child.lineno}')
                                sys.exit(1)
"; then
              violations=$((violations + 1))
            fi
          done
          if [ $violations -gt 0 ]; then
            exit 1
          fi

      # 运行功能测试
      - name: Run tests
        run: pytest tests/ -x --tb=short

每个迭代周期（1-2周）：
  ├── 开发阶段：AI 生成代码 + Rule 约束 + 任务级 prompt
  ├── 提交阶段：Pre-PR 自动检查 → 人工审核结构性变更
  ├── 合入阶段：通过后合入主分支
  └── 盘点阶段：从债清单中选 2-3 条，作为下个迭代的重构任务