本文档是一份指南，旨在帮助经验丰富的程序员以及非程序员使用“Vibe Coding”开发应用/服务。编码经验较少的初级开发者和策划人员也可以按照以下步骤获得稳定的结果。
核心原则：与其让 AI 立即编写代码，不如先让它创建文档（Design.md、ToDo.md），然后再开始开发。
0. 整体流程概览
[1] 请求创建 Concept.md
↓
[2] 创建 Design.md（UI/UX 参考文档）
↓
[3] 确定技术栈（参考下面的决策树）
↓
[4] 创建 ToDo.md（模块级技术规范 + 开发计划）
↓
[5] 创建 GitHub 仓库并进行初始提交
↓
[6] 将应用描述 + Design.md + ToDo.md 传递给 Claude Code 或 Grok Build 开始开发
↓
[7] 重复：按模块实现 → 测试 → commit/push
1. Concept.md — 从一个简单的想法开始
首先，用 2-3 行简要描述你想制作的应用或服务，格式为：“我想做一个类似这样的东西；请创建一个 Concept.md 文档，详细说明实现它的步骤和方法。”
下载生成的文档并保存为 Concept.md。
2. Design.md — 首先创建 UI/设计参考文档
如果应用有 UI，最好先编写 Design.md。也就是说，如果你有想参考的服务或应用，或者你自己知道如何设计 UI，你可以通过提供在 Figma 等工具中设计的图像来提出请求。
方法
- 选择一个你喜欢的实际部署的网站。（例如，linear.app、stripe.com、toss.im 等）
- 指示 Claude 或 Grok：“分析该网站的布局结构、调色板、排版、边距/间距和组件样式，并将其整理到 Design.md 中。”
提示示例
分析 https://linear.app 的设计并编写一个 Design.md 文档。 你必须包含以下项目： 1. 整体布局结构（Header/Sidebar/Body/Footer 的位置） 2. 调色板（主要、次要、背景、文本颜色的 HEX 代码） 3. 排版（字体类型、字号系统、字重） 4. 边距和间距规则（间距比例） 5. 主要组件的样式，如按钮、卡片和输入表单 6. 深色模式支持和颜色映射
提示
- 如果你有设计感，由于生成的 Design.md 内容都是用自然语言描述的，你可以阅读它并直接修改/完善到你想要的方向。这份文档将成为所有后续 UI 实现的标准。
- 如果你只是说“让它像这个网站一样”，每次的结果都会不同。你必须用文档固定下来以保持一致性。
2. 技术栈决策推荐树
根据你要创建的服务类型首先确定技术栈。
通用服务器（后端）原则
- 必须能够在任何本地环境中直接从 CLI 安装和运行。
- 语言/运行时应该是 Node.js 或 Python。
- 使用经过验证的、在所有操作系统上都能稳定部署和支持的包/执行环境工具：
- Python → uv
- Node.js → npm
数据库选择标准
详细的提示说明（如果你有开发知识）
这个项目是一个 Web 应用。使用 React 配置前端，并且应该能够在本地使用
npm run dev立即测试，其结构应允许稳定部署。使用 Node.js 配置后端，由于需要关系型数据库，请使用 MariaDB。包含一个可以在本地开发环境中通过 CLI 直接安装/运行的设置脚本。检查此内容和 Concept.md 文档，编写一个 ToDo.md 文档以进行详细的技术实现。
- 使用此提示附加 Concept.md 文档，或复制并粘贴 Concept.md 文档的内容。
但如果我是不知道上述内容的非开发者呢？
只需给出如下综合指示：
我不确定如何运行这个项目，所以请推荐一种方法。推荐是 Web 应用更好，还是 OS 安装方法在开发期间更容易检查，或者构建为移动应用更好。如果可以在 Web 浏览器中展示，则使用 React 配置前端；如果需要作为移动应用提供服务，则使用 Flutter 配置前端。如果是需要本地安装的方法，则使用 npm 或 uv 进行配置，这些工具可以通过 CLI 轻松部署和安装。设置一个允许稳定部署的结构。我不确定是否需要后端，但为 Node.js 或部署/安装设置一个稳定的结构。如果需要数据库，如果需要关系型数据库则使用 MariaDB，如果只是键值数据库，则在本地开发中使用 AWS DynamoDB，并配置为易于部署到 AWS。如果是可以在本地开发环境中通过 CLI 直接安装/运行的格式，请包含所有设置脚本。推荐这样一个详细的技术栈，检查此内容和 Concept.md 文档，并编写一个 ToDo.md 文档以进行详细的技术实现。
3. 管理后台 — 如果有服务器则必不可少
你可能不知道它是否是一个有服务器的服务，但通常最好构建一个，以便开发者可以亲自掌握整个应用的运行状态和进度。
- 有服务器的项目应默认包含管理后台的实现。
- 管理后台应包含的最低项目：
- 服务器健康检查
- 关键数据状态（核心指标，如订阅者数量、处理案例数量等）
- 最近的错误/日志
- 主要任务的处理进度（批处理、队列等）
提示示例
如果此服务包含服务器，请在开发计划中包含一个管理后台。该后台应允许检查服务器状态、核心指标和最近的日志/错误。将默认管理员帐户设置为 'admin'，密码为 '12345'，并包含在管理后台中更改密码的功能。检查 ToDo.md，如果认为有必要，将其包含在开发计划中。
4. 最终确定 ToDo.md — 模块级开发计划
编程的基础是模块化。 如果在编写代码之前向 ToDo.md 添加内容以细分为模块，则可以创建出未来易于维护的良好架构。
提示示例
检查 ToDo.md 文档，并根据以下指南验证其是否编写良好，并修改/补充任何不足之处。 ToDo.md 要求： 1. 设计整个系统，使其通过面向对象设计进行模块化。 2. 明确指定每个模块的角色、输入/输出和数据结构，以确保最大程度的封装。 3. 创建一个实现顺序作为复选框列表（从没有依赖关系的模块开始）。 4. 包含数据库模式设计。 5. 描述非技术人员何时以及如何轻松测试。
在完成的 ToDo.md 中要验证的项目：
- 项目概述（一段）
- 已确认的技术栈（步骤 2 中决策树的结果）
- 模块列表和每个模块的详细技术规范（非技术人员可能觉得难以理解）
- 模块名称和角色
- 输入/输出（API 端点和请求/响应格式）
- 使用的数据结构 / 数据库表（或集合）设计
- 与其他模块的依赖关系
- 实现顺序（以复选框形式，按依赖顺序）
- 检查每个测试方法是否以我能理解的级别编写。
重要
- 你不一定需要自己阅读和审查生成的 ToDo.md。 虽然看起来准备完美事情就会顺利，但 Vibe Coding 的核心是先创建结果，然后逐步修改以获得你想要的东西——这是最有价值和最有趣的部分。
实践部分：环境设置 → GitHub → 开始 Claude Code 开发
编写方式让即使是第一次安装开发工具的人也能跟上。
- 尽管如此，如果它看起来太复杂，你不知道为什么要使用它，并且感到无聊透顶，请先点击下面的链接去听一堂免费课程。
https://nomadcoders.co/git-for-beginners
5. 准备开发环境（只安装 2 个东西）
我们将安装两个东西。
你还需要一个 GitHub 帐户。在 https://github.com 免费注册（完成电子邮件验证）。使用 Claude Code 或 Grok Build 需要一个 Claude 付费计划（Pro/Max/Team）或 Grok 付费帐户。
5-1. 🪟 Windows 用户安装步骤
① 安装 Git
- 在浏览器中访问 https://git-scm.com/download/win → 自动开始下载。
- 运行下载的安装程序。
- 出现许多安装选项；只需保持所有默认值，一直点击“Next”。
- 但是，当出现“Choosing the default editor”屏幕时，最好选择 “Use Visual Studio Code as Git's default editor”（如果你尚未安装 VS Code，默认选项也可以）。
- 验证安装：从开始菜单运行 PowerShell 并输入：
git --version
→ 如果出现类似 git version 2.xx.x 的版本号，则表示成功。如果没有，请尝试关闭并重新打开 PowerShell。
② 安装 VS Code
- 访问 https://code.visualstudio.com → 点击 Download for Windows。
- 运行安装程序 → 一直点击“Next”。但是，在选项屏幕中勾选这两项：
- “Add to PATH”
- “Add 'Open with Code' action to file/directory context menus”
- 安装后运行 VS Code。如果在第一个屏幕上出现韩语语言包安装通知，你可以安装它。
5-2. 🍎 Mac 用户安装步骤
① 安装 Git
- 打开 终端：Cmd + Space → 输入“Terminal” → 回车。
- 输入：
git --version
- 如果立即显示版本号，说明已安装 → 转到 ②。如果出现安装指南弹出窗口（“Command Line Developer Tools...”），请点击 “Install” 并等待。（这就是 Git 安装）。
- 完成后再次使用
git --version验证。
② 安装 VS Code
- 访问 https://code.visualstudio.com → 点击 Download for macOS。
- 解压下载的文件，并将 Visual Studio Code.app 拖到 Applications 文件夹。（重要！不要直接从 Downloads 文件夹使用它）。
- 从 Applications 运行 VS Code。
5-3. （通用）在 Git 中注册我的名字 — 仅首次
此设置用于在提交中留下“谁做了工作”的记录。在 PowerShell（Windows）或终端（Mac）中：
git config --global user.name "你的名字" git config --global user.email "你的-github-邮箱@example.com"
输入你用于注册 GitHub 的相同邮箱。
6. 创建 GitHub 仓库并使用 VS Code 连接到我的电脑
将“仓库”视为一个保存一个项目的云文件夹。流程是：在 GitHub 网站上创建一个空仓库 → 使用 VS Code 将其克隆到我的电脑 → 上传规划文档 → 将该仓库连接到 Claude Code web。
6-1. 在 GitHub 网站上创建仓库
- 登录 https://github.comhttps://github.com/)。
- 点击右上角的 + 按钮 → New repository。
- 按如下方式输入：
- Repository name：项目名称（英文，用连字符代替空格。例如，my-first-app）
- 选择 Private（公司项目必须是 Private！）
- 勾选“Add a README file”复选框 ✅ ← 初学者必须勾选此项。这会使下一步（克隆）更简单。
- 点击 Create repository。
- 在创建的仓库页面上，点击绿色的 <> Code 按钮 → 复制 HTTPS 选项卡中的地址。
6-2. 使用 VS Code 克隆到我的电脑
- 运行 VS Code。
- Ctrl + Shift + P（Mac 上为 Cmd + Shift + P）→ 打开命令面板。
- 输入
clone→ 选择 “Git: Clone”。 - 粘贴复制的仓库地址并按回车。
- 你也可以选择 “Clone from GitHub” → 如果浏览器打开并要求 GitHub 登录/授权，请批准。（仅首次）。
- 选择保存项目的位置（例如，最好创建一个 Documents/Projects 文件夹）。
- 克隆完成后，右下角会出现一个 “Open” 通知 → 点击它。
- 如果在左侧文件资源管理器中看到
README.md，则成功！🎉 这个文件夹现在就是我的电脑和 GitHub 之间连接的工作文件夹。
6-3. 上传规划文档 — Concept.md、Design.md、ToDo.md
Claude Code web 可以读取仓库内的文件。 因此，将规划文档放入仓库等同于“上传文档”。
- 在 VS Code 文件资源管理器的空白处右键单击 → New File → 输入名称
Concept.md。 - 粘贴你准备好的应用描述并保存（Ctrl+S / Cmd+S）。
- 以相同方式创建并插入
Design.md（如果有 UI）和ToDo.md文件。 - 现在上传到 GitHub（commit & push）— 使用 6-4 中的方法。
6-4. 在 VS Code 中提交和推送 — 仅用鼠标
- 保存文件时，VS Code 左侧的分支形状图标（Source Control） 上会出现一个数字徽章。
- 点击该图标 → 你会看到已更改文件的列表。
- 在顶部的消息输入框中，写一行关于你做了什么的内容。（例如，添加了规划文档）。
- 点击 ✔ Commit 按钮 → 保存完成在我的电脑上。
- 如果出现“There are no staged changes”弹出窗口，请点击 “Yes” 提交所有内容。
- 然后点击 Sync Changes 按钮 → 上传（push）到 GitHub 完成。
- 在 GitHub 网站上刷新仓库，即可看到你刚刚上传的
Concept.md。现在 Claude Code web 也可以读取此文档。
拉取（下载） 也在同一屏幕上完成：如果 Claude 在云端上传了更改，Sync Changes 按钮将同时处理下载和上传。
7. 将仓库连接到 Claude Code Web 并开始开发
现在在浏览器中打开 Claude Code web 并连接你刚刚创建的 GitHub 仓库。
7-1. 连接 Claude Code Web ↔ GitHub 仓库（仅首次）
- 访问 https://claude.ai/code → 使用你的 Claude 帐户登录。
- 首次访问时，会出现 Connect GitHub 指南 → 按照指南操作。
- 你将跳转到 GitHub 页面，并出现 Claude GitHub App 安装屏幕：
- 选择你的 GitHub 帐户（或组织）。
- 选择访问范围：建议选择 “Only select repositories” 并指定在 6-1 中创建的仓库。
- 点击 Install / Authorize。
- 返回 Claude 完成连接。如果出现环境设置屏幕，保持默认设置。
- 开始新会话（任务）时，从仓库选择列表中选择你的仓库，输入提示，任务开始。
7-2. 了解 Claude Code 和 Grok Build Web 的工作原理（重要！）
Claude Code 和 Grok Build web 在云端的虚拟计算机上工作，而不是在我的电脑上。流程是：
① 我输入提示
↓
② Claude Code/Grok Build 在云端克隆我的仓库并编写代码
↓
③ 将结果作为“新任务分支”推送到 GitHub
↓
④ 我将该分支拉取到我的电脑进行测试，或通过 GitHub 上的 Pull Request 检查更改
↓
⑤ 如果我喜欢，合并到 main 中。
- 由于它总是将结果上传到新分支，而不会直接触及主分支，因此无需担心现有代码被破坏。（Grok Build 在主分支上工作，但可以撤消，所以不用担心出错）。
7-4. 开发开始提示
一旦三个文档（Concept.md / Design.md / ToDo.md）在 main 中准备就绪，最后在一个新会话中开始开发。
开发这个项目。根据仓库中的以下文档进行： - Concept.md：要制作的应用的描述 - ToDo.md：模块级开发计划（按此顺序实现） - Design.md：设计标准（所有 UI 都遵循此文档）
工作规则： 1. 根据 ToDo.md 中的实现顺序，一次处理一个模块。 2. 当一个可测试的单元完成时，通过 README 或回复告诉我如何在我的本地电脑上运行/测试它。由于我是非开发者，请像教初学者一样解释清楚。 3. 在 ToDo.md 中用复选标记标记已完成的项目。 4. 告诉我任务分支名称，并使用易于记忆的提交消息进行推送。 5. 如果有不清楚的部分，不要猜测；问我。
7-5. 开发过程中重复的循环
① Web Claude Code 在任务分支中实现一个模块 → push
↓
② 将该任务分支拉取到我的电脑（VS Code）并直接运行/测试
↓
③ 如果有问题 → 复制整个错误消息并粘贴到 web 会话中
如果没有问题 → “好的，继续下一个开发”
↓
返回 ① 处理下一个模块
↓
④ 一旦所有功能完成且测试通过
→ 通过 Pull Request 合并到 main 分支
→ 部署始终基于 main
8. 分支 — 在任务分支中测试并合并到 main 进行部署
8-1. 什么是分支？
- main 分支 = 始终运行良好的成品展示。部署始终基于
main。 - 任务分支（例如，
claude/feature-login）= 通过复制main创建的施工现场。你可以在这里随意构建和破坏；main是安全的。
Claude Code web 总是创建一个新的任务分支并推送结果。 因此，你只需要知道三件事：
- 如何检查我的文件夹当前在哪个分支上。
- 如何拉取 Claude 推送的任务分支到我的电脑进行测试。
- 如何在完成时合并到 main 并部署。
8-2. 检查你在哪个分支上
- 查看 VS Code 屏幕最左下角的状态栏。分支名称显示在分支图标旁边。（例如，
main或claude/feature-login）。
8-3. 拉取 Claude Code/Grok Build 创建的任务分支到我的电脑进行测试
当 web Claude Code 说“我已推送到分支 OO”时，将该分支带到我的电脑进行测试。Grok Build 在 web 屏幕的右上角有一个“Push to Github”按钮，按下此按钮进行推送。
使用 VS Code（仅用鼠标）：
- 点击左下角的分支名称 → 打开分支列表。
- 如果看不到新分支，请在 Source Control 选项卡中运行 ... 菜单 → Fetch，然后重试。
- 从列表中选择以 origin/claude/... 开头的 Claude 任务分支 → 你的文件夹将更改为该分支状态。
8-4. 完成时合并到 main — Pull Request
如果任务分支中的功能完成且测试通过，则通过 GitHub 网站上的 Pull Request（PR）合并到 main。
- 在 GitHub 上访问你的仓库 → 点击 Pull requests 选项卡。
- 点击 Claude 创建的 PR。如果没有，则 New pull request → base：
main，compare：选择任务分支 → Create pull request。 - 点击 Merge pull request → Confirm merge → 反映到
main！ - 将你的电脑上的 main 更新到最新：
- 点击 VS Code 左下角的分支 → 选择
main→ 在 Source Control 选项卡中点击 Sync Changes。
9. 提示技巧（通用）
Vibe Coding 的质量与提示的质量成正比。
- 指定不要做什么 — “在我批准之前不要随意修改代码”，“不要添加库，只使用现有的技术栈。”
- 一次一个模块 — 如果在一个提示中要求整个应用，质量会下降。按照 ToDo.md 的顺序小批量请求。
- 原样粘贴错误 — 不要总结错误消息；复制整个终端输出。
- 让 Claude 在模棱两可时提问 — 在提示中包含“如果有不清楚的部分，不要猜测；问我。”
- 基于文档进行沟通 — “正如我之前所说” ❌ → “根据 Design.md 的设计” ✅。仓库中的文档比对话记忆稳定得多。
结束。
正如古代墨菲斯所说：
“尼奥。我只能为你展示那扇门。你必须自己走过去。”
