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）。
• 是否异常吞掉，没有打印关键日志。
• 是否有明显的性能问题（比如 N+1 查询）。
• 是否没有处理外部输入的长度和类型校验。

可以要求 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_canceled=true）。

这个提示词里没有一句废话，每个信息都是可验证的输入输出定义。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 - 测试：pytest

5.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 string，content text，created_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 Development（SDD）的雏形。很多人分辨不清 Vibe Coding 和 Spec-Driven 的关系，我简单说明。

Vibe Coding 是工作模式：开发者用自然语言驱动 AI 生成代码。它的重点在“交互方式”。

Spec-Driven 是工程方法：先定义规格（Spec），再根据规格实现。它的重点在“契约先行”。

两者不是对立关系，反而应该结合。Vibe Coding 决定了你“怎么和 AI 说话”，Spec-Driven 决定了你“让 AI 按什么标准干活”。如果没有 Spec，Vibe Coding 很容易陷入“越改越乱”的沼泽；如果没有 Vibe Coding，Spec-Driven 在原型阶段会显得过重。合理的流程是：先用 Vibe Coding 做探索和原型，当需求逐渐明确后，把关键接口和模型规范固化为 SPEC，再继续用 Vibe Coding 实现剩余部分。

所以，当你下次使用 AI 写代码时，不要只问“帮我写一个登录功能”。先问自己：登录的输入输出是什么？用户数据存在哪里？统一返回格式是什么？测试怎么跑？写清楚这些，再开始让 AI 写代码。这就是从提示词思维转向工程规范思维的第一步。

7. 常见问题与排查方法

需要强调一点：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 能力稳定发挥的轨道。

如果你现在还在“死磕提示词”，我建议你先做三件事：

1. 给当前项目建一个简洁的SPEC.md，明确目录、命名、命令和强制约束。
2. 把下一次 AI 任务拆到足够小，定义清楚输入、输出和验收标准。
3. 要求 AI 生成代码的同时生成测试，并跑通测试后再提交。

这三步做完之后，你会发现提示词突然变简单了。真正让 AI 干活不失控的，是背后那套看不见的规范。

下一步可以继续探索的方向：把SPEC.md生成流程接入项目脚手架，用 AI 自动从现有代码中提取规范；在 CI 流程中增加“AI 生成代码扫描”，检测是否违反规范；还可以尝试把规格定义和代码生成做成两阶段流水线，让 AI 先出规格，再出实现。这些方向的基础，都是先把工程规范立起来。