规范驱动开发：从Vibe-Coding到AI工程化的实践指南

1. 先搞清楚“规范驱动开发”到底在解决什么问题

如果你正在用大模型生成代码，或者团队里有人开始用 AI 辅助编程，大概率会遇到这几个问题：生成的代码风格五花八门，每次都要手动调整；项目结构、命名规则、注释格式，AI 好像“听不懂”；今天调好的 prompt，明天换个模型或者换个场景，效果又不一样了。这些问题，本质上不是 AI 能力不行，而是我们缺少一套能让 AI 稳定、高效、符合团队要求地工作的“工程化方法”。

“规范驱动开发”就是冲着这个痛点来的。它不是一个新工具，而是一种思路：把开发规范（代码风格、架构约束、安全规则等）变成机器可读、可执行的指令，让 AI 在生成代码、审查代码、重构代码时，能自动遵循这些规范。这样做的直接好处是，AI 的输出从一开始就更接近“可交付”状态，减少了大量人工对齐和修改的成本。

这里的关键词是“驱动”。它不是事后用 Lint 工具去检查，而是把规范作为“输入条件”或“上下文”，前置到 AI 的工作流里。比如，你告诉 AI：“请按照我们项目的 ESLint 配置和 React 函数组件规范，生成一个用户登录表单。” AI 生成的代码就应该直接符合这些要求。

从“Vibe-Coding”走向“AI 工程化”，可以理解为从“感觉对了就行”的随意使用，到“有流程、有标准、可重复”的系统化应用。Vibe-Coding 更偏向于个人、临时的、基于直觉的 AI 编码互动，而 AI 工程化则强调团队协作、流程集成和质量可控。规范驱动，就是实现这种转变的核心杠杆。

所以，这篇文章适合所有已经开始用 AI 写代码，但觉得效率瓶颈越来越明显，或者团队协作起来很乱的开发者、技术负责人。最值得关注的不是某个具体工具，而是如何设计这套“规范即指令”的流程，并把它落地到日常开发中。

2. 拆解“规范驱动”的三个核心层次：从个人到团队

规范驱动开发不是一蹴而就的，我建议分三个层次来理解和落地，从易到难，从个人到团队。

2.1 第一层：代码风格与静态检查规范

这是最基础、也最容易入手的一层。目标很简单：让 AI 生成的代码，在格式上和团队已有的代码库保持一致。

具体要做什么？

1. 识别并提取现有规范：你的项目里肯定有.eslintrc.js、.prettierrc、tsconfig.json、.editorconfig这些配置文件。第一步就是把这些配置规则整理出来，让 AI 知道“标准”是什么。
2. 将规范转化为 AI 可理解的指令：你不能直接把配置文件扔给 AI。你需要用自然语言总结关键规则。例如：

   “我们项目使用 ESLint + Prettier。关键规则：使用 2 个空格缩进；字符串使用单引号；行尾不加分号；React 组件使用函数式声明并默认导出；接口命名以I开头。”

3. 在 Prompt 中嵌入规范指令：在每次让 AI 生成代码的提示词（Prompt）里，把这些规范指令作为固定前缀或系统指令。例如，你的 Prompt 模板可以是：

   【代码规范】 1. 语言：TypeScript，严格模式。 2. 风格：遵循项目 .eslintrc 和 .prettierrc 配置（已附关键规则）。 3. 组件：使用 React 函数组件，配合 `React.FC` 类型。 4. 命名：组件名帕斯卡命名，变量名驼峰命名，常量全大写。 5. 导出：默认导出组件。 【任务】 请生成一个用户个人资料卡片组件，包含头像、姓名、邮箱和编辑按钮。

实测要点：

• 不要一次性给所有规则：AI 的上下文窗口有限。优先传递最影响可读性和合并冲突的规则（如缩进、引号、分号）。
• 先验证单条规则：可以先测试“请用双引号”或“请用 4 个空格缩进”这种简单规则，看 AI 是否遵从。
• 使用“系统提示词（System Prompt）”：如果你用的是 ChatGPT API、Claude API 或 IDE 插件，通常有设置系统提示词的地方。把固定的规范指令放在这里，比每次在用户提示词里写更高效。

2.2 第二层：架构与设计模式规范

这一层更难，但也更有价值。它关乎代码的结构而不仅仅是格式。目标是让 AI 生成的代码，符合项目的整体架构和设计模式。

具体要做什么？

1. 定义架构边界：明确项目是 MVC、MVVM、分层架构（Controller-Service-Repository）、还是模块化架构。告诉 AI 各层的职责。例如：“我们采用前后端分离，前端是 React + Zustand 状态管理，API 调用统一放在src/services目录下。”

2. 约定设计模式与最佳实践：比如，“状态管理使用 Zustand，每个 Store 放在src/stores下”；“数据获取使用 TanStack Query，查询逻辑放在自定义 hook 中”；“错误处理使用 try-catch 包裹，并调用统一的错误通知函数showErrorToast”。

3. 提供参考范例（Few-Shot Learning）：这是最有效的方法。在 Prompt 中给出一两个符合架构规范的代码片段作为例子。AI 的模仿能力很强。例如：

   【架构范例】 这是我们一个标准的 API Service 文件 (`src/services/userService.ts`)： ```typescript import apiClient from ‘../utils/apiClient’; import type { UserProfile } from ‘../types/user’; export const userService = { async getProfile(userId: string): Promise<UserProfile> { try { const response = await apiClient.get(`/users/${userId}`); return response.data; } catch (error) { console.error(‘Failed to fetch user profile:’, error); throw new Error(‘获取用户信息失败’); } }, // ... 其他方法 };

   【任务】 请参照上述范例，创建一个productService.ts，包含getProductList和getProductById方法。

实测要点：

• 范例贵精不贵多：1-2 个典型、清晰的范例，比一段冗长的文字描述更管用。
• 结合目录结构说明：在 Prompt 里说明文件应该放在哪个目录（如src/components/ui/），AI 有时甚至能在回复中给出正确的相对路径引用建议。
• 关注依赖注入和模块关系：如果项目有明确的依赖管理规范（如使用特定 DI 容器），需要在 Prompt 中说明如何引入其他模块。

2.3 第三层：业务流程与领域规则规范

这是最高层，也是最需要领域知识的一层。目标是让 AI 在生成代码时，能嵌入正确的业务逻辑和领域规则。

具体要做什么？

1. 提炼业务规则：将产品需求、用户故事中的业务规则提炼成清晰、无歧义的表述。例如：“用户下单后，如果库存不足，订单状态应标记为‘待备货’，并通知仓储系统，而不是直接失败。”
2. 定义领域模型与状态流转：用文字或简单的图表描述核心领域对象（如 Order, Product, User）及其关键属性和状态机。例如：“Order 对象的状态流转：pending->paid->shipped->delivered。只有paid状态的订单才能发货。”
3. 将业务规则作为生成逻辑代码的约束条件：在 Prompt 中，业务规则是生成“正确”代码的必须条件。例如：

   【业务规则】 1. 优惠券计算规则：全场通用券可与其他优惠叠加，但商品专属券不能叠加。 2. 运费规则：订单满 99 元包邮，否则收取 10 元运费。 3. 库存校验：下单时立即锁定库存，支付失败后 15 分钟释放。 【任务】 根据以上规则，编写一个 `calculateOrderTotal` 函数，接收订单商品列表和优惠券信息，返回最终支付金额。

实测要点：

• 规则必须明确且无冲突：模糊的业务规则会导致 AI 生成不确定的代码。在让 AI 动手前，先和产品经理或业务方确认规则。
• 可以分步进行：复杂的业务逻辑，可以让 AI 先生成伪代码或逻辑步骤，确认无误后再生成具体实现代码。
• 结合测试用例：一种高级用法是，将业务规则转化为测试用例的描述，然后让 AI 同时生成实现代码和对应的单元测试。这能极大提升代码的可靠性。

3. 从理论到实操：搭建你的规范驱动工作流

理解了层次，下一步就是把它变成可重复的工作流。这里没有银弹工具，但有一套可以组合使用的“工具箱”。

3.1 工具链选型与配置

你需要三类工具配合：

1. AI 编码助手：如 Cursor、GitHub Copilot、Windsurf、Codeium，或直接使用 ChatGPT/Claude 的 IDE 插件。它们是代码生成的“执行引擎”。
2. 规范管理与注入工具：
   • IDE 配置：确保项目的.editorconfig、ESLint、Prettier 配置在 IDE 中生效并自动格式化。这样即使 AI 生成略有偏差，保存时也能自动纠正。
   • 自定义 Prompt 模板/片段：使用 Cursor 的.cursorrules文件，或 Copilot 的自定义指令功能，将团队规范写成模板。也可以使用文本扩展工具（如 Espanso）快速插入规范指令片段。
   • 向量知识库：对于大型、复杂的规范文档（如架构设计文档、API 规范），可以将其切片并存入向量数据库（如 Chroma、Pinecone）。在编写相关代码时，让 AI 助手自动检索并引用这些规范。
3. 验证与集成工具：
   • Git Hooks：在pre-commit钩子中运行 ESLint、Prettier 和类型检查，确保 AI 生成的代码在提交前符合规范。
   • CI/CD 流水线：在 PR 检查中运行更严格的静态分析、安全扫描和自动化测试，确保规范在团队协作层面被强制执行。

3.2 实操步骤：以一个新功能开发为例

假设你要开发一个“用户积分兑换商品”的新功能。

步骤一：准备规范上下文

1. 打开你的“规范指令”文档或模板。
2. 根据功能所属模块，组合相关规范：
   • 风格层：插入基础代码风格指令。
   • 架构层：插入“服务层位于src/services，调用方式参考userService范例”的指令。
   • 业务层：插入“积分规则：100积分抵1元，兑换后积分不减反增的日志需告警”等业务规则。

步骤二：构造生成 Prompt将规范上下文与具体任务结合：

【项目规范】（此处粘贴组合好的规范指令） 【具体任务】 在 `src/services` 目录下创建 `pointService.ts`，实现以下方法： 1. `getExchangeableProducts()`: 获取可兑换商品列表。 2. `exchangeProduct(productId: string, points: number)`: 执行积分兑换。 - 需调用现有的 `userApi.deductPoints` 接口扣减积分。 - 需调用 `orderApi.createExchangeOrder` 接口创建兑换订单。 - 需记录兑换日志到 `exchangeLog` 表。 - 业务规则见上。 请使用 TypeScript，并包含必要的错误处理。

步骤三：生成与初步审查

1. 将 Prompt 发送给 AI 编码助手生成代码。
2. 不要直接接受全部代码。重点审查：
   • 架构符合度：生成的 Service 文件位置、引入依赖的方式是否正确？
   • 业务逻辑：积分计算、接口调用顺序、错误处理是否符合业务规则？
   • 边界情况：积分不足、商品下架等情况是否处理？

步骤四：本地验证与格式化

1. 将生成的代码放入项目。
2. 运行npm run lint和npm run type-check进行检查。
3. 使用 IDE 的自动格式化功能（保存时自动运行 Prettier）。
4. 尝试运行相关的单元测试（如果有的话），或手动模拟调用一下新 Service 的方法。

步骤五：提交与 CI 验证

1. 提交代码。Git 的pre-commit钩子会自动进行基础检查。
2. 创建 Pull Request。CI 流水线会运行更全面的测试和扫描。
3. 如果 CI 失败，根据报错信息（是格式问题、类型问题还是测试失败）定位原因，是规范指令不清晰？还是 AI 理解有误？修正后重新生成或修改。

3.3 关键参数与配置示例

• .cursorrules文件示例 (Cursor IDE)：

  # 项目通用规范 - 语言：TypeScript 5.x with Strict Mode - 样式：遵循项目内 .prettierrc 配置 - 组件：使用 React 函数组件 + `React.FC`，默认导出 - 状态管理：使用 Zustand，store 文件置于 `src/stores/` - API 调用：使用 `src/utils/apiClient` 的 axios 实例，错误处理使用 try-catch 并向上抛出 - 命名：接口 `I` 前缀，类型 `T` 前缀，组件帕斯卡命名，变量/函数驼峰命名 # 目录结构提示 - `src/components/ui/`: 通用 UI 组件 - `src/components/features/`: 业务功能组件 - `src/services/`: API 服务层 - `src/stores/`: 状态管理 - `src/utils/`: 工具函数

  将这个文件放在项目根目录，Cursor 在生成代码时会自动参考这些规则。

• GitHub Copilot 自定义指令示例： 在 Copilot 设置中，你可以设置全局或工作区指令。例如：

  你是一个经验丰富的 TypeScript/React 开发者，正在开发一个电商后台管理系统。 请始终遵循以下规则： 1. 使用 TypeScript 严格模式，定义明确的接口。 2. 使用 async/await 处理异步，配合 try-catch 进行错误处理，错误需用 `console.error` 记录并抛出。 3. 组件使用函数式组件，优先使用 `React.FC` 类型。 4. API 调用请使用项目中已定义的 `apiClient` (从 `src/lib/api-client` 导入)。 5. 如果需要创建新的工具函数，请放在 `src/utils/` 目录下。 请先思考实现步骤，再生成代码。

4. 常见问题与精准排查指南

刚开始实践规范驱动开发，肯定会遇到各种问题。别急着怀疑 AI 的能力，大部分问题出在规范和沟通上。

4.1 问题：AI 生成的代码风格依然不一致

排查顺序：

1. 检查规范指令是否具体：“遵循 Prettier” 太模糊。要给出具体规则，如“缩进 2 空格”、“单引号”、“行宽 100”。
2. 检查 IDE 自动格式化是否开启：生成代码后，保存文件，看 Prettier/ESLint 是否自动修正。如果没有，先确保你的 IDE 插件已正确安装并指向项目配置。
3. 检查上下文长度：如果你的规范指令非常长，可能超出了 AI 模型的上下文窗口，后面的指令被截断了。尝试精简指令，只保留最核心的规则。
4. 分而治之：不要试图用一个 Prompt 解决所有规范。将“代码风格”和“业务逻辑”分开。先让 AI 用任何风格写出逻辑正确的代码，然后再用一个专门的 Prompt 让其重构以符合代码风格。

4.2 问题：AI 不理解项目特定的架构或设计模式

排查顺序：

1. 提供“范例”而非“描述”：与其说“我们使用仓库模式”，不如直接给一个UserRepository.ts的完整代码示例。Few-Shot 学习的效果远好于 Zero-Shot。
2. 检查范例的准确性：你提供的范例代码本身是否符合最佳实践？如果范例有瑕疵，AI 会完美复现这些瑕疵。
3. 在 Prompt 中明确“不要做什么”：有时 AI 会过度联想。如果你不希望它使用某个库或某种写法，明确指出来。例如：“请不要使用 Redux，请使用 Zustand。”，“请不要使用any类型。”
4. 利用项目现有代码作为上下文：像 Cursor 的 “@” 引用功能，或 Copilot 的 “/docs” 指令，可以直接引用项目中的现有文件作为范例。在 Prompt 里写“请参考src/services/authService.ts的写法”。

4.3 问题：业务逻辑复杂，AI 生成的代码有漏洞

排查顺序：

1. 分解任务：不要让它一次性生成整个复杂流程。将任务分解为多个子步骤，并分步生成和审查。例如，先生成“计算积分折扣”的函数，验证无误后，再生成“创建订单”的函数。
2. 要求 AI 先输出逻辑步骤或伪代码：在 Prompt 中要求：“在生成具体代码前，请先列出实现这个功能的关键步骤和需要处理的边界条件。” 审查其逻辑步骤，比直接审查代码更容易发现业务理解偏差。
3. 结合测试驱动开发（TDD）：先让 AI 根据业务规则生成单元测试用例，然后再生成实现代码来通过这些测试。这能强制 AI 思考各种边界情况。
4. 人工审查必不可少：对于核心业务逻辑，AI 目前仍是辅助。开发者必须对生成的代码进行严格的逻辑审查，特别是涉及资金、安全、核心流程的部分。

4.4 问题：团队协作时，每个人的 Prompt 和生成结果差异大

排查顺序：

1. 建立团队共享的规范库：这是最关键的一步。使用一个共享文档（如 Notion、Confluence）或项目内的DEVELOPMENT_GUIDE.md文件，统一存放所有层次的规范指令和最佳范例。
2. 标准化 Prompt 模板：为常见的开发任务（如“创建新 API Service”、“创建新 React 组件”）创建标准的 Prompt 模板，并放在团队共享规范库中。
3. 在 Code Review 中审查“规范性”：在 PR Review 时，不仅审查代码逻辑，也要审查其是否符合团队既定规范。将常见的规范违反点总结成 Checklist。
4. 定期同步与优化：定期（如每两周）讨论在 AI 协作中遇到的新问题，更新和优化规范指令与 Prompt 模板。这是一个持续迭代的过程。

5. 边界与进阶思考：什么能做，什么不能做

规范驱动开发能大幅提升效率，但它不是万能药。清楚它的边界，才能更好地使用它。

能做的（当前比较成熟的）：

• 大幅减少样板代码编写：CRUD 接口、表单组件、简单的服务层代码，生成质量和速度很高。
• 统一代码风格和基础模式：只要规范清晰，AI 能很好地保持一致性。
• 快速生成测试用例和文档骨架：根据实现代码生成对应的单元测试、接口文档注释，非常高效。
• 辅助代码重构和解释：将老代码扔给 AI，让其按照新规范重构，或解释复杂代码段。
• 加速新人上手：新成员通过规范指令和范例，能快速理解项目架构并产出符合要求的代码。

不能做或要慎做的（当前局限性）：

• 替代复杂的系统架构设计：AI 无法理解宏观的业务架构和技术选型背后的深层权衡。架构设计仍需资深工程师主导。
• 生成完全正确无误的核心业务逻辑：涉及复杂状态流转、分布式事务、严密安全规则的逻辑，必须经过严格的人工设计和审查。
• 理解模糊或矛盾的需求：“做一个用户喜欢的页面”这种需求，AI 无从下手。必须将需求转化为清晰、可执行的技术任务描述。
• 处理未知或高度创新的问题：对于没有先例、需要创造性解决方案的问题，AI 基于现有模式生成的结果可能不是最优解。

进阶思考：从“驱动”到“融合”规范驱动开发的高级阶段，是让规范本身成为项目“活文档”的一部分。我们可以探索：

• 规范即代码（Specification as Code）：用结构化的方式（如 OpenAPI Spec 描述 API， PlantUML 描述架构）定义规范，并让 AI 直接读取这些结构化规范来生成代码。
• 自动化规范验证与修复：在 CI/CD 流水线中，不仅检查代码风格，还能用 AI 分析生成的代码是否违反了架构约束或业务规则，并尝试自动修复。
• 规范的自演进：通过分析大量成功的代码提交和 Review 意见，让 AI 辅助发现和总结出新的、更优的团队最佳实践，反过来更新规范库。

从 Vibe-Coding 到 AI 工程化，核心区别就在于是否建立了可重复、可验证、可协作的流程。规范驱动开发是这个流程的基石。它开始可能会觉得有点繁琐，需要花时间整理规范和设计 Prompt，但一旦跑通，带来的团队效能提升和代码质量保障是显而易见的。我的建议是，从一个小的、风格层的规范开始实践，跑通整个“定义-注入-生成-验证”的循环，再逐步向架构层和业务层扩展。