为什么要关注 AI 编程的质量控制

在使用 Cursor、Claude Code 等AI编程工具写代码的这段时间里，笔者发现：AI 可以让代码的编写速度提升2-3倍，但如果没有适当的质量控制，最终反而可能花更多时间在调试和重构上。

这不只是我一个人的忧虑。下表对比了几项研究和调查中有关开发与调试时间的关键数据：

维度	传统开发场景	AI辅助的后变化	数据来源
集成、测试和调试	约30%–40%	—	Pressman
验证和调试	约占35%–50%	—	ACM Queue
简单任务	—	完成时间减少55.8%<br（提速55.8%）	GitHub Copilot RCT
复杂任务	—	完成时间增加19%<br（减速19%）	METR RCT
开发者调研	—	45.2%认为调试AI代码更耗时；66%认为代码“差不多但不完全对”	stack Overflow

以上数据反映出一个核心原则：

AI 开发的效率瓶颈是“质量检查”。

接下来我会分享我的质量检查流程，这套流程可以适配任何主流AI编程工具，并不局限于claude code的插件生态。

---

准备工作：让编程方式适应“AI”习惯

在进入具体的检查流程之前，有两个准备工作能让后续的质量检查事半功倍。

按功能组织代码

项目代码的组织方式通常有两种选择：按技术层分类（分层架构）或按业务功能分类（按功能组织）。在 AI 辅助编程的场景下，后者会是更好的选择：

分层架构

src/
├── routers/      # 所有路由/API 端点
├── services/     # 所有业务逻辑
├── repositories/ # 所有数据访问
└── models/       # 所有数据模型

特点：分离技术功能。常导致逻辑分散和复杂的依赖关系。

按功能组织架构

src/
├── user/
│   ├── __init__.py    # Python 包标识
│   ├── router.py      # FastAPI 路由定义
│   ├── service.py     # 业务逻辑
│   ├── models.py      # 数据模型（SQLAlchemy）
│   ├── schemas.py     # Pydantic 数据验证
│   └── CLAUDE.md      # 模块特定规范
└── order/
    ├── __init__.py
    ├── router.py
    ├── service.py
    ├── models.py
    └── schemas.py

特点：分离业务领域。促进模块化、可重用性和易于维护。

为什么按功能组织对 AI 更友好？

举个例子：当你提出修改评论功能时，如果是分层架构，它需要分别读取 routers/review.py、services/review_service.py、models/review_model.py，可能还有 schemas/review_schema.py——至少4个不同目录的文件。而按功能组织时，所有相关文件都在 src/review/ 目录下，AI 可以一次性理解整个模块的上下文。

此外，每个模块可以有自己的 CLAUDE.md，定义该模块的特定规则和约束。这让 AI 在不同模块间切换时，能自动适应不同的开发规范。

---

用 Make 命令统一入口

每个新项目的第一件事，我都会创建一个 Makefile。它解决了以下几个痛点：

痛点	解决方案
每次告诉 AI “运行 ruff check && mypy . && pytest”	简化为 “运行 make check”
不同项目命令不一样	无论技术栈如何，make test 始终有效
新成员不知道项目规范	看 Makefile 就知道该做什么

---

如何创建 Makefile

1. 创建文件

在项目根目录创建名为 Makefile 的文件（没有扩展名）：

touch Makefile

2. 基础模板（可直接复制使用）

.PHONY: help setup dev run stop format check test clean

help: ## 显示帮助信息（默认目标）
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'

setup: ## 初始化开发环境
	@echo "🔧 Installing dependencies..."
	pip install -r requirements.txt

dev: ## 本地开发模式
	@echo "🚀 Starting dev server..."
	python manage.py runserver

run: ## 生产模式
	@echo "🚀 Starting production server..."
	gunicorn app:app

format: ## 格式化代码
	@echo "✨ Formatting code..."
	black .
	isort .

check: ## 代码检查
	@echo "🔍 Checking code..."
	flake8 .
	black --check .

test: ## 运行测试
	@echo "🧪 Running tests..."
	pytest -v

clean: ## 清理临时文件
	@echo "🧹 Cleaning up..."
	find . -type d -name "__pycache__" -exec rm -rf {} +
	find . -type f -name "*.pyc" -delete

3. 使用方法

命令行输入：

make          # 或 make help，显示所有可用命令
make setup    # 初始化环境
make dev      # 启动开发服务器
make format   # 格式化代码
make check    # 检查代码
make test     # 运行测试

在项目根目录创建 CLAUDE.md，记录这些规则：

# 项目开发指南

## 常用命令
- `make help` - 查看所有命令
- `make dev` - 启动开发服务器
- `make check` - 代码检查（ruff + mypy + pytest）
- `make format` - 自动格式化代码

## 项目结构
...

这样 AI 每次都能读取这些规范，保持一致的开发习惯。

---

关键语法、工具解释

语法	含义
.PHONY: ...	声明这些目标不对应真实文件，避免与同名文件冲突
target: ## 注释	## 后面的文字会被 help 命令提取显示
@	不显示命令本身，只显示执行结果
$(MAKEFILE_LIST)	当前 Makefile 文件路径

工具	作用	示例
uv	Python 包管理器	uv sync 安装依赖，uv run 运行命令
uvicorn	ASGI Web 服务器	uvicorn main:app --reload 启动带热重载的开发服务器
black .	代码格式化器	把单引号变双引号，统一行长度88字符
ruff	代码检查工具（Linter）	ruff check --fix . 自动修复代码风格问题
pre-commit	Git 钩子框架	pre-commit install 提交前自动运行格式化和检查

---

质量检查流程

第一道防线：Hooks 自动化

每次 Claude code 完成代码编写后，我配置的 Hook 会自动运行格式化：

{
  "hooks": {
    "stop": [
      {
        "type": "command",
        "command": "make format",
        "timeout": 60
      }
    ]
  }
}

这确保了代码风格的一致性，无需人工干预。对于不同的 IDE，有不同的 Hook 实现方式，需要读者自行探索，以 Cursor、Trae 为例，它们的替代实现方式如下：

Cursor:

1. 打开 Cursor 设置：点击左下角「设置」→「扩展设置」→ 搜索「Cursor: Custom Hooks」
2. 添加如下配置（直接复制替换）：

{
  "cursor.hooks.afterAiEdit": [
    {
      "type": "command",
      "command": "make format",
      "timeout": 60000, // 超时时间 60 秒（对应你配置的 60）
      "runInTerminal": false, // 静默运行，不弹出终端
      "blockUi": false // 不阻塞 UI，后台自动格式化
    }
  ]
}

Trae:

1. 在项目根目录创建 .trae/workflows.yaml 文件：

# Trae 工作流配置（核心是监听 AI 生成完成事件）
workflows:
  ai-code-format:
    triggers:
      - type: ai:generation:completed # AI 生成代码完成触发
        scope: workspace # 作用于整个工作区
    actions:
      - type: command # 执行格式化命令
        command: make format
        timeout: 60 # 超时时间 60 秒
        runInBackground: true # 后台静默运行
        onFailure:
          - type: notification # 格式化失败时弹窗提示
            message: "代码格式化失败，请手动运行 make format 修复"

2. 启用工作流：在 Trae 侧边栏「工作流」面板，勾选 ai-code-format 启用即可。

---

第二道防线：测试策略

关于 Mock，需要注意一点：Mock 通过不代表真实环境能跑——它往往掩盖真实的边界条件，单元测试全绿、上线即翻车的情况屡见不鲜。AI 编程尤其如此：讨好型AI会为了让测试通过而写 Mock 数据，就像为了提高通过率而让卷子出的简单一样。无法真正验证边界情况。

因此，Mock 应该仅用于必要场景：付费 API、时间逻辑、不稳定第三方服务。其余情况优先集成测试。

为了让 AI 遵循这套测试策略，可以在 CLAUDE.md 里要求：

## 测试规范
- 实现新功能时，先写测试，确认测试失败，再写实现代码
- 每次修改后运行 `make test` 确保没有破坏现有功能
- 不要为了让测试通过而修改测试本身
- 外部 API、时间相关逻辑使用 Mock，其他场景优先使用真实依赖

---

第三道防线：本地 AI Review

对于大的改动，可以在 AI IDE/CLI 内直接对新增的代码目录进行审查，比较通用的工具包括：

1. code-reviewer：Google出品的代码审查skill，实现较为简洁，通用。
2. /code-review：如果你正在使用claude code，那么官方给出的 /code-review 指令已经够用。
3. Spec Kit/OpenSpec 原生指令：对于spec规范开发的早期开源实践，Spec Kit/OpenSpec 分别提供了原生审查指令 /speckit.analyze+/speckit.checklist 、/openspec:review，无需额外配置。

何时使用？

• 必须：涉及架构改动、新功能、安全相关
• 推荐：重要的业务逻辑修改
• 可选：小的 bug 修复、简单的文案修改

此外，作为独立开发者，隔一段时间对整个模块做一次 Review 也是一种好习惯。

---

第四道防线：Pre-commit Hook

这是最关键的一环——如果检查不通过，代码根本无法提交。我的做法是用 pre-commit 框架配合 make check，配置如下：

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: make-check
        name: Run make check
        entry: make check
        language: system
        pass_filenames: false

所有检查逻辑都在 Makefile 里统一管理，pre-commit 只负责在提交时触发。

然后在 Makefile 里加一个 setup 命令：

setup: ## 初始化开发环境
	@uv sync
	@uv run pre-commit install

运行 make setup 后，每次 git commit 都会自动触发 make check。

如果是独立开发，这一步其实可以手动做。但我还是建议配置 setup 命令，这样换台电脑或者重新拉项目时，跑一下 make setup 就能恢复开发环境，不用记那么多步骤，或者重新配置一遍。

这些配置工作本身也可以让 AI 编程工具来做——告诉它"帮我配置 pre-commit，提交时运行 make check"，它会帮你生成配置文件并安装好。Cursor、Trae 等 IDE 的配置方法参考第一道防线。

---

第五道防线：GitHub 集成（可选）

Claude Code 与 Trae 提供了 GitHub 集成功能，可以在每次 Pull Request 时自动触发 AI 代码审查。

Claude Code

在 Claude Code 里运行 /install-github-app，按照提示完成授权流程就行。

安装完成后，你会发现项目里多了 .github/workflows 目录，里面包含了 Claude 的审查工作流配置。之后每次提交 PR，Claude 都会自动审查代码并在 PR 里留下评论。如果你想调整它的审查风格或关闭某些检查，直接在 PR 里评论即可。

Trae

第一步：启用 Trae GitHub 集成

1. 在 Trae 中打开项目 → 侧边栏「Integrations」→ 选择 GitHub → 完成授权；
2. 勾选「Auto-review Pull Requests」选项；

第二步：配置 AI 审查规则
在项目根目录创建 .trae/review.yaml 配置审查规则：

# Trae AI 代码审查配置
review:
  triggers:
    - pull_request: [opened, synchronize] # 触发时机
  rules:
    - name: 语法与风格检查
      check: [syntax, style, format]
      severity: error # 严重级别
    - name: 逻辑与性能检查
      check: [logic, performance, security]
      severity: warning
  prompt: |
    你是专业的代码审查工程师，针对 PR 代码差异，重点检查：
    1. 是否符合项目代码规范（参考 make check 规则）
    2. 是否存在安全漏洞（如 SQL 注入、未授权访问）
    3. 是否有性能瓶颈（如循环嵌套过深、未优化查询）
    4. 给出可直接落地的修复建议，而非泛泛而谈
  output:
    format: markdown # 输出格式
    post_to_pr: true # 自动发布到 PR 评论
    notify_via: [github_comment, trae_alert] # 通知方式