最近总有人问我为什么我的提示词已经写得很详细让 AI 把“每一步都讲清楚”生成出来的代码还是到处都是小问题要么目录结构混乱要么函数职责不清要么上线后才发现缺少异常处理其实问题往往不在提示词本身而在项目缺少一套能约束 AI 行为的工程规范。Vibe Coding 听起来像是在“跟着感觉写代码”但它真正的核心不是把提示词写得越来越长而是把工程约束前置到 AI 生成链路里。本文我会从概念、分工、实战到工程建议完整拆解为什么“提示词 工程规范”才是 AI 辅助开发的最优解。1. 背景与核心概念1.1 Vibe Coding 到底是什么Vibe Coding 这个词最早在 AI 编程圈流行起来它描述的场景是开发者不再逐行手写代码而是通过自然语言描述需求让大模型生成大部分实现人主要负责理解、校验和调整方向。很多人把它理解成“随便说说就能生成代码”。但更准确的理解是Vibe Coding 是一种人机协作的编程模式目标是让开发者把注意力从语法细节中解放出来放在需求拆解、整体设计和质量把控上。举个例子传统开发中实现一个接口可能需要写 Controller、Service、Mapper、DTO 等一堆文件。Vibe Coding 模式下你只需要告诉模型“按项目现有分层结构新增一个用户查询接口返回脱敏后的用户信息”模型会基于项目上下文生成对应代码你再去 review、调整和补充测试。但是这里有一个非常关键的隐含前提模型必须能“理解”项目的分层结构、命名习惯、异常处理约定。如果你的项目里没有任何规范文件AI 就只能靠猜。猜得多了代码风格就会漂移时间一长项目就会变成难以维护的“AI 代码混合体”。1.2 为什么提示词解决不了全部问题提示词工程当然有作用它可以提高单次生成的准确性。比如你给 AI 一段高质量的提示词模板要求它“使用 Python 3.11、遵循 Pydantic 模型校验、所有对外接口返回统一响应结构”生成结果会比裸提问好很多。但提示词的问题在于它是一次性的、上下文有关联的、且容易被后续对话“忘掉”。你在第一条消息里告诉 AI 要遵守规范生成第二个模块时如果上下文窗口不够大它可能又把之前的约定丢了。更关键的是提示词只约束“这次回答”不约束“这个仓库的所有代码”。团队里其他人如果也使用 AI 编程提示词各不相同最终就会产生四种不同的命名风格、三层不同的异常处理策略。所以说提示词是“点状”约束工程规范才是“面状”约束。项目越复杂、参与的人越多越不能依赖把规范塞进提示词里这种“人肉传播”的方式。1.3 工程规范才是稳定器工程规范是什么它不只是一份文档而是一套可以被工具执行的约定。常见的形式包括代码风格配置ESLint、Ruff、Black、Prettier 等。项目结构约定layered architecture、feature structure 等。提交与分支规范Conventional Commits、Git Flow。质量门禁CI 里的单元测试、静态检查、覆盖率阈值。代码评审要求MR/PR 必须有描述、必须通过测试、必须有人 review。AI 辅助开发规则允许 AI 改哪些目录、禁止生成哪些不安全模式。这些规范存在于项目仓库中能被 AI 读取也能被 CI 强制执行还能作为代码评审的检查清单。它们不会因为某个人的提示词写得不好而失效这就是“稳定器”的意义。2. 环境准备与协作基础2.1 工具链与角色分工想要真正落地“Vibe Coding 工程规范”不需要一步到位引入很重的平台最先要明确的是人与工具的分工。我比较推荐的最小工具链是代码仓库Git 是底线AI 生成的内容也要走完整的版本管理。AI 编程助手可以是 IDE 插件也可以是独立 CLI关键是能读取当前仓库内容。规范文件放在仓库根目录里例如AGENTS.md或CLAUDE.mdAI 助手会自动读取。统一的 lint 与格式化工具确保 AI 生成代码经过工具归一化。CI 或本地钩子在合并之前做质量拦截。这套组合的核心思想是AI 负责生成工具负责校验人负责决策。2.2 仓库结构与分支策略工程规范的第一步是让 AI 知道你的仓库长什么样。很多项目把规范分散在不同目录里AI 很难快速理解。建议在仓库根目录放一个简洁的说明文件写清楚技术栈版本。目录结构。命名规范。如何运行测试。如何新增一个业务模块。禁止事项。这样 AI 第一次读取仓库时就能形成“全局观”而不是只盯着单个文件“头痛医头”。分支策略上无论团队用什么流程至少要保证一条原则AI 生成的改动不要直接推到主干必须经过 Pull Request 和代码评审。这不是不信任 AI而是给“工程规范”一个生效的时机。2.3 让 AI 参与的最小闭环如果你之前没有在项目里用过 AI 编程建议先搭一个最小闭环你写需求描述。AI 读取规范和上下文后生成代码。本地运行 lint 和测试。你 review 差异发现问题后让 AI 修正。通过后提交 PR进入评审。第一步到第二步之间其实存在一个容易忽略的环节把需求描述翻译成“符合项目规范的任务”。你可以在项目里维护一个任务模板让每次 AI 生成都能对齐同一个基线。3. 提示词与工程规范的分工3.1 提示词的作用边界提示词在 Vibe Coding 里的作用应该被限定在“描述任务”和“表达意图”而不是承担“维护项目一致性”的职责。举个例子一个相对合理的提示词是请按本仓库 AGENTS.md 的规范新增一个用户注册接口。 要求 1. 使用现有 Service 层命名风格。 2. 参数校验放在 Controller 层。 3. 返回统一响应结构 ResultT。 4. 补充单元测试覆盖成功与失败分支。 5. 先不要改数据库表结构。这个提示词里前两行是“任务描述”后面几条是“边界约束”。它不需要把整个项目的编码规范写进去因为规范已经放在仓库文件里模型能自己读取。相反一个试图把所有规范都塞进提示词的做法是你现在是资深工程师请严格按我下面的规范开发函数命名要动词开头Controller 要返回 ResultT异常要捕获 BizException所有类要加注释……这种提示词最大的问题是不可复用。每次生成前你都要重新输入一遍只要少写一条AI 就可能跑偏。3.2 把规范变成可执行文件代码里最可靠的东西是可执行文件。工程规范也应该尽量“可执行化”。第一层是给 AI 读的规范文件比如AGENTS.md。第二层是给工具读的配置比如eslint.config.js、pyproject.toml、.pre-commit-config.yaml。第三层是给 CI 读的流水线配置。这三层规范是层层递进的关系AI 辅助你“生成符合规范的代码”lint 工具“检查代码是否符合规范”CI 和评审“决定是否符合合入标准”。我以前见过一个团队花了很大精力写团队规范文档结果没有接入任何工具。AI 生成的代码照样通过了合并因为 nobody 真正去执行文档里的要求。后来他们把关键规范做成 lint rules问题立刻少了一半。这就是“可执行”的价值。3.3 从 Vibe Coding 到 Spec-Driven现在不少团队开始讨论 Vibe Coding 和 Spec-Driven Development 的区别。简单来说Vibe Coding 更看重“快速生成、快速验证”适合原型探索和单模块开发而 Spec-Driven 强调先把接口、数据结构、行为边界定义清楚再让 AI 基于规格落实现代码适合多人协作和长期维护的项目。这两者并不是对立关系。更健康的做法是“先用 Vibe Coding 快速验证方案可行性再用 Spec-Driven 固化关键模块的契约”。你在提示词里写得再欢如果没有规格文档和契约测试后续改造时 AI 依然不知道改一处会破坏哪里。工程规范就是帮你把“临时灵感”沉淀为“长期资产”的中间层。4. 完整实战从一条提示词到一套规范4.1 业务场景与需求下面我们模拟一个完整的例子。假设项目是一个 FastAPI 风格的 Python 后端服务现在需要新增一个“查询用户详情”的接口要求不能返回手机号等敏感字段需要做登录鉴权。为了演示规范的作用我会故意分成“只有提示词”和“有工程规范”两种情况来对比。4.2 先写提示词示例与问题先看一种常见写法给项目加一个用户查询接口路径是 /api/v1/users/{user_id}返回用户信息不要返回手机号和密码需要登录才能访问。如果项目里没有任何规范AI 可能会把接口直接放在main.py里不区分 Controller/Service。返回原始 SQLAlchemy 模型导致把密码字段也序列化出去。没有统一的响应结构前端无从判断错误码。鉴权逻辑随手写在路由装饰器里无法复用。这种问题的根源不是 AI 能力弱而是提示词没有说清楚“项目里约定是什么”。4.3 建立项目规范文件为了让 AI 生成符合预期的代码我们先在仓库根目录放一个AGENTS.md包含关键约束# AGENTS.md ## 技术栈 - Python 3.11 - FastAPI SQLAlchemy 2.x Pydantic v2 - 使用 pytest 编写单元测试 ## 目录结构 - app/api/v1/ 放路由层 - app/services/ 放业务逻辑 - app/models/ 放 ORM 模型 - app/schemas/ 放 Pydantic 响应模型 - app/core/ 放鉴权、配置等基础能力 ## 命名规范 - 路由文件以 router 结尾例如 user_router.py - Service 类名使用 UserService 风格 ## 接口规范 - 所有接口使用统一响应结构{code: 0, message: ok, data: ...} - 业务异常抛出 BizException由全局异常处理器统一处理 ## 安全要求 - 响应中禁止返回 password、phone 等敏感字段 - 需要登录的接口必须在路由层配置 Depends(get_current_user) - 修改数据库前必须先更新对应迁移文件不允许隐式建表 ## 测试要求 - 每个新接口至少包含一个成功用例和一个失败用例 - 测试数据使用固定 fixture不要依赖开发数据库这个文件的作用是在你写提示词之前就已经把项目最重要的约定告诉 AI。之后你只需要写“做什么”而不用每次都重复“怎么做”。4.4 编写提示词与生成代码有了规范文件提示词可以变得很简洁按照 AGENTS.md 的规范实现“查询用户详情”接口 - 路径/api/v1/users/{user_id} - 仅登录用户可访问 - 返回脱敏后的用户信息 - 用户不存在时抛出标准业务异常 - 补测试此时模型会参照规范自动完成分层实现而不是把所有代码堆进一个文件。下面是生成后的示意代码我们重点关注它在安全与结构上是否满足规范。假设app/api/v1/user_router.py内容大约如下# 文件路径app/api/v1/user_router.py from fastapi import APIRouter, Depends, HTTPException from app.core.security import get_current_user from app.models import User from app.schemas.user import UserRead from app.services.user_service import UserService router APIRouter(prefix/api/v1/users, tags[users]) router.get(/{user_id}, response_modelUserRead) def get_user_detail( user_id: int, current_userDepends(get_current_user), ): user UserService.get_by_id(user_id) if user is None: raise HTTPException(status_code404, detailuser not found) return UserRead.model_validate(user)再看app/schemas/user.py这里重点体现脱敏# 文件路径app/schemas/user.py from pydantic import BaseModel, ConfigDict class UserRead(BaseModel): model_config ConfigDict(from_attributesTrue) id: int username: str email: str # 注意这里没有 phone、password 字段核心点在UserRead响应模型中只声明了允许返回的字段ORM 模型即使包含phone和password也不会被序列化出去。这样即使 AI 后续在模型里新增字段只要响应模型不更新就不会造成敏感字段泄漏。4.5 加入自动化质量门禁规范文件只是“建议”真正要兜底的是自动化检查。我们可以给项目加上本地 pre-commit 和 CI 配置。一个简单的pre-commit配置示例# 文件路径.pre-commit-config.yaml repos: - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.4.9 hooks: - id: ruff args: [--fix] - repo: https://github.com/psf/black-pre-commit-mirror rev: 23.12.1 hooks: - id: blackCI 里至少要有 lint、test 两个阶段# 文件路径.github/workflows/ci.yml name: CI on: pull_request: jobs: quality: runs-on: ubuntu-latest steps: - name: 拉取代码 uses: actions/checkoutv4 - name: 安装 Python uses: actions/setup-pythonv5 with: python-version: 3.11 - name: 安装依赖 run: pip install -r requirements-dev.txt - name: 静态检查 run: ruff check . - name: 单元测试 run: pytest --covapp --cov-fail-under80说明一下这里使用了actions/checkoutv4等常见版本标签具体版本号请以官方仓库发布为准。重点是AI 生成的代码必须经过 CI 才能合并不能绕过质量门禁。4.6 对比有无规范的多轮返工次数同样一个接口需求没有规范时我和身边团队的实践里经常出现 46 轮返工比如第一轮路由和业务逻辑混在一起。第二轮加了分层但响应模型返回了敏感字段。第三轮补了响应模型但缺少异常处理。第四轮功能完整了但测试写得不完整。第五轮测试补齐了CI 的 lint 又挂了。有规范之后生成结果通常 1 到 2 轮就能通过大部分检查。剩下的人工 review 主要集中在业务逻辑是否准确而不是在格式、安全、结构上反复折磨。这就是“工程规范作为核心”的直接收益。5. 常见问题与排查思路5.1 高频问题处理表问题现象常见原因解决思路AI 生成的代码目录混乱项目没有目录结构说明在 AGENTS.md 中明确app/下各目录职责并在提示词里指定“按规范分层”响应接口出现敏感字段响应模型直接序列化 ORM 对象增加显式 Pydantic 响应模型只声明可返回字段并在 review 时重点检查新代码不通过 lint代码规范没有接入本地钩子配置 pre-commit 或 IDE 保存时自动格式化提示词里要求“生成后运行 lint 并修复”提示词写了大量规则但效果不稳定规则只存在于对话中项目层不可见把规则下沉到仓库规范文件让 AI 每次都能读取多分支同时由 AI 修改导致冲突没有定义 AI 可改动范围在规范文件里限制 AI 只能改指定目录复杂重构先切任务分支测试覆盖率一直上不去只让 AI 写功能代码没让它补测试在提示词默认追加“补充单元测试覆盖成功与失败分支”功能能跑但可读性差缺少函数职责和命名约定在规范里增加命名规则与单函数长度限制AI 生成后人工 review 再要求重构5.2 排查清单遇到 AI 生成代码不合预期时建议按下面顺序自查规范文件是否存在并且放在 AI 助手默认读取的位置规范文件是否写了“禁止事项”而不只是“推荐事项”当前分支是基于最新主干吗AI 上下文是否已经过期提示词里是否模糊使用了“等等”“类似”这类词本地是否运行了 lint、test能不能通过是否有人在 review 时真正检查过敏感字段、权限逻辑、异常路径新需求是否超出了 AGENTS.md 描述的范围导致 AI 无从参考大多数人所谓“AI 写不好代码”其实都能在这七条里找到突破口。6. 最佳实践与工程建议6.1 提示词层面的收敛不要把提示词当成万能钥匙。好的提示词应该短小、聚焦、可复用。我习惯把提示词分成三部分任务要做什么。约束不要做什么、必须遵守什么。验证完成后需要怎么自测。例如任务实现用户详情接口。 约束不要修改现有数据库表遵循 AGENTS.md 中目录结构。 验证运行 pytest 相关用例确保通过运行 ruff check . 无错误。这样写的好处是每次生成前都能快速检查“任务、约束、验证”三要素是否齐全。少了任何一个都容易出现歧义。6.2 工程规范层面的执行工程规范要发挥作用必须做到“机器可读、工具可执行、评审可核对”。机器可读是指规范文件用 Markdown 放在仓库根目录AI 工具能自动加载。工具可执行是指 lint、test、format 都接入 CI 或本地钩子。评审可核对是指 code review 时能对照规范逐条检查而不是凭感觉“看起来没问题”。另外规范文件本身也应该纳入版本管理并且和业务代码同步演进。规范不是用来供着的而是需要团队定期 review 的“活文档”。当某次 AI 生成暴露了新的问题应该把解法沉淀进规范文件而不是只在对话里提醒一次。6.3 安全与合规边界AI 编程带来效率提升的同时也会放大安全风险。工程规范里至少应该明确禁止生成硬编码密钥、Token、数据库连接串。禁止在生产环境上直接执行 AI 建议的迁移或删除操作。所有涉及用户敏感信息的响应必须通过显式的响应模型控制。AI 生成的依赖必须经过人工确认不能直接pip install或npm install到生产依赖。数据库变更必须走迁移文件评审不能在代码里create_all隐式建表。这些边界看起来像老生常谈但在 AI 辅助开发里容易被忽略。因为 AI 给出的代码看起来很专业导致开发者下意识降低了警惕。6.4 团队协作与文化最后是团队层面。如果只有一个人用 Vibe Coding那可能只需要个人规范如果整个团队都在用工程规范就必须成为公共基础设施。你可以在团队内部落地三个动作每周选择一个真实模块集体 review 一次 AI 生成代码总结共性问题。把共性问题更新到 AGENTS.md 和 lint 配置里。在 PR 模板中增加“是否已阅读项目规范”“AI 参与度如何”等选项让 AI 辅助开发变得透明。透明不是为了追责而是为了让“人机协作”的经验可沉淀。久而久之团队的提示词模板、规范文件、代码评审标准会形成一套完整的内部知识库比任何外部教程都更贴合实际项目。7. 总结与延伸学习这篇内容想强调的核心观点是Vibe Coding 真正的核心不是把提示词写得越来越复杂而是用工程规范把 AI 的创造力约束在项目可控范围内。提示词解决“这一次生成对不对”工程规范解决“这个项目长期能不能维护”。两者结合AI 辅助开发才能真正从个人玩具走向生产级实践。如果你刚开始尝试 Vibe Coding建议先做三件事在你当前项目里写一个精简的AGENTS.md把目录结构、命名规范、安全红线列出来。给项目接入 lint、test 和 pre-commit让本地工具先兜底。每次让 AI 生成代码后强制走一遍 review 确认清单尤其关注敏感字段和权限逻辑。再往后可以继续研究 Spec-Driven Development、契约测试、AI 代码评审工具等方向。它们和 Vibe Coding 并不是替代关系而是从不同维度把“AI 写代码”这件事做得更稳、更可维护。如果让我给一个最朴素的建议我会说先别急着堆提示词。把项目规范写清楚让 AI 每次都知道边界在哪里你的开发体验会有质的改变。
最近总有人问我为什么我的提示词已经写得很详细让 AI 把“每一步都讲清楚”生成出来的代码还是到处都是小问题要么目录结构混乱要么函数职责不清要么上线后才发现缺少异常处理其实问题往往不在提示词本身而在项目缺少一套能约束 AI 行为的工程规范。Vibe Coding 听起来像是在“跟着感觉写代码”但它真正的核心不是把提示词写得越来越长而是把工程约束前置到 AI 生成链路里。本文我会从概念、分工、实战到工程建议完整拆解为什么“提示词 工程规范”才是 AI 辅助开发的最优解。1. 背景与核心概念1.1 Vibe Coding 到底是什么Vibe Coding 这个词最早在 AI 编程圈流行起来它描述的场景是开发者不再逐行手写代码而是通过自然语言描述需求让大模型生成大部分实现人主要负责理解、校验和调整方向。很多人把它理解成“随便说说就能生成代码”。但更准确的理解是Vibe Coding 是一种人机协作的编程模式目标是让开发者把注意力从语法细节中解放出来放在需求拆解、整体设计和质量把控上。举个例子传统开发中实现一个接口可能需要写 Controller、Service、Mapper、DTO 等一堆文件。Vibe Coding 模式下你只需要告诉模型“按项目现有分层结构新增一个用户查询接口返回脱敏后的用户信息”模型会基于项目上下文生成对应代码你再去 review、调整和补充测试。但是这里有一个非常关键的隐含前提模型必须能“理解”项目的分层结构、命名习惯、异常处理约定。如果你的项目里没有任何规范文件AI 就只能靠猜。猜得多了代码风格就会漂移时间一长项目就会变成难以维护的“AI 代码混合体”。1.2 为什么提示词解决不了全部问题提示词工程当然有作用它可以提高单次生成的准确性。比如你给 AI 一段高质量的提示词模板要求它“使用 Python 3.11、遵循 Pydantic 模型校验、所有对外接口返回统一响应结构”生成结果会比裸提问好很多。但提示词的问题在于它是一次性的、上下文有关联的、且容易被后续对话“忘掉”。你在第一条消息里告诉 AI 要遵守规范生成第二个模块时如果上下文窗口不够大它可能又把之前的约定丢了。更关键的是提示词只约束“这次回答”不约束“这个仓库的所有代码”。团队里其他人如果也使用 AI 编程提示词各不相同最终就会产生四种不同的命名风格、三层不同的异常处理策略。所以说提示词是“点状”约束工程规范才是“面状”约束。项目越复杂、参与的人越多越不能依赖把规范塞进提示词里这种“人肉传播”的方式。1.3 工程规范才是稳定器工程规范是什么它不只是一份文档而是一套可以被工具执行的约定。常见的形式包括代码风格配置ESLint、Ruff、Black、Prettier 等。项目结构约定layered architecture、feature structure 等。提交与分支规范Conventional Commits、Git Flow。质量门禁CI 里的单元测试、静态检查、覆盖率阈值。代码评审要求MR/PR 必须有描述、必须通过测试、必须有人 review。AI 辅助开发规则允许 AI 改哪些目录、禁止生成哪些不安全模式。这些规范存在于项目仓库中能被 AI 读取也能被 CI 强制执行还能作为代码评审的检查清单。它们不会因为某个人的提示词写得不好而失效这就是“稳定器”的意义。2. 环境准备与协作基础2.1 工具链与角色分工想要真正落地“Vibe Coding 工程规范”不需要一步到位引入很重的平台最先要明确的是人与工具的分工。我比较推荐的最小工具链是代码仓库Git 是底线AI 生成的内容也要走完整的版本管理。AI 编程助手可以是 IDE 插件也可以是独立 CLI关键是能读取当前仓库内容。规范文件放在仓库根目录里例如AGENTS.md或CLAUDE.mdAI 助手会自动读取。统一的 lint 与格式化工具确保 AI 生成代码经过工具归一化。CI 或本地钩子在合并之前做质量拦截。这套组合的核心思想是AI 负责生成工具负责校验人负责决策。2.2 仓库结构与分支策略工程规范的第一步是让 AI 知道你的仓库长什么样。很多项目把规范分散在不同目录里AI 很难快速理解。建议在仓库根目录放一个简洁的说明文件写清楚技术栈版本。目录结构。命名规范。如何运行测试。如何新增一个业务模块。禁止事项。这样 AI 第一次读取仓库时就能形成“全局观”而不是只盯着单个文件“头痛医头”。分支策略上无论团队用什么流程至少要保证一条原则AI 生成的改动不要直接推到主干必须经过 Pull Request 和代码评审。这不是不信任 AI而是给“工程规范”一个生效的时机。2.3 让 AI 参与的最小闭环如果你之前没有在项目里用过 AI 编程建议先搭一个最小闭环你写需求描述。AI 读取规范和上下文后生成代码。本地运行 lint 和测试。你 review 差异发现问题后让 AI 修正。通过后提交 PR进入评审。第一步到第二步之间其实存在一个容易忽略的环节把需求描述翻译成“符合项目规范的任务”。你可以在项目里维护一个任务模板让每次 AI 生成都能对齐同一个基线。3. 提示词与工程规范的分工3.1 提示词的作用边界提示词在 Vibe Coding 里的作用应该被限定在“描述任务”和“表达意图”而不是承担“维护项目一致性”的职责。举个例子一个相对合理的提示词是请按本仓库 AGENTS.md 的规范新增一个用户注册接口。 要求 1. 使用现有 Service 层命名风格。 2. 参数校验放在 Controller 层。 3. 返回统一响应结构 ResultT。 4. 补充单元测试覆盖成功与失败分支。 5. 先不要改数据库表结构。这个提示词里前两行是“任务描述”后面几条是“边界约束”。它不需要把整个项目的编码规范写进去因为规范已经放在仓库文件里模型能自己读取。相反一个试图把所有规范都塞进提示词的做法是你现在是资深工程师请严格按我下面的规范开发函数命名要动词开头Controller 要返回 ResultT异常要捕获 BizException所有类要加注释……这种提示词最大的问题是不可复用。每次生成前你都要重新输入一遍只要少写一条AI 就可能跑偏。3.2 把规范变成可执行文件代码里最可靠的东西是可执行文件。工程规范也应该尽量“可执行化”。第一层是给 AI 读的规范文件比如AGENTS.md。第二层是给工具读的配置比如eslint.config.js、pyproject.toml、.pre-commit-config.yaml。第三层是给 CI 读的流水线配置。这三层规范是层层递进的关系AI 辅助你“生成符合规范的代码”lint 工具“检查代码是否符合规范”CI 和评审“决定是否符合合入标准”。我以前见过一个团队花了很大精力写团队规范文档结果没有接入任何工具。AI 生成的代码照样通过了合并因为 nobody 真正去执行文档里的要求。后来他们把关键规范做成 lint rules问题立刻少了一半。这就是“可执行”的价值。3.3 从 Vibe Coding 到 Spec-Driven现在不少团队开始讨论 Vibe Coding 和 Spec-Driven Development 的区别。简单来说Vibe Coding 更看重“快速生成、快速验证”适合原型探索和单模块开发而 Spec-Driven 强调先把接口、数据结构、行为边界定义清楚再让 AI 基于规格落实现代码适合多人协作和长期维护的项目。这两者并不是对立关系。更健康的做法是“先用 Vibe Coding 快速验证方案可行性再用 Spec-Driven 固化关键模块的契约”。你在提示词里写得再欢如果没有规格文档和契约测试后续改造时 AI 依然不知道改一处会破坏哪里。工程规范就是帮你把“临时灵感”沉淀为“长期资产”的中间层。4. 完整实战从一条提示词到一套规范4.1 业务场景与需求下面我们模拟一个完整的例子。假设项目是一个 FastAPI 风格的 Python 后端服务现在需要新增一个“查询用户详情”的接口要求不能返回手机号等敏感字段需要做登录鉴权。为了演示规范的作用我会故意分成“只有提示词”和“有工程规范”两种情况来对比。4.2 先写提示词示例与问题先看一种常见写法给项目加一个用户查询接口路径是 /api/v1/users/{user_id}返回用户信息不要返回手机号和密码需要登录才能访问。如果项目里没有任何规范AI 可能会把接口直接放在main.py里不区分 Controller/Service。返回原始 SQLAlchemy 模型导致把密码字段也序列化出去。没有统一的响应结构前端无从判断错误码。鉴权逻辑随手写在路由装饰器里无法复用。这种问题的根源不是 AI 能力弱而是提示词没有说清楚“项目里约定是什么”。4.3 建立项目规范文件为了让 AI 生成符合预期的代码我们先在仓库根目录放一个AGENTS.md包含关键约束# AGENTS.md ## 技术栈 - Python 3.11 - FastAPI SQLAlchemy 2.x Pydantic v2 - 使用 pytest 编写单元测试 ## 目录结构 - app/api/v1/ 放路由层 - app/services/ 放业务逻辑 - app/models/ 放 ORM 模型 - app/schemas/ 放 Pydantic 响应模型 - app/core/ 放鉴权、配置等基础能力 ## 命名规范 - 路由文件以 router 结尾例如 user_router.py - Service 类名使用 UserService 风格 ## 接口规范 - 所有接口使用统一响应结构{code: 0, message: ok, data: ...} - 业务异常抛出 BizException由全局异常处理器统一处理 ## 安全要求 - 响应中禁止返回 password、phone 等敏感字段 - 需要登录的接口必须在路由层配置 Depends(get_current_user) - 修改数据库前必须先更新对应迁移文件不允许隐式建表 ## 测试要求 - 每个新接口至少包含一个成功用例和一个失败用例 - 测试数据使用固定 fixture不要依赖开发数据库这个文件的作用是在你写提示词之前就已经把项目最重要的约定告诉 AI。之后你只需要写“做什么”而不用每次都重复“怎么做”。4.4 编写提示词与生成代码有了规范文件提示词可以变得很简洁按照 AGENTS.md 的规范实现“查询用户详情”接口 - 路径/api/v1/users/{user_id} - 仅登录用户可访问 - 返回脱敏后的用户信息 - 用户不存在时抛出标准业务异常 - 补测试此时模型会参照规范自动完成分层实现而不是把所有代码堆进一个文件。下面是生成后的示意代码我们重点关注它在安全与结构上是否满足规范。假设app/api/v1/user_router.py内容大约如下# 文件路径app/api/v1/user_router.py from fastapi import APIRouter, Depends, HTTPException from app.core.security import get_current_user from app.models import User from app.schemas.user import UserRead from app.services.user_service import UserService router APIRouter(prefix/api/v1/users, tags[users]) router.get(/{user_id}, response_modelUserRead) def get_user_detail( user_id: int, current_userDepends(get_current_user), ): user UserService.get_by_id(user_id) if user is None: raise HTTPException(status_code404, detailuser not found) return UserRead.model_validate(user)再看app/schemas/user.py这里重点体现脱敏# 文件路径app/schemas/user.py from pydantic import BaseModel, ConfigDict class UserRead(BaseModel): model_config ConfigDict(from_attributesTrue) id: int username: str email: str # 注意这里没有 phone、password 字段核心点在UserRead响应模型中只声明了允许返回的字段ORM 模型即使包含phone和password也不会被序列化出去。这样即使 AI 后续在模型里新增字段只要响应模型不更新就不会造成敏感字段泄漏。4.5 加入自动化质量门禁规范文件只是“建议”真正要兜底的是自动化检查。我们可以给项目加上本地 pre-commit 和 CI 配置。一个简单的pre-commit配置示例# 文件路径.pre-commit-config.yaml repos: - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.4.9 hooks: - id: ruff args: [--fix] - repo: https://github.com/psf/black-pre-commit-mirror rev: 23.12.1 hooks: - id: blackCI 里至少要有 lint、test 两个阶段# 文件路径.github/workflows/ci.yml name: CI on: pull_request: jobs: quality: runs-on: ubuntu-latest steps: - name: 拉取代码 uses: actions/checkoutv4 - name: 安装 Python uses: actions/setup-pythonv5 with: python-version: 3.11 - name: 安装依赖 run: pip install -r requirements-dev.txt - name: 静态检查 run: ruff check . - name: 单元测试 run: pytest --covapp --cov-fail-under80说明一下这里使用了actions/checkoutv4等常见版本标签具体版本号请以官方仓库发布为准。重点是AI 生成的代码必须经过 CI 才能合并不能绕过质量门禁。4.6 对比有无规范的多轮返工次数同样一个接口需求没有规范时我和身边团队的实践里经常出现 46 轮返工比如第一轮路由和业务逻辑混在一起。第二轮加了分层但响应模型返回了敏感字段。第三轮补了响应模型但缺少异常处理。第四轮功能完整了但测试写得不完整。第五轮测试补齐了CI 的 lint 又挂了。有规范之后生成结果通常 1 到 2 轮就能通过大部分检查。剩下的人工 review 主要集中在业务逻辑是否准确而不是在格式、安全、结构上反复折磨。这就是“工程规范作为核心”的直接收益。5. 常见问题与排查思路5.1 高频问题处理表问题现象常见原因解决思路AI 生成的代码目录混乱项目没有目录结构说明在 AGENTS.md 中明确app/下各目录职责并在提示词里指定“按规范分层”响应接口出现敏感字段响应模型直接序列化 ORM 对象增加显式 Pydantic 响应模型只声明可返回字段并在 review 时重点检查新代码不通过 lint代码规范没有接入本地钩子配置 pre-commit 或 IDE 保存时自动格式化提示词里要求“生成后运行 lint 并修复”提示词写了大量规则但效果不稳定规则只存在于对话中项目层不可见把规则下沉到仓库规范文件让 AI 每次都能读取多分支同时由 AI 修改导致冲突没有定义 AI 可改动范围在规范文件里限制 AI 只能改指定目录复杂重构先切任务分支测试覆盖率一直上不去只让 AI 写功能代码没让它补测试在提示词默认追加“补充单元测试覆盖成功与失败分支”功能能跑但可读性差缺少函数职责和命名约定在规范里增加命名规则与单函数长度限制AI 生成后人工 review 再要求重构5.2 排查清单遇到 AI 生成代码不合预期时建议按下面顺序自查规范文件是否存在并且放在 AI 助手默认读取的位置规范文件是否写了“禁止事项”而不只是“推荐事项”当前分支是基于最新主干吗AI 上下文是否已经过期提示词里是否模糊使用了“等等”“类似”这类词本地是否运行了 lint、test能不能通过是否有人在 review 时真正检查过敏感字段、权限逻辑、异常路径新需求是否超出了 AGENTS.md 描述的范围导致 AI 无从参考大多数人所谓“AI 写不好代码”其实都能在这七条里找到突破口。6. 最佳实践与工程建议6.1 提示词层面的收敛不要把提示词当成万能钥匙。好的提示词应该短小、聚焦、可复用。我习惯把提示词分成三部分任务要做什么。约束不要做什么、必须遵守什么。验证完成后需要怎么自测。例如任务实现用户详情接口。 约束不要修改现有数据库表遵循 AGENTS.md 中目录结构。 验证运行 pytest 相关用例确保通过运行 ruff check . 无错误。这样写的好处是每次生成前都能快速检查“任务、约束、验证”三要素是否齐全。少了任何一个都容易出现歧义。6.2 工程规范层面的执行工程规范要发挥作用必须做到“机器可读、工具可执行、评审可核对”。机器可读是指规范文件用 Markdown 放在仓库根目录AI 工具能自动加载。工具可执行是指 lint、test、format 都接入 CI 或本地钩子。评审可核对是指 code review 时能对照规范逐条检查而不是凭感觉“看起来没问题”。另外规范文件本身也应该纳入版本管理并且和业务代码同步演进。规范不是用来供着的而是需要团队定期 review 的“活文档”。当某次 AI 生成暴露了新的问题应该把解法沉淀进规范文件而不是只在对话里提醒一次。6.3 安全与合规边界AI 编程带来效率提升的同时也会放大安全风险。工程规范里至少应该明确禁止生成硬编码密钥、Token、数据库连接串。禁止在生产环境上直接执行 AI 建议的迁移或删除操作。所有涉及用户敏感信息的响应必须通过显式的响应模型控制。AI 生成的依赖必须经过人工确认不能直接pip install或npm install到生产依赖。数据库变更必须走迁移文件评审不能在代码里create_all隐式建表。这些边界看起来像老生常谈但在 AI 辅助开发里容易被忽略。因为 AI 给出的代码看起来很专业导致开发者下意识降低了警惕。6.4 团队协作与文化最后是团队层面。如果只有一个人用 Vibe Coding那可能只需要个人规范如果整个团队都在用工程规范就必须成为公共基础设施。你可以在团队内部落地三个动作每周选择一个真实模块集体 review 一次 AI 生成代码总结共性问题。把共性问题更新到 AGENTS.md 和 lint 配置里。在 PR 模板中增加“是否已阅读项目规范”“AI 参与度如何”等选项让 AI 辅助开发变得透明。透明不是为了追责而是为了让“人机协作”的经验可沉淀。久而久之团队的提示词模板、规范文件、代码评审标准会形成一套完整的内部知识库比任何外部教程都更贴合实际项目。7. 总结与延伸学习这篇内容想强调的核心观点是Vibe Coding 真正的核心不是把提示词写得越来越复杂而是用工程规范把 AI 的创造力约束在项目可控范围内。提示词解决“这一次生成对不对”工程规范解决“这个项目长期能不能维护”。两者结合AI 辅助开发才能真正从个人玩具走向生产级实践。如果你刚开始尝试 Vibe Coding建议先做三件事在你当前项目里写一个精简的AGENTS.md把目录结构、命名规范、安全红线列出来。给项目接入 lint、test 和 pre-commit让本地工具先兜底。每次让 AI 生成代码后强制走一遍 review 确认清单尤其关注敏感字段和权限逻辑。再往后可以继续研究 Spec-Driven Development、契约测试、AI 代码评审工具等方向。它们和 Vibe Coding 并不是替代关系而是从不同维度把“AI 写代码”这件事做得更稳、更可维护。如果让我给一个最朴素的建议我会说先别急着堆提示词。把项目规范写清楚让 AI 每次都知道边界在哪里你的开发体验会有质的改变。
