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

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

以上数据反映出一个核心原则：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。它解决了以下几个痛点：

如何创建 Makefile

touch Makefile

.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

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

# 项目开发指南

## 常用命令
---

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

## 项目结构
---
...

关键语法、工具解释

质量检查流程

第一道防线：Hooks 自动化

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

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

这确保了代码风格的一致性，无需人工干预。对于不同的 IDE，有不同的 Hook 实现方式：

{
  "cursor.hooks.afterAiEdit": [
    {
      "type": "command",
      "command": "make format",
      "timeout": 60000,
      "runInTerminal": false,
      "blockUi": false
    }
  ]
}

workflows:
  ai-code-format:
    triggers:

      - type: ai:generation:completed
        scope: workspace
    actions:

      - type: command
        command: make format
        timeout: 60
        runInBackground: true
        onFailure:

          - type: notification
            message: "代码格式化失败，请手动运行 make format 修复"

第二道防线：测试策略

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。

这些配置工作本身也可以让 AI 编程工具来做——告诉它"帮我配置 pre-commit，提交时运行 make check"，它会帮你生成配置文件并安装好。

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

Claude Code 与 Trae 提供了 GitHub 集成功能，可以在每次 Pull Request 时自动触发 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
    notify_via: [github_comment, trae_alert]

写在最后

AI 编程工具让代码编写速度大幅提升，但代码质量不会自动随之而来。质量保障是一道需要主动设置的防线，而非被动等待的结果。

让我总结一下本文的要点：

1. 按功能组织代码：让 AI 更容易理解模块上下文，减少跨目录跳转的混乱。
2. 统一命令入口：用 Makefile 封装常用操作，降低与 AI 的沟通成本。
3. 自动化格式化：通过 Hooks 在代码生成后自动运行，保持风格一致。
4. 测试策略要务实：Mock 仅用于必要场景，优先集成测试验证真实边界。
5. 本地 AI Review：大改动前让 AI 审查代码，发现潜在问题。
6. Pre-commit 拦截：提交前强制检查，守住最后一道防线。

写得快是能力，写得对是智慧。

质量检查可能会让单次迭代变慢，但它能避免你在深夜调试一个本不该出现的 Bug。把时间投资在正确的地方，这才是 Vibe Coding 的精髓。