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 生成的代码在格式上和团队已有的代码库保持一致。具体要做什么识别并提取现有规范你的项目里肯定有.eslintrc.js、.prettierrc、tsconfig.json、.editorconfig这些配置文件。第一步就是把这些配置规则整理出来让 AI 知道“标准”是什么。将规范转化为 AI 可理解的指令你不能直接把配置文件扔给 AI。你需要用自然语言总结关键规则。例如“我们项目使用 ESLint Prettier。关键规则使用 2 个空格缩进字符串使用单引号行尾不加分号React 组件使用函数式声明并默认导出接口命名以I开头。”在 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 生成的代码符合项目的整体架构和设计模式。具体要做什么定义架构边界明确项目是 MVC、MVVM、分层架构Controller-Service-Repository、还是模块化架构。告诉 AI 各层的职责。例如“我们采用前后端分离前端是 React Zustand 状态管理API 调用统一放在src/services目录下。”约定设计模式与最佳实践比如“状态管理使用 Zustand每个 Store 放在src/stores下”“数据获取使用 TanStack Query查询逻辑放在自定义 hook 中”“错误处理使用 try-catch 包裹并调用统一的错误通知函数showErrorToast”。提供参考范例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): PromiseUserProfile { 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 在生成代码时能嵌入正确的业务逻辑和领域规则。具体要做什么提炼业务规则将产品需求、用户故事中的业务规则提炼成清晰、无歧义的表述。例如“用户下单后如果库存不足订单状态应标记为‘待备货’并通知仓储系统而不是直接失败。”定义领域模型与状态流转用文字或简单的图表描述核心领域对象如 Order, Product, User及其关键属性和状态机。例如“Order 对象的状态流转pending-paid-shipped-delivered。只有paid状态的订单才能发货。”将业务规则作为生成逻辑代码的约束条件在 Prompt 中业务规则是生成“正确”代码的必须条件。例如【业务规则】 1. 优惠券计算规则全场通用券可与其他优惠叠加但商品专属券不能叠加。 2. 运费规则订单满 99 元包邮否则收取 10 元运费。 3. 库存校验下单时立即锁定库存支付失败后 15 分钟释放。 【任务】 根据以上规则编写一个 calculateOrderTotal 函数接收订单商品列表和优惠券信息返回最终支付金额。实测要点规则必须明确且无冲突模糊的业务规则会导致 AI 生成不确定的代码。在让 AI 动手前先和产品经理或业务方确认规则。可以分步进行复杂的业务逻辑可以让 AI 先生成伪代码或逻辑步骤确认无误后再生成具体实现代码。结合测试用例一种高级用法是将业务规则转化为测试用例的描述然后让 AI 同时生成实现代码和对应的单元测试。这能极大提升代码的可靠性。3. 从理论到实操搭建你的规范驱动工作流理解了层次下一步就是把它变成可重复的工作流。这里没有银弹工具但有一套可以组合使用的“工具箱”。3.1 工具链选型与配置你需要三类工具配合AI 编码助手如 Cursor、GitHub Copilot、Windsurf、Codeium或直接使用 ChatGPT/Claude 的 IDE 插件。它们是代码生成的“执行引擎”。规范管理与注入工具IDE 配置确保项目的.editorconfig、ESLint、Prettier 配置在 IDE 中生效并自动格式化。这样即使 AI 生成略有偏差保存时也能自动纠正。自定义 Prompt 模板/片段使用 Cursor 的.cursorrules文件或 Copilot 的自定义指令功能将团队规范写成模板。也可以使用文本扩展工具如 Espanso快速插入规范指令片段。向量知识库对于大型、复杂的规范文档如架构设计文档、API 规范可以将其切片并存入向量数据库如 Chroma、Pinecone。在编写相关代码时让 AI 助手自动检索并引用这些规范。验证与集成工具Git Hooks在pre-commit钩子中运行 ESLint、Prettier 和类型检查确保 AI 生成的代码在提交前符合规范。CI/CD 流水线在 PR 检查中运行更严格的静态分析、安全扫描和自动化测试确保规范在团队协作层面被强制执行。3.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并包含必要的错误处理。步骤三生成与初步审查将 Prompt 发送给 AI 编码助手生成代码。不要直接接受全部代码。重点审查架构符合度生成的 Service 文件位置、引入依赖的方式是否正确业务逻辑积分计算、接口调用顺序、错误处理是否符合业务规则边界情况积分不足、商品下架等情况是否处理步骤四本地验证与格式化将生成的代码放入项目。运行npm run lint和npm run type-check进行检查。使用 IDE 的自动格式化功能保存时自动运行 Prettier。尝试运行相关的单元测试如果有的话或手动模拟调用一下新 Service 的方法。步骤五提交与 CI 验证提交代码。Git 的pre-commit钩子会自动进行基础检查。创建 Pull Request。CI 流水线会运行更全面的测试和扫描。如果 CI 失败根据报错信息是格式问题、类型问题还是测试失败定位原因是规范指令不清晰还是 AI 理解有误修正后重新生成或修改。3.3 关键参数与配置示例.cursorrules文件示例 (Cursor IDE)# 项目通用规范 - 语言TypeScript 5.x with Strict Mode - 样式遵循项目内 .prettierrc 配置 - 组件使用 React 函数组件 React.FC默认导出 - 状态管理使用 Zustandstore 文件置于 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 生成的代码风格依然不一致排查顺序检查规范指令是否具体“遵循 Prettier” 太模糊。要给出具体规则如“缩进 2 空格”、“单引号”、“行宽 100”。检查 IDE 自动格式化是否开启生成代码后保存文件看 Prettier/ESLint 是否自动修正。如果没有先确保你的 IDE 插件已正确安装并指向项目配置。检查上下文长度如果你的规范指令非常长可能超出了 AI 模型的上下文窗口后面的指令被截断了。尝试精简指令只保留最核心的规则。分而治之不要试图用一个 Prompt 解决所有规范。将“代码风格”和“业务逻辑”分开。先让 AI 用任何风格写出逻辑正确的代码然后再用一个专门的 Prompt 让其重构以符合代码风格。4.2 问题AI 不理解项目特定的架构或设计模式排查顺序提供“范例”而非“描述”与其说“我们使用仓库模式”不如直接给一个UserRepository.ts的完整代码示例。Few-Shot 学习的效果远好于 Zero-Shot。检查范例的准确性你提供的范例代码本身是否符合最佳实践如果范例有瑕疵AI 会完美复现这些瑕疵。在 Prompt 中明确“不要做什么”有时 AI 会过度联想。如果你不希望它使用某个库或某种写法明确指出来。例如“请不要使用 Redux请使用 Zustand。”“请不要使用any类型。”利用项目现有代码作为上下文像 Cursor 的 “” 引用功能或 Copilot 的 “/docs” 指令可以直接引用项目中的现有文件作为范例。在 Prompt 里写“请参考src/services/authService.ts的写法”。4.3 问题业务逻辑复杂AI 生成的代码有漏洞排查顺序分解任务不要让它一次性生成整个复杂流程。将任务分解为多个子步骤并分步生成和审查。例如先生成“计算积分折扣”的函数验证无误后再生成“创建订单”的函数。要求 AI 先输出逻辑步骤或伪代码在 Prompt 中要求“在生成具体代码前请先列出实现这个功能的关键步骤和需要处理的边界条件。” 审查其逻辑步骤比直接审查代码更容易发现业务理解偏差。结合测试驱动开发TDD先让 AI 根据业务规则生成单元测试用例然后再生成实现代码来通过这些测试。这能强制 AI 思考各种边界情况。人工审查必不可少对于核心业务逻辑AI 目前仍是辅助。开发者必须对生成的代码进行严格的逻辑审查特别是涉及资金、安全、核心流程的部分。4.4 问题团队协作时每个人的 Prompt 和生成结果差异大排查顺序建立团队共享的规范库这是最关键的一步。使用一个共享文档如 Notion、Confluence或项目内的DEVELOPMENT_GUIDE.md文件统一存放所有层次的规范指令和最佳范例。标准化 Prompt 模板为常见的开发任务如“创建新 API Service”、“创建新 React 组件”创建标准的 Prompt 模板并放在团队共享规范库中。在 Code Review 中审查“规范性”在 PR Review 时不仅审查代码逻辑也要审查其是否符合团队既定规范。将常见的规范违反点总结成 Checklist。定期同步与优化定期如每两周讨论在 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但一旦跑通带来的团队效能提升和代码质量保障是显而易见的。我的建议是从一个小的、风格层的规范开始实践跑通整个“定义-注入-生成-验证”的循环再逐步向架构层和业务层扩展。