如何让 AI 不再误解你：Vibe Coding 需求文档指南

章老师说

507人浏览 · 2026-04-13 08:17:39

章老师说 · 2026-04-13 08:17:39 发布

注：本文内容完全由AI生成。最近我找大模型请教：在Vibe Coding场景，应该如何写好需求文档。大模型输出的内容我感觉非常好，分享出来，供大家参考。

在“Vibe Coding”（氛围式编程、感知驱动开发）逐渐流行的今天，开发方式正在从“严格规格驱动”转向“意图+上下文驱动”。开发者越来越多地借助 AI 编码助手，通过自然语言来描述需求，由模型生成代码。在这种范式下，传统意义上的“需求文档”（PRD）并没有消失，反而变得更关键——只是写法需要彻底改变。

这篇文章将系统说明：在 Vibe Coding 场景下，什么样的需求文档才是“高质量”的。

一、Vibe Coding 对需求文档提出了新要求

传统需求文档的核心是“给人看”，强调完整性、严谨性和可追溯性。但在 Vibe Coding 中，需求文档往往是“人 + AI 共读”的输入，其目标变成：

让 AI 正确理解你的意图，并稳定地产出符合预期的代码。

这带来三个本质变化：

从“规格说明”转向“意图表达”
- 不只是“做什么”，还要说明“为什么这么做”
从“结构严谨”转向“语义清晰”
- AI更依赖语义上下文，而不是格式规范
从“一次性交付”转向“可迭代对话”
- 文档本身就是 Prompt 的一部分，可以不断演进

因此，一个好的需求文档，本质上就是一个“高质量的长上下文 Prompt”。

二、一个好的 Vibe Coding 需求文档应该包含什么？

1. 背景与目标（Why）

这是最容易被忽略，但最关键的部分。

错误写法（传统风格）：

实现一个用户登录接口

正确写法（Vibe 风格）：

当前系统缺少统一认证入口，导致多个服务重复实现登录逻辑。本需求希望构建一个标准化登录接口，支持后续扩展 OAuth 和多因子认证。

👉 为什么重要？

AI 在没有背景时，容易做出“局部最优”的设计（比如只写一个简单 API），而不是“系统性方案”。

2. 使用场景（Context）

描述系统在哪些情况下使用这个功能。

示例：

Web 用户通过账号密码登录
移动端通过 token 自动续期
内部服务通过 service account 调用

👉 作用：

帮助 AI 理解边界条件
避免生成“只适用于单一场景”的代码

3. 核心需求（What）

这是需求的主体，但要注意写法。

建议采用：

分点描述
每一点尽量单一职责
避免模糊词（如“尽量”“优化”“合理”）

示例：

1. 提供 POST /login 接口
2. 输入为 username + password
3. 返回 JWT token（有效期 1 小时）
4. 登录失败返回明确错误码（401 / 403）
5. 支持登录限流（同一 IP 每分钟最多 5 次）

👉 关键点：

让 AI 不需要“猜”，而是“执行”。

4. 非功能性要求（Constraints）

这是区分“普通输出”和“工程级代码”的关键。

包括：

性能要求（QPS、延迟）
安全要求（加密、审计）
可扩展性
兼容性

示例：

- 必须支持水平扩展（无状态设计）
- token 签名使用 HS256
- 密码存储必须使用 bcrypt
- 日志需包含 user_id 和 request_id

👉 如果不写这一部分，AI 默认会走“最简单实现”，而不是“可上线实现”。

5. 输入输出示例（Examples）

这是提升 AI 生成质量的“杀手锏”。

示例：

请求：
POST /login
{
  "username": "test",
  "password": "123456"
}

响应：
{
  "token": "xxx",
  "expires_in": 3600
}

👉 为什么有效？

因为 AI 对“模式”极其敏感，有例子时准确率会显著提升。

6. 边界与异常（Edge Cases）

很多错误都来自这里。

示例：

用户不存在
密码错误超过5次锁定账户
token 过期
并发登录冲突

👉 明确写出来，可以显著减少后续反复修改。

7. 技术偏好（Tech Preferences）

在 Vibe Coding 中，如果你不说，AI会“自己选”。

例如：

使用 Go + Gin
使用 PostgreSQL
使用 Redis 做缓存
遵循 RESTful 风格

👉 这一步可以避免“技术栈漂移”。

三、如何写得更“AI 友好”？

1. 使用结构化表达

推荐结构：

# 背景
# 目标
# 场景
# 功能需求
# 非功能需求
# 示例
# 边界情况
# 技术约束

👉 比长篇叙述更有效。

2. 避免模糊语言

例如：

模糊写法	清晰写法
提高性能	P99 < 100ms
做好安全	使用 HTTPS + JWT
支持高并发	支持 10k QPS

3. 尽量“显式”，不要“隐含”

错误：

系统需要安全

正确：

所有接口必须进行身份认证，使用 JWT 校验

4. 分层描述（从抽象到具体）

先说目标，再说实现细节：

目标：统一认证
方案：JWT
实现：接口定义

👉 这样 AI 更容易构建正确的逻辑结构。

5. 把“决策”写出来

AI 最大的问题是：它不知道你已经做过哪些取舍。

例如：

不使用 OAuth，是因为当前系统是内部系统

👉 这能避免 AI“过度设计”。

四、一个完整示例（简化版）

# 背景
当前系统登录逻辑分散，需要统一认证服务

# 目标
提供标准登录接口，支持 Web 和移动端

# 场景
- 用户登录
- token 校验
- token 续期

# 功能需求
1. POST /login
2. 输入 username/password
3. 返回 JWT token
4. 提供 /validate 接口校验 token

# 非功能需求
- QPS >= 5000
- 无状态设计
- 使用 bcrypt 存储密码

# 示例
（略）

# 边界
- 登录失败锁定
- token 过期处理

# 技术
- Go + Gin
- Redis 做限流