跳转至

第二课：Vibe Coding 基本功 —— 从"随缘编程"到"可控共创"

一、开篇：为什么你的 vibe coding 总是翻车？

先做一个简单的自检：过去一周，你有多少次对 AI 说"不对，我要的不是这个"？

如果超过 5 次，说明你正在经历 vibe coding 的第一阶段——随缘编程。你大概听说过"用自然语言写代码"的宣传，于是你打开 Claude Code，把脑子里模糊的想法一股脑扔进去，等着魔法发生。有时候魔法确实发生了，但更多时候，你发现自己在一个死循环里：AI 理解偏了 → 你纠正 → AI 过度修正 → 你继续纠正 → 算了，手写吧。

这不是你的问题，也不是 AI 的问题。问题在于你还没有学会和 AI 协作的语言。

我们这节课要解决的，就是这件事。学完之后，你应该能做到：

  • 用一句话让 Claude Code 输出你想要的结果，而不是"差不多"的结果
  • 掌握一套结构化的协作框架，让大项目不再失控
  • 让你的 AI 搭档真正理解项目，而不是每次对话都从零开始

二、先装一个后视镜：Statusline

在进入核心方法论之前，我们先解决一个"不知道自己不知道"的问题。

你用 Claude Code 的时候，有没有想过：现在在哪个分支？上下文还剩多少？当前工作目录在哪？

这些信息在你敲下每一条指令的时候都应该看到。Claude Code 支持自定义 statusline，在终端底部固定显示关键状态。

alt text

配置方式

复制以下prompt给claude code，大体意思就是你给我配置个statusline，在claude code界面的底部告诉我当前 git 分支、工作路径、剩余 context window 百分比。

/statusline

# Claude CLI Status Line Script Prompt

**Purpose:** Write a shell script to be used as a `statusline` handler in Claude CLI code configuration.

**Input:** The script receives a JSON object (from stdin) containing:
- Current working directory
- AI model name  
- Context window remaining percentage

**Output:** A two-line formatted status display that includes all essential information.

---

## Visual Design Goals

Create an attractive status line that feels professional and is easy to scan. The display should:
- Show user and host information (retrieved from system)
- Display the active Git branch (retrieved from filesystem)  
- Identify the current AI model being used
- **Prominently display the remaining context window as a percentage** ← This is essential
- Show the current working directory
- Use a subtle color palette that differentiates sections without being loud

---

## Layout Requirements

**First line:** User info, Git branch, model identifier, and a visual progress indicator showing remaining context
**Second line:** The full path of the current working directory

---

## Robustness Requirements

- Gracefully handle missing information (no Git repo, missing JSON fields, etc.)  
- Use terminal-safe Unicode characters with ASCII fallbacks where needed
- All special characters and colors should work reliably across different terminal environments
- Handle edge cases like very long paths or unusual characters in filenames
- Use safe output techniques to prevent interpretation issues

---

## Key Constraint

**The context window percentage must be clearly visible and updated in real-time.** This is the primary metric users need to monitor. Choose an appropriate visual representation (progress bar, percentage number, or both).

---

## Delivery Format

Write the complete, production-ready script that can be immediately configured in Claude CLI's code settings under the `statusline` configuration option. The script should be self-contained and require no external dependencies beyond standard Unix tools.

Include brief inline comments explaining sections if needed, but keep the code clean and maintainable.

刷新后，终端底部就会出现一行固定信息：当前 git 分支、工作路径、剩余 context window 百分比。

这件事为什么重要？ 因为 Claude Code 的 context window 是有限资源。就像开车需要看油表和倒后镜一样，你在做 vibe coding 的时候需要持续监控上下文余量。当 context 快耗尽时，你的 AI 搭档会开始"遗忘"早期指令，行为会变得不稳定——这就是很多"之前还好好的，后来就崩了"的根因。

番外：Git —— 把存档交给你的副驾驶

上一节你看到了 statusline 上的 git 分支信息。你可能会想：我要学 git 吗？

在传统软件开发中，git 是必修课——clone、branch、merge、rebase……一堆命令等着你背。但在 vibe coding 里，你不操作 git，你只需要告诉 AI 你想干什么：

你想做的事 对 Agent 说
看看 AI 改了什么 "帮我看看上次改了哪些文件，总结一下核心改动"
回退到某个状态 "回退到改 XXX 之前的状态"
保存当前进度 "存个档，我接下来要试一个新方向"
理解项目怎么变成这样的 "这个文件最近有哪些改动，为什么改的？"

Agent 能读 git 历史，用自然语言输出变更摘要，甚至画出一棵可视化的 history tree——这比任何 Git GUI 都友好，因为 GUI 仍然要求你会读 diff、会看 commit graph。

你甚至不需要主动要求。每次 AI 动手改代码之前，让它自动：

git add -A && git commit -m "checkpoint: before <即将做的事>"

改完满意就保留，不满意就一句"回退到刚才的存档"——比游戏里的 Save/Load 还简单。

你只需要记住一件事：把 commit 当成游戏存档，而不是交付物。 存档不需要完美，存档只需要在翻车时能救你一命。

三、显化你的需求：把阴阳翻译成人话

让我们从一个和编程毫无关系的比喻开始。

3.1 年夜饭桌上的翻译官

想象一个场景：年夜饭桌上，二舅端着酒杯阴阳你："小 X 现在是大人物了，我们这帮亲戚高攀不起咯。"

如果你下意识说"不不不，怎么是大人物呢。"——你输了。你跳进了他的框架，越解释越被动。

正确的做法是什么？绕过他的措辞，直接翻译他话里的真实含义。 你可以平静地说："二舅，您是说我现在混得好了，忘本了，看不起您老了？"

二舅会立刻否认："哎呀，我只是随口一说，你怎么当真了？"

看到了吗？一旦你把潜台词大白话讲出来，对方自己就会撤回。因为隐晦攻击的力量来源于它的模糊性，你把它显化之后，它就失去了杀伤力。

3.2 设身处地地为AI着想

和 AI 协作时，你在扮演那个"阴阳怪气"的角色——只不过你不是故意的。你的需求在脑海里是清晰的，但你说出来的话是模糊的：

你对 AI 说的 AI 实际理解的 你真正想要的
"帮我写个登录" 一个用户名+密码的表单 OAuth 2.0，支持 Google 和 GitHub，带 JWT 刷新机制
"优化一下性能" 随便加点缓存 把首页冷启动从 3.2 秒降到 1 秒以内
"这个页面太丑了" 换个字体颜色 重新设计布局，符合 Material Design 3 规范

你发现规律没有？你越模糊，AI 的发挥空间越大，偏离你预期的概率就越高。

3.3 需求显性化三板斧

把你的需求"翻译"成 AI 能准确理解的语言，只需要问自己三个问题：

第一问：输入是什么？输出是什么？

别说"做个工具"，说"接收一个 Markdown 文件路径，输出一个渲染后的 HTML 页面"。

第二问：约束条件是什么？

别说"做好看一点"，说"使用 Tailwind CSS，配色参考 GitHub 暗色主题，支持移动端响应式布局"。

第三问：边界在哪里？

别说"支持所有功能"，说"第一版只支持 h1-h3 标题、段落和代码块，其余元素后续迭代"。

这三问看起来像废话——「这不是产品经理的活吗？」是的，在 vibe coding 里，你就是产品经理，只是你不用写 PRD，你在脑子自问自答 30 秒就够了。 这 30 秒的投入，能省下你后面 30 分钟的纠错循环。

3.4 实战演示：BTC 价格监控

让我们走一个极端例子。你对 Claude Code 说：

"帮我监控 BTC 价格"

没有输入输出定义，没有约束，没有边界。AI 不知道你要的是命令行工具、网页 Dashboard、还是 Slack 机器人。

现在用三板斧重新表达：

"做一个命令行脚本，接收一个币种代码（如 BTC），调用 CoinGecko 免费 API 获取实时美元价格，格式化为 BTC: $68,420.50 (24h: +3.2%) 输出到终端。每 30 秒刷新一次，按 q 退出。用 Python 写，依赖不超过 requests 一个库。"

区别在哪里？AI 不需要猜了。 它知道输入（币种代码）、输出（格式化的终端文本）、约束（CoinGecko API、Python、单依赖）、边界（仅支持终端输出，不做 Dashboard）。

思考时间：回想你最近一次"AI 没理解你"的场景。用三板斧重写那条指令，看看如果当时这样表达，结果会有什么不同。

3.5 主奴辩证法：为什么不能一键直出

说到 BTC 监控，你可能会问：加个 --dangerously-skip-permissions 一键直出不就行了？

确实可以。但你有没有想过：当你把一切需求都外包给 AI 的时候，AI 获得了执行的全部主动权，而你——名义上的"主人"——实际上变成了被动等待结果的依赖者。

这就是黑格尔的"主奴辩证法"在 AI 协作中的映射。奴隶（AI）通过劳动掌握了现实，主人（你）却丧失了独立行动的能力。

在 vibe coding 中，这意味着：如果不参与共创，你就永远不会真正理解你的项目。 当 AI 生成的代码出了 bug，你不知道该改哪里。当需求变化时，你不知道从何下手。你拥有了代码，但你不拥有对代码的认知。

因此，我们需要一个框架来规范你和 AI 的协作关系。

四、RIPER 框架：把 vibe coding 装进轨道

4.1 传统软件开发的类比

在传统软件公司里，一个需求的落地大概经过这么几步：

  1. 产品经理解释"我们要做什么"（需求分析）
  2. 技术负责人拆解"有哪些方案、各有什么优劣"（技术选型）
  3. 团队一起定稿"具体怎么实现"（详细设计）
  4. 开发写代码、测试验证（实现与验证）
  5. Code Review 检查代码和设计的偏离（审查）

发现没有？每个环节都有专人负责，有明确的输入输出和检查标准。 这就是工程化。

而 vibe coding 的问题是：这五个环节全部坍缩到了"你的一句话 → AI 的一次输出"里。你指望一句话覆盖五个环节的全部决策，这当然会翻车。

RIPER 框架把传统软件开发的五个步骤还原到 AI 协作中。它强制你和 AI 在每一步只聚焦一件事。

4.2 五步详解

Research（研究）—— 给 AI 一个愿望

目标：让 AI 理解你的需求背景，探索可行性，而不是直接写代码。

这一步，你要像给新同事介绍项目一样，告诉 AI 现状是什么、你遇到了什么问题、你想达到什么效果。不要在这里问"怎么实现"——先让 AI 确认它理解了你要做什么。

实用工具：zread（https://zread.ai/cli）—— 在 Research 阶段，让 AI 通过 zread 阅读外部文档和代码库，建立对技术背景的理解。

常见坑：很多人在这一步就直接要求 AI"帮我写代码"。跳过了背景铺垫，AI 只能靠猜测来填补信息缺口。你的需求越复杂，AI 猜错的概率就越高。

Innovation（创新）—— 拆解需求，对比方案

目标：将大需求拆成多个可独立决策的环节，每个环节讨论 2-3 个可选方案。

比如"做一个终端 PPT 工具"，拆成：Markdown 解析方案（正则 vs 统一 AST vs lexer）、渲染方案（ANSI 转义码 vs 终端 UI 框架）、幻灯片导航方案（分页 vs 滚动 vs 全屏切换）。

每个方案比较：实现复杂度、用户体验、可维护性。不要在这一步敲定所有细节——先列出选项，再做取舍。

实用工具：AskUserQuestion —— 在 Claude Code 中使用 AskUserQuestion 工具，AI 可以把不确定的决策点抛还给你，而不是自行猜测。

常见坑：跳过 Innovation 直接进入 Plan。没有多方对比的方案往往是"第一个想到的方案"，而不是"最合适的方案"。

Plan（计划）—— 敲定细节，写出执行路线图

目标：将 Innovation 阶段选定的方案固化为可执行的 Implementation Plan。

这里的核心判断是：什么时候算"想清楚了"？ 一个实用的自检标准——当你能清晰回答这四个问题时，Plan 就完成了：

  1. 现状是什么？（当前代码结构、技术栈、限制条件）
  2. 动机是什么？（为什么要做这个改动？不做的后果是什么？）
  3. 实现路径是什么？（分几步？每一步的输入输出是什么？）
  4. 验证方式是什么？（完成后，如何证明它是对的？）

如果这四个问题中任何一个你答不上来，说明 Innovation 还不够充分，回到上一步。

实用方法：Uncertainty Detector —— 构造一个subagent，在做 Plan 之前，让 AI 列出它还有哪些信息不确定。如果列表非空，继续 Innovation。

常见坑：Plan 写得太细。一个 Implementation Plan 应该像菜单，不是菜谱。列出步骤和每个步骤的验收标准就够了，不要预先写好所有代码。

Execute（执行） —— 按计划推进，先测试再代码

目标：严格按照 Plan 的顺序执行，每一步独立验证，不跳跃。

核心原则：先写测试，再写代码，直到测试通过。 这不是教条——在 AI 协作中，测试是你的安全带。当 AI 在第六步做了某件事，你需要在第十步确认它还是对的，测试就是你的自动验证器。

一个重要技巧：如果 Execute 做不完，把当前进度写入 handoff.md 文件。 这个文件比 compact 更可控，因为： - compact 是 AI 自动生成摘要——你看不到它丢了什么 - handoff.md 是你自己写的——你知道哪些部分完成了，哪些卡住了，下次新会话时把 handoff.md 喂给新的 AI 实例即可无缝续接 - 另一个 Execute 阶段的高频操作是让 AI 在每次改动前自动 checkpoint。一句"动手前先存档"就够了——翻车时一句"回退到上次存档"即可原地复活。你不需要学会任何 git 命令

常见坑：AI 做 Step 3 的时候"顺手优化了"Step 1 的代码。执行阶段必须克制——一步一个脚印，多余的改动是 scope creep 的温床。

Review（审查） —— 用计划反查代码偏移

目标：拿着 Plan 阶段的产物，逐条检查代码实现和计划的偏离程度。

不要让 AI 泛泛地"检查一下代码有没有问题"——这种指令和"帮我写个登录"一样模糊。你应该让 AI 对照 Implementation Plan，逐条汇报完成情况：

  • 哪些步骤按计划完成了？
  • 哪些步骤实际实现和计划有偏差？偏差的理由是什么？
  • 有没有计划外的改动？是否有必要？

Review 不是挑刺——它是你建立"对代码的认知"的关键环节。还记得主奴辩证法吗？Review 就是你把主动权从"AI 写了什么"收回到"我知道我有什么"的过程。

4.3 RIPER 速查表

阶段 核心问题 输入 输出 不要做的事
Research 我们要解决什么问题？ 现状描述 + 痛点 需求理解文档 不要讨论方案
Innovation 有哪些可行的方案？ 需求理解 方案对比 + 推荐 不要写具体计划
Plan 确定了以后怎么做？ 选定方案 Implementation Plan 不要写代码
Execute 如何一步步实现？ Plan + 测试用例 通过的代码 不要改计划外的东西
Review 代码和计划一致吗？ Plan + 代码 偏移报告 + 修正 不要泛泛而查

4.4 一个重要提醒

RIPER 不是一个死板的流程。对于 5 分钟的小任务，你可以在脑子里 30 秒跑完五步。对于 5 天的大功能，每一步都需要正式写出来。

框架的价值不是约束你，而是确保你没有漏掉关键步骤。 就像飞行员在执行 Checklist——即使飞了 20 年，起飞前还是会对照清单逐项确认。不是因为不会，而是因为人一定会犯错。

五、实战演练

5.1 Demo 1：Slidet —— 终端里的 PowerPoint

项目地址: https://github.com/Xpectuer/slidet/tree/main

背景问题：你需要做一个技术分享，手上有 Markdown 文稿。但你不想打开 PowerPoint 或 Keynote——那意味着调字体、对位置、调动画，花在排版上的时间比花在内容上的还多。

技术方案：一个终端应用，读取 Markdown 文件，按 --- 分隔幻灯片，使用 ANSI 转义码在终端渲染全屏幻灯片，支持左右箭头翻页、q 退出。

实现要点： - Markdown 解析用正则即可（只支持标题、列表、代码块、粗体），不需要完整 AST - 终端渲染直接操作 ANSI 转义序列，不依赖 ncurses 等重量级库 - 幻灯片切换用全屏重绘，清除上一帧的残留

学生自检：打开 Claude Code，给出需求三板斧 + RIPER 流程，尝试在 30 分钟内搭出 Slidet 的最小可用版本（支持标题和段落渲染即可）。

5.2 Demo 2：UIGen —— Vibe Coding 的前端组件工作台

背景问题：你有一个前端项目的想法，但你不想手动搭 Vite + React + Tailwind + 路由 + 状态管理……这套脚手架搭完，你的灵感已经冷了。

alt text

技术方案：一个简化版的"bolt.new"式工作台。界面分两栏——左边写组件的自然语言描述，右边实时渲染组件。底层用 AI 生成 React 组件的代码，直接注入沙箱渲染。

实现要点： - 核心机制：用户输入组件描述 → AI 生成 JSX → 实时渲染预览 - CLAUDE.md 是灵魂：把 AI 探索组件库、理解项目结构的结果持久化为 CLAUDE.md，后续每次对话只需读文件即可获得项目全貌，不需要重复探索 - 课程直播中将演示如何为新组件类型添加"导出"功能——这是一个经典的多文件联动改动，非常适合展示 Execute 阶段的操作

alt text

思考时间：UIGen 的 CLAUDE.md 里应该放什么？想 30 秒再看答案。

至少应该包含：项目技术栈、目录结构、关键组件的位置、编码规范、路由设计。换句话说，就是一个新成员加入团队时需要知道的一切。

六、作业：用 RIPER 开发一个LLM Wiki 工具

任务

各行各业，学习新事物是永恒不变的需求，用 RIPER 框架 + Claude Code，开发一个llm wiki，帮助你学习任何事情，或让AI成为你的私人定制助理。

要求

见 作业文档

七、常见问题集锦

Q：小任务也需要走完 RIPER 五步吗？

不需要形式化地走完五步。但你应该在脑子里快速过一遍：我要解决什么问题？有哪些方式？选哪个？怎么做？做完了检查一下对不对？这 30 秒的思考是区分"可控 coding"和"随缘 coding"的分界线。

Q：RIPER 和 Agile/Scrum 是什么关系？

可以理解为 AI 协作版的敏捷开发。区别在于：Scrum 解决的是"团队怎么协作"，RIPER 解决的是"你怎么和 AI 协作"。RIPER 中的一个 Sprint 可能只有 30 分钟。

Q：我怎么知道应该在哪个阶段花更多时间？

一个粗暴但有效的经验法则：如果项目在前期看起来"很简单，直接写就行"，那 Research + Innovation 大概率需要多花点时间。越是"一看就懂"的项目，越容易在 Execute 阶段发现方向错了。

Q：Claude Code 的上下文不够用怎么办？

第一，每个阶段开一个新会话，用 handoff.md 传递上下文。第二，在 CLAUDE.md 中写好项目全貌，每次新会话第一步就是读它。第三，善用 compact 功能，但要自己检查 compact 之后关键信息是否还在。

八、下一步学习建议

完成本课作业后，你已经掌握了 vibe coding 的"驾驶执照"。接下来可以往两个方向深入：

  • 工程化方向：学习多人协作中如何使用 CLAUDE.md 和 handoff.md 做上下文传递，探索如何将 RIPER 融入团队 CI/CD 流程
  • 产品化方向：把你的工具从"自己能用的脚本"升级为"别人也能用的产品"，学习如何进行用户测试、处理边界 case、写好的 README

但无论往哪个方向走，这节课教的核心能力不会变：清楚地表达需求、结构化地推进执行、持续地验证结果。 这不是 AI 时代的新技能——这是软件工程 50 年来一直在教的技能。AI 只是让这些技能的重要性格外放大了。