核心理念

① 意图驱动 Intent-Driven

说"想要什么"，不说"怎么做"。让 AI 利用项目上下文自主选择实现路径。

② 对话式迭代 Conversational

不是一次生成，而是多轮细化。每轮交互都建立在上一轮上。

③ 人机协作 Human-AI

人类管目标、架构、安全；AI 管语法、样板、修复。分工不同，缺一不可。

④ 渐进验证 Progressive

小步快跑，每次生成立即验证，而不是一次大段生成后统一测试。

下面正文按 意图驱动 → 迭代验证（综合"对话式迭代"与"渐进验证"）→ 人机协作 三条主线展开。

Vibe Coding 的有效实践建立在三个相互支撑的核心理念之上：意图驱动、迭代验证、人机协作。理解并内化这三个理念，是从"偶尔用 AI 生成代码"进化到"系统性高效 AI 开发"的关键。

理念一：意图驱动（Intent-Driven）

从"告诉 AI 怎么做"到"告诉 AI 要什么"

传统编程思维要求开发者在写代码前，脑子里已经有了清晰的实现路径。这种思维迁移到 AI 交互中，会产生过于具体、限制过多的提示词，反而束缚了 AI 的发挥。

意图驱动的核心转变是：描述"什么"（What），而非"如何"（How）。

低效的指令式提示：

写一个 async 函数 getUserById，参数是 id: string，
从 PostgreSQL 的 users 表中查询 id、name、email、created_at 四个字段，
使用 prisma client，如果找不到返回 null，如果出错 throw Error。

高效的意图式提示：

实现"根据 ID 获取用户"的功能，结合我们项目现有的 Prisma 设置，
返回用户基本信息，找不到时返回 null。

前者把实现细节全部规定死了，AI 只是一个代码转录工具。后者让 AI 利用已有的项目上下文（Prisma schema、现有的工具函数、错误处理惯例）自主生成最合适的实现。

意图的三个层次

有效的意图表达不是一句话，而是一个有层次的描述结构：

┌─────────────────────────────────────────────────┐
│  层次一：目标（Goal）                             │
│  "我想实现什么功能，解决什么问题"                  │
│  示例："实现用户邮件通知功能"                      │
├─────────────────────────────────────────────────┤
│  层次二：约束（Constraint）                       │
│  "有哪些不能违反的规则和边界"                      │
│  示例："使用现有的 EmailService，遵守用户通知偏好   │
│         设置，失败时不能影响主流程"                │
├─────────────────────────────────────────────────┤
│  层次三：偏好（Preference）                       │
│  "在满足约束的前提下，倾向哪种风格或方式"           │
│  示例："异步处理，失败时记录日志而非抛出异常"        │
└─────────────────────────────────────────────────┘

完整示例：

【目标】为订单完成事件添加邮件通知功能
【约束】
- 使用 src/services/EmailService.ts 中已有的 sendEmail 方法
- 必须读取用户的通知偏好（users.notification_preferences）
- 邮件发送失败不能影响订单完成的主流程
【偏好】
- 通知逻辑放在独立的 event handler 中，不要耦合在订单 service 里
- 失败时用 logger.warn 记录，不要 throw

这种三层结构的提示，能够让 AI 在保持方向正确的同时，发挥其在实现细节上的能力。

意图驱动的上下文工程

对于长期项目，意图不只存在于单次对话中，而是通过上下文文件持久化到整个项目中。这就是 Context Coding 的核心实践。

# CLAUDE.md（意图的项目级声明）

## 项目目标
这是一个 B2B SaaS 平台，核心目标是帮助中小企业管理销售线索。
代码应该优先保证数据完整性和操作可追溯性，而非追求最简洁的实现。

## 技术约束（不可违反）
- 所有数据变更操作必须写入 audit_log 表
- 金额相关字段统一使用整数（分）存储，不使用浮点数
- 外部 API 调用必须有超时设置（最长 10 秒）和重试逻辑

## 代码偏好
- 错误处理使用 Result 模式（见 src/lib/result.ts）
- 优先使用显式类型，减少 TypeScript 类型推断的依赖

理念二：迭代验证（Iterative Verification）

小步快跑，即时确认

迭代验证的本质是：每一步生成都要立即验证，而不是积累大量代码后统一测试。

这个原则看起来简单，但在实践中很容易被打破——当 AI 生成的代码看起来很合理时，人们往往倾向于继续要求更多功能，将验证推迟。这是 Vibe Coding 中最常见的陷阱之一。

反模式（危险）：

第一步：生成用户认证模块
第二步：生成订单管理模块（还没验证认证模块）
第三步：生成支付集成（还没验证订单模块）
第四步：生成通知系统（还没验证支付集成）
↓
发现问题：认证模块的 Token 处理有漏洞，
导致后续三个模块的权限检查全部依赖了错误的实现...

正确模式：

第一步：生成用户认证模块 → 运行验证 → 确认 Token 逻辑正确 ✓
第二步：生成订单管理模块 → 运行验证 → 确认权限检查生效 ✓
第三步：生成支付集成 → 运行验证 → 确认金额计算精度 ✓
第四步：生成通知系统 → 运行验证 → 确认失败不影响主流程 ✓

验证方法分级

不同类型的代码需要不同的验证手段，选择合适的验证方法能在效率和可靠性之间取得平衡：

验证方法	适用场景	成本	覆盖深度	示例
直接运行	所有场景的第一步	极低	浅（发现崩溃和明显错误）	node script.js、npm run dev
单元测试	纯函数、业务逻辑	低	深（覆盖各种输入情况）	Jest / Vitest 断言
集成测试	API 端点、数据库操作	中	中深（验证组件协作）	Supertest + 测试数据库
人工测试	UI 交互、复杂流程	中	依赖测试者经验	手动点击、模拟用户操作
CI 门禁	所有提交到主分支的代码	低（自动化）	全面（组合以上方法）	GitHub Actions、GitLab CI

渐进式积累策略

迭代验证的目标不只是发现当前的错误，更是建立一个随项目成长的可信任代码库。

迭代 1：生成基础 CRUD → 运行验证 → 积累 4 个通过的单元测试
迭代 2：添加分页功能 → 运行验证 → 测试套件增长到 9 个
迭代 3：添加搜索功能 → 运行验证 → 测试套件增长到 14 个
...
迭代 N：每次新功能的加入，都在原有测试套件的基础上扩展
         当出现回归问题时，自动测试会立即报警

这种模式下，代码库随时间推移变得越来越可靠，而不是越来越脆弱。

验证的反馈循环

当验证失败时，错误信息本身就是下一轮 AI 交互的输入，形成紧密的反馈循环：

生成代码
    ↓
运行验证
    ↓
[通过] → 继续下一步
[失败] → 将错误信息直接提供给 AI：
         "运行后出现以下错误，请修复：
          TypeError: Cannot read property 'id' of undefined
          at getUserById (src/services/user.ts:24)"
    ↓
AI 修复
    ↓
再次验证
    ↓
（循环直到通过）

这个循环的关键是：不要试图自己理解并手动修复错误，把错误信息给 AI。这正是 Vibe Coding 高效的地方——错误诊断和修复的认知负担由 AI 承担。

理念三：人机协作（Human-AI Collaboration）

各司其职，扬长避短

有效的人机协作不是"人类监督 AI"，也不是"AI 替代人类"，而是双方在各自擅长的领域发挥最大价值。

维度	人类的优势	AI 的优势
业务理解	理解真实的用户需求和业务背景	不了解业务背景，依赖人类提供
模式识别	识别架构问题、技术债务、代码坏味道	识别语法模式、生成符合规范的代码
创造性判断	做出权衡决策，选择最合适的方案	在给定约束下生成实现
代码生产	慢（受限于打字速度和认知负荷）	极快（秒级生成数百行代码）
知识广度	深度专业知识，但广度有限	广泛的编程知识，但缺乏深度专业化
安全意识	凭经验识别风险	需要明确指令才会关注安全
一致性	疲劳后质量下降	持续稳定（无疲劳效应）

协作工作流模型

高效的人机协作遵循一个清晰的职责分工模型：

┌──────────────────────────────────────────────────────────────┐
│                    Vibe Coding 协作模型                        │
├──────────────────────┬───────────────────────────────────────┤
│     人类的职责        │           AI 的职责                   │
├──────────────────────┼───────────────────────────────────────┤
│ 定义业务目标          │ 理解目标并生成实现方案                  │
│ 确定架构方向          │ 在架构约束内生成具体代码                │
│ 维护上下文文件        │ 遵循上下文文件中的规范                  │
│ 提出明确的意图        │ 将意图转化为可运行的代码                │
│ 运行和验证结果        │ 根据验证反馈修复问题                    │
│ 审查安全关键路径      │ 在人类审查前标记可能的风险点             │
│ 做出技术决策          │ 提供多个可能方案供人类选择              │
│ 管理项目长期方向      │ 执行当前会话的具体任务                  │
└──────────────────────┴───────────────────────────────────────┘

"信任但验证"原则

Vibe Coding 中最重要的心理态度是：对 AI 的输出保持专业的怀疑，但不陷入无谓的审查。

"信任但验证"（Trust but Verify）来自于苏联谚语，在冷战谈判中被里根总统引用。它描述的是一种务实的合作关系：在建立合作的同时，保持独立的验证机制。

在 Vibe Coding 语境中，这意味着：

信任（Trust）：

• 相信 AI 能够生成符合常见模式的正确实现
• 不必对每行代码进行人工理解，专注于行为验证
• 允许 AI 做出实现细节的决策

验证（Verify）：

• 运行所有生成的代码，不假设"看起来对"就是真的对
• 对安全关键代码进行有针对性的人工审查
• 建立自动化测试作为持续的"不信任但验证"机制

建立有效协作的实践

1. 提供充分的上下文

AI 的输出质量直接取决于输入上下文的质量。在每次会话开始时，确保 AI"了解"：

• 项目的技术栈和架构
• 当前任务的业务背景
• 已有的相关代码（通过文件引用或 CLAUDE.md）

2. 明确表达不满意

当 AI 的生成结果不符合预期时，不要接受"凑合能用"的代码。明确指出问题：

"这个实现有个问题：它在每次请求时都创建新的数据库连接，
应该使用连接池。请修改为使用 src/lib/db.ts 中的 prisma 单例。"

3. 引导 AI 自我批评

在提交到版本库之前，让 AI 对自己的输出进行审查：

"你刚刚生成了这段认证代码，请从安全角度审查它，
列出你能发现的所有潜在问题。"

这种自我审查往往能发现 AI 在初次生成时忽视的问题。

4. 保持主导权

协作的核心是人类始终保持对项目方向的主导权。当 AI 建议了一个你不认同的架构方向时，明确拒绝并说明原因——这不只是纠正当前生成，也是在训练这次会话的上下文，让后续生成更符合你的判断。

三个理念的相互关系

这三个理念并非孤立存在，而是相互支撑的有机整体：

意图驱动 → 为人机协作提供清晰的分工边界
    ↓              ↑
迭代验证 ←→ 人机协作中的验证职责由人类承担
    ↑              ↓
意图驱动 ← 验证结果反馈，精化下一轮的意图表达

• 意图驱动确保人类在方向上保持主导，AI 在实现上发挥能力
• 迭代验证确保每一步都建立在可靠基础上，错误不会积累
• 人机协作确保双方的优势都得到充分发挥，而非互相替代

当你在日常开发中遇到困惑时，回归这三个问题往往能找到答案：

1. 我有没有清楚地表达意图，而非过度指定实现？
2. 我有没有及时验证，而非积累未经验证的代码？
3. 我是在发挥人类的优势（判断、验证、方向），还是在做 AI 更擅长的事（手写样板代码）？

掌握这三个核心理念，是成为高效 Vibe Coding 实践者的关键一步。