Article

零基础 Vibe Coding 实战教程 - 用一个真实项目讲清楚完整工作流

更新于：2026-09-03 • 15 min read

用一个真实项目讲清楚一套完整的 Vibe Coding 工作流。

这次的 Vibe Coding 教程案例叫 RicoScreenshot，截图美化编辑工具。我们会完整跑一遍 Vibe Coding 的网站开发流程，工作流是通用的，再复杂一次的的项目也适用。

RicoScreenshot 主界面

从重新整理项目结构、制定视觉规范、规划功能，再一路做到界面改版、功能开发、交互调整、部署上线，整个流程花费两天的闲暇时间，实操过程中其实是简单的，只是文章里我要把整个流程都拆解清楚，所以显得繁琐，熟悉之后，实际做起来是很快的。

先从需求上来说，截图美化是我平时一直在用的功能，写文章配图、做产品展示图都离不开。之前我使用的是开源项目 image-beautifier，它也是谷歌截图插件 ShotEasy 使用的截图美化内核，基于 LeaferJS 开发。

项目本身的基础不错，只是功能比较简单。用得越久，我自己积累的需求也越来越多：更丰富的背景、完整的标注工具、设备套壳、浏览器边框、更顺手的导出方式……这次正好趁着重做，把这些需求一起做进去。

在线地址：shot.ricoui.com
开源地址：github.com/ricocc/shoteasy

RicoScreenshot 主界面日常制作产品宣传图片

项目保持纯前端，没有后端。图片的读取、编辑和导出全部在浏览器端完成，截图不会上传到服务器。项目采用 MIT 协议，基于 image-beautifier 二次开发，也感谢原作者 Chenliwen 的工作。

核心原则：每个环节做正确的事

工具介绍完，这篇文章更想分享的是整个开发过程。如果你刚开始接触 Vibe Coding，这类项目很适合拿来跑第一次完整流程：没有数据库、账号系统和复杂后端，修改结果直接在浏览器里就能看到，又足够让你经历代码阅读、功能规划、视觉设计、交互调整、测试和部署这些真实开发环节。

我也不会在文章里堆很长的提示词。 Prompt 当然有用，但每个阶段该让 AI 做什么、做到什么程度再进下一步，比提示词本身重要得多。很多 Vibe Coding 教程做到”功能能运行”就结束了，可一个能长期用的产品，还要解决默认状态、信息层级、操作路径、间距、反馈和整体视觉一致性，这也是设计师参与 Vibe Coding 最有优势的地方。

这次完整流程整理成六步：

读懂项目 → 建立视觉规范 → 规划功能 → 开发实现 → 视觉与交互调整 → 测试上线

RicoScreenshot 的 Vibe Coding 六步工作流

重点是每一个环节做正确的事。这套流程不仅适用于当前项目，更复杂的项目我也是这么做的。

先简单看一下成品

先从使用者的角度看看它现在长什么样。

RicoScreenshot 主界面

点击、拖拽或者直接粘贴图片都可以导入，不需要先进入一个空首页，再跳到编辑页面。图片放进去之后会自动保持比例，当前背景和最终导出的效果直接显示在画布上。

目前主要能力可以分成四类。

背景美化

支持渐变、纯色和图片背景。渐变素材来自我的另外一个原创项目 GradientsHub 的本地精选，图片背景接入了 Unsplash 的图库主题，也支持上传自己的本地图片。背景还能继续微调：模糊、遮罩、噪点、渐变角度、填充方式和九宫格对齐。

RicoScreenshot 背景美化

标注

常用的截图标注能力基本都补齐了：矩形、实心矩形、圆圈、直线、箭头、画笔、放大镜、步骤序号、文字、模糊、马赛克、聚光、Emoji。平时写教程圈重点、标步骤、打码敏感信息，直接就能完成。底部标注工具栏可以收起，不用的时候不会一直挡着画布。

样机展示

可以给截图加 MacBook、iPhone 等设备边框，也支持浏览器窗口样式，地址栏 URL、顶部尺寸这些细节都能调，做产品展示图方便很多。

尺寸和导出

内置了常用社交媒体的尺寸预设，导出支持 PNG / JPG / WebP，1x / 2x / 3x 倍率，导出完一键复制到剪贴板。

另外还有撤销重做、深色浅色主题、画布缩放和拖拽、水印、HDR 效果、屏幕截取等能力。

也可以打开原项目对比着看设计和交互上做了哪些改变：screenshot.shoteasy.fun

开发前要注意什么

先回答两个常见问题。

PRD 和项目文档需要写得很详细吗？

不需要，把项目是做什么的、技术栈、哪些东西不能乱动写清楚就够，后面边做边补。

不确定想做的功能能不能实现？也没关系，把需求列出来让 AI 评估优先级和实现成本，它比你想的更清楚边界在哪。这两件事分别会在第一步和第三步展开。

开发前先记住这条主线：

先确定当前阶段要解决什么，再让 AI 开始执行。Prompt 不需要写得很复杂，阶段清楚、上下文完整、验收目标明确，推进起来就如鱼得水。

第一步：先让 AI 读懂项目

不要一上手就写代码，这应该是后期阶段的环节。你拿到一个项目，AI 对整个项目还没有完整的理解，直接动手很容易出现局部方案和原架构对不上，项目越往后做，这种问题越难收拾。

所以第一步只做一件事：读项目。

AGENTS.md 也不用自己动手写。我给 AI 的指令就一句：

通读项目，把项目架构和规范写入仓库根目录的 AGENTS.md。

它读完项目，AGENTS.md 就顺带生成好了：

- 项目是做什么的
- 使用什么技术栈
- 目录如何组织
- 核心模块是什么
- 哪些技术方案暂时不要随意替换
- 常用开发命令
- 项目约定

比如这个项目里画布渲染用的是 LeaferJS，状态管理用 MobX，这些都被它写了进去，之后每个新会话的 AI 先读这份文件，动手前就有完整的上下文。

指令怎么写是小事，这个阶段只有一个目标：确认 AI 真的理解了项目。 它输出的架构理解和 AGENTS.md 我都会自己过一遍，看有没有理解错核心模块、数据从哪里进、怎么流转、组件之间是什么关系、有没有把旧代码或辅助代码误认成主逻辑。有偏差就让它改，确认没问题再往下走。

把理解留在项目里

AGENTS.md 只收最基础的信息，架构理解这类内容，我会继续让 AI 整理进 DOCS/：

DOCS/
├── project-overview.md
├── architecture.md
└── development.md

这样做两头都省事：新会话直接读文档，不用每次重新解释项目；我自己隔几天回来，也能马上知道项目做到哪了。我现在的习惯是尽量把上下文落到文件里。

接下来判断要不要重构

读懂项目以后，也别默认先重构一遍。先看现有结构会不会明显影响接下来的开发：架构本来就清楚的，沿用就行，为了”看起来更漂亮”做大重构没有必要。

原项目的部分功能耦合比较明显，我又准备加不少新能力，所以才先做了一轮有限的结构整理。

这一阶段的原则是只调结构、不加功能。第一次做二次开发的话，这条尤其重要：结构调整和功能开发混在一起，一旦出错，很难判断是哪一步引入的。旧版本的处理我更推荐用 Git tag 或者单独开分支保存，不用把整套旧代码复制进项目目录。

第二步：先把视觉规范定下来

代码理解完之后，第二步先解决视觉。

AI 写一个按钮、一张卡片、一个面板都不难。真正的问题是，当它连续写几十个组件以后，这些组件能不能保持同一种视觉语言。

如果没有规则，很容易做得设计不统一、有拼凑感，越做越乱。

所以我会在仓库根目录维护一份 DESIGN.md，记录整个项目的视觉规则：主色和中性色、背景色、字体、字号层级、圆角、阴影、间距、按钮和面板样式、图标来源、深色主题规则。

DESIGN.md 相关的内容，我以前的文章里有仔细说明。

DESIGN.md 的最佳实践

这份规范不用从零写，我直接用了自己的另一个开源项目 design.ricoui.com，一个围绕 DESIGN.md 做的设计系统工作台。先从品牌库里挑一份接近目标风格的规范作底，在工作台里调颜色、字体、间距，边改边看预览，调完把整份 DESIGN.md 交给 AI：

应用主题 DESIGN.md, 之后修改都遵守规范。先根据规范统一当前项目的视觉。

RicoUI 品牌视觉规范库

这句提示词同样简单，目的是做到：正式开始大量 UI 开发之前，先给 AI 一套长期稳定的视觉标准。

这样之后增加新的面板、新按钮、新工具，AI 都有同一个参考。

合理使用设计 Skills

首先要清楚，设计 Skill 不是装得越多越好。它们都会进入 Agent 的判断过程，规则重叠时不一定互相增强，反而可能把不同作者的审美偏好混在一起。

一个让 AI 大胆，一个要求克制；一个偏大圆角和宽松留白，另一个强调高密度和强对比。最后做出来的东西没有明显错误，也没有清楚的方向。

我常用的设计 Skill 有 4 个：

分别对应四种能力：通用设计审查、设计判断、复杂动画实现和小型交互优化。

Impeccable 提供设计语言和按需命令，Skills for Design Engineers 提供判断原则，GSAP Skills 解决特定技术实现，transitions.dev 处理小而准确的交互优化。它们都不会要求我默认执行整套规则。

我现在把 Design Skill 和 DESIGN.md 搭配作为工作流使用。

Design Skill 负责交互原则和用户体验检查，比如动画是否必要、反馈是否准确、操作是否顺手；
具体的设计规范则交给 DESIGN.md，包括字体、配色、圆角、间距、组件样式和品牌原则。
Agent 先读 DESIGN.md，知道这个项目应该长什么样，再调用对应的 Skill 检查它做得对不对。

图标也要统一

视觉调整里还有一个我一直很在意的细节：图标。

图标对整个项目质感的提升非常大，一套成熟且契合的图标库非常有必要。

比如 Lucide、Reicon 或其他风格统一的开源图标库，我这次使用的图标库是：Mage Icons。

原因很简单，AI 临时生成 SVG 时，每个图标很容易有自己的线宽、圆角、尺寸和视觉重心。单独看一个可能没有明显问题，放到一排以后就会很乱，图标本身很小，却非常影响界面的精致程度。

然后把图标来源也写进 DESIGN.md。这个阶段结束以后，后面的 UI 开发都遵守同一套规则。

第三步：整理功能，不要想到什么就做什么

视觉方向定了，再规划功能。我会先让 AI 把所有想做的需求全部列出来，然后按优先级和复杂度整理。比如三个常见来源：

第一是原项目已经准备做的。

原项目 README 里留了 TODO，比如 Undo / Redo、Unsplash 背景图，这些本身是合理的产品需求，直接进第一批清单。

第二是自己长期使用出来的需求

这类需求反而最明确。

因为我平时真的会拿截图工具写文章、做产品图，所以很多问题不是临时想出来的。比如：导出后直接复制、更顺手的标注、快捷键、浏览器边框、设备套壳、画布缩放、更多尺寸、工具栏别一直挡着画布。这些都是在长期使用里一点点积累出来的。

第三是看竞品。

截图美化这个赛道已经比较成熟，Shots.so、Pika、Screenshot Studio 都值得打开用一遍。但我看竞品不会只抄功能列表，更多是看默认背景是什么、图片导入后第一步发生什么、面板默认展开还是收起、哪些功能放一级入口、导出要几步、常用值默认设成多少。

很多产品的体验差距就藏在这些地方，所以看完竞品要做的是先收集，再判断哪些能力真的适合当前产品。

最后整理成 TODO

我会让 AI 把需求整理成任务清单，标上优先级、实现复杂度和完成状态，比如：

## P0

- [ ] Undo / Redo
- [ ] 图片背景
- [ ] 基础标注
- [ ] 导出优化

## P1

- [ ] 浏览器边框
- [ ] 设备套壳
- [ ] 快捷键
- [ ] 深浅主题

## P2

- [ ] HDR 水印
- [ ] 屏幕截取
- [ ] 更多尺寸预设

后面的开发就按照这份清单往下推进。

对于新手来说，TODO 很重要。

它除了告诉你接下来做什么，还留下了明确的工作进度。当前会话断开，或者换到另外一个模型继续开发，只要让新的 Agent 读一下 TODO，它很快就能知道：

哪些已经完成，哪些正在做，哪些还没有开始。不用每次都翻很长的对话去找项目进度。

到这里，项目其实已经拥有三个非常重要的上下文文件：

AGENTS.md → 这个项目怎么工作
DESIGN.md → 这个项目应该长什么样
TODO.md → 这个项目接下来做什么

这三份文件准备好以后，真正开始开发会轻松很多。

第四步：开始写代码

到这一步，大部分具体开发交给 Agent，节奏就是从 TODO 最上面开始，一次做一个功能。你甚至可以设一个 /goal，让它自己完整跑完这个循环。

拿初始页面举例，我给出的要求大概是：

初始页直接显示 4:3 画布，用户可以点击、拖拽和粘贴图片导入。导入以后直接进入当前画布编辑，不增加额外中转页面。

这里已经不需要告诉 AI React 怎么写、事件监听怎么绑、文件读取 API 怎么调，这些实现细节让模型自己判断。

我更关注的是：这个功能最终应该怎么工作。

类似的要求还有：底部标注工具栏支持收起、导出完成后复制到剪贴板、高频操作加快捷键等，这些本来就是设计和产品层面的判断。

一个循环大概是这样：实现 Undo / Redo → 运行 → 检查 → 确认没问题 → 更新 TODO → 进入下一个功能。

只要上下文文件都准备好了，AI 已经知道技术栈、视觉规范和现有架构，你不需要每做一个功能就重新解释整套项目。所以真正开发时，每轮对话反而可以很短。这也是前面准备 AGENTS.md、DESIGN.md 和 DOCS/ 的意义。

避免 AI 每次都做全量测试

开发过程中还有一个我经常遇到的问题：AI 很容易过度测试。

就算只改了一个小模块，它也会继续跑完整的 lint、测试和生产构建。一次两次问题不大，项目做久了会浪费很多时间和 Token。所以建议明确给 AGENTS.md 里面写入：

根据风险进行适度验证；不要为每次小改动都运行完整构建。

优先使用能够验证当前修改行为的最小测试范围。
仅当出现故障、跨模块影响或者架构调整时，再扩大测试范围。

例如只改一个按钮的间距，确认当前组件没有问题就够。到了新增核心功能、大范围重构或者最终收尾的时候，再跑完整检查。开发和测试的规模尽量匹配当前修改的规模。

第五步：手动走查视觉和交互

这一步是整个项目里我投入注意力最多的部分，也是很多 Vibe Coding 教程略过的部分。功能开发完成只说明它能工作，但能用和好用之间，还差着大量细节。 这个阶段我会重新回到自己最熟悉的设计师角色：亲自使用，发现问题，给出修改方向，然后让 AI 快速落实。

真实的交互感知

至少在现在，AI 很难替你完成真实使用后的体验判断。

拿底部功能工具栏来说：

它放在顶部和底部有什么区别？使用频次如何？默认展开还是收起？展开会不会挡画布？收起入口放哪、用户找不找得到？切换工具后要不要保持状态？

同一个功能，只要这些默认行为发生变化，使用体验就会完全不同。

如果直接问 AI：工具栏应该放顶部还是底部？ 它放哪个位置都能给出合理的理由，但按照我自己的使用体验：

底部工具栏属于相对低频的操作区域，移动到底部以后距离画布更近，同时减少页面上方的信息压力。工具栏需要支持收起，收起以后左下角保留明确入口，并通过 hover 告诉用户这里是标注工具。

这里最重要的其实不是 Prompt。是你亲自使用以后，能第一时间发现：当前操作体验有问题。

设计师做 Vibe Coding 的优势，很大一部分就在这里。

AI 可以快速执行修改，但到底哪里别扭、哪里多余、信息层级有没有问题、什么状态更符合用户预期，这些判断依然需要真实使用。

其他的用户体验内容可以概括为 操作路径、空间关系、及时反馈、用户预期、压力测试 等分类，有空可以详细聊聊这块。

如何准确描述问题

实际使用 → 找到一个具体问题 → 描述理想状态 → AI 修改 → 刷新验证。

走查过程中，你可能会遇到一些问题：一是需要调整的位置说不清，你看到了却很难描述在哪里，担心 AI 无法理解；二是控件/组件/交互方式说不出来，你知道它长什么样，但不知道它的学名是什么。

一、直接说/模糊描述 不必一开始就追求专业的表达。比如”底部工具栏左数第三个图标，交互不对""导航菜单打开的逻辑有错误”，先把问题描述出来就行。可以把 Agent 当成同事，它已经读过项目代码，配合当前上下文，模糊一点的描述通常也能定位。解决不了再换其他方式。

二、直接截图 把页面截图直接发给 Agent，再附上问题，AI 能够判断。但是要注意你调用的模型支不支持图片识别，支持的话，截图比打字描述快得多。

三、顺便补一点 UI 基础知识 如果确实不知道某个控件或者交互叫什么，也可以查一下 UI 视觉词典。有两个网站：namethatui.com 和它的中文版 learnui.qiaomu.ai。它们能帮你查询任意控件和交互的标准中英文名，顺带辨析容易混的控件，比如 Switch 和 Checkbox、Dialog 和 Drawer 的区别。

知道准确术语以后，再和 AI 沟通，定位通常会更准确。

第六步：回归测试，把项目真正收尾

最后一步是测试和收尾。这个项目没有完整的自动化测试，所以我主要做两类检查。

第一类是代码检查，让 AI 跑 pnpm lint 和 pnpm build，确保没有明显问题、生产构建能过。这件事开发过程中一直在做，收尾时再来一次总检查。

第二类是手工走查。我把核心路径整理进 DOCS/development.md，自己一项项过：点击/拖拽/粘贴导入、背景切换、渐变设置、标注、撤销重做、设备套壳、浏览器边框、水印、画布缩放、深浅主题、PNG / JPG / WebP 导出、多倍率导出、复制到剪贴板、快捷键、屏幕截取。核心路径全走一遍，再部署。

最后把项目文档补齐

收尾时顺手让 AI 把项目文档也整理了，最后留下的结构大概是：

├── AGENTS.md
├── DESIGN.md
├── TODO.md
└── DOCS/
    ├── project-overview.md
    ├── architecture.md
    ├── user-guide.md
    ├── development.md
    └── component-api.md

分别负责：

AGENTS.md：AI 进入项目首先需要知道的信息
DESIGN.md：整个项目的视觉规则。
TODO.md：当前任务、优先级和开发进度。
project-overview.md：项目整体说明
architecture.md：架构和数据流
user-guide.md：面向使用者的功能说明
development.md：开发方式、命令和回归清单
component-api.md：组件相关 API

推荐的项目文档结构

这套结构不用每个项目照搬，思路就一条：把长期有价值的信息从会话搬到文件里。下次开新会话，AI 先读这些文件就能接着干。

如果你是新手，可以直接照着这套流程做

RicoScreenshot 是纯前端项目，没有数据库、后端服务和复杂部署环境，技术栈也比较明确。

但这类项目反而很接近很多人真实使用 Vibe Coding 的场景。这套流程很适合作为 Vibe Coding 新手的第一次完整项目练习，整条路线是：

找到项目 → 读懂再动手 → 准备 AGENTS.md → 架构理解写进 DOCS → 判断要不要整理结构 → 准备 DESIGN.md → 统一视觉 → 整理 TODO → 按优先级开发 → 一次解决一个明确问题 → 用真实内容体验调整 → lint / build → 手工回归 → 补文档 → 部署上线

第一次做的时候，直接把这套流程写进自己的 TODO.md，一项项完成就行。必要的原则：知道当前处于哪个阶段，只解决这个阶段最重要的问题。 读项目时就专心读，定视觉的时候不要顺手去堆新功能，开发时一次只做一个任务，功能齐了再集中检查视觉和交互，最后测试收尾。

完整走一遍，你对 Vibe Coding 的理解会比做十个 Demo 清楚得多。

想自己部署一份 RicoScreenshot

RicoScreenshot 没有后端、环境变量和数据库，本地跑起来很简单。可以直接把 GitHub 地址丢给 AI 让它跑起来，或者手动走下面的流程。环境要求 Node.js 18+ 和 pnpm：

# 启用 Corepack，自动匹配仓库指定的 pnpm 版本
corepack enable

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

开发服务器默认跑在 http://localhost:5173; 生产构建用 pnpm build，产出的 dist/ 是纯静态文件，Vercel、Netlify、Cloudflare Pages、GitHub Pages 随便挑一个托管，都不需要服务器。项目还保留了组件库构建 pnpm build:lib，可以把截图编辑器打包成 React 组件，嵌进你自己的项目。

部署到 Cloudflare

Cloudflare 网站支持中文，并且免费版不限带宽，个人网站根本用不完，国内访问速度还行。

先说一个容易迷惑的地方：Cloudflare 后台里 Workers 和 Pages 放在同一个入口，并且 Workers 优先级很高，但你要用的是 Pages。 选 Pages，不用碰 Workers。Workers 是边缘计算平台，跑 API、SSR、定时任务用的，配置要自己写；Pages 是给网站用的，连上仓库选好框架就能部署，静态请求和带宽都不限量。这个项目是纯静态站，Pages 刚好。

第一步：把仓库放到自己账号下

部署平台需要读取你自己的仓库。最简单的方式是在 GitHub 仓库页面右上角点 Fork，一键复制到你的账号。如果你本地已经改好了内容，也可以新建一个空仓库，把代码推上去：

git remote set-url origin https://github.com/你的用户名/你的仓库名.git
git push -u origin master

第二步：连接 Cloudflare

登录 Cloudflare Dashboard，支持 Google/GitHub 账号直接登录。
左侧菜单进入计算 → Workers 和 Pages，点右上角 创建应用程序。
点进来默认创建的是 Worker，别在这里选。往下看，底部有一行小字 “想要部署 Pages？开始使用”，点它。
选择 导入现有 Git 存储库。
授权 GitHub，搜索并选中刚才的仓库。
构建设置里框架预设选择对应框架，构建命令和输出目录会自动填好（建议设置为 pnpm run build 输出到 dist）。最后点 保存并部署。