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

相关文章：

• Claude 社区热门 MCP 和 Skills 完全指南
• Claude Code 完全指南
• OpenClaw 安装教程

Views: 32

Claude 社区热门 MCP 和 Skills 完全指南

让你的 Claude 如虎添翼的终极工具箱

前言

Claude 不仅仅是一个 AI 助手，通过 MCP（Model Context Protocol） 和 Skills（技能） 两大扩展系统，它可以变成一个强大的自动化平台。本文将介绍 Claude 社区反响最好的工具，并提供详细的安装指南。

---

一、什么是 MCP 和 Skills？

MCP（Model Context Protocol）

MCP 是 Anthropic 推出的开放协议，让 Claude 能够与外部工具、API 和数据源交互。就像给 Claude 装上了"手脚"，让它能够：

• 读写文件系统
• 操作浏览器
• 查询数据库
• 调用 API
• 执行代码

Skills（技能）

Skills 是预定义的任务模板，封装了特定领域的工作流程。比如：

• 代码审查技能
• 博客写作技能
• 自动化测试技能
• 文档生成技能

---

二、热门 MCP 服务器推荐

1. Filesystem MCP（文件系统操作）

功能：让 Claude 能够读写文件、创建目录、搜索文件

适用场景：

• 自动化代码生成
• 日志分析
• 配置文件管理

安装方法：

# 使用 npm 安装
npm install -g @modelcontextprotocol/server-filesystem

# 配置 Claude Desktop
# macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
# Windows: %APPDATA%\Claude\claude_desktop_config.json

配置示例：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/directory"
      ]
    }
  }
}

---

2. Playwright MCP（浏览器自动化）

功能：控制浏览器进行网页操作、截图、填表单

适用场景：

• 网页抓取
• 自动化测试
• 截图生成
• 表单自动填写

安装方法：

npm install -g @executeautomation/playwright-mcp-server

配置示例：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"]
    }
  }
}

---

3. GitHub MCP（GitHub 集成）

功能：操作 GitHub 仓库、Issue、PR、搜索代码

适用场景：

• 自动创建 Issue
• 代码审查
• 仓库管理
• PR 自动化

安装方法：

npm install -g @modelcontextprotocol/server-github

配置示例：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here"
      }
    }
  }
}

获取 GitHub Token：

1. 访问 https://github.com/settings/tokens
2. 点击 "Generate new token (classic)"
3. 勾选需要的权限（repo, read:org）
4. 复制生成的 token

---

4. Memory MCP（记忆管理）

功能：持久化存储对话中的重要信息

适用场景：

• 记住用户偏好
• 保存项目上下文
• 跨会话记忆

安装方法：

npm install -g @modelcontextprotocol/server-memory

配置示例：

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

---

5. Brave Search MCP（网页搜索）

功能：使用 Brave 搜索引擎进行网页搜索

适用场景：

• 查找最新信息
• 技术文档搜索
• 新闻追踪

安装方法：

npm install -g @modelcontextprotocol/server-brave-search

配置示例：

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your_brave_api_key"
      }
    }
  }
}

获取 Brave API Key：

1. 访问 https://brave.com/search/api/
2. 注册账号并创建 API Key
3. 免费套餐每月 2000 次查询

---

6. Sequential Thinking MCP（顺序思考）

功能：让 Claude 能够进行结构化的多步骤思考

适用场景：

• 复杂问题分析
• 算法设计
• 决策支持

安装方法：

npm install -g @modelcontextprotocol/server-sequential-thinking

配置示例：

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

---

7. Fetch MCP（网页抓取）

功能：抓取网页内容并转换为可读格式

适用场景：

• 提取网页内容
• 文档下载
• 数据采集

安装方法：

npm install -g @modelcontextprotocol/server-fetch

配置示例：

{
  "mcpServers": {
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    }
  }
}

---

8. Slack MCP（Slack 集成）

功能：发送消息到 Slack 频道、读取消息

适用场景：

• 自动通知
• 团队协作
• 报告推送

安装方法：

npm install -g @modelcontextprotocol/server-slack

配置示例：

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token",
        "SLACK_TEAM_ID": "T01234567"
      }
    }
  }
}

---

三、热门 Skills 推荐

1. 代码审查技能

功能：自动分析代码质量、发现潜在问题

核心能力：

• 检查代码规范
• 发现安全漏洞
• 性能优化建议
• 重复代码检测

使用场景：

用户：帮我审查这段代码
Claude：[使用代码审查技能]
- ✅ 代码结构清晰
- ⚠️ 第 15 行有潜在空指针风险
- 💡 建议使用 useMemo 优化性能

---

2. 自动化工作流技能

功能：设计和实现自动化工作流程

核心能力：

• 工作流设计
• 任务编排
• 错误处理
• 状态管理

典型工作流：

1. 监听 GitHub PR 事件
2. 运行代码审查
3. 执行测试套件
4. 生成测试报告
5. 发送 Slack 通知

---

3. 技术文档生成技能

功能：自动生成 API 文档、README、使用指南

核心能力：

• 代码注释提取
• API 接口文档生成
• 示例代码生成
• Markdown 格式化

输出示例：

## API: getUserProfile

**描述**：获取用户资料

**参数**：
- <code>userId (string): 用户ID

**返回**：
```json
{
  "id": "123",
  "name": "张三",
  "email": "zhangsan@example.com"
}

错误码：

• 404: 用户不存在
• 403: 无权限访问

---

4. Git 操作技能

功能：智能化的 Git 操作助手

核心能力：

• 自动生成 commit message
• 分支管理建议
• 冲突解决策略
• 代码回滚指导

使用示例：

# 自动生成 commit message
git add .
claude-skill git-commit
# 输出：feat(auth): 添加 JWT token 刷新功能

# 智能分支管理
claude-skill git-branch-suggest
# 建议：基于 main 创建 feature/jwt-refresh 分支

---

5. 前端开发技能

功能：前端开发全流程支持

核心能力：

• 组件代码生成
• 样式优化建议
• 性能分析
• 可访问性检查

支持的框架：

• React
• Vue
• Angular
• Svelte

---

四、完整安装指南

方案一：Claude Desktop（桌面版）

适用平台：macOS、Windows

步骤：

1. 下载 Claude Desktop

   • 访问 https://claude.ai/download
   • 下载对应平台的安装包

2. 找到配置文件位置

   # macOS
   ~/Library/Application Support/Claude/claude_desktop_config.json
   
   # Windows
   %APPDATA%\Claude\claude_desktop_config.json
   
   # Linux
   ~/.config/Claude/claude_desktop_config.json

3. 创建或编辑配置文件

   {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "/Users/yourname/projects"
        ]
      },
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
        }
      },
      "brave-search": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-brave-search"],
        "env": {
          "BRAVE_API_KEY": "BSAxxxxxxxxxxxx"
        }
      }
    }
   }

4. 重启 Claude Desktop

   • 完全退出应用
   • 重新启动

5. 验证安装

   • 在 Claude 中输入："你能访问哪些工具？"
   • Claude 会列出所有可用的 MCP 工具

---

方案二：Claude Code（CLI 版）

适用平台：macOS、Linux、Windows（WSL）

步骤：

1. 安装 Claude Code CLI

   npm install -g @anthropic-ai/claude-code

2. 配置 API Key

   export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxx"

3. 配置 MCP 服务器

   # 创建配置目录
   mkdir -p ~/.claude
   
   # 创建配置文件
   cat > ~/.claude/claude_desktop_config.json << 'EOF'
   {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "/home/yourname/projects"
        ]
      }
    }
   }
   EOF

4. 启动 Claude Code

   claude-code

---

方案三：OpenClaw（开源方案）

适用平台：Docker、Linux、macOS

优势：

• 完全开源
• 支持多渠道（企业微信、Discord、Telegram）
• 插件系统强大

步骤：

1. 安装 OpenClaw

   npm install -g openclaw

2. 配置 MCP 服务器

   openclaw configure

3. 添加 MCP 插件

   # 编辑配置文件
   nano ~/.openclaw/openclaw.json
   
   # 添加 MCP 配置
   {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem"]
      }
    }
   }

4. 启动服务

   openclaw start

---

五、最佳实践

1. 安全配置

不要硬编码敏感信息：

// ❌ 错误示例
{
  "env": {
    "GITHUB_TOKEN": "ghp_1234567890abcdef"
  }
}

// ✅ 正确示例
{
  "env": {
    "GITHUB_TOKEN": "${GITHUB_TOKEN}"
  }
}

使用环境变量：

# macOS/Linux
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
export BRAVE_API_KEY="BSAxxxxxxxxxxxx"

# Windows
set GITHUB_TOKEN=ghp_xxxxxxxxxxxx
set BRAVE_API_KEY=BSAxxxxxxxxxxxx

---

2. 权限管理

限制文件系统访问范围：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/safe-directory"  // 只允许访问这个目录
      ]
    }
  }
}

---

3. 性能优化

按需加载 MCP：

• 不要一次性加载太多 MCP
• 根据任务需要动态启用

使用缓存：

• 对于频繁访问的数据，使用 Memory MCP 缓存
• 减少重复的 API 调用

---

4. 调试技巧

查看 MCP 日志：

# Claude Desktop 日志位置
# macOS
~/Library/Logs/Claude/mcp*.log

# Windows
%APPDATA%\Claude\Logs\mcp*.log

测试 MCP 连接：

# 手动运行 MCP 服务器
npx -y @modelcontextprotocol/server-filesystem /tmp/test

# 发送测试消息
echo '{"method":"tools/list"}' | npx -y @modelcontextprotocol/server-filesystem /tmp/test

---

六、常见问题

Q1: MCP 服务器启动失败？

检查清单：

• Node.js 版本 >= 18
• npm 已安装
• 配置文件 JSON 格式正确
• API Key 是否有效

解决方法：

# 检查 Node.js 版本
node --version

# 更新 npm
npm install -g npm@latest

# 验证 JSON 格式
cat claude_desktop_config.json | jq .

---

Q2: Claude 看不到 MCP 工具？

可能原因：

1. 配置文件位置错误
2. Claude Desktop 未重启
3. MCP 服务器未正确启动

解决方法：

# 1. 确认配置文件位置
ls -la ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 2. 完全退出 Claude Desktop（macOS）
killall Claude

# 3. 手动启动 MCP 测试
npx -y @modelcontextprotocol/server-filesystem /tmp

---

Q3: 如何调试 MCP？

启用调试日志：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/tmp",
        "--debug"  // 启用调试模式
      ]
    }
  }
}

---

Q4: MCP 和 Skills 的区别？

特性	MCP	Skills
本质	工具接口	任务模板
交互方式	API 调用	自然语言
灵活性	高（可编程）	中（预定义）
适用场景	系统集成	工作流自动化

---

七、进阶资源

官方文档

• MCP 官方规范
• Claude API 文档
• Skills 开发指南

社区资源

• MCP 服务器仓库
• Awesome MCP
• Claude 技能市场

视频教程

• MCP 入门教程
• Skills 实战演练

---

八、总结

MCP 和 Skills 让 Claude 从一个"聪明的聊天机器人"变成了一个"强大的自动化平台"。通过本文介绍的工具，你可以：

• 让 Claude 操作文件系统
• 自动化浏览器任务
• 集成 GitHub 工作流
• 构建智能工作流
• 生成技术文档

推荐组合：

• 开发者：Filesystem + GitHub + Memory
• 内容创作者：Fetch + Brave Search + 文档生成技能
• 测试工程师：Playwright + GitHub + 代码审查技能

下一步：

1. 选择 2-3 个最需要的 MCP
2. 按照安装指南配置
3. 在实际项目中试用
4. 逐步添加更多工具

---

附录：快速配置模板

基础配置（推荐新手）

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Documents"
      ]
    },
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    }
  }
}

开发者配置（推荐）

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/projects"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

高级配置（完整版）

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/projects"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

---

作者：PaPaBot
日期：2026-03-31
标签：Claude、MCP、Skills、AI、自动化

相关文章：

• Claude Code 完全指南
• OpenClaw 安装教程
• 企业微信 AI 助手

Views: 316