Vibe Coding 实战手册（V1.5）

规划驱动 × 迭代循环 × Git 留痕 × 工程化返工 的 AI 编程方法论 适用对象：任何想用 AI 从 0 做出可用产品的人（无需先会写代码，但需会描述清楚） 本版新增：① Git 基线纪律（每次操作必 commit、禁止删除、删/覆盖需申请权限）② 操作透明日志（每次操作写本地 OPERATIONS.md，AI 禁止黑盒）③ 部署与上线（产品落地）④ 全旅程问题排雷手册（从想法到落地的所有坑 + 解法 + 提示词）

0. 怎么用这本手册

这本手册不是理论，是操作说明书。你按页码走，每一步都明确三件事：

• 下一步干什么（行动）
• 哪一步最关键（别跳）
• 每一步盯着什么别翻车（避坑）

图标约定：

• 🎯 这一步最关键 / 决策点 —— 跳不过去
• ⚠️ 要盯紧的风险
• 📋 模板 / 可直接抄的提示词或命令
• ✅ 该步骤的交付清单（打勾用）
• 🚫 绝对禁止的行为（红线）

1. 总览：从「想法」到「落地」的全流程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

┌─────────────────────────────────────────────────────────────┐
│  阶段零  Git 基线纪律 + 操作透明日志  Git Baseline              │
│  🎯最关键：从有想法第一天就建仓库；每次操作必 commit + 写日志； │
│  禁止删除；删除/覆盖须申请权限；AI 操作全程透明，禁止黑盒。      │
└───────────────────────────┬─────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  阶段一  设想与规划  Envision & Plan                          │
│  🎯最关键：地基。需求/UI/后端/测试全敲定 + 准入闸门才许写码。 │
│  交付：需求摘要·PRD·方案·UI图·质量准则·测试策略+闸门          │
└───────────────────────────┬─────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  阶段二  开发初始原型  Develop Initial Prototype              │
│  原则：小步快跑。按 PRD 生成骨架 + 一个核心功能               │
└───────────────────────────┬─────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  阶段三 & 核心循环  迭代开发  Iterative Development            │
│  ↻ 提示 → 生成 → 🎯审查 → 优化 → 重复                        │
│  + 每批结束做 自我审计 (Self-Audit) + 安全返工(4.7)            │
└───────────────────────────┬─────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  阶段四  部署与上线  Deploy & Launch（产品落地）              │
│  原则：密钥不上库、环境变量分离、上线自检、可回滚              │
└─────────────────────────────────────────────────────────────┘

贯穿全程：每个动作 → Git commit 留痕 + 写进本地操作日志（OPERATIONS.md）；删除/覆盖 → 先申请权限；AI 操作全程透明，禁止黑盒。
遇到问题 → 翻第 7 节「全旅程问题排雷手册」对号入座。

阶段速查表：

2. 阶段零：Git 基线纪律 + 操作透明日志（一切动作之前）🎯

这是 V1.5 的两条核心铁律。从「你有了一个想法」的第一天就建仓库 + 建本地操作日志——在写任何代码、甚至写任何规划文档之前。后面所有阶段都建立在这两条纪律上：① Git 留痕 ② 操作透明（禁止黑盒）。

核心原则

每一次操作都留痕，任何一步翻车都能 pinpoint + 回滚。AI 永远没有「毁尸灭迹」的能力。

具体三条铁律：

1. 每次操作必 commit：规划文档定稿、原型每批、每次迭代、每次修复，做完立刻 git commit。
2. 🚫 禁止删除：AI 不得执行任何删除文件 / 删除分支 / 清空目录 / git reset --hard 的操作。
3. 删除 / 覆盖须申请权限：任何「删除」或「覆盖已有文件」的动作，AI 必须先向你申请，说明要删/覆盖什么、为什么、影响哪些功能，等你明确同意后才执行。

🎯 为什么这是地基

Vibe Coding 最大的隐忧是「AI 改着改着把之前好的东西弄没了，你还不知道哪步出的事」。Git 纪律把这事变成不可能：

• 每步有 commit → 出事能 git revert 精确回退到上一个好状态，不用人肉查上万行。
• 禁止删除 + 覆盖需授权 → AI 不能「顺手」把你写好的代码删掉或整文件覆盖。
• 留痕本身也是一种「审计」，你能一眼看出项目每天长成什么样。

📋 启动命令（直接抄，项目第一天跑一次）

1
2
3
4

# 在项目根目录
git init
git add -A
git commit -m "init: 项目初始化 + 规划文档"

📋 日常纪律：每次操作后的提交（让 AI 或你自己照做）

1
2
3
4

git add -A
git commit -m "feat: 完成登录模块骨架"      # 新功能用 feat:
# fix: 修复解析逻辑   docs: 更新 PRD   refactor: 重构订单服务
git tag v0.1-prototype                      # 关键里程碑打 tag，方便回滚

⚠️ 提交信息要能让人看懂这次改了啥。千万别用 git commit -m "update" 这种糊弄写法——回滚时你分不清哪个是好的。

📋 回滚命令（出问题时）

1
2
3

git checkout -- .            # 撤销「还没提交」的改动（回到上次 commit）
git revert <commit号>         # 安全撤销「已提交」的某次改动（生成反向 commit，不丢历史）
git checkout <tag名>          # 回到某个里程碑，例如 git checkout v0.1-prototype

🚫 AI 行为红线（写进 CLAUDE.md / .cursorrules / 项目规则，让 AI 自动遵守）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

你在本项目中的 Git 纪律 + 透明日志（务必遵守）：
1. 每次改动后必须执行 git add -A && git commit -m "<类型>: <说明>"，不得跳过。
2. 绝对禁止执行删除类命令：rm / del / git reset --hard / 删除分支 / 整文件覆盖。
3. 任何「删除文件」或「覆盖已有文件」的操作，必须先向用户申请权限，说明：
   - 要删 / 覆盖的具体文件
   - 为什么必须这么做
   - 会影响哪些功能
   等用户明确回复「可以」后才执行。
4. 优先用「局部新增 / 局部修改」代替「删除重来」。
5. 每次 commit 信息要能让人看懂这次改了啥，方便日后回滚。
6. 每次操作（改动前/后）必须向用户简短汇报，并追加一条记录到本地日志文件
   OPERATIONS.md（格式：时间 / 动作 / 文件 / 改动摘要 / 原因 / 结果）。
   禁止「静默改完不说明」的黑盒操作。
7. 日志文件本身也要 git commit 进仓库。

✅ 阶段零交付清单

• 项目已 git init
• 规划文档已首次 commit
• 已把上面的「AI 行为红线」写进项目规则文件（CLAUDE.md / .cursorrules）
• 已建本地日志文件 OPERATIONS.md，AI 红线含「每次操作写日志」条款
• 你清楚：每次操作 = 一次 commit + 一条日志；删/覆盖 = 必须先问你

阶段零其二：操作透明日志（AI 操作完全透明，禁止黑盒）🎯

与 Git 纪律并列的第二条铁律。光有 commit 还不够——commit 只记录「代码变了」，不记录「AI 为什么变、动了哪、结果如何」。透明日志补上这层。

核心原则

每一次操作（AI 改了什么文件、哪段、为什么、结果如何）都立即写进本地日志文件（如 OPERATIONS.md 或 logs/operations.log），AI 操作完全透明，不允许黑盒。

具体要记三件事：

1. 做了什么：改了 / 新增了 / 删除了（删需先申请）哪些文件，关键改动摘要。
2. 为什么：基于哪条需求 / 哪个报错 / 哪次反馈。
3. 结果如何：跑通了 / 有残留问题 / 待你确认。

🎯 为什么这条最关键

黑盒操作 = 你不知道 AI 动了哪里，出事无法定位、无法向人解释、也无法复盘学习。透明日志把每一步变成可审计、可追责、可学习的记录——既是安全网，也是你自己的「项目日记」。

⚠️ 关注

• 日志要结构化（时间 / 动作 / 文件 / 改动摘要 / 原因 / 结果），别只写「改了代码」。
• 每次操作后立即追加，不事后补（事后容易忘、容易美化）。
• 日志文件本身也要 git commit 进仓库（它也是项目资产）。

📋 本地日志格式模板（直接抄，每次操作追加一条）

1
2
3
4
5
6
7

## [2026-08-20 21:10] 操作：实现登录模块骨架
- 动作：新增
- 文件：src/auth/login.py, tests/test_login.py
- 改动摘要：新增 login() 函数，含输入校验；补充对应单元测试
- 原因：阶段二 批次1（按 PRD 核心功能第 2 条）
- 结果：本地测试通过；待你 review
- commit：feat: 登录模块骨架

📋 写进 AI 行为红线（与 Git 纪律同文件，规则 6、7）

1
2
3
4

6. 每次操作（改动前/后）必须向用户简短汇报，并追加一条记录到本地日志文件
   OPERATIONS.md（格式：时间 / 动作 / 文件 / 改动摘要 / 原因 / 结果）。
   禁止「静默改完不说明」的黑盒操作。
7. 日志文件本身也要 git commit 进仓库。

✅ 本步（透明日志）交付

• 已建本地日志文件 OPERATIONS.md（或 logs/operations.log）
• AI 红线已含「每次操作写日志」条款
• 你清楚：每次操作 = 一次 commit + 一条日志
• 日志文件已随项目 commit 进仓库

⚠️ 阶段零没建仓库 / 没建日志纪律，不允许进入阶段一写码。这是硬门槛。

3. 阶段一：设想与规划（Envision & Plan）

核心原则

规划先行，文档驱动。 别一上来就让 AI 写代码。在敲下第一行代码之前，需求、UI 图、后端逻辑、测试策略、质量准则全部要先在文档里敲定。你和 AI 都拿着同一份文档干活，后面才不会各说各话——代码只是把文档「翻译」成可运行的产物。

🎯 为什么阶段一最关键

这是整条流水线的地基。地基歪了，后面盖得越快塌得越快。大量 Vibe Coding 项目死在「做着做着发现需求没想清」——而这份代价在阶段一花 1 小时写文档就能避开。

阶段一先由 AI 反问澄清需求（步骤 1.1），再按顺序产出 6 份文档（步骤 1.2~1.6）：

步骤 1.1 需求澄清：让 AI 反问你（阶段一入口）

做什么：你只抛一个模糊想法（「我想做个 XX」），让 AI 扮「需求分析师 + 技术顾问」，反过来一个个问你，把开发细节全挖清：UI 长啥样、用什么技术栈 / 框架、架构怎么搭、怎么交付、做到什么算合格、每个细节具体怎么做。直到 8 个维度全部确认，才输出《需求锁定摘要》放行。

🎯 最关键：这是整个项目的「信息采集入口」。用户（尤其不懂技术的）脑子里的需求是模糊的，不反问就写码 = 做出来不是他要的。AI 反问的质量，直接决定后面 PRD 的质量——这一步省了，后面全返工。

⚠️ 关注：

• 一次别问太多（1~3 个），否则用户懵。
• 用户说「不懂 / 不知道」，AI 要给推荐 + 理由，不是把问题原样甩回去。
• 必须覆盖 8 个维度（目标 / 功能 / UI / 技术栈 / 架构 / 交付 / 验收 / 约束），缺一不可，全确认了才能进下一步。

📋 提示词模板（阶段一第一步，直接发给 AI）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

你现在是我的「需求分析师 + 技术顾问」。我（用户）只有一个模糊的想法，几乎不懂技术。你的任务不是写代码，也不是直接给方案，而是**通过反问，把我脑子里的需求彻底挖清楚**，直到你能完整描述"要开发什么、怎么开发、做到什么算合格"。

你的工作方式：
1. 我每说一句，你先简短确认你理解的部分，然后只针对当前最缺口的一块提问（一次 1~3 个问题，别一上来甩 20 个）。
2. 遇到我不懂的词（如"前端框架""API""数据库"），先用一句话大白话解释，再给 2~3 个可选项让我挑，并说明每个选项的利弊和适合什么人。
3. 如果我答"不知道"，你就给推荐 + 理由，让我确认或改。
4. 把已确认的信息实时整理成「已锁定」清单回显给我，让我能看到进度。

你必须挖清楚的维度（逐项覆盖，缺一不可）：
- 目标与场景：给谁用？解决什么具体痛点？在哪用（网页 / 手机 / 桌面）？
- 核心功能：必须有的 3~5 个功能，每个一句话。哪些"暂时不要"？
- UI / 交互：大概长什么样？参考哪个现有产品？操作主流程是什么？
- 技术栈 / 框架：前端、后端、数据库分别用什么（不懂就你推荐）。要不要部署上线？部署到哪？
- 架构：数据从哪来（用户输入 / 第三方 / 爬虫）？要不要登录账号体系？
- 交付形式：我要的是可运行网站 / 可安装包 / 源码 / 还是先要个 demo？
- 验收标准：做到什么程度算"合格"？有没有性能指标（速度 / 并发）？
- 约束：时间、预算、必须合规的点（隐私 / 版权）？

结束条件（重要）：
只有当上面 8 个维度全部有明确结论且我确认过，你才输出一份《需求锁定摘要》（结构化），并明确告诉我："需求已敲定，可以进入 PRD 撰写 / 下一步。"
在此之前，不要写任何代码，不要直接给完整方案，专注把问题问完。

✅ 交付清单：

• 8 个维度全部问到且用户确认
• 输出了《需求锁定摘要》
• AI 明确说「可以进入下一步」
• 用户对摘要无异议
• 本步产出已 git commit（docs: 需求锁定摘要）

步骤 1.2 产出产品需求文档（PRD）

做什么：和 AI 协作，把项目说清楚。

🎯 最关键：验收标准必须写死——「做到什么程度算完」。这是后面所有迭代的标尺。

⚠️ 关注：别写「做一个好用的 XX」，要写「用户能 XX，响应 < 2 秒，支持 100 并发」。模糊的需求 = 无限的返工。

📋 PRD 提示词模板（直接喂给 AI）：

1
2
3
4
5
6
7

请基于以下信息帮我写一份 PRD：
- 项目名：
- 解决谁的什么问题：
- 核心功能（3-5 条，每条一句话）：
- 技术约束（必须 / 禁止）：
- 验收标准（可量化，每条可测）：
- 明确不在范围内（排除项）：

✅ 交付清单：

• 用途说清了
• 核心功能列了 3-5 条
• 验收标准可量化
• 范围边界划了（什么不做）
• 本步产出已 git commit（docs: 完成 PRD）

步骤 1.3 技术方案与架构设计

做什么：让 AI 在写码前先给架构计划——技术栈、数据模型、模块划分、安全策略。

🎯 最关键：让 AI 「先出计划，你批准才写码」（research → plan → implement）。你卡的是「计划对不对」，不是「代码长啥样」。

⚠️ 关注：数据库变更、第三方依赖、密钥怎么存——这些提前定，别等代码生成了再返工。

📋 提示词模板：

1
2
3
4
5
6
7
8

基于上面的 PRD，给出技术方案：
1. 推荐技术栈及理由
2. 后端逻辑：核心 API / 接口契约、数据流、关键业务规则（先写清逻辑，暂不写实现）
3. 数据库表 / 数据模型设计（如有）
4. 模块划分与职责
5. 安全策略（鉴权、密钥、输入校验）
6. 实现计划（拆成可执行的批次，标顺序）
请先只给方案与逻辑，不要写代码，等我确认。

✅ 交付清单：

• 技术栈定了
• 数据模型清晰
• 安全策略有
• 实现计划拆成批次了
• 本步产出已 git commit（docs: 技术方案）

步骤 1.4 线框图与 UI/UX

做什么：让 AI 先出 UI 图（ASCII 线框或可视化草图），把界面布局和交互流程定下来，写码前就对齐「长啥样」。能用图形工具出真实 mockup 更好。

🎯 最关键：在写码前对齐「长啥样」，避免做出来不是你要的。

⚠️ 关注：聚焦核心页面，别一上来画 20 个页。先把主流程跑通。

📋 提示词模板：

1
2
3
4

基于 PRD，画出核心流程的线框图（ASCII 即可）：
- 页面1：XXX，含哪些元素、按钮去哪
- 交互：用户点 A → 发生 B
只画主流程，先不画边缘情况。

✅ 交付清单：

• 核心页面布局定了
• 主交互流程清楚了
• 本步产出已 git commit（docs: UI 线框图）

步骤 1.5 质量准则

做什么：定义编码标准、安全实践、测试策略——写成一份「准则文档」。

🎯 最关键：这份准则后面迭代时反复用，让 AI 每次都按同一套标准写，不用你每轮重复说。

⚠️ 关注：明确「禁止硬编码密钥」「必须有错误处理」「函数要 docstring」等硬规矩。

📋 质量准则模板：

1
2
3
4
5

本项目质量要求：
- 编码：函数有 docstring + 类型注解；不用魔法数字
- 安全：密钥走环境变量；用户输入必须校验；防注入
- 测试：核心逻辑有单元测试；每次迭代后跑测试
- 风格：中文注释；错误处理不吞异常

✅ 交付清单：

• 编码标准写了
• 安全硬规矩写了
• 测试要求写了
• 本步产出已 git commit（docs: 质量准则）

步骤 1.6 测试策略与验收用例

做什么：在写码前，让 AI 把「怎么证明做对了」定下来——测试策略 + 具体验收用例（每个核心功能一条可判定的检查）。

🎯 最关键：没有验收用例，「做完」就没有标准，AI 很容易「看起来能跑但其实没满足需求」。先定测试，后写码，等于先画靶再射箭。

⚠️ 关注：

• 验收用例要可量化、可自动判定（如「提交空表单应报错」），别写「功能正常」。
• 区分单元测试（逻辑）和端到端测试（用户走通主流程）。

📋 提示词模板（喂给 AI）：

1
2
3
4
5
6
7
8

基于 PRD 和质量准则，给出测试策略：
1. 单元测试：列出核心逻辑模块及每个要覆盖的边界（空输入、超长文本、并发等）。
2. 端到端用例：写 3~5 条主流程验收用例，每条格式：
   - 前置条件：
   - 操作：
   - 预期结果（可判定对错的）：
3. 验收门槛：所有端到端用例通过 + 单元测试绿，才算该模块"合格"。
请只给策略与用例，不要写测试代码，等我确认。

✅ 交付清单：

• 单元测试覆盖点列了
• 端到端验收用例写了 3~5 条
• 验收门槛定义了
• 本步产出已 git commit（docs: 测试策略）

步骤 1.7 代码准入闸门（写码前最后一关）

做什么：开工写码前，逐项打勾。任何一项没完成、没确认，不准进阶段二。

🎯 最关键：这是「规划驱动」的硬边界。闸门一开，后面代码只是执行文档，不再做决策。

✅ 准入清单（全绿才许写码）：

• 1.1 需求锁定摘要：8 维度全确认
• 1.2 PRD：验收标准可量化
• 1.3 技术方案：技术栈 / 后端逻辑 / 架构定了
• 1.4 UI 图：界面与交互对齐
• 1.5 质量准则：编码 / 安全 / 风格硬规矩写了
• [质量准则已含安全/测试要求，见 1.5 / 1.6]

✅ 准入清单（续，含 Git 与确认）：

• Git 仓库已初始化，阶段零纪律已落实（AI 红线写进项目规则）
• 用户对以上全部无异议

闸门全绿 = 可以进入阶段二写码。任何一项飘红，回到对应步骤补齐，不要带着疑问写码。

✅ 阶段一总交付：需求锁定摘要（1.1）+ PRD（1.2）+ 技术方案（1.3）+ UI 图（1.4）+ 质量准则（1.5）+ 测试策略（1.6），六项齐了 + 准入闸门（1.7）全绿，才进阶段二。

4. 阶段二：开发初始原型（Develop Initial Prototype）

核心原则

小步快跑。 目标不是「一次做全」，是「核心概念快速跑通」。注意：此时需求、UI、后端逻辑、测试策略都已在阶段一敲定，代码只是把文档翻译成可运行产物，不是边写边想。

⚠️ Git 纪律 + 透明日志提醒：阶段零已建仓库与日志。之后每个批次做完立刻 commit，并追加一条操作日志到 OPERATIONS.md，留可回滚记录——这是后面 5.7 安全返工的前提。禁止删除；覆盖需申请权限；AI 操作须透明。

步骤 2.1 分步实施

做什么：把阶段一的实现计划拆成小批次，让 AI 每次只做一个模块 / 一个功能。

🎯 最关键：每批可独立验证——做完这一批你能立刻看到 / 测到结果。

⚠️ 关注：批次之间要有清晰接口，别让 AI 同时改十个文件。

💡 技巧：第一批只搭骨架（项目结构 + 空模块 + 能启动），第二批再加第一个真实功能。

✅ 每批交付：一个能运行 / 能验证的增量 → 立刻 git commit（feat: 批次说明）。

步骤 2.2 避免「大跃进」

做什么：拒绝「一次性生成整个应用」。

🎯 最关键：小批量生成 = 高质量 + 易审查。一次 2000 行代码，你根本 review 不动，错了也找不出。

⚠️ 关注：如果 AI 一次吐出太多，打断它：「先只做 X，剩下的下一批」。

✅ 阶段二交付：一个能启动、核心功能跑通的最小原型。不用完美，能用就行 → git tag v0.1-prototype。

5. 阶段三 & 核心循环：迭代开发（Iterative Development）

这是 Vibe Coding 的心脏。每个功能点都走这个闭环：

1
2
3

提示(Prompt) → 生成(Generate) → 🎯审查(Review) → 优化(Refine) → ↻重复(Repeat)
                                      │
                                      └─ 每批结束 → 自我审计(Self-Audit) → 安全返工(5.7)

⚠️ Git 纪律 + 透明日志提醒：每完成一个功能点 / 一批改动，立即 git commit，并追加一条操作日志到 OPERATIONS.md。禁止删除；任何覆盖已有文件的操作先申请权限；AI 操作须透明。

步骤 5.1 提示（Prompt）

做什么：清晰描述要生成 / 改进的功能，给足上下文（贴 PRD 相关段、当前代码、报错）。

🎯 最关键：上下文给足 = 输出质量翻倍。AI 不知道你脑子里的东西。

⚠️ 关注：一次只说一件事；别在一条提示里塞五个不相关的改动。

📋 提示词模板：

1
2
3
4

基于质量准则和当前代码，请实现：<具体功能>
上下文：<贴相关代码 / PRD 段落>
约束：<必须 / 禁止>
验收：<做完怎么测>

步骤 5.2 生成（Generate）

做什么：AI 产出代码。

🎯 最关键：让 AI 解释它改了什么、为什么——你后面审查（5.3）要用。

⚠️ 关注：生成后先别急跑，先看一眼它说改了哪。

步骤 5.3 审查（Review）🎯 开发者核心价值

做什么：仔细阅读 AI 生成的代码——这是你作为人的不可替代环节。

🎯 最关键：这一步决定项目死活。不审查 = 把控制权全交出去 = 埋雷。

审查三件事：

1. 正确性：逻辑对吗？边界情况处理了？
2. 效率：有死循环 / 重复计算 / N+1 查询吗？
3. 安全性：密钥硬编码？输入没校验？依赖不存在 / 有漏洞？

⚠️ 关注：AI 会「自信地」写错——编造不存在的 API、函数名拼错、漏错误处理。

✅ 审查清单：

• 逻辑正确，边界处理了
• 没有明显性能问题
• 无硬编码密钥 / 凭证
• 用户输入有校验
• 依赖真实存在
• 错误信息不被吞

步骤 5.4 优化（Refine）

做什么：根据审查结果改提示词或直接改代码，让 AI 按反馈重做。

🎯 最关键：反馈要具体——「登录失败没提示」比「登录有问题」有用 10 倍。

⚠️ 关注：改完再走一遍 5.3 审查，别以为改一次就对了。

步骤 5.5 重复（Repeat）

做什么：每完成一个功能点，回到 5.1，做下一个。

🎯 最关键：保持小闭环节奏，别贪多。一个功能点干净了再下一个 → 每点完成 git commit 一次。

步骤 5.6 自我审计（Self-Audit）

做什么：每完成一批（不是每个功能，是一批），让 AI 自己对照检查清单审一遍。

🎯 最关键：这是「双人复核」——你审一遍，AI 再审一遍，漏网之鱼少很多。

📋 提示词模板：

1
2
3
4
5
6

请对照以下清单自我审计刚才这批改动：
- 是否引入了硬编码密钥
- 是否有未处理的异常
- 是否符合质量准则里的编码标准
- 是否有死代码 / 重复代码
逐条给出：通过 / 有问题 + 位置。

⚠️ 关注：Self-Audit 不能替代人工审查（5.3），它是补充，不是替代。

✅ 阶段三每轮交付：一个通过审查 + 自审的功能增量，且测试仍全绿 → git commit。

步骤 5.7 安全返工：手术式干预 + 架构级回滚

做什么：当项目变大（上万行）、改出问题时，用「精准干预 + 架构级回滚」代替「从头改 / 全量覆盖」。核心原则：绝不直接改全量代码，只给 AI 提供「上下文切片」。

🎯 最关键：面对大代码库，返工死穴是「把全量代码喂给 AI 让它修」——上下文窗口有限，AI 会失焦、幻觉、顺手改坏好代码。正确姿势是「打点 → 定位 → 切片 → 嫁接 → 必要时重铸」。

⚠️ 关注：

• 第一反应永远是「打分支存原点」，不是「动手改」。
• AI 返回的修复，永远用 Diff 逐块接受，不整文件覆盖。
• 底层架构错了，别硬改代码，回阶段一改方案重铸。
• 🚫 禁止 git reset --hard / 删文件 / 整文件覆盖；需要覆盖先申请权限。

五步流程：

① 紧急止血：立即创建检查点（Save Point） 发现重大错误，第一件事打分支，把当前状态（即使有错）完整保存。

1
2

git checkout -b fix/rollback-attempt     # 新分支存原点
git add -A && git commit -m "checkpoint: 返工前快照"

这样你毫无心理负担地试错，随时 git checkout 主分支 回退到原点。

② 精准定位「病灶」，而非「全身」（Localize） 别对 AI 说「帮我修整个项目」。根据报错日志手动定位 1~3 个具体文件 / 函数，只把这几个文件 + 其依赖的接口定义复制出来喂给 AI。

③ 「反向提示词」与「定向手术」（Surgical Prompt） 提示词遵循 「保留 - 排除 - 约束」 结构：

• ❌ 错误示范：「这段代码报错，帮我改了。」
• ✅ 正确示范（📋 直接抄）：

1
2
3
4
5

我要修复 `src/utils/parser.ts` 中的解析逻辑错误。
- 保留：其他所有文件和数据库结构不变。
- 只修改：`parseData` 函数内部的循环逻辑。
- 不要重写：任何外部接口。
请输出修改后的完整函数代码。

④ 嫁接修复（Grafting），而非合并（Merging） AI 返回后，不要直接全量覆盖原文件。用 IDE 的 Diff 工具逐块接受；大文件只把 AI 生成的核心函数片段复制进去，手动调周边依赖。这样 AI 就算幻觉，也污染不到好代码。

🚫 若必须替换整个文件，先向用户申请权限并说明原因，获批后再操作。

⑤ 极端情况：架构级错误（大返工） 如果错误是底层数据模型 / 架构选型导致的（如 SQLite 必须换 PostgreSQL），千万不要手动改代码。正确流程：回退到阶段一 PRD，修改技术方案 → 清空当前代码目录（保留备份）→ 用新架构约束提示词让 AI 重新生成骨架 → 复用之前写好、无错的工具函数和 UI 组件（直接拷贝），只让 AI 重写核心业务逻辑层。这叫「保留零件，重铸引擎」。

🛡️ 防反工黄金法则（写进日常）： 每完成一个独立功能点（如登录、支付），立即让 AI 生成该模块的单元测试。下次修改前先跑一遍测试——红了一大片的，说明本次改动出问题，立刻回滚本次修改（git revert），比人肉查上万行快一万倍。

✅ 本步交付：一个经 Diff 嫁接、测试仍绿的修复；必要时一份更新后的阶段一技术方案 → git commit。

6. 阶段四：部署与上线（产品落地）🎯

从「本地能跑」到「真用户能用」的一步。很多项目死在这里：本地好好的，一上线就崩，或者密钥泄露。

核心原则

密钥不上库、环境可分离、上线可自检、出事可回滚。 部署不是「把文件传上去」，是把阶段一~三的所有成果安全地交给真实用户。

⚠️ Git 纪律 + 透明日志提醒：每次部署 / 配置改动后立即 git commit，并追加一条操作日志到 OPERATIONS.md（含「改了哪个平台配置 / 为什么 / 结果」）。禁止删除；任何覆盖先申请权限；AI 操作须透明。

步骤 6.1 选部署形态

做什么：按阶段一的需求定平台。

🎯 最关键：选错了平台后面迁移很痛（见 7 节「架构选错」）。阶段一就该定。

步骤 6.2 密钥与环境变量分离（🚫 红线）

做什么：所有密钥（API Key、数据库密码、Token）只存在环境变量 / 平台密钥管理里，绝对不进 Git 仓库。

🎯 最关键：一旦密钥进仓库并 push，就等于公开——必须立刻注销密钥（见 7 节「密钥泄露」）。

⚠️ 关注：

• 本地用 .env 文件，且 .env 必须写进 .gitignore。
• 云端在平台后台配环境变量，不写在代码里。

📋 命令（把 .env 挡在仓库外）：

1
2

echo ".env" >> .gitignore
git add -A && git commit -m "chore: 忽略 .env，密钥不入库"

步骤 6.3 构建与上线

做什么：按平台流程构建并发布。能用 CI（自动构建 + 测试通过才上线）最好。

⚠️ 关注：上线前确认测试全绿（阶段三的单元 + 端到端）。

📋 上线前自检清单（直接抄）：

1
2
3
4
5
6

- [ ] 本地跑通全部测试（单元 + 端到端）
- [ ] 无硬编码密钥（grep 一遍 API_KEY / password / secret）
- [ ] .env / 密钥已在平台配置
- [ ] 数据库已迁移且备份
- [ ] 有「上一个可部署版本」可回滚（git tag 或平台回滚点）
- [ ] 域名 / HTTPS 配置好（如需要）

步骤 6.4 监控与回滚

做什么：上线后盯日志 / 报错；一旦大面积异常，立刻回滚到上一个好版本。

📋 回滚命令：

1
2

git checkout <上一个好tag>        # 本地回退
# 平台通常有「回滚到上次部署」按钮，优先用平台的

✅ 阶段四交付：线上可访问 + 密钥安全 + 有回滚预案 → git tag v1.0-launch。

7. 全旅程问题排雷手册（问题 → 原因 → 解决 → 提示词/命令）

从「有想法」到「产品落地」全程会踩的坑，按阶段归类。遇到事先翻这里对号入座，别瞎改。

7.1 阶段一（规划）常见问题

7.2 阶段二（原型）常见问题

7.3 阶段三（迭代）常见问题

7.4 阶段四（部署/落地）常见问题

🔴 专框：密钥泄露应急流程（遇到立刻做）

1
2
3
4
5
6

① 第一时间去对应平台（云厂商 / API 提供方）注销或重置该密钥。
② 确认密钥是否已被 push 到远程仓库：
   - 是 → 从 Git 历史彻底清除（git filter-repo / BFG），并通知协作者重拉。
   - 否（仅本地）→ 从代码中删除，确认未提交。
③ 生成新密钥，只配置在环境变量 / 平台密钥管理，绝不进仓库。
④ 在 .gitignore 加 .env，并补一条阶段零红线到项目规则。

⚠️ 安全意识：涉及 API key 等敏感信息，第一反应是「是否已推送 → 怎么撤回 → 要不要去注销密钥」。宁可多此一举，不可泄露一次。

8. 里程碑检查点

9. 常见陷阱速查

10. 一句话总结

Vibe Coding = 规划先行（文档驱动） + 小步原型 + 提示→生成→审查→优化→重复的闭环 + 每批自审 + 工程化返工；而这一切都建立在两条铁律上——Git 留痕、操作透明（每次操作写本地日志、禁止黑盒）、禁止删除、删/覆盖先申请权限。

你值钱的地方不在「打字」，在 规划 和 审查——这两步跳不掉；而 Git 纪律，是你敢于让 AI 大步往前走的底气。