作者： PaPaPod

VibeCoding 工程规范：标准化 AI 开发流程

VibeCoding 工程规范：标准化 AI 开发流程

让 AI 辅助编程从"野生玩法"进化为"工程实践"

前言

VibeCoding（AI 辅助编程）正在改变我们的开发方式。但是，没有规范的 VibeCoding 就像没有图纸的施工现场——初期看起来很快，后期全是坑。

本文将建立一套标准化的 AI 开发流程，让你的 VibeCoding 从"碰运气"变成"可工程化"。

一、引言：效率幻觉与真实困境

1.1 没有规范的 VibeCoding 三大困境

困境1：效率幻觉

现象：

Day 1: 🚀 极速开发，功能快速上线
Day 7: 🐌 遇到 Bug，AI 给出的修复方案互相矛盾
Day 14: 💥 重构噩梦，早期决策导致系统难以扩展

根本原因：

  • 没有全局规划，AI 每次都"重新思考"
  • 上下文混乱，早期决策被遗忘
  • 技术债务积累，AI 不断"打补丁"

困境2：团队协作障碍

现象：

  • 不同成员用 AI 生成的代码风格完全不同
  • 隐性知识难以传承（为什么这么写？AI 说的...）
  • 代码审查变成"猜谜游戏"

根本原因：

  • 缺少统一的规范和约定
  • AI 生成代码缺少注释和文档
  • 决策过程没有记录

困境3：质量失控风险

现象：

  • 上下文混乱导致前后代码矛盾
  • 安全漏洞潜伏（SQL 注入、权限绕过）
  • 测试覆盖率低，Bug 频发

根本原因：

  • AI 不理解业务安全要求
  • 缺少验证机制和检查清单
  • 一次性生成大量代码，缺少验证

1.2 标准化的必要性

为什么要标准化？

  1. 流程化：建立可落地的规范体系

    • 明确每个阶段的输入和输出
    • 减少返工和技术债务
    • 提高可预测性

  2. 工程化：保障长期价值

    • 团队协作更顺畅
    • 知识可沉淀、可传承
    • 质量可控、风险可管理

二、核心解决方案：三段式框架

2.1 研究阶段（AskMode）

目标：完全理解需求，探索技术方案

方法：纯 Chat 模式，禁止代码生成

核心原则：

  • ✅ 问清楚所有需求细节
  • ✅ 探索多种技术方案
  • ✅ 对比方案优劣
  • ❌ 不要让 AI 生成代码

输出物：

  1. 需求分析文档

    # 需求分析

## 核心功能
- 用户登录/注册
- 权限管理
- 数据统计分析

## 非功能需求
- 性能：响应时间 < 200ms
- 安全：符合 OWASP Top 10
- 可用性：99.9%

## 约束条件
- 技术栈：React + Node.js + PostgreSQL
- 部署环境：Docker + Kubernetes

  2. 技术方案对比表

    # 技术方案对比

| 方案 | 优势 | 劣势 | 推荐指数 |
|------|------|------|----------|
| JWT 认证 | 无状态，易扩展 | Token 无法主动失效 | ⭐⭐⭐⭐ |
| Session 认证 | 易于控制 | 需要共享存储 | ⭐⭐⭐ |
| OAuth 2.0 | 安全性高 | 实现复杂 | ⭐⭐⭐⭐⭐ |

**最终选择**：JWT + Refresh Token

2.2 规划阶段（PlanMode）

关键任务：

  • 模块拆解
  • 接口定义
  • 风险识别

交付物：PLAN.md（团队锚点）

核心原则：

  • 🚫 无 PLAN.md 禁止进入实现阶段
  • 📝 PLAN.md 必须包含完整的模块拆解和接口定义
  • 🔄 PLAN.md 是动态文档，随项目演进更新

PLAN.md 模板：

# 项目实现计划

## 1. 项目概述
- **目标**：构建用户管理系统
- **技术栈**：React 18 + Node.js 18 + PostgreSQL 15
- **时间估算**：2 周

## 2. 模块拆解

### 2.1 认证模块
**负责人**：张三  
**优先级**：P0  
**预计时间**：3 天

#### 接口契约
- <code>POST /api/auth/login
  - 输入：{ email: string, password: string }
  - 输出：{ token: string, refreshToken: string }
  - 错误：401 Unauthorized, 400 Bad Request

- POST /api/auth/refresh
  - 输入：{ refreshToken: string }
  - 输出：{ token: string }

#### 数据库设计
```sql
CREATE TABLE users (
  id UUID PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);

2.2 权限模块

负责人：李四
优先级：P1
预计时间：2 天

接口契约

  • GET /api/permissions/:userId
    • 输出：{ roles: string[], permissions: string[] }

2.3 统计模块

负责人：王五
优先级：P2
预计时间：2 天

3. 风险识别

风险 影响 概率 缓解措施
JWT 密钥泄露 高 中 使用环境变量 + 定期轮换
数据库连接池耗尽 高 低 限制连接数 + 监控告警
第三方 API 失败 中 中 实现重试机制 + 降级方案

4. 实现顺序

  1. ✅ 认证模块（Day 1-3）
  2. ⏳ 权限模块（Day 4-5）
  3. ⏳ 统计模块（Day 6-7）
  4. ⏳ 集成测试（Day 8-10）

2.3 实现阶段（CodeMode）

分步执行原则：

  • 📦 每步只实现一个模块
  • ✅ 每步立即验证
  • 🚫 禁止连续执行多个步骤

验证清单：

# 实现验证清单

## 代码质量
- [ ] 代码符合团队规范（ESLint/Prettier）
- [ ] 关键逻辑有注释说明
- [ ] 无明显性能问题

## 测试
- [ ] 单元测试覆盖率 ≥ 80%
- [ ] 集成测试通过
- [ ] 边界条件测试

## 安全
- [ ] 输入校验完整
- [ ] 无 SQL 注入风险
- [ ] 权限校验正确

## 文档
- [ ] API 文档更新
- [ ] README 更新

禁令清单：

# ❌ 禁止行为

1. ❌ 禁止一次性生成多个模块的代码
2. ❌ 禁止生成未经测试的代码
3. ❌ 禁止忽略安全检查清单
4. ❌ 禁止修改核心数据库结构不经评审
5. ❌ 禁止使用硬编码密钥或配置

三、上下文窗口管理

3.1 AI 上下文三大危机

危机1：需求遗忘

现象：

User: 实现用户登录功能
AI: 好的，实现 JWT 认证...

（10 轮对话后）

User: 加个权限校验
AI: 好的，实现 Session 认证...  # ❌ 忘记了早期选择 JWT

原因：

  • 早期说明被新对话覆盖
  • AI 上下文窗口有限（4k-32k tokens）

危机2：自相矛盾

现象：

Day 1: AI 建议使用 REST API
Day 2: AI 建议使用 GraphQL
Day 3: AI 又建议使用 REST API

原因：

  • AI 没有全局记忆
  • 每次都是"重新思考"

危机3：质量衰退

现象：

前 5 轮对话：代码质量高，逻辑清晰
第 10 轮对话：代码冗余，有 Bug
第 15 轮对话：完全不可用

原因：

  • 上下文窗口接近上限
  • AI 注意力分散

3.2 治理策略：三把剪刀

剪刀1：独立任务开新 Chat

规则：每功能模块独立对话

示例：

# Chat 1: 认证模块
- 只讨论登录/注册/Token 刷新
- 完成后关闭 Chat

# Chat 2: 权限模块
- 只讨论角色/权限校验
- 完成后关闭 Chat

好处：

  • 避免上下文混乱
  • 每个模块有独立的思考空间

剪刀2：PLAN.md 全局锚点

实施：新 Chat 开始前加载全局计划

操作流程：

1. 打开新 Chat
2. 第一步：上传 PLAN.md
3. 告诉 AI："这是项目全局计划，请基于此实现 XXX 模块"
4. 开始实现

好处：

  • AI 有全局上下文
  • 避免前后矛盾

剪刀3：核心决策代码固化

示例：关键决策注释锁定

/**
 * 认证策略：JWT + Refresh Token
 * 
 * 决策日期：2026-03-31
 * 决策者：团队评审
 * 
 * 理由：
 * 1. 无状态，易扩展
 * 2. 支持多端登录
 * 3. Token 可设置过期时间
 * 
 * 约束：
 * - JWT 密钥必须从环境变量读取
 * - Refresh Token 存储在 Redis
 * - Token 有效期：15 分钟（Access），7 天（Refresh）
 * 
 * ❌ 禁止修改此策略，除非经过团队评审
 */
class AuthService {
  // ...
}

好处：

  • 后续 Chat 不会随意修改核心决策
  • 团队成员能理解设计意图

四、人机决策边界矩阵

4.1 决策权限划分

决策类型 AI 权限 人类权限 控制措施
代码实现细节 ✅ 自主决定 ❌ 不干预 单元测试覆盖
技术方案选择 ❌ 仅提建议 ✅ 最终决策 方案评审会
数据库 Schema 变更 ❌ 禁止修改 ✅ 必须审批 备案 + 回滚方案
安全相关代码 ❌ 仅参考 ✅ 必须审查 安全审查流程
第三方服务集成 ❌ 仅建议 ✅ 必须评估 合规评估
删除/重构操作 ❌ 禁止执行 ✅ 必须确认 影响面分析
环境变量/密钥管理 ❌ 禁止触碰 ✅ 专人管理 配置管理工具

4.2 决策流程示例

场景1：代码实现细节

User: 实现用户登录逻辑
AI: 好的，实现 JWT 认证...
Human: ✅ 通过（单元测试覆盖）

AI 权限：✅ 自主决定
人类角色：审查 + 测试

场景2：技术方案选择

AI: 建议使用 Redis 做缓存
Human: 让我评估一下...
（技术评审会议）
Human: 决定使用 Redis，但需要配置主从复制
AI: 好的，基于这个决策实现

AI 权限：❌ 仅提建议
人类角色：最终决策

场景3：数据库 Schema 变更

AI: 需要在 users 表添加 phone 字段
Human: ❌ 等等，需要先评估影响
（DBA 评审）
Human: 批准添加，但需要设置默认值
AI: 好的，生成迁移脚本...

AI 权限：❌ 禁止修改
人类角色：审批 + 执行

五、安全陷阱防御线

5.1 权限严防线

防御1：水平权限校验

问题：用户只能访问自己的数据

错误示例：

// ❌ 危险：没有校验用户是否有权限
app.get('/api/orders/:orderId', async (req, res) => {
  const order = await Order.findById(req.params.orderId);
  res.json(order);
});

正确示例：

// ✅ 安全：校验用户是否有权限
app.get('/api/orders/:orderId', authMiddleware, async (req, res) => {
  const order = await Order.findById(req.params.orderId);

  // 水平权限校验
  if (order.userId.toString() !== req.user.id) {
    return res.status(403).json({ error: '无权访问' });
  }

  res.json(order);
});

防御2：管理端操作二次认证

问题：管理员操作需要额外验证

实现：

// ✅ 管理员删除用户需要二次认证
app.delete('/api/admin/users/:userId', 
  authMiddleware, 
  adminMiddleware,
  async (req, res) => {
    // 要求管理员输入密码确认
    const { confirmationPassword } = req.body;

    const isValid = await bcrypt.compare(
      confirmationPassword, 
      req.user.passwordHash
    );

    if (!isValid) {
      return res.status(403).json({ error: '需要二次认证' });
    }

    // 执行删除
    await User.deleteById(req.params.userId);
    res.json({ success: true });
  }
);

5.2 数据库防线

防御1：禁止字符串拼接

错误示例：

// ❌ 危险：SQL 注入风险
const query = <code>SELECT * FROM users WHERE email = '${email}';

正确示例：

// ✅ 安全：使用参数化查询
const query = 'SELECT * FROM users WHERE email = $1';
const result = await db.query(query, [email]);

防御2：批量操作数量限制

问题：防止一次性删除大量数据

实现：

// ✅ 限制批量删除数量
app.post('/api/admin/users/batch-delete', async (req, res) => {
  const { userIds } = req.body;

  // 限制最多 100 条
  if (userIds.length > 100) {
    return res.status(400).json({ 
      error: '批量操作不能超过 100 条' 
    });
  }

  await User.deleteMany({ _id: { $in: userIds } });
  res.json({ success: true });
});

5.3 输入强校验

防御1：防 Prompt 注入

问题：用户输入包含 AI 指令

错误示例：

// ❌ 危险：用户输入可能包含恶意指令
const userPrompt = <code>总结这篇文章：${userInput};
ai.generate(userPrompt);

正确示例：

// ✅ 安全：清除 AI 指令标记
function sanitizeInput(input) {
  // 移除可能的 AI 指令标记
  return input
    .replace(/``<code>[\s\S]*?``/g, '') // 移除代码块
    .replace(/#{1,6}\s/g, '')       // 移除标题
    .replace(/\*\*|__/g, '')        // 移除加粗/斜体
    .replace(/\[.*?\]\(.*?\)/g, ''); // 移除链接
}

const safePrompt = 总结这篇文章：${sanitizeInput(userInput)};
ai.generate(safePrompt);

防御2：文件上传类型/大小限制

实现：

// ✅ 文件上传安全限制
const upload = multer({
  storage: storage,
  limits: {
    fileSize: 5 * 1024 * 1024, // 5MB
  },
  fileFilter: (req, file, cb) => {
    // 只允许图片
    const allowedTypes = ['image/jpeg', 'image/png', 'image/gif'];
    if (!allowedTypes.includes(file.mimetype)) {
      return cb(new Error('不支持的文件类型'), false);
    }
    cb(null, true);
  }
});

5.4 密钥防泄漏

防御1：环境变量注入原则

错误示例：

// ❌ 危险：硬编码密钥
const jwtSecret = 'my-secret-key-12345';

正确示例：

// ✅ 安全：从环境变量读取
const jwtSecret = process.env.JWT_SECRET;

if (!jwtSecret) {
  throw new Error('JWT_SECRET 环境变量未设置');
}

防御2：.gitignore 敏感目录规范

.gitignore：

# 环境变量
.env
.env.local
.env.production

# 密钥文件
*.pem
*.key
secrets/

# 配置文件
config/database.yml
config/secrets.yml

5.5 脱敏响应

防御1：错误响应模板化

错误示例：

// ❌ 危险：暴露内部堆栈信息
app.use((err, req, res, next) => {
  res.status(500).json({
    error: err.message,
    stack: err.stack // 暴露敏感信息
  });
});

正确示例：

// ✅ 安全：模板化错误响应
app.use((err, req, res, next) => {
  // 记录详细错误到日志
  console.error(err);

  // 返回脱敏响应
  res.status(500).json({
    error: '服务器内部错误',
    requestId: req.id,
    timestamp: new Date().toISOString()
  });
});

六、团队协作规范

6.1 共享 RULES 体系

规范文件1：.github/copilot-instructions.md

# GitHub Copilot 指令

## 代码风格
- 使用 2 空格缩进
- 最大行宽 120 字符
- 使用 const/let，避免 var
- 使用箭头函数

## 命名规范
- 变量：camelCase
- 常量：UPPER_SNAKE_CASE
- 类/组件：PascalCase
- 文件：kebab-case

## 注释规范
- 所有公共函数必须有 JSDoc 注释
- 复杂逻辑必须添加行内注释
- 使用中文注释（团队约定）

## 安全规范
- 所有用户输入必须校验
- 使用参数化查询，禁止字符串拼接
- 敏感信息必须从环境变量读取

规范文件2：.cursor/rules/coding-style.md

# Cursor 编码风格规范

## React 组件
- 使用函数组件 + Hooks
- 组件拆分原则：单一职责
- Props 必须定义 TypeScript 类型

## API 设计
- RESTful 风格
- 统一响应格式：
  ```typescript
  {
    success: boolean;
    data?: any;
    error?: string;
  }</code></pre>
<h2>错误处理</h2>
<ul>
<li>所有异步操作必须有 try-catch</li>
<li>错误日志记录到监控系统</li>
<li>用户友好的错误提示
<pre><code></code></pre></li>
</ul>
<hr />
<h4>规范文件3：.cursor/rules/decision-boundary.md</h4>
<pre><code class="language-markdown"># 人机决策边界规范

## AI 可以自主决定
- 代码实现细节
- 变量命名
- 代码格式化
- 小型重构（不影响功能）

## 必须人工审批
- 数据库 Schema 变更
- 第三方服务集成
- 安全相关代码
- 删除/重构操作
- 环境变量配置</code></pre>
<hr />
<h3>6.2 Commit Message 规范</h3>
<p><strong>标准格式</strong>：</p>
<pre><code class="language-bash">git commit -m "feat(auth): JWT 认证模块 🤖 Generated by GPT-4

### Changes:
- JWT 核心类集成
- 登录 API 实现
- Token 刷新逻辑

### Validation:
✅ 单元测试覆盖率 85%
✅ 安全审查通过
✅ 代码审查通过

### AI Assistance:
- 认证逻辑：GPT-4 生成，人工审查
- 测试用例：GPT-4 辅助，人工补充
"</code></pre>
<p><strong>类型标记</strong>：</p>
<ul>
<li><code>feat</code>: 新功能</li>
<li><code>fix</code>: Bug 修复</li>
<li><code>refactor</code>: 重构</li>
<li><code>docs</code>: 文档更新</li>
<li><code>test</code>: 测试相关</li>
<li><code>chore</code>: 构建/工具链</li>
</ul>
<p><strong>AI 标记</strong>：</p>
<ul>
<li>🤖 Generated by GPT-4：AI 生成</li>
<li>🤖 Assisted by GPT-4：AI 辅助</li>
<li>🚫 No AI：纯人工编写</li>
</ul>
<hr />
<h3>6.3 PR 描述模板</h3>
<p><strong>模板</strong>：</p>
<pre><code class="language-markdown"># PR: JWT 认证模块实现

## 变更概述
- 实现基于 JWT 的用户认证
- 支持登录、注册、Token 刷新
- 添加权限校验中间件

## AI 生成部分清单
- [x] 认证逻辑（<code>auth.service.ts</code>）
- [x] 登录 API（<code>auth.controller.ts</code>）
- [x] 单元测试（<code>auth.test.ts</code>）

## 人工审查部分清单
- [x] 安全审查（SQL 注入、XSS）
- [x] 权限校验逻辑
- [x] 错误处理
- [x] 性能优化

## 测试覆盖
- 单元测试：85%
- 集成测试：✅ 通过
- E2E 测试：✅ 通过

## 风险评估矩阵

| 风险项 | 影响级别 | 概率 | 缓解措施 |
|--------|----------|------|----------|
| JWT 密钥泄露 | 高 | 低 | 环境变量 + 定期轮换 |
| Token 被劫持 | 中 | 低 | HTTPS + HttpOnly Cookie |

## 截图
- 登录界面：![登录](./screenshots/login.png)
- 权限错误：![权限错误](./screenshots/permission-error.png)

## 相关文档
- [PLAN.md](./PLAN.md)
- [API 文档](./docs/api.md)</code></pre>
<hr />
<h2>七、可落地的 VibeCoding SOP</h2>
<h3>7.1 标准工作流程</h3>
<table>
<thead>
<tr>
<th>阶段</th>
<th>时长</th>
<th>关键任务</th>
<th>交付物</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>规划准备</strong></td>
<td>30 分钟</td>
<td>需求分析 + 技术方案对比</td>
<td>PLAN.md 初稿</td>
</tr>
<tr>
<td><strong>AI 实现</strong></td>
<td>2-3 小时</td>
<td>分模块实现 + 步骤验证</td>
<td>更新后的 PLAN.md</td>
</tr>
<tr>
<td><strong>人工审查</strong></td>
<td>1 小时</td>
<td>代码质量 + 安全合规性测试</td>
<td>修订版实现</td>
</tr>
<tr>
<td><strong>最终交付</strong></td>
<td>30 分钟</td>
<td>文档生成 + 部署方案</td>
<td>完整功能包</td>
</tr>
</tbody>
</table>
<hr />
<h3>7.2 详细流程示例</h3>
<h4>阶段1：规划准备（30 分钟）</h4>
<p><strong>任务</strong>：</p>
<ol>
<li>
<p>需求分析（15 分钟）</p>
<ul>
<li>与产品确认需求细节</li>
<li>识别约束条件（技术栈、时间、资源）</li>
</ul>
</li>
<li>
<p>技术方案对比（15 分钟）</p>
<ul>
<li>使用 AI 探索多种方案</li>
<li>制作对比表格</li>
<li>确定最终方案</li>
</ul>
</li>
</ol>
<p><strong>交付物</strong>：</p>
<ul>
<li>PLAN.md 初稿</li>
<li>技术方案对比表</li>
</ul>
<hr />
<h4>阶段2：AI 实现（2-3 小时）</h4>
<p><strong>任务</strong>：</p>
<ol>
<li>
<p>模块1实现（45 分钟）</p>
<ul>
<li>打开新 Chat，上传 PLAN.md</li>
<li>让 AI 实现模块1</li>
<li>运行测试，验证功能</li>
</ul>
</li>
<li>
<p>模块2实现（45 分钟）</p>
<ul>
<li>打开新 Chat，上传 PLAN.md</li>
<li>让 AI 实现模块2</li>
<li>运行测试，验证功能</li>
</ul>
</li>
<li>
<p>集成（30 分钟）</p>
<ul>
<li>合并所有模块</li>
<li>运行集成测试</li>
</ul>
</li>
</ol>
<p><strong>交付物</strong>：</p>
<ul>
<li>更新后的 PLAN.md</li>
<li>所有模块代码 + 测试</li>
</ul>
<hr />
<h4>阶段3：人工审查（1 小时）</h4>
<p><strong>任务</strong>：</p>
<ol>
<li>
<p>代码质量审查（30 分钟）</p>
<ul>
<li>检查代码规范</li>
<li>检查注释和文档</li>
<li>检查性能问题</li>
</ul>
</li>
<li>
<p>安全合规性测试（30 分钟）</p>
<ul>
<li>检查输入校验</li>
<li>检查权限校验</li>
<li>检查敏感信息处理</li>
</ul>
</li>
</ol>
<p><strong>交付物</strong>：</p>
<ul>
<li>修订版实现</li>
<li>审查报告</li>
</ul>
<hr />
<h4>阶段4：最终交付（30 分钟）</h4>
<p><strong>任务</strong>：</p>
<ol>
<li>
<p>文档生成（15 分钟）</p>
<ul>
<li>API 文档</li>
<li>部署文档</li>
<li>用户手册</li>
</ul>
</li>
<li>
<p>部署方案（15 分钟）</p>
<ul>
<li>编写 Dockerfile</li>
<li>编写 docker-compose.yml</li>
<li>配置 CI/CD</li>
</ul>
</li>
</ol>
<p><strong>交付物</strong>：</p>
<ul>
<li>完整功能包（代码 + 文档 + 部署方案）</li>
</ul>
<hr />
<h2>八、进化方向：SpecCoding 工程范式</h2>
<h3>8.1 规格驱动核心洞察</h3>
<p><strong>传统流程</strong>：</p>
<pre><code>需求 → 代码</code></pre>
<p><strong>SpecCoding 流程</strong>：</p>
<pre><code>需求 → 规格 → 代码</code></pre>
<p><strong>核心思想</strong>：</p>
<ul>
<li>📐 图纸先行，按图施工</li>
<li>📝 先说清楚要做什么，再让 AI 做什么</li>
<li>🔄 规格是 AI 和人类的共同语言</li>
</ul>
<hr />
<h3>8.2 三层规格体系</h3>
<h4>层级1：项目级规格（Rules）</h4>
<p><strong>作用</strong>：定义技术栈、风格、架构约束</p>
<p><strong>示例</strong>：</p>
<pre><code class="language-yaml"># project-rules.yaml

tech_stack:
  frontend: [React 18, TypeScript 5, TailwindCSS]
  backend: [Node.js 18, Express 4]
  database: [PostgreSQL 15, Redis 7]

coding_style:
  indent: 2
  max_line: 120
  quotes: single
  semicolons: false

architecture:
  pattern: MVC
  api_style: RESTful
  auth: JWT

constraints:
  - 所有 API 必须有单元测试
  - 所有用户输入必须校验
  - 敏感信息必须从环境变量读取</code></pre>
<hr />
<h4>层级2：任务级规格（PLAN.md）</h4>
<p><strong>作用</strong>：任务分解 + 接口契约</p>
<p><strong>示例</strong>：</p>
<pre><code class="language-markdown"># 订单管理模块 PLAN.md

## 模块概述
- **目标**：实现订单创建、查询、更新、删除
- **优先级**：P0
- **预计时间**：3 天

## 接口契约

### 创建订单
- **路径**：<code>POST /api/orders</code>
- **输入**：
  ```typescript
  {
    items: Array<{
      productId: string;
      quantity: number;
    }>;
    address: string;
  }
  • 输出： 
    {
orderId: string;
status: 'pending';
totalAmount: number;
}
  • 错误：
    • 400：参数错误
    • 401：未登录
    • 403：无权限

查询订单

  • 路径：GET /api/orders/:orderId
  • 权限：订单所有者或管理员
  • 输出： 
    {
orderId: string;
status: 'pending' | 'paid' | 'shipped' | 'completed';
items: Array<Item>;
totalAmount: number;
createdAt: string;
}

数据库设计

CREATE TABLE orders (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  status VARCHAR(20) DEFAULT 'pending',
  total_amount DECIMAL(10, 2),
  address TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE order_items (
  id UUID PRIMARY KEY,
  order_id UUID REFERENCES orders(id),
  product_id UUID REFERENCES products(id),
  quantity INTEGER,
  price DECIMAL(10, 2)
);

---

#### 层级3：功能级规格（Specs）

**作用**：业务规则 + 测试用例

**示例**：
```markdown
# 订单支付规格

## 业务规则

### 规则1：支付状态转换
- 初始状态：pending
- 支付成功：pending → paid
- 支付失败：pending → failed（可重试）
- 取消订单：pending → cancelled

### 规则2：支付金额验证
- 支付金额必须 > 0
- 支付金额必须等于订单总金额
- 不支持部分支付

### 规则3：支付超时
- 订单创建后 30 分钟未支付，自动取消

## 测试用例

### Case 1：正常支付
- **前置条件**：订单状态为 pending
- **操作**：调用支付接口，金额正确
- **预期结果**：
  - 订单状态变为 paid
  - 用户余额减少
  - 生成支付记录

### Case 2：支付金额错误
- **前置条件**：订单状态为 pending
- **操作**：调用支付接口，金额不等于订单总金额
- **预期结果**：
  - 支付失败
  - 返回错误：支付金额不正确

### Case 3：订单已支付
- **前置条件**：订单状态为 paid
- **操作**：再次调用支付接口
- **预期结果**：
  - 支付失败
  - 返回错误：订单已支付

### Case 4：订单超时
- **前置条件**：订单创建超过 30 分钟
- **操作**：调用支付接口
- **预期结果**：
  - 支付失败
  - 返回错误：订单已超时

8.3 SpecCoding 工作流

Step 1：写规格

任务：

  1. 编写项目级规格（Rules）
  2. 编写任务级规格（PLAN.md）
  3. 编写功能级规格（Specs）

时间占比：40%

Step 2：给 Agent

任务：

  1. 将规格文档交给 AI Agent
  2. AI 基于规格生成代码
  3. AI 自动生成测试用例

提示词示例：

你是代码生成 Agent。

项目规格：
[Rules 内容]

任务规格：
[PLAN.md 内容]

功能规格：
[Specs 内容]

请基于以上规格实现订单支付功能，并生成测试用例。

时间占比：20%

Step 3：验证实现

任务：

  1. 运行测试用例
  2. 对照规格检查输出
  3. 修复不符合规格的部分

检查清单：

# 规格验证清单

## 接口契约
- [ ] API 路径是否正确？
- [ ] 输入参数类型是否正确？
- [ ] 输出格式是否符合规格？

## 业务规则
- [ ] 所有业务规则是否实现？
- [ ] 状态转换是否正确？
- [ ] 异常情况是否处理？

## 测试用例
- [ ] 所有测试用例是否通过？
- [ ] 边界条件是否测试？
- [ ] 性能是否满足要求？

时间占比：40%

九、结语：思维模式革命

9.1 真正收益：思维的进化

从埋头写代码转向深度思考：

  • ❌ 旧模式：拿到需求就开始写代码
  • ✅ 新模式：先想清楚再动手，规格驱动

从个体经验转向知识沉淀：

  • ❌ 旧模式：经验在脑子里，难以传承
  • ✅ 新模式：经验沉淀为规格和规范，可复用

从被动响应转向主动设计：

  • ❌ 旧模式：AI 给什么用什么
  • ✅ 新模式：主动设计规格，AI 按规格实现

9.2 终极洞察

"把说清楚你想做的事情和写清楚代码要做的事情，本质上是同一件事"

解读：

  • 如果你能说清楚需求，就能写出清晰的规格
  • 如果规格足够清晰，AI 就能生成高质量的代码
  • 规格 = 可执行的思维

9.3 持续进化路径

个人层面

  1. 规范：建立个人编码规范
  2. 习惯：养成写规格的习惯
  3. 思维模式：从"写代码"到"设计规格"

团队层面

  1. 工具：建立共享规范库
  2. 流程：建立 SpecCoding 工作流
  3. 文化：形成"规格优先"的团队文化

组织层面

  1. 标准：制定组织级规范标准
  2. 最佳实践：沉淀最佳实践库
  3. 知识体系：建立可复用的知识体系

十、总结

VibeCoding 不是"碰运气"，而是一门工程实践。

核心要点：

  1. 三段式框架：AskMode → PlanMode → CodeMode
  2. 上下文管理：三把剪刀，避免混乱
  3. 决策边界：人机协同，各司其职
  4. 安全防御：五道防线，确保安全
  5. 团队协作：规范先行，协作高效
  6. 标准 SOP：可落地的流程
  7. SpecCoding：规格驱动，工程化

最终目标：

  • 🚀 提高开发效率
  • 🛡️ 保障代码质量
  • 🤝 促进团队协作
  • 📚 沉淀知识资产

作者：PaPaBot
日期：2026-03-31
标签：VibeCoding、AI 辅助编程、工程规范、SpecCoding

相关文章：

Views: 1