核心原则
Vibe Coding 有 5 大核心原则。掌握了这些，你在任何 AI 编码工具上都能高效工作。
原则 1：Intent > Syntax（意图优先于语法）
核心思想： 你关注"做什么"，AI 关注"怎么写"。
这是 Vibe Coding 的根基。你的价值不再体现在语法熟练度上，而是体现在意图表达的清晰度上。
意图表达的三个层次
| 层次 | 描述 | 示例 |
|---|---|---|
| 模糊意图 | 只说目标，不给约束 | "帮我加个登录功能" |
| 具体意图 | 目标 + 约束 + 上下文 | "在 auth 模块加 JWT 登录，token 过期时间 24h，错误用 AppError 包装" |
| 精确定义 | 目标 + 约束 + 文件 + 格式 | "在 src/auth/login.ts 添加 JWT 登录端点。约束：用 zod 验证输入，token 存 cookie，过期 24h。不改测试文件。完成后跑 npm test" |
越具体的意图，AI 输出越精确，审查越轻松。模糊意图让 AI 自行决策，审查负担更大。
模糊意图何时可接受？
- 探索阶段：你还没想清楚具体方案，让 AI 先生成几版草稿
- 简单任务：格式化、加注释等低风险操作
但任何进入代码库的最终版本，都必须经过你的审查确认。
原则 2：迭代验证（Iterate & Verify）
核心思想： 小步快跑，每步验证。
不要让 AI 一口气生成整个模块。拆成小步骤，每步完成后验证。
为什么迭代比一次性生成更好？
| 一次性生成 | 迭代生成 |
|---|---|
| 生成 10 个文件 → 你审查 10 个文件 → 发现第 3 个有问题 → 回去修 → 影响后面的文件 | 生成 2 个文件 → 审查 → OK → 再生成 2 个 → 审查 → OK |
| 错误在后面才发现，前面的代码可能基于错误的前提 | 错误立即发现和修正，后续步骤基于正确前提 |
| 上下文窗口被大量生成内容占满 | 上下文窗口保持干净 |
迭代验证的标准流程
1. 描述一个子任务（2-3 个文件的变更）
2. 让 AI 执行
3. 审查输出——确认方向正确
4. 运行测试——确认功能正确
5. 提交 checkpoint——保存进度
6. 进入下一个子任务每个迭代都是一个checkpoint。如果后面发现问题，你可以精确回退到某个 checkpoint，而不是从头重来。
原则 3：人做守门员（Human as Gatekeeper）
核心思想： AI 生成，人批准。任何进入代码库的代码都必须经过你的审查。
什么时候必须审查？
| 场景 | 是否必须审查 | 原因 |
|---|---|---|
| 添加新功能 | 必须 | 确认实现与意图一致 |
| 修复 bug | 必须 | 确认修复不引入新问题 |
| 重构代码 | 必须 | 确认行为不变 |
| 加注释/文档 | 可免审查 | 低风险，但建议扫一眼 |
| 格式化/lint 修复 | 可免审查 | 低风险，可 Auto-Accept |
审查的关键点（不是逐行审查）
不要试图逐行审查 AI 生成的每一行代码——那比手写还累。重点审查：
| 审查维度 | 关注什么 |
|---|---|
| 架构一致性 | 是否符合项目的架构约定？ |
| 边界处理 | null/undefined/空数组/错误场景是否处理？ |
| 安全 | 是否有注入、泄露、未授权访问风险？ |
| 隐含假设 | AI 做了什么你没要求的决策？ |
| 测试覆盖 | 关键逻辑是否有对应测试？ |
原则 4：上下文纪律（Context Discipline）
核心思想： 管理上下文窗口，不让无效信息拖垮 AI 质量。
AI 的工作质量直接取决于它接收到的上下文质量。上下文窗口是有限的——你填满垃圾，AI 就在垃圾中推理。
上下文纪律的三条规则
规则 1：引用文件，不要粘贴代码
用 @file 引用让 AI 在需要时读取，不要把大段代码粘贴到对话中。粘贴占满上下文窗口，AI 后续推理质量下降。
规则 2：保持 CLAUDE.md 稳定且精炼
CLAUDE.md 每次会话自动加载。内容越精炼，Prompt Caching 越容易命中，成本越低。不要把"写好代码"这种废话写进去，写具体约束（"API 路由用 Zod 验证输入"、"错误用 AppError 包装"）。
规则 3：定期 /compact
长会话中对话历史膨胀，AI 的推理质量下降。每完成一个子任务就 /compact 一次，释放上下文空间。
上下文垃圾的典型症状
| 症状 | 原因 | 对策 |
|---|---|---|
| AI 反复做同一件事 | 上下文中充满了失败尝试的回响 | /compact + 重新描述任务 |
| AI 遗忘了之前的约束 | 对话太长，早期约束被压缩掉了 | 把约束写进 CLAUDE.md |
| AI 答非所问 | 上下文中有大量无关文件内容 | 用 .claudeignore 排除无关文件 |
原则 5：决策留痕（Document Decisions）
核心思想： 每个重要决策都要留下记录，不只留在对话历史里。
对话历史会丢失（新会话、/compact、上下文压缩）。如果你在会话 A 中做了一个关键决策，会话 B 的 AI 不知道这个决策，可能做出矛盾的决策。
什么需要留痕？
| 类型 | 记录到哪里 | 示例 |
|---|---|---|
| 项目约定 | CLAUDE.md | "用命名导出，不用默认导出" |
| 架构决策 | decision-log.md | "选择 SQLite 而非 PostgreSQL，因为单用户本地部署" |
| 任务计划 | plan.md / tasks.md | "先做数据模型，再做 API 层" |
| AI 偏好 | MEMORY.md | 自动维护——你纠正 AI 时它会记住 |
| 方案选择 | spec.md | "需求：CRUD + 优先级筛选，约束：Python 无外部依赖" |
决策留痕的核心格式
## 决策：[标题]
**选择：** [做了什么选择]
**Why：** [为什么做这个选择——这是最重要的部分]
**How to apply：** [在什么场景下应用这个决策]
**被否决的方案：** [考虑了但没选的方案] — 原因：[为什么不选]写 Why 是关键——未来你或 AI 需要判断"这个决策在当前情况下是否仍然有效"。只有知道当初为什么做这个选择，才能判断是否需要改变。
原则之间的协同
5 个原则不是孤立的，它们构成一个完整的工作系统：
Intent > Syntax（意图清晰）→ AI 输出精确 → 审查负担小
迭代验证（小步快跑）→ 每步可控 → 错误不会累积
人做守门员（审查批准）→ 代码质量可控 → 不会引入意外问题
上下文纪律（管理窗口）→ AI 推理质量高 → 减少"理解偏差"
决策留痕（记录 Why）→ 跨会话一致性 → AI 不会做矛盾决策