Vibe Coding 这个词从 2025 年初开始火遍 AI 编程社区很多人把它理解成“用自然语言给 AI 写一段话然后让 AI 把整个项目生成出来”。于是大量开发者把时间花在打磨提示词上——加背景、加风格、加约束恨不得把一句“帮我写个网站”扩展到 500 字。结果呢小 Demo 跑得飞快一旦涉及真实业务代码结构混乱、依赖关系不明、改动一处崩三处最后只能推倒重来。不是提示词不行而是你只盯着提示词忽略了 Vibe Coding 真正的核心工程规范。本文不讲“一个月学会 XXX”那种空话。我会从 Vibe Coding 的常见误区出发说明为什么工程规范才是 AI 辅助编程的主线然后给出一套可以直接落地的规范框架、提示词模板、任务拆分方法和测试验收清单。就算你不完全认同这个概念也至少能从中拿到一套“让 AI 生成代码变得可控”的操作思路。1. Vibe Coding 是什么问题出在哪Vibe Coding 最直白的解释是“顺着感觉编程”你通过自然语言向 AI 描述需求AI 生成代码你运行看效果不合适再让 AI 修改。这在原型验证、小工具、脚本编写上效率极高因为你不用等别人写好库也不用自己敲每一行。但问题也在这里。Vibe Coding 的“感觉驱动”和软件的“确定性要求”天然冲突。你给 AI 的提示词相当于临时需求AI 生成的代码却要长期运行和迭代。很多项目死掉不是因为 AI 写不出代码而是因为没有边界AI 可以在任何文件里任意加代码导致模块职责混乱。没有契约函数入参、返回值、错误处理方式不明确AI 每次生成都“自由发挥”。没有测试AI 说“应该跑通”但实际跑没跑通没人验证。没有上下文管理一个会话里塞了几十个需求AI 到后面已经忘了最开始的结构。没有人审代码AI 生成几十个文件开发者看都不看直接提交埋下隐患。这些问题的共同根源是你用写提示词的方式替代了本来应当由工程规范承担的职责。如果我们把 Vibe Coding 视为一个“AI 结对编程”过程那提示词只是你和 AI 之间的对话工程规范则是双方都要遵守的契约。没有契约对话越多混乱越多。2. 工程规范才是真正的核心很多人以为工程规范就是“写文档”“定规范”这种增加工作量的事。实际上在 Vibe Coding 场景里工程规范是让 AI 生成代码可用的前提。原因有三点。第一AI 模型本身没有长期记忆。它每次生成都基于当前上下文窗口中的内容。如果你不把项目约束、代码结构、接口定义放在上下文里AI 就会按自己的统计惯性输出有时是 Python 风格有时是 Java 风格甚至同一个项目里两种风格混用。工程规范可以用文件的形式长期存在只要你把它嵌入会话就相当于给 AI 补上了长期记忆。第二AI 对“模糊需求”的处理方式偏向于“平均化”。你告诉它“写一个用户登录”它会做出一个最常规的登录。但如果项目里已经有自己封装好的鉴权中间件、数据库访问层、统一响应体AI 不知道这些约束自然就不会用。此时你逐字逐句描述这些中间件又费时又费力。直接把规范文件丢给 AI它才能按项目已有的地基去施工。第三规范能把“验收”从主观感觉变成客观检查。Vibe Coding 的效率陷阱是“AI 改一下、我跑一下、不行再改”循环成本很低但容易让人失去判断。有了规范就有了明确的输入输出、测试用例、代码格式检查AI 生成完可以直接用脚本验证而不是凭感觉判断。所以工程规范做的事情不是限制 AI而是给 AI 一个确定性的工作范围。AI 的生成能力很强但越强的东西越需要边界。3. 构建 Vibe Coding 的工程规范框架我建议把规范拆成七个维度每个维度都可以独立成文件或配置也可以合并成一个SPEC.md。关键是你的 AI 协作流程必须能读取并遵循这些约定。3.1 项目上下文与约束文件这是最基础的规范。它回答三个问题这个项目是做什么的、技术栈是什么、有哪些必须遵守的约束。推荐做法是在项目根目录维护一个SPEC.md内容涵盖项目目标、技术选型、目录结构、命名规范、依赖管理方式、运行命令、测试命令、已知限制。这个文件不是给人看的文档而是给 AI 的“入职培训手册”。每次新建会话时第一条消息就把SPEC.md的内容贴给 AI。一个适合 Vibe Coding 的SPEC.md模板如下# 项目 SPEC ## 项目目标 [用一两句话说明项目要解决的问题] ## 技术栈 - 语言Python 3.12 - Web 框架FastAPI - 数据库PostgreSQL 15 SQLAlchemy 2 - 测试pytest ## 目录结构 src/ api/ # 路由与接口定义 services/ # 业务逻辑 models/ # ORM 模型 schemas/ # 序列化与校验 tests/ api/ services/ ## 命名规范 - Python 文件snake_case - 类名CamelCase - 函数与变量snake_case - URL 路径一律使用 kebab-case ## 运行命令 - 启动make dev - 测试make test - 格式检查make lint ## 强制约束 - 禁止在 services 层直接使用 HTTP 请求 - 所有外部资源访问必须经过 services 封装 - 所有接口返回统一格式{code: 0, data: ..., message: ok}这里面的信息不需要多但每一项都要具体。你给 AI 的约束越具体AI 生成的代码就越贴近项目。3.2 任务拆分与子会话管理Vibe Coding 最常见的失败模式是“一个会话做太多事”。比如“帮我实现订单模块”这里面有数据模型、API、服务层、测试、文档AI 一股脑生成完结果每个部分都很薄弱。正确做法是把任务拆到“一个会话能完成并验证”的粒度。我建议用类似 Git Issue 的方式定义任务每条任务包含目标、输入、输出、验收标准。任务模板## 任务实现用户注册接口 ### 目标 提供 POST /api/v1/auth/register 接口。 ### 输入 请求体格式见 schema/auth.py。 ### 输出 - 新文件 src/api/v1/auth.py - 修改 src/services/auth.py - 新增测试 tests/services/test_auth.py ### 验收 - 运行 make test 全部通过 - 接口返回格式符合统一响应规范 - 用户密码必须使用 bcrypt 加密存储在任务进行中不要让 AI 同时处理多个这样的任务。一个会话只聚焦一个任务完成后立即关闭或新建会话。这能避免上下文被无关内容污染也能让 AI 在单一职责下发挥更稳定。3.3 代码结构与模块边界AI 生成代码时往往会自作主张创建新文件。如果没有目录结构约束它可能把工具函数放在路由文件里把配置信息写死在业务代码里下次改需求时根本找不到。规范里需要明确“什么代码应该放在哪个目录”。例如API 层只负责解析参数、调用 service、返回响应不写业务逻辑。Service 层只处理流程编排和业务规则不直接操作 ORM 对象。Model 层只定义数据结构和关系不参与接口逻辑。通用工具放在utils或helpers但必须被多个模块复用而不是单点逻辑的工具化。为了让 AI 遵守你可以在SPEC.md中写一句类似“新增文件必须放在对应职责目录禁止跨层调用 import”。同时在实际会话里如果 AI 生成了越界文件要立刻让它改正而不是留到后面。3.4 接口与数据模型先行Vibe Coding 里最容易失控的是数据模型和接口的不一致。AI 第一次生成 UserModel 有nickname字段第二次生成注册接口却用了username前后不匹配接口调试时才发现。解决方式是在让 AI 写功能代码之前先让它生成接口定义和数据模型并且这些定义要由人工确认。你可以把这一步理解为“和小模型对齐接口”。一个高效做法是让 AI 先输出 JSON Schema 或 OpenAPI 片段再输出模型代码。例如{ name: RegisterRequest, type: object, properties: { email: {type: string, format: email}, password: {type: string, minLength: 8} }, required: [email, password] }然后你确认这些字段和项目现有逻辑一致再让 AI 生成实现代码。接口先行可以避免 AI 把很多字段拍脑袋写进代码。3.5 测试与验收清单不要让 AI 只生成业务代码必须同时要求它生成测试代码。测试是验证 AI 输出是否正确的唯一客观依据。在 Vibe Coding 流程中我习惯要求 AI 遵守以下验收清单每个新增函数至少有一个单元测试。每个新增 API 端点至少有一个集成测试。测试覆盖成功路径和至少一条失败路径。测试文件必须能独立运行不依赖外部网络或者真实数据库用 mock 或内存数据库。修改完代码后必须运行make test并给出测试结果。如果你只是让 AI“写完看看效果”效果判断是主观的但如果你让它“跑完测试再总结”AI 自己会去调整代码直到测试通过。虽然 AI 也可能构造出恰好让测试通过的代码但至少比直接提交没有测试的代码强得多。3.6 提交与版本规范AI 生成的代码往往没有清晰的提交信息容易直接生成一个大 commit。规范里需要约定提交格式我建议使用 Conventional Commits。比如feat: 添加用户注册接口fix: 修复订单金额计算精度问题refactor: 抽取通用分页函数test: 增加注册流程集成测试还有一个细节不要让 AI 一次性提交所有文件。你可以让 AI 先git diff人工确认改动范围再分批提交。有时候 AI 会顺手修改配置文件或者生成缓存文件这些都不应该混进功能提交。3.7 代码审查与人工把关Vibe Coding 不等于“不用看代码”。就算 AI 生成的测试全部通过你还是需要做 code review。原因很简单现有自动化测试覆盖不了所有需求场景特别是并发、安全性、业务边界这些不容易被测试覆盖的部分。人工审查时可以重点关注AI 是否在代码中留下了硬编码秘钥或敏感信息。是否使用了不安全的函数比如eval、exec。是否异常吞掉没有打印关键日志。是否有明显的性能问题比如 N1 查询。是否没有处理外部输入的长度和类型校验。可以要求 AI 在生成代码时用注释标注可疑区域或者要求它输出“风险自检清单”。虽然不是所有问题都能被 AI 发现但至少能提高意识。4. 从提示词到工程规范的落地路径规范框架搭好了但要真正用起来还需要把规范嵌入到你的日常 Vibe Coding 工作流中。下面几节是比较落地的操作方式。4.1 先定义输入输出再写提示词很多人写提示词的习惯是“描述背景 描述场景 提要求”。比如“帮我写一个用户管理系统包含注册、登录、个人信息修改使用 React FastAPI要有良好的用户体验”。这种提示词看起来完整但对 AI 而言最关键的信息缺失了系统的输入输出契约、数据流方向、技术边界。正确方式是先定义输入输出再让 AI 填充实现。我用一个简单示例说明。假设你要写一个“根据用户 ID 获取订单列表”的接口提示词的写法可能是请实现 GET /api/v1/orders/{user_id} 接口。 输入user_id 是 UUID放在路径参数中。 输出返回满足统一格式的订单列表每条订单包含 id、product_name、amount、status、created_at。 限制 - 使用分页查询page 和 page_size 从 query 参数读取。 - 只返回当前用户自己的订单不能越权。 - 状态为 canceled 的订单要过滤掉除非传入 include_canceledtrue。这个提示词里没有一句废话每个信息都是可验证的输入输出定义。AI 收到后不会猜因为边界已经画好。4.2 把规范嵌入 AI 上下文工程规范不是写一次就完了而是每次会话都需要让 AI 知道。对于支持 system prompt 或上下文注入的工具可以把SPEC.md中必要的部分直接作为系统提示词。例如你是这个项目的资深开发者。项目的技术栈和规范如下 [粘贴 SPEC.md 的关键内容] 在编写代码前如果需要新增文件或修改接口请先列出计划等待用户确认。 所有代码必须符合项目已有的命名规范和目录结构。 每个功能必须附带测试代码并运行 make test 得到通过结果后才能交付。注意 system prompt 里不要写太多语气和情绪要写事实和约束。AI 对明确的规则更敏感对文学性描述反而不敏感。4.3 建立可复用提示词模板提示词模板不是把一堆形容词堆进去而是把规范性约束固定下来。你可以针对不同场景做模板“实现新功能”包含需求描述、接口定义、数据模型约束、测试要求。“修改现有功能”包含现有代码路径、问题描述、影响范围、回归测试要求。“重构代码”包含目标结构、行为不变要求、性能目标、测试保证。“排查 Bug”包含问题现象、错误日志、期望行为、执行环境、定位思路。模板的价值是让每次会话的起点一致。你不需要每次重新描述项目背景只需要填充本任务的变量。举个例子一个“修改现有功能”的模板## 修改任务 ### 现有代码位置 src/services/payment.py ### 问题描述 当订单金额为 0 时创建支付单返回 500期望返回 400。 ### 影响范围 只允许修改 src/services/payment.py 和对应测试文件。 ### 验收标准 - 订单金额为 0 时接口返回 400错误信息为 amount must be positive - 正常金额创建支付单不受影响 - 新增测试覆盖金额为 0 的情况 - 运行 pytest tests/services/test_payment.py 全部通过4.4 用 AI 做规范和代码的交叉验证规范不一定都是人写的也可以让 AI 帮你检查并补全。例如你可以把当前项目的SPEC.md和最新代码目录给 AI让它检查是否匹配。AI 可能会发现项目使用了requests但约束要求使用httpx。新增了services/payment.py但SPEC.md的目录结构中没写。测试命令写的是make test实际项目里没有 Makefile。这种交叉验证可以在每个功能会话结束时执行。你可以用一条专门的“审核提示词”请根据项目 SPEC.md 检查本次 AI 生成或修改的代码。检查项 1. 文件路径是否在规范目录内 2. 命名是否与规范一致 3. 是否引入规范之外的第三方库 4. 是否遵守统一响应格式 5. 是否包含测试 6. 是否执行了 lint 输出检查结论如果发现违规请列出具体文件和修改建议。4.5 定期重构 AI 生成的代码Vibe Coding 生成的代码短期内结构可能没问题但几个月后一定会膨胀。原因是 AI 在多次会话中重复实现逻辑缺少统一抽象。我建议每完成一个里程碑专门用一个会话做重构目标是消除重复代码、统一异常处理、优化命名。重构会话的规范是“行为不变结构替换”。同时在重构前必须有完整的测试否则重构后无法判断是否破坏行为。如果测试覆盖不足先让 AI 补测试再开始重构。5. 实际工作流示例下面用一个比较完整的示例来演示“工程规范驱动 Vibe Coding”到底怎么跑。假设我们正在开发一个简单的笔记服务技术栈为 FastAPI SQLite SQLAlchemy。5.1 项目初始化与规范文件在项目根目录创建SPEC.md写入我们前面模板的内容。这里简化一下# 笔记服务 SPEC ## 技术栈 - Python 3.12 - FastAPI - SQLAlchemy 2.0 SQLite - pytest ## 目录结构 app/ main.py api/ services/ models.py schemas.py tests/ ## 全局规范 - API 返回格式{code: 0, data: ..., message: success} - 禁止在 api 层写业务逻辑 - 所有数据库操作通过 models 中的 session 依赖完成 ## 命令 - 启动uvicorn app.main:app --reload - 测试pytest5.2 定义首个任务并启动会话我们在 issue 或聊天工具中写入第一个任务## 任务创建笔记模型和新增笔记接口 ### 目标 实现 POST /api/v1/notes请求体为 {title: xxx, content: xxx}。 ### 输出 - app/models.py 增加 Note 模型 - app/schemas.py 增加 NoteCreate 和 NoteOut - app/api/notes.py 增加路由 - tests/test_notes.py 增加测试 ### 验收 - pytest 通过 - 使用 curl 发送请求返回 code: 0 - title 不能为空content 可以为空5.3 给 AI 的会话提示词在 AI 编程工具中第一轮提示词请阅读项目根目录的 SPEC.md并按规范实现下面任务。 任务创建笔记模型和新增笔记接口 - 请求体字段title 必填content 可选 - 数据模型id 自增主键title stringcontent textcreated_at datetime - API 返回统一格式 {code: 0, data: NoteOut, message: success} - 需要提供 pytest 测试测试使用临时数据库 - 不要修改 app/main.py除非需要注册新的路由 实现前请先给出文件清单和变更计划。5.4 AI 返回与人工确认AI 可能会返回一个实施计划类似计划 1. 修改 app/models.py添加 Note 模型 2. 修改 app/schemas.py添加 NoteCreate、NoteOut 3. 新建 app/api/notes.py添加 router并在 main.py 中注册 4. 新建 tests/test_notes.py添加两个测试 注意由于需要注册新路由需要修改 main.py我会在改动中单独说明。这时你确认计划然后允许 AI 执行。执行完后AI 应该给出运行测试的结果。如果测试失败就让它继续修复。5.5 运行测试在命令行运行pytest预期输出中所有测试通过。如果没有检查是环境问题还是代码问题再让 AI 修复。5.6 提交代码确认无误后根据改动范围分批提交git add app/models.py app/schemas.py app/api/notes.py tests/test_notes.py git commit -m feat: 添加笔记模型与新增笔记接口如果 AI 顺手修改了其他文件谨慎合并。超过提交规范的部分应该单独 commit 或丢弃。6. Vibe Coding 与 Spec-Driven 开发的区别和结合前文提到的SPEC.md其实已经接近 Spec-Driven DevelopmentSDD的雏形。很多人分辨不清 Vibe Coding 和 Spec-Driven 的关系我简单说明。Vibe Coding 是工作模式开发者用自然语言驱动 AI 生成代码。它的重点在“交互方式”。Spec-Driven 是工程方法先定义规格Spec再根据规格实现。它的重点在“契约先行”。两者不是对立关系反而应该结合。Vibe Coding 决定了你“怎么和 AI 说话”Spec-Driven 决定了你“让 AI 按什么标准干活”。如果没有 SpecVibe Coding 很容易陷入“越改越乱”的沼泽如果没有 Vibe CodingSpec-Driven 在原型阶段会显得过重。合理的流程是先用 Vibe Coding 做探索和原型当需求逐渐明确后把关键接口和模型规范固化为 SPEC再继续用 Vibe Coding 实现剩余部分。所以当你下次使用 AI 写代码时不要只问“帮我写一个登录功能”。先问自己登录的输入输出是什么用户数据存在哪里统一返回格式是什么测试怎么跑写清楚这些再开始让 AI 写代码。这就是从提示词思维转向工程规范思维的第一步。7. 常见问题与排查方法问题现象可能原因排查方式解决方案AI 生成的代码与现有代码风格不一致会话上下文没有项目规范查看SPEC.md是否被包含检查首次提示词在 system prompt 中嵌入规范明确命名和目录约束AI 忘了上一次会话的约定上下文被新内容覆盖回顾对话是否过长拆分任务新会话重新粘贴规范保持单会话单一任务AI 生成的接口字段前后不一致缺少数据模型定义检查是否有稳定的 schema 文件先用 JSON Schema 定义输入输出再让 AI 实现测试一直失败AI 反复修改无法通过测试环境不一致或依赖缺失检查本地依赖和服务器环境在提示词中注明运行环境提供requirements.txt或pyproject.tomlAI 修改了不该修改的文件任务边界不清晰检查 diff找出无关改动在提示词中明确“禁止修改除指定文件外的任何文件”代码能跑通但无法维护缺少模块拆分和错误处理code review 时观察业务逻辑是否堆在 api 层增加结构规范要求业务逻辑必须放 services 层提交信息含糊不清没有提交规范查看 git log引入 Conventional Commits并要求 AI 生成 commit 建议提示词模板在不同 AI 工具间效果差异大工具上下文处理方式不同观察 AI 是否读取了项目文件针对不同工具调整 system prompt 长度和格式AI 生成的代码包含潜在安全漏洞缺乏审查环节检查敏感操作如 SQL 拼接、eval、硬编码秘钥在验收清单中增加安全扫描强制 code review需要强调一点Vibe Coding 不是“让 AI 自己闭环”而是“人和 AI 在一个有边界的工程环境中协作”。边界就是规范。8. 最佳实践与合规提醒把工程规范落地到团队或独立项目时有几条建议值得参考。第一次使用 AI 写代码时先花 20 分钟写SPEC.md比在会话里反复解释节省的时间多得多。任何 AI 生成的代码确认之前至少看一遍 diff。不要因为“AI 写的应该没问题”就跳过。敏感信息、私钥、用户隐私数据必须通过环境变量注入禁止出现在 AI 生成的代码或提示词中。不要将内部代码或核心业务逻辑直接发送给云端 AI 工具除非你确认数据使用范围合规。涉及公司项目时要遵循公司的数据安全制度。对测试的信任要有限度。AI 能通过你写的测试不代表没有潜在问题。边界情况、并发、权限校验仍需要人工补充。定期做一次整体代码审查专门找 AI 生成的重复代码和反模式。不要等到项目膨胀后才处理。如果团队多人使用 Vibe Coding建议把SPEC.md和提示词模板放到仓库统一管理让所有参与者使用同一套规范。安全与合规不是空话。AI 生成代码的能力越强越需要约束它的权限和数据流。在本地隔离环境测试不把敏感数据交给未知服务是任何时候都要守住的底线。9. 总结与下一步Vibe Coding 的价值不在于你能把提示词写多长而在于你能不能让 AI 在一个受控的工程框架里持续产出高质量代码。工程规范不是限制 AI 的天花板而是让 AI 能力稳定发挥的轨道。如果你现在还在“死磕提示词”我建议你先做三件事给当前项目建一个简洁的SPEC.md明确目录、命名、命令和强制约束。把下一次 AI 任务拆到足够小定义清楚输入、输出和验收标准。要求 AI 生成代码的同时生成测试并跑通测试后再提交。这三步做完之后你会发现提示词突然变简单了。真正让 AI 干活不失控的是背后那套看不见的规范。下一步可以继续探索的方向把SPEC.md生成流程接入项目脚手架用 AI 自动从现有代码中提取规范在 CI 流程中增加“AI 生成代码扫描”检测是否违反规范还可以尝试把规格定义和代码生成做成两阶段流水线让 AI 先出规格再出实现。这些方向的基础都是先把工程规范立起来。
Vibe Coding的核心不是提示词，而是工程规范
Vibe Coding 这个词从 2025 年初开始火遍 AI 编程社区很多人把它理解成“用自然语言给 AI 写一段话然后让 AI 把整个项目生成出来”。于是大量开发者把时间花在打磨提示词上——加背景、加风格、加约束恨不得把一句“帮我写个网站”扩展到 500 字。结果呢小 Demo 跑得飞快一旦涉及真实业务代码结构混乱、依赖关系不明、改动一处崩三处最后只能推倒重来。不是提示词不行而是你只盯着提示词忽略了 Vibe Coding 真正的核心工程规范。本文不讲“一个月学会 XXX”那种空话。我会从 Vibe Coding 的常见误区出发说明为什么工程规范才是 AI 辅助编程的主线然后给出一套可以直接落地的规范框架、提示词模板、任务拆分方法和测试验收清单。就算你不完全认同这个概念也至少能从中拿到一套“让 AI 生成代码变得可控”的操作思路。1. Vibe Coding 是什么问题出在哪Vibe Coding 最直白的解释是“顺着感觉编程”你通过自然语言向 AI 描述需求AI 生成代码你运行看效果不合适再让 AI 修改。这在原型验证、小工具、脚本编写上效率极高因为你不用等别人写好库也不用自己敲每一行。但问题也在这里。Vibe Coding 的“感觉驱动”和软件的“确定性要求”天然冲突。你给 AI 的提示词相当于临时需求AI 生成的代码却要长期运行和迭代。很多项目死掉不是因为 AI 写不出代码而是因为没有边界AI 可以在任何文件里任意加代码导致模块职责混乱。没有契约函数入参、返回值、错误处理方式不明确AI 每次生成都“自由发挥”。没有测试AI 说“应该跑通”但实际跑没跑通没人验证。没有上下文管理一个会话里塞了几十个需求AI 到后面已经忘了最开始的结构。没有人审代码AI 生成几十个文件开发者看都不看直接提交埋下隐患。这些问题的共同根源是你用写提示词的方式替代了本来应当由工程规范承担的职责。如果我们把 Vibe Coding 视为一个“AI 结对编程”过程那提示词只是你和 AI 之间的对话工程规范则是双方都要遵守的契约。没有契约对话越多混乱越多。2. 工程规范才是真正的核心很多人以为工程规范就是“写文档”“定规范”这种增加工作量的事。实际上在 Vibe Coding 场景里工程规范是让 AI 生成代码可用的前提。原因有三点。第一AI 模型本身没有长期记忆。它每次生成都基于当前上下文窗口中的内容。如果你不把项目约束、代码结构、接口定义放在上下文里AI 就会按自己的统计惯性输出有时是 Python 风格有时是 Java 风格甚至同一个项目里两种风格混用。工程规范可以用文件的形式长期存在只要你把它嵌入会话就相当于给 AI 补上了长期记忆。第二AI 对“模糊需求”的处理方式偏向于“平均化”。你告诉它“写一个用户登录”它会做出一个最常规的登录。但如果项目里已经有自己封装好的鉴权中间件、数据库访问层、统一响应体AI 不知道这些约束自然就不会用。此时你逐字逐句描述这些中间件又费时又费力。直接把规范文件丢给 AI它才能按项目已有的地基去施工。第三规范能把“验收”从主观感觉变成客观检查。Vibe Coding 的效率陷阱是“AI 改一下、我跑一下、不行再改”循环成本很低但容易让人失去判断。有了规范就有了明确的输入输出、测试用例、代码格式检查AI 生成完可以直接用脚本验证而不是凭感觉判断。所以工程规范做的事情不是限制 AI而是给 AI 一个确定性的工作范围。AI 的生成能力很强但越强的东西越需要边界。3. 构建 Vibe Coding 的工程规范框架我建议把规范拆成七个维度每个维度都可以独立成文件或配置也可以合并成一个SPEC.md。关键是你的 AI 协作流程必须能读取并遵循这些约定。3.1 项目上下文与约束文件这是最基础的规范。它回答三个问题这个项目是做什么的、技术栈是什么、有哪些必须遵守的约束。推荐做法是在项目根目录维护一个SPEC.md内容涵盖项目目标、技术选型、目录结构、命名规范、依赖管理方式、运行命令、测试命令、已知限制。这个文件不是给人看的文档而是给 AI 的“入职培训手册”。每次新建会话时第一条消息就把SPEC.md的内容贴给 AI。一个适合 Vibe Coding 的SPEC.md模板如下# 项目 SPEC ## 项目目标 [用一两句话说明项目要解决的问题] ## 技术栈 - 语言Python 3.12 - Web 框架FastAPI - 数据库PostgreSQL 15 SQLAlchemy 2 - 测试pytest ## 目录结构 src/ api/ # 路由与接口定义 services/ # 业务逻辑 models/ # ORM 模型 schemas/ # 序列化与校验 tests/ api/ services/ ## 命名规范 - Python 文件snake_case - 类名CamelCase - 函数与变量snake_case - URL 路径一律使用 kebab-case ## 运行命令 - 启动make dev - 测试make test - 格式检查make lint ## 强制约束 - 禁止在 services 层直接使用 HTTP 请求 - 所有外部资源访问必须经过 services 封装 - 所有接口返回统一格式{code: 0, data: ..., message: ok}这里面的信息不需要多但每一项都要具体。你给 AI 的约束越具体AI 生成的代码就越贴近项目。3.2 任务拆分与子会话管理Vibe Coding 最常见的失败模式是“一个会话做太多事”。比如“帮我实现订单模块”这里面有数据模型、API、服务层、测试、文档AI 一股脑生成完结果每个部分都很薄弱。正确做法是把任务拆到“一个会话能完成并验证”的粒度。我建议用类似 Git Issue 的方式定义任务每条任务包含目标、输入、输出、验收标准。任务模板## 任务实现用户注册接口 ### 目标 提供 POST /api/v1/auth/register 接口。 ### 输入 请求体格式见 schema/auth.py。 ### 输出 - 新文件 src/api/v1/auth.py - 修改 src/services/auth.py - 新增测试 tests/services/test_auth.py ### 验收 - 运行 make test 全部通过 - 接口返回格式符合统一响应规范 - 用户密码必须使用 bcrypt 加密存储在任务进行中不要让 AI 同时处理多个这样的任务。一个会话只聚焦一个任务完成后立即关闭或新建会话。这能避免上下文被无关内容污染也能让 AI 在单一职责下发挥更稳定。3.3 代码结构与模块边界AI 生成代码时往往会自作主张创建新文件。如果没有目录结构约束它可能把工具函数放在路由文件里把配置信息写死在业务代码里下次改需求时根本找不到。规范里需要明确“什么代码应该放在哪个目录”。例如API 层只负责解析参数、调用 service、返回响应不写业务逻辑。Service 层只处理流程编排和业务规则不直接操作 ORM 对象。Model 层只定义数据结构和关系不参与接口逻辑。通用工具放在utils或helpers但必须被多个模块复用而不是单点逻辑的工具化。为了让 AI 遵守你可以在SPEC.md中写一句类似“新增文件必须放在对应职责目录禁止跨层调用 import”。同时在实际会话里如果 AI 生成了越界文件要立刻让它改正而不是留到后面。3.4 接口与数据模型先行Vibe Coding 里最容易失控的是数据模型和接口的不一致。AI 第一次生成 UserModel 有nickname字段第二次生成注册接口却用了username前后不匹配接口调试时才发现。解决方式是在让 AI 写功能代码之前先让它生成接口定义和数据模型并且这些定义要由人工确认。你可以把这一步理解为“和小模型对齐接口”。一个高效做法是让 AI 先输出 JSON Schema 或 OpenAPI 片段再输出模型代码。例如{ name: RegisterRequest, type: object, properties: { email: {type: string, format: email}, password: {type: string, minLength: 8} }, required: [email, password] }然后你确认这些字段和项目现有逻辑一致再让 AI 生成实现代码。接口先行可以避免 AI 把很多字段拍脑袋写进代码。3.5 测试与验收清单不要让 AI 只生成业务代码必须同时要求它生成测试代码。测试是验证 AI 输出是否正确的唯一客观依据。在 Vibe Coding 流程中我习惯要求 AI 遵守以下验收清单每个新增函数至少有一个单元测试。每个新增 API 端点至少有一个集成测试。测试覆盖成功路径和至少一条失败路径。测试文件必须能独立运行不依赖外部网络或者真实数据库用 mock 或内存数据库。修改完代码后必须运行make test并给出测试结果。如果你只是让 AI“写完看看效果”效果判断是主观的但如果你让它“跑完测试再总结”AI 自己会去调整代码直到测试通过。虽然 AI 也可能构造出恰好让测试通过的代码但至少比直接提交没有测试的代码强得多。3.6 提交与版本规范AI 生成的代码往往没有清晰的提交信息容易直接生成一个大 commit。规范里需要约定提交格式我建议使用 Conventional Commits。比如feat: 添加用户注册接口fix: 修复订单金额计算精度问题refactor: 抽取通用分页函数test: 增加注册流程集成测试还有一个细节不要让 AI 一次性提交所有文件。你可以让 AI 先git diff人工确认改动范围再分批提交。有时候 AI 会顺手修改配置文件或者生成缓存文件这些都不应该混进功能提交。3.7 代码审查与人工把关Vibe Coding 不等于“不用看代码”。就算 AI 生成的测试全部通过你还是需要做 code review。原因很简单现有自动化测试覆盖不了所有需求场景特别是并发、安全性、业务边界这些不容易被测试覆盖的部分。人工审查时可以重点关注AI 是否在代码中留下了硬编码秘钥或敏感信息。是否使用了不安全的函数比如eval、exec。是否异常吞掉没有打印关键日志。是否有明显的性能问题比如 N1 查询。是否没有处理外部输入的长度和类型校验。可以要求 AI 在生成代码时用注释标注可疑区域或者要求它输出“风险自检清单”。虽然不是所有问题都能被 AI 发现但至少能提高意识。4. 从提示词到工程规范的落地路径规范框架搭好了但要真正用起来还需要把规范嵌入到你的日常 Vibe Coding 工作流中。下面几节是比较落地的操作方式。4.1 先定义输入输出再写提示词很多人写提示词的习惯是“描述背景 描述场景 提要求”。比如“帮我写一个用户管理系统包含注册、登录、个人信息修改使用 React FastAPI要有良好的用户体验”。这种提示词看起来完整但对 AI 而言最关键的信息缺失了系统的输入输出契约、数据流方向、技术边界。正确方式是先定义输入输出再让 AI 填充实现。我用一个简单示例说明。假设你要写一个“根据用户 ID 获取订单列表”的接口提示词的写法可能是请实现 GET /api/v1/orders/{user_id} 接口。 输入user_id 是 UUID放在路径参数中。 输出返回满足统一格式的订单列表每条订单包含 id、product_name、amount、status、created_at。 限制 - 使用分页查询page 和 page_size 从 query 参数读取。 - 只返回当前用户自己的订单不能越权。 - 状态为 canceled 的订单要过滤掉除非传入 include_canceledtrue。这个提示词里没有一句废话每个信息都是可验证的输入输出定义。AI 收到后不会猜因为边界已经画好。4.2 把规范嵌入 AI 上下文工程规范不是写一次就完了而是每次会话都需要让 AI 知道。对于支持 system prompt 或上下文注入的工具可以把SPEC.md中必要的部分直接作为系统提示词。例如你是这个项目的资深开发者。项目的技术栈和规范如下 [粘贴 SPEC.md 的关键内容] 在编写代码前如果需要新增文件或修改接口请先列出计划等待用户确认。 所有代码必须符合项目已有的命名规范和目录结构。 每个功能必须附带测试代码并运行 make test 得到通过结果后才能交付。注意 system prompt 里不要写太多语气和情绪要写事实和约束。AI 对明确的规则更敏感对文学性描述反而不敏感。4.3 建立可复用提示词模板提示词模板不是把一堆形容词堆进去而是把规范性约束固定下来。你可以针对不同场景做模板“实现新功能”包含需求描述、接口定义、数据模型约束、测试要求。“修改现有功能”包含现有代码路径、问题描述、影响范围、回归测试要求。“重构代码”包含目标结构、行为不变要求、性能目标、测试保证。“排查 Bug”包含问题现象、错误日志、期望行为、执行环境、定位思路。模板的价值是让每次会话的起点一致。你不需要每次重新描述项目背景只需要填充本任务的变量。举个例子一个“修改现有功能”的模板## 修改任务 ### 现有代码位置 src/services/payment.py ### 问题描述 当订单金额为 0 时创建支付单返回 500期望返回 400。 ### 影响范围 只允许修改 src/services/payment.py 和对应测试文件。 ### 验收标准 - 订单金额为 0 时接口返回 400错误信息为 amount must be positive - 正常金额创建支付单不受影响 - 新增测试覆盖金额为 0 的情况 - 运行 pytest tests/services/test_payment.py 全部通过4.4 用 AI 做规范和代码的交叉验证规范不一定都是人写的也可以让 AI 帮你检查并补全。例如你可以把当前项目的SPEC.md和最新代码目录给 AI让它检查是否匹配。AI 可能会发现项目使用了requests但约束要求使用httpx。新增了services/payment.py但SPEC.md的目录结构中没写。测试命令写的是make test实际项目里没有 Makefile。这种交叉验证可以在每个功能会话结束时执行。你可以用一条专门的“审核提示词”请根据项目 SPEC.md 检查本次 AI 生成或修改的代码。检查项 1. 文件路径是否在规范目录内 2. 命名是否与规范一致 3. 是否引入规范之外的第三方库 4. 是否遵守统一响应格式 5. 是否包含测试 6. 是否执行了 lint 输出检查结论如果发现违规请列出具体文件和修改建议。4.5 定期重构 AI 生成的代码Vibe Coding 生成的代码短期内结构可能没问题但几个月后一定会膨胀。原因是 AI 在多次会话中重复实现逻辑缺少统一抽象。我建议每完成一个里程碑专门用一个会话做重构目标是消除重复代码、统一异常处理、优化命名。重构会话的规范是“行为不变结构替换”。同时在重构前必须有完整的测试否则重构后无法判断是否破坏行为。如果测试覆盖不足先让 AI 补测试再开始重构。5. 实际工作流示例下面用一个比较完整的示例来演示“工程规范驱动 Vibe Coding”到底怎么跑。假设我们正在开发一个简单的笔记服务技术栈为 FastAPI SQLite SQLAlchemy。5.1 项目初始化与规范文件在项目根目录创建SPEC.md写入我们前面模板的内容。这里简化一下# 笔记服务 SPEC ## 技术栈 - Python 3.12 - FastAPI - SQLAlchemy 2.0 SQLite - pytest ## 目录结构 app/ main.py api/ services/ models.py schemas.py tests/ ## 全局规范 - API 返回格式{code: 0, data: ..., message: success} - 禁止在 api 层写业务逻辑 - 所有数据库操作通过 models 中的 session 依赖完成 ## 命令 - 启动uvicorn app.main:app --reload - 测试pytest5.2 定义首个任务并启动会话我们在 issue 或聊天工具中写入第一个任务## 任务创建笔记模型和新增笔记接口 ### 目标 实现 POST /api/v1/notes请求体为 {title: xxx, content: xxx}。 ### 输出 - app/models.py 增加 Note 模型 - app/schemas.py 增加 NoteCreate 和 NoteOut - app/api/notes.py 增加路由 - tests/test_notes.py 增加测试 ### 验收 - pytest 通过 - 使用 curl 发送请求返回 code: 0 - title 不能为空content 可以为空5.3 给 AI 的会话提示词在 AI 编程工具中第一轮提示词请阅读项目根目录的 SPEC.md并按规范实现下面任务。 任务创建笔记模型和新增笔记接口 - 请求体字段title 必填content 可选 - 数据模型id 自增主键title stringcontent textcreated_at datetime - API 返回统一格式 {code: 0, data: NoteOut, message: success} - 需要提供 pytest 测试测试使用临时数据库 - 不要修改 app/main.py除非需要注册新的路由 实现前请先给出文件清单和变更计划。5.4 AI 返回与人工确认AI 可能会返回一个实施计划类似计划 1. 修改 app/models.py添加 Note 模型 2. 修改 app/schemas.py添加 NoteCreate、NoteOut 3. 新建 app/api/notes.py添加 router并在 main.py 中注册 4. 新建 tests/test_notes.py添加两个测试 注意由于需要注册新路由需要修改 main.py我会在改动中单独说明。这时你确认计划然后允许 AI 执行。执行完后AI 应该给出运行测试的结果。如果测试失败就让它继续修复。5.5 运行测试在命令行运行pytest预期输出中所有测试通过。如果没有检查是环境问题还是代码问题再让 AI 修复。5.6 提交代码确认无误后根据改动范围分批提交git add app/models.py app/schemas.py app/api/notes.py tests/test_notes.py git commit -m feat: 添加笔记模型与新增笔记接口如果 AI 顺手修改了其他文件谨慎合并。超过提交规范的部分应该单独 commit 或丢弃。6. Vibe Coding 与 Spec-Driven 开发的区别和结合前文提到的SPEC.md其实已经接近 Spec-Driven DevelopmentSDD的雏形。很多人分辨不清 Vibe Coding 和 Spec-Driven 的关系我简单说明。Vibe Coding 是工作模式开发者用自然语言驱动 AI 生成代码。它的重点在“交互方式”。Spec-Driven 是工程方法先定义规格Spec再根据规格实现。它的重点在“契约先行”。两者不是对立关系反而应该结合。Vibe Coding 决定了你“怎么和 AI 说话”Spec-Driven 决定了你“让 AI 按什么标准干活”。如果没有 SpecVibe Coding 很容易陷入“越改越乱”的沼泽如果没有 Vibe CodingSpec-Driven 在原型阶段会显得过重。合理的流程是先用 Vibe Coding 做探索和原型当需求逐渐明确后把关键接口和模型规范固化为 SPEC再继续用 Vibe Coding 实现剩余部分。所以当你下次使用 AI 写代码时不要只问“帮我写一个登录功能”。先问自己登录的输入输出是什么用户数据存在哪里统一返回格式是什么测试怎么跑写清楚这些再开始让 AI 写代码。这就是从提示词思维转向工程规范思维的第一步。7. 常见问题与排查方法问题现象可能原因排查方式解决方案AI 生成的代码与现有代码风格不一致会话上下文没有项目规范查看SPEC.md是否被包含检查首次提示词在 system prompt 中嵌入规范明确命名和目录约束AI 忘了上一次会话的约定上下文被新内容覆盖回顾对话是否过长拆分任务新会话重新粘贴规范保持单会话单一任务AI 生成的接口字段前后不一致缺少数据模型定义检查是否有稳定的 schema 文件先用 JSON Schema 定义输入输出再让 AI 实现测试一直失败AI 反复修改无法通过测试环境不一致或依赖缺失检查本地依赖和服务器环境在提示词中注明运行环境提供requirements.txt或pyproject.tomlAI 修改了不该修改的文件任务边界不清晰检查 diff找出无关改动在提示词中明确“禁止修改除指定文件外的任何文件”代码能跑通但无法维护缺少模块拆分和错误处理code review 时观察业务逻辑是否堆在 api 层增加结构规范要求业务逻辑必须放 services 层提交信息含糊不清没有提交规范查看 git log引入 Conventional Commits并要求 AI 生成 commit 建议提示词模板在不同 AI 工具间效果差异大工具上下文处理方式不同观察 AI 是否读取了项目文件针对不同工具调整 system prompt 长度和格式AI 生成的代码包含潜在安全漏洞缺乏审查环节检查敏感操作如 SQL 拼接、eval、硬编码秘钥在验收清单中增加安全扫描强制 code review需要强调一点Vibe Coding 不是“让 AI 自己闭环”而是“人和 AI 在一个有边界的工程环境中协作”。边界就是规范。8. 最佳实践与合规提醒把工程规范落地到团队或独立项目时有几条建议值得参考。第一次使用 AI 写代码时先花 20 分钟写SPEC.md比在会话里反复解释节省的时间多得多。任何 AI 生成的代码确认之前至少看一遍 diff。不要因为“AI 写的应该没问题”就跳过。敏感信息、私钥、用户隐私数据必须通过环境变量注入禁止出现在 AI 生成的代码或提示词中。不要将内部代码或核心业务逻辑直接发送给云端 AI 工具除非你确认数据使用范围合规。涉及公司项目时要遵循公司的数据安全制度。对测试的信任要有限度。AI 能通过你写的测试不代表没有潜在问题。边界情况、并发、权限校验仍需要人工补充。定期做一次整体代码审查专门找 AI 生成的重复代码和反模式。不要等到项目膨胀后才处理。如果团队多人使用 Vibe Coding建议把SPEC.md和提示词模板放到仓库统一管理让所有参与者使用同一套规范。安全与合规不是空话。AI 生成代码的能力越强越需要约束它的权限和数据流。在本地隔离环境测试不把敏感数据交给未知服务是任何时候都要守住的底线。9. 总结与下一步Vibe Coding 的价值不在于你能把提示词写多长而在于你能不能让 AI 在一个受控的工程框架里持续产出高质量代码。工程规范不是限制 AI 的天花板而是让 AI 能力稳定发挥的轨道。如果你现在还在“死磕提示词”我建议你先做三件事给当前项目建一个简洁的SPEC.md明确目录、命名、命令和强制约束。把下一次 AI 任务拆到足够小定义清楚输入、输出和验收标准。要求 AI 生成代码的同时生成测试并跑通测试后再提交。这三步做完之后你会发现提示词突然变简单了。真正让 AI 干活不失控的是背后那套看不见的规范。下一步可以继续探索的方向把SPEC.md生成流程接入项目脚手架用 AI 自动从现有代码中提取规范在 CI 流程中增加“AI 生成代码扫描”检测是否违反规范还可以尝试把规格定义和代码生成做成两阶段流水线让 AI 先出规格再出实现。这些方向的基础都是先把工程规范立起来。