Vibe Coding Survival Skill for Claude

开发避坑与自救：贯穿全程的纪律

这是 vibe-coding-kit 里贯穿整个开发过程的 Skill。前面几个 Skill 是"开工前想清楚"，但 Vibe Coding 真正翻车，大多发生在"开工后"。下面这些不属于某个阶段，要在整个开发过程里持续做。对不写代码的人来说，这几件事比任何技术选型都重要。

> 配套：vibe-coding-requirements（需求）、vibe-coding-architecture（选型）、vibe-coding-production（上线）。

> 流程角色： 本 skill 是 harness.json 里的 always_on——不占流水线某一阶段，而是全程在跑。它和账本（docs/进度账本.md）的关系有两条：① 卡住、改坏、改不动时，把问题记进账本的「阻塞项」；② 红线（动钱 / 动别人隐私）是硬提示，一旦触及，不管在哪个阶段都要停下来提醒用户找真人把关——这条优先级高于"按门推进"。

一、贯穿全程的四件事

1. 管理好和 AI 的对话（最易忽略，却最致命）

AI 在长对话里会"忘事"——聊久了它会忘记早先的决定、自相矛盾，甚至改坏之前好的部分。对策：

• 维护一份项目说明书（见第三节），每开一个新对话，先把它整段贴进去。
• 一个功能做完、对话变得又长又乱时，果断开新对话，别恋战。
• 重要决定（选了什么技术、定了什么规则）随手记进说明书，别只存在对话里——对话会丢、会乱、会被你关掉。

2. 守住范围（别让 demo 越长越大）

做着做着冒出"要不再加个……"，AI 每次都说行，于是越加越多、越来越脆，最后全盘崩掉。对策：

• 准备一个"以后再说"清单。新点子先记进去，不打断当前这件事。
• 当前这件事彻底做好、能用了，再回头看清单，挑真正值得的做。一次只推进一件事。

3. 保住能用的版本（别把唯一能跑的版本改坏）

非技术用户最痛的事：改着改着坏了，又退不回去，之前能用的也没了。对策：

• 每当一个版本"能正常用"，就完整复制一份存好（比如把整个文件夹复制成 项目-2024-06-能用版）。
• 之后再大胆改也不怕，坏了就从备份拿回来。
• 懂 git 的话用 git 更专业；但对不写代码的人，"复制整个文件夹"是最朴素可靠的保险，别嫌土。

4. 让 AI 证明给你看（别轻信"我做好了"）

AI 经常很自信地说"已完成"，但实际没跑通——它不是骗你，是它自己也没真运行过。对策：

• 每次它说做好了，就追问："我怎么自己验证它真的好了？给我具体步骤。"
• 然后你亲手按步骤跑一遍。没亲眼看到它在你这儿跑通，就别当它做完了。

二、⚠ 红线：这些情况，请找真人工程师把关

有些事，一个不写代码的人靠 AI 单干风险太高，一个 bug 就可能是真金白银或法律责任。碰到下面这些，强烈建议找一个懂行的人帮你过一遍，别全压在 AI 身上：

• 真实收付款 / 动到钱：自己接支付、转账、扣费、管钱。出错就是真实损失。
• 存别人的个人信息：手机号、身份证、住址、聊天记录等。这涉及隐私和法律合规，做错可能违法。
• 出错有真实后果的场景：医疗、安全、合同、关键业务等。
• 要给很多人用、且一旦挂掉影响很大的系统。

> 会判断"哪些我能自己搞定、哪些该收手找人"，本身就是行家的一部分。能看懂架构（见 vibe-coding-architecture）会让这个判断更准。

三、📄 你的项目说明书（把一切串起来）

各个 Skill 的产出，汇总进一个文档，这就是你的"项目说明书"。它有两个作用：① 让你随时看得懂自己的项目；② 每开新对话先整段贴给 AI，直接解决"AI 忘事"。

完整可复制的模板见仓库 examples/项目说明书-模板.md。骨架：

【项目说明书】
· 一句话：这个项目是做什么的
· 需求基准描述：……
· 选定技术栈：…… / 为什么选它
· 目录结构：……
· 开发规范要点：……
· 安全清单：……
· 部署步骤：……
· 验收清单：……
· "以后再说"清单：……
· 当前进度 / 还剩什么没做：……
· 能用版备份在哪：……

让 AI 帮你维护它：

> "每次有重要改动，提醒我该更新项目说明书的哪一部分。"

关键原则速查（全套件通用）

| 原则 | 含义 |

|------|------|

| 需求没说清，等于没说 | AI 会朝着模糊的方向飞速跑偏 |

| 先说问题，再说方案 | 描述方案会锁死 AI，描述问题才有更优解 |

| AI 会忘事 | 长对话里它会丢失上下文，靠项目说明书兜底 |

| 一次只推进一件事 | 范围一散，项目就脆 |

| 先备份，再动手 | 永远留一个能用的版本可退回 |

| 没亲眼跑通，就不算做完 | 别轻信 AI 的"已完成" |

| 复杂度是负债 | 每引入一个组件，都是在向未来借债 |

| 你有权说不 | AI 推荐的任何东西都是可选的 |

| 没有代价的方案不存在 | 不讲代价的推荐不可信 |

| 维护成本是最终裁决 | 一年后修不修得动，比什么都重要 |

| 懂"为什么"才算懂 | 用 6 维度拷问、追问取舍，把每个项目变成一次升级 |

| 动钱和动别人隐私，先找人 | 这两条红线别独自硬上 |

救急话术

| 场景 | 话术 |

|------|------|

| AI 忘事了 | （开新对话）"这是我的项目说明书，请基于它继续：……" |

| demo 不对 | "我做了 X，看到的是 Y，但我期望的是 Z，怎么回事？" |

| 报错了 | "这是完整报错（贴上），帮我看怎么回事，用大白话说。" |

| 验证 | "我怎么自己验证它真的好了？给我具体步骤。" |

| 改坏了 | （从"能用版"备份恢复，然后）"我们从这个能用的版本重新来，这次只改 X。" |

| 记进度 | "每次有重要改动，提醒我该更新项目说明书的哪一部分。" |

输出格式硬约束（交付前必检）

> 以下约束来自项目治理配置 harness.json 和 CLAUDE.md。

> 在声称"完成"之前，你必须逐条确认。

必须产出的内容

• [ ] docs/项目说明书.md 中「以后再说清单」已存在（可以暂时为空，但不能缺这一节）
• [ ] docs/项目说明书.md 中「能用版备份在哪」建议填写
• [ ] docs/项目说明书.md 中「当前进度 / 还剩什么没做」建议填写（与 docs/进度账本.md 的当前阶段/步骤对得上）

硬性检查

• [ ] 「以后再说清单」这一节存在（标题可见）
• [ ] 如果开发中冒出了新点子，已记入「以后再说」而不是直接动手加功能
• [ ] 至少做过一次"能用版"备份，且路径已记入项目说明书

自检完成声明

全部通过后声明：

"✅ 硬约束自检通过：以后再说清单已建立，范围已守住，能用版备份已记录。"