Vibe Coding 实战手册

date: 2020/01/09
author: zone

[!abstract] 核心理念
AI 编程的本质不是「让 AI 写代码」，而是「让 AI 理解你想要什么」。
你的需求描述能力，决定了 AI 的输出质量。

一、注意力机制与上下文工程

为什么要理解这个？

不理解 AI 的工作原理，你就永远在瞎试。

很多人用 AI 编程的体验是：有时候特别好用，有时候特别蠢。这是因为你不知道它的「注意力」是怎么分配的。

注意力机制的本质

大语言模型基于 Transformer 架构，核心是 注意力机制（Attention）。

模型在生成每个字的时候，会「看」之前所有的内容，但不是平均地看，而是有重点地看。

你给 AI 的输入（上下文）：
┌─────────────────────────────────────────────────┐
│ 系统提示 │ 历史对话 │ 当前问题 │ 相关文件 │ ... │
└─────────────────────────────────────────────────┘
      ↓           ↓          ↓          ↓
   注意力权重分配（不均匀）
      ↓
   AI 的回答

[!important] 关键点
上下文越长，每个部分能分到的「注意力」就越少。

这就是为什么：

对话太长，AI 会「忘记」前面说的
一次塞太多需求，AI 会漏掉一些
重要信息放在中间，容易被忽略

上下文腐烂（Context Rot）

Anthropic 的工程团队提出了 Context Rot（上下文腐烂） 概念：

[!quote]
随着上下文窗口中 token 数量增加，模型准确回忆信息的能力会下降。

这不是 bug，是架构的固有限制。n 个 token 会产生 n² 个注意力关系，上下文越长，关系越稀疏。

上下文工程策略

问题	策略
上下文太长	定期开新对话，保持上下文干净
重要信息被稀释	把关键信息放在开头或结尾
AI「忘记」之前的约定	用 CLAUDE.md 固化重要规则
一次性需求太多	拆分成多个小任务

[!tip] 实战建议
把 AI 的上下文窗口想象成一个容量有限的工作台。东西太多就会乱，要定期清理。

二、提示词工程

提示词的本质

提示词不是「咒语」，是沟通协议。

你和 AI 之间的沟通，本质上和你跟一个新来的实习生沟通是一样的：

说清楚要做什么
说清楚怎么做
说清楚做成什么样

提示词的三层结构

┌─────────────────────────────────────────┐
│  第一层：角色设定（你是谁）              │
│  「你是一个资深的 React 开发者...」      │
├─────────────────────────────────────────┤
│  第二层：任务描述（做什么）              │
│  「实现一个用户登录功能...」             │
├─────────────────────────────────────────┤
│  第三层：约束条件（怎么做）              │
│  「使用 TypeScript，遵循项目现有风格...」│
└─────────────────────────────────────────┘

[!tip] 提示
Claude code已经内置了一份系统提示词，所以当我们使用的时候只需要输入第二层 + 第三层即可

CLAUDE.md：一劳永逸的提示词

Claude Code 有一个特殊文件叫 CLAUDE.md，启动时自动加载到上下文。

这相当于一次性把「角色设定」和「约束条件」固化下来，每次对话不用重复说。

[!example] CLAUDE.md 模板

# 项目：[项目名称]

## 技术栈
- 前端：React 18 + TypeScript + Tailwind CSS
- 后端：Node.js + Express + Prisma
- 数据库：PostgreSQL

## 代码规范
- 组件使用函数式写法，不用 class
- 异步操作用 async/await
- 错误处理用 try-catch，不要静默失败
- 变量命名：camelCase，组件命名：PascalCase

## 项目结构
- /src/components - 可复用组件
- /src/pages - 页面组件
- /src/hooks - 自定义 hooks
- /src/utils - 工具函数
- /src/api - API 调用

## 重要约定
- 所有 API 响应统一格式：{ success, data, error }
- 表单验证使用 zod
- 状态管理使用 zustand
- 不要安装新依赖，除非我明确要求

思考模式关键词

Claude Code 支持不同级别的思考深度，通过关键词触发：

关键词	思考深度	适用场景	建议使用频率
（不加）	快速响应	简单修改	20%
`think`	基础思考	常规功能	30%
`think hard`	深度思考	需要设计的功能	35%
`think harder`	更深思考	复杂逻辑	10%
`ultrathink`	最深思考	架构决策	5%

[!tip] 经验之谈
宁可多花 30 秒让它想清楚，也不要花 30 分钟改它的烂代码。

三、无歧义需求描述

歧义是效率杀手

最常见的问题就是：需求描述有歧义。

你说「做个登录功能」，AI 可能给你：

只有用户名密码的简单登录
带手机验证码的登录
带第三方 OAuth 的登录
以上全部

然后你说「不对」，它改一版，还是不对，再改，还是不对……时间就这么浪费了。

SMART-C 框架

要素	含义	示例
Specific	具体	不说「登录」，说「邮箱+密码登录」
Measurable	可衡量	「密码至少8位，包含大小写和数字」
Actionable	可执行	「使用 bcrypt 加密，JWT 生成 token」
Restricted	有约束	「不要用第三方登录库」
Testable	可测试	「登录成功跳转 /dashboard，失败显示错误」
Context	有上下文	「参考现有的 /api/register 接口风格」

实战对比

[!failure] 差的描述
帮我做个用户管理功能

[!success] 好的描述
实现用户管理模块，包含以下功能：

1. 用户列表页

表格展示：ID、用户名、邮箱、角色、创建时间、状态

支持分页，每页 20 条

支持按用户名、邮箱搜索

支持按角色、状态筛选

2. 用户详情/编辑

点击用户名进入详情页

可编辑：用户名、邮箱、角色、状态

不可编辑：ID、创建时间

保存后返回列表页

3. 技术要求

使用现有的 /api/users 接口

表格用 shadcn/ui 的 Table 组件

表单验证用 react-hook-form + zod

4. 参考

样式参考现有的 /admin/products 页面

API 调用方式参考 src/api/products.ts

需求描述模板

## 功能：[功能名称]

### 用户故事
作为 [角色]，我希望 [做什么]，以便 [达到什么目的]

### 功能点
1. [功能点1]
2. [功能点2]
3. ...

### 界面要求
- [布局要求]
- [交互要求]
- [样式参考]

### 技术要求
- [使用的技术/库]
- [接口规范]
- [性能要求]

### 边界情况
- [异常情况1如何处理]
- [异常情况2如何处理]

### 验收标准
- [ ] [标准1]
- [ ] [标准2]

四、验证效果

核心理念

[!note] Vibe Coding 的核心
你不需要理解代码，你只需要验证结果。

验证流程

AI 生成代码
    ↓
能跑起来吗？ ──否──→ 让 AI 修
    ↓是
功能对吗？ ──否──→ 描述问题，让 AI 改
    ↓是
边界情况对吗？ ──否──→ 补充边界情况，让 AI 处理
    ↓是
通过 ✓

快速验证清单

验证项	怎么验证
能编译	`pnpm build` 不报错
能运行	页面能打开，不白屏
主流程通	核心功能点一遍
边界情况	空数据、错误输入、网络错误
响应式	手机尺寸看一眼

整个过程不超过 5 分钟。

让 AI 自己写测试

[!tip] 高效做法
让 AI 写完功能后，再让它写测试。
1
2
3
4
5
6
为刚才实现的用户登录功能编写单元测试，覆盖以下场景：
1. 正常登录成功
2. 密码错误
3. 用户不存在
4. 账户被锁定
5. 输入格式错误
然后跑测试，测试不过就让它改。这比你手动点点点高效多了。

五、代码审查

要不要看代码？

原则：平时不看，关键时刻看。

场景	要不要看
普通 CRUD	不看
核心业务逻辑	看关键部分
安全相关（认证、支付）	仔细看
性能敏感	看并优化
上线前	让 AI 做一次全面审查

让 AI 审查代码

与其自己看，不如让 AI 审查：

审查 src/api/auth.ts 文件，检查以下方面：
1. 安全漏洞（SQL注入、XSS、CSRF）
2. 错误处理是否完善
3. 边界情况是否覆盖
4. 代码是否符合项目规范
5. 有没有性能问题

列出所有问题，并给出修复建议。

上线前安全审查

[!warning] 上线前必做

think hard 对整个项目做安全审查，重点检查：
1. 认证和授权逻辑
2. 敏感数据处理（密码、token）
3. API 接口安全
4. 前端 XSS 防护
5. 依赖包的已知漏洞

给我一份安全审查报告。

六、Bug 定位与修复

正确姿势

出 bug 了怎么办？不要自己去翻代码。

正确的做法是：把 bug 的所有信息喂给 AI，让它定位和修复。

Bug 报告模板

## Bug 描述
[一句话描述问题]

## 复现步骤
1. [步骤1]
2. [步骤2]
3. [步骤3]

## 期望行为
[应该发生什么]

## 实际行为
[实际发生了什么]

## 错误信息
[粘贴完整的错误日志/控制台输出]

## 环境信息
- 浏览器：Chrome 120
- 操作系统：macOS
- 相关文件：src/pages/Login.tsx

实战对比

[!failure] 差的 bug 报告
登录不好使了，帮我看看

[!success] 好的 bug 报告
Bug：登录时页面无响应

复现步骤

打开 /login 页面

输入正确的邮箱和密码

点击登录按钮

期望行为
跳转到 /dashboard

实际行为
按钮变成 loading 状态后一直转圈，没有跳转，也没有错误提示

控制台错误
1
2
POST http://localhost:3000/api/auth/login 500
Uncaught (in promise) Error: Request failed with status 500
网络请求
Response: {“error”: “Cannot read property ‘password’ of undefined”}

复杂 Bug 的渐进式调试

第一轮：让 AI 分析可能的原因
> 分析这个 bug 可能的原因，列出 3-5 个最可能的原因，按可能性排序

第二轮：逐个排查
> 先检查第一个可能性：[xxx]，在相关代码中加入日志，帮我定位

第三轮：确认并修复
> 确认是 [xxx] 的问题，修复它，并确保不影响其他功能

让 AI 解释代码

如果你实在需要理解某段代码：

解释 src/utils/auth.ts 中的 validateToken 函数：
1. 这个函数做了什么
2. 输入和输出是什么
3. 有哪些边界情况处理
4. 可能出问题的地方

比自己读代码快 10 倍。

七、常用技巧

技巧一：分而治之

不要一次提一堆需求。

一次一个功能，做完一个再做下一个。原因前面讲过：上下文有限，塞太多会「注意力分散」。

推荐节奏：

一个功能 = 一轮对话
一轮对话 = 描述需求 → 生成 → 验证 → 微调
大功能完成后，开新对话

技巧二：先让 AI 读文件

开新对话时，先让 AI 建立上下文：

阅读以下文件，理解项目结构和现有代码风格：
- src/App.tsx
- src/components/Layout.tsx
- src/api/index.ts
- src/types/index.ts

读完后告诉我你的理解。

这样后续的代码生成会更符合项目风格。

技巧三：用「参考」来约束风格

1	实现一个 ProductCard 组件，参考现有的 UserCard 组件的风格和结构

比你描述半天「要怎么怎么样」有效得多。

技巧四：让 AI 先出方案

复杂功能不要直接让 AI 写代码，先让它出方案：

think hard 关于如何实现订单系统，我需要：
- 订单创建、支付、发货、完成的完整流程
- 订单状态机
- 库存扣减逻辑

先给我一个设计方案，不要写代码。包括：
1. 数据库表设计
2. API 接口设计
3. 核心流程图
4. 需要注意的边界情况

方案确认后再让它实现，避免返工。

技巧五：保存好用的提示词

建立一个提示词库：

# 我的提示词库

## 代码审查
> 审查 [文件] 的代码质量，检查...

## Bug 修复
> 这个功能出现了问题...

## 重构
> 重构 [文件]，目标是...

## 性能优化
> 分析 [功能] 的性能问题...

好用的提示词是可以复用的。

八、高级技巧

Plan 模式

当你面对复杂任务时，可以让 AI 先制定计划：

我需要实现一个完整的电商后台系统，包括：
- 商品管理
- 订单管理
- 用户管理
- 数据统计

think harder 制定一个详细的实施计划，包括：
1. 任务拆解（按优先级排序）
2. 每个任务的预估工作量
3. 任务之间的依赖关系
4. 建议的实施顺序

不要写代码，只要计划。

AI 会给你一份详细的项目计划。然后你可以：

1	好的，按照这个计划，我们先做第一个任务：[任务名]

这样大项目也能有条不紊地推进。

[!tip] 经验之谈
Claude code 使用 Shift+Tab 可切换模式 Edit \ Plan

多文件协同修改

当修改涉及多个文件时：

这个功能需要修改以下文件，请一起修改，确保一致性：
- src/types/user.ts（添加新字段）
- src/api/user.ts（更新接口）
- src/pages/UserProfile.tsx（更新界面）
- src/components/UserForm.tsx（更新表单）

修改内容：给用户添加「部门」字段

让 AI 模拟用户测试

假设你是一个普通用户，测试刚才实现的注册流程：
1. 列出你会尝试的所有操作（包括正常和异常）
2. 预测每个操作的结果
3. 找出可能的问题

这能帮你发现很多边界情况。

渐进式重构

老代码需要重构时：

我需要重构 src/utils/helpers.ts，这个文件太大了（500行）。

请：
1. 分析这个文件的功能分类
2. 建议如何拆分成多个小文件
3. 给出拆分后的文件结构
4. 一个一个地执行拆分，每次拆分后确保项目能正常运行

上下文恢复

对话太长需要开新会话时，如何恢复上下文：

我们之前在做 [项目名] 的 [功能名]。

当前进度：
- [x] 已完成：[列表]
- [ ] 进行中：[当前任务]
- [ ] 待完成：[列表]

请先阅读以下文件恢复上下文：
- [相关文件列表]

然后我们继续 [当前任务]。

让 AI 写文档

项目完成后：

为这个项目生成以下文档：

1. README.md
   - 项目介绍
   - 技术栈
   - 本地开发指南
   - 部署指南

2. API 文档
   - 所有接口的请求/响应格式
   - 认证方式
   - 错误码说明

3. 数据库文档
   - 表结构说明
   - 字段说明
   - 关系图

速查表

思考模式关键词

关键词	场景
`think`	常规功能
`think hard`	需要设计的功能
`think harder`	复杂逻辑
`ultrathink`	架构决策

CLAUDE.md 必备内容

# 技术栈
# 代码规范
# 项目结构
# 重要约定
# 常用命令

[!tip] 经验之谈
如果是现存项目可使用 /init 生成

需求描述 SMART-C

Specific - 具体
Measurable - 可衡量
Actionable - 可执行
Restricted - 有约束
Testable - 可测试
Context - 有上下文

Bug 报告模板

## Bug 描述
## 复现步骤
## 期望行为
## 实际行为
## 错误信息
## 环境信息

FAQ

[!faq]- 中文好用吗？
非常好用，全程用中文没问题。

[!faq]- 团队怎么协作？
每个人独立使用，代码合并还是用 Git。可以共享 CLAUDE.md 保持风格统一。

[!faq]- 会取代程序员吗？
不会。但会用 AI 的程序员会取代不会用的。

[!faq]- 学习曲线陡吗？
不陡。会写需求文档，就会用 AI 编程。

[!quote] 结语
这是一个沟通能力比编码能力更重要的时代。