文档优先的氛围编程系统

# 为什么你的氛围编程一塌糊涂（以及彻底修复你的完整指南）

先把话说清楚。氛围编程本身不是问题，问题在于你。你听说可以跟 AI 编程智能体对话、然后交付软件。于是你以为自己是个魔术师。你打开一个 AI，用一句话描述你的应用创意，期待它还给你他妈的魔法。但出乎意料的是，你得到的是破碎的代码、凭空捏造的 UI 和配色、无法路由或互连的页面，以及一个"勉强能用"但实际上根本跑不起来的应用。

然后你把这些错误归咎于 AI。

就像个白痴一样。

真相是：AI 产生幻觉不是因为它坏了，而是因为你没给它任何可以抓住的东西。

没有结构，没有清晰度，没有基础。

氛围编程是有效的。

但前提是你必须理解自己在构建什么，并给你的 AI 智能体一套真正完整的系统来运作。接下来的内容是你需要了解的一切：构建模块、专业词汇、真实工作流——全部用连穴居人都能看懂的方式来解释。

如果你读完这些还是无法交付产品，问题在于努力，而不是信息。

这不是一篇可以扫一眼就忘掉的帖子。这是氛围编程从头到尾的完整系统。现在就收藏它，把它保存到你的 Clawdbot 记忆里。

每次开启新项目时都回来查阅。把它当作参考手册的人将会构建出令人惊叹的东西。只是扫一遍的人将继续卡死在原地、一事无成。

现在，让我们来修复你。

# 第一部分：你为什么在失败

你失败是因为你跳过了基础知识。

你不知道什么是组件，不知道状态（state）意味着什么，不理解为什么点击按钮没有任何反应，也不知道为什么你的网站在笔记本上看起来不错，却在手机上一片混乱。

正因为你不懂这些，你就无法向 AI 描述它们。

AI 是一个翻译器，它把你的意图转化为代码。但如果你的意图很糟糕，代码就会很糟糕。如果你无法清晰表达自己想要什么，AI 就会猜测。而猜测叠加猜测，最终演变成彻底的、纯粹的混乱。

解决方法不是更好的提示词。
解决方法是更好的理解。

一旦你清楚自己在构建什么，写提示词就变得轻而易举。因为你终于知道该问什么，那些词语会自然而然地浮现出来。

# 第二部分：文档优先系统

这正是所有人犯错的地方。

你打开 Cursor，打开一个聊天窗口，开始描述你的应用，然后让 AI 立刻开始写代码。没有计划，没有参考资料，没有任何"唯一真理来源"。

这就是为什么你的项目在前几个文件刚开始后就分崩离析。

真正的系统是文档优先，代码其次。永远这样做。

在你写下任何一行代码之前，应该先为项目撰写规范性的文档 Markdown 文件。

清晰、具体、毫不含糊地描述你正在构建的内容。

为什么？

因为 AI 编程工具拥有强大的执行能力，但缺乏确定性。

它们在没有结构性护栏的情况下执行任务。缺少锁定的约束条件和权威性文档，会导致 AI 凭空捏造需求、擅自做出架构决策，并产生解决你从未提出的问题的代码。

失败的原因不是缺乏编程能力。
失败的原因是缺乏纪律性和上下文持久性。

以下是你在碰任何代码之前应该撰写的文档体系。六份规范性文档，定义你的整个项目，外加一些在跨会话时帮助 AI 保持对齐和持续性的文件。

规范文档（你的知识库）：

1. **PRD.md（产品需求文档）**——完整的规格说明。你在构建什么、面向谁、有哪些功能、哪些在范围内、哪些明确不在范围内。用户故事、成功标准、非目标，以及每个功能的具体标准。这是你的合同。AI读完就能清楚知道"完成"对你来说意味着什么。没有这份文档？你不是在构建应用，你是在祈祷凭空得到一个。

2. **APP_FLOW.md**——用简明英语记录每一个页面和每一条用户导航路径。什么触发每个流程。带决策点的逐步序列，成功时发生什么，出错时发生什么，以及带路由的页面清单。这能防止AI去猜测用户如何在应用中穿行。

3. **TECH_STACK.md**——每个包、依赖项、API和工具都锁定到精确版本。没有歧义。当AI看到"使用React"时，它可能选择任意版本。当它看到"Next.js 14.1.0、React 18.2.0、TypeScript 5.3.3"时，它构建的正是你指定的内容。这份文档消除了幻觉依赖和随机技术选择。

4. **FRONTEND_GUIDELINES.md**——你完整的设计系统。字体、带精确十六进制代码的调色板、间距比例、布局规则、组件样式、响应式断点，以及UI库偏好。每一个视觉决策都被锁定。AI在创建每个组件时都会参考这份文档。不再有随机颜色或不一致的间距，让你持续保持心流状态。

5. **BACKEND_STRUCTURE.md**——定义了每张表、每列、每种类型和关系的数据库模式。认证逻辑、API端点契约、存储规则和边界情况。如果你在使用Supabase，这份文档包含精确的SQL结构。AI依照这份蓝图构建后端，而不是凭借自己的假设。

6. **IMPLEMENTATION_PLAN.md**——逐步的构建顺序。

不是"构建应用"。更像是：步骤1.1初始化项目，步骤1.2从TECH_STACK.md安装依赖，步骤1.3创建文件夹结构，步骤2.1按照FRONTEND_GUIDELINES.md构建导航栏组件，依此类推。

步骤越多，AI猜测越少。AI猜测越少，幻觉越少。

这些文档相互交叉引用。PRD定义功能，APP_FLOW定义用户如何体验它们，TECH_STACK定义用什么来构建它们，FRONTEND_GUIDELINES定义它们的外观，BACKEND_STRUCTURE定义数据如何运作，IMPLEMENTATION_PLAN定义构建顺序。

这就是你的知识库。

AI读完这些，就拥有了它所需的一切。

---

两个会话文件（你的持久化层）：

**CLAUDE.md**——这是AI每次会话自动首先读取的文件。它包含每次AI会话必须遵守的规则、约束、模式和上下文。你的技术栈摘要、文件命名规范、组件模式，以及设计系统令牌。什么被允许，什么被禁止。把它想象成AI专为你的项目定制的操作手册。Claude Code无需你开口，就能从项目根目录读取这份文件。

progress.txt —— 这是每个人都会遗漏的文件。这个文件记录了已完成的内容、进行中的内容，以及接下来要做什么。每次完成一个功能，你就更新这个文件。每次开启新会话、每次打开新终端窗口、每次切换分支，AI都会首先读取这个文件，以获取你进度的上下文记忆。没有它，每个新会话都从零开始，一路上错误不断。有了它，AI会从你上次离开的地方精确接续。

这就是它为什么重要：AI在会话之间没有记忆。当你关闭终端、打开新终端或开启新对话时，一切都消失了。progress.txt就是你的外部记忆。它是跨会话的桥梁。

虔诚地更新它。每完成一个你实现的功能后，详尽地记录构建了什么、什么能用、什么有问题、下一步做什么。

# 第三步：审讯系统

在你动手写任何文档之前，先让AI把你的想法拆解得体无完肤。

这是改变一切的提示词：

> "在编写任何代码之前，仅在规划模式下对我的想法进行无休止的追问。不作任何假设。持续提问，直到没有任何假设剩余为止。"

当你的思路清晰度耗尽的地方，AI就开始产生幻觉。所以如果你延伸自己的清晰度，就能迫使AI在开始在破损的地基上建造之前，先找出你思维中的漏洞。

AI应该向你提问的内容：

这是为谁做的？用户的核心操作是什么？他们完成该操作后会发生什么？哪些数据需要保存？哪些数据需要展示？出错时会发生什么？成功时会发生什么？这是否需要登录？这是否需要数据库？这是否需要在移动端运行？

如果你无法回答这些问题，说明你还没准备好开始构建。

先去把答案找出来。

下面是一个好的审讯过程示例。

假设你在构建一个食谱分享应用：

这是为谁做的？想要保存和分享食谱的家庭厨师。核心操作？用户创建一个包含标题、食材列表、步骤和照片的食谱。之后会发生什么？食谱被保存到他们的个人主页，并显示在公开动态上。保存哪些数据？食谱标题、食材（数组）、步骤（数组）、照片URL、作者ID、时间戳。展示哪些数据？最近食谱的动态流、单个食谱详情页、用户自己的食谱合集。错误状态？上传失败、必填字段缺失、未授权的编辑尝试。是否需要登录？是的，创建食谱需要登录。浏览是公开的。数据库？是的，用户表和食谱表通过外键关联。移动端？是的，大多数用户会在做饭时用手机添加食谱。

那些答案不只是答案。

它们是你规范Markdown文档的原始素材。

用户描述为你的PRD提供内容。数据结构为你的BACKEND STRUCTURE提供内容。流程为你的APP FLOW提供内容。移动端需求为你的FRONTEND GUIDELINES提供内容。

一旦审讯完成并且你对所有问题都有了明确答案，使用以下第二个提示词：

> "根据我们的审讯内容，生成我的规范文档文件：
- PRD.md
- APP_FLOW.md
- TECH_STACK.md
- FRONTEND_GUIDELINES.md
- BACKEND_STRUCTURE.md
- IMPLEMENTATION_PLAN.md。
以我们对话中的答案作为原始素材。要具体详尽，不留任何模糊之处。"

AI将根据审讯输出起草所有文档。你审阅它们，纠正任何模糊之处，补充任何遗漏内容，并将其锁定为你的唯一可信来源。

执行顺序：
审讯 → 文档 → 代码。

永远、永远不要跳过这些步骤。

# 4: UI 与 UX

两个人人挂在嘴边、却没人简单解释过的术语。

UI 是指它看起来怎么样（颜色、字体、按钮形状、间距），即视觉层。UX 是指使用起来感觉如何（用户能弄清楚该做什么吗？流程是否直观？人们会不会卡住？他们是感到沮丧还是愉悦？）

你可能有漂亮的 UI，却有糟糕的 UX。

精美的按钮，但没人知道该怎么点。

你也可能有丑陋的 UI，却有出色的 UX。

功能完善、清晰明了，人们知道该做什么——只是外观难看。

跟 AI 沟通时，明确说清楚你指的是哪一个。"让它看起来更好看"是 UI。"让它更容易使用"是 UX。"让按钮更醒目"则两者都是。

这里有个大多数人不知道的技巧：用截图作为参考。找一个你喜欢的应用或网站（也许在 Framer 或 Dribbble 上），截图后直接发给 Claude Code 或 Cursor。提示词可以是"匹配这个布局"、"完全复现这套 UI"，或"以这套 UI 为灵感"。AI 能分析图片，从截图中提取设计模式、间距、配色方案、排版和组件结构。这比用文字描述一个设计要好无数倍。谷歌的 Gemini 3 Pro 是我目前发现的在匹配高端美学设计方面最出色的模型。

你也可以截下自己正在进行中的作品，然后说"这是它现在的样子，这是问题所在，帮我修复。"视觉参考消除歧义的速度，比任何文字描述都快。

更妙的是：Cursor 有一个浏览器侧边栏，让你可以同时进行设计和编码。

你可以实时看到应用的渲染效果，点击元素、移动位置、更新颜色、测试布局，并实时调整 CSS，然后通过 Agent 模式将这些改动直接应用到代码库中。这是迭代视觉设计的最快方式，省去了截图、粘贴、等待的循环。

你需要了解的设计风格：

这些是目前占主导地位的视觉语言。当你在 FRONTEND GUIDELINES .md 或 AI 提示词中引用这些术语时，它们能解锁具体、可辨识的美学风格，而不是模糊的描述。

**毛玻璃态（Glassmorphism）**——磨砂玻璃效果。半透明元素配合背景模糊、细微边框，以及悬浮在彩色背景上的柔和阴影。想想 Apple 的 macOS、Windows 11、Spotify 的移动端应用。在 CSS 中使用 `backdrop-filter: blur()`。无需厚重阴影即可创造层次感与纵深感。看起来高端。非常适合卡片、模态框、导航栏和仪表盘。风险在于：透明度可能降低可读性，因此要保持文字对比度。

**新野蛮主义（Neobrutalism）**——原始、大胆、刻意不加修饰。高对比度颜色、粗黑边框、平面阴影、撞色调色板、个性字体。想想 Gumroad、早期 Notion 的风格。这是带有态度的极简主义。适用于创意品牌、作品集、独立工具。因为其他所有东西看起来都一样，所以它格外突出。告诉 AI："neobrutalist 风格，粗边框加粗体主色。"

**新拟态（Neumorphism / Soft UI）**——元素看起来像是从背景中挤出或按入的。两侧柔和、漫射的阴影营造出触感十足的 3D 感。微妙而优雅，但在无障碍性方面比较棘手，因为低对比度会让按钮难以辨认。最适合小型 UI 元素、开关、滑块、卡片。不适合作为整体设计语言。

Bento网格——一种模块化布局，内容被排列在不同大小的块中，就像日式便当盒一样。苹果公司将这一风格发扬光大。不同尺寸的卡片创造出视觉节奏与层次感。重要内容用大卡片，次要信息用小卡片。这种布局天生就适合响应式设计，因为网格会在移动端自动重排。非常适合用于仪表盘、产品页面、功能展示和作品集。这可能是最值得学习的实用趋势，因为它解决了真实存在的布局问题。

深色模式——它不再只是一个偏好设置开关，而是一套完整的设计系统。深色背景配合浅色文字、精心设计的对比度，以及低饱和度的强调色。它能减轻眼睛疲劳，在OLED屏幕上节省电量，同时呈现出高端质感。如果你在构建任何消费类应用，从一开始就同时规划浅色和深色模式。不要事后随意添加。在你的FRONTEND_GUIDELINES.md中提前定义好两套调色板和主题。

动态排版——文字会移动、拉伸，并响应滚动或光标操作。标题在进入视图时播放动画，文字随滚动缩放，还有富有交互感的字体处理效果。不仅仅是简单的淡入效果。借助现代CSS和Framer Motion这类库，无需大量JavaScript即可实现。在适合的设计场景下，将其少量用于英雄区域和关键时刻。

微交互——响应用户操作的细微动画。按钮在悬停时轻微缩放，复选框被点击时弹跳一下，加载转圈动画充满生命力。这些细节将精良的产品与真正业余的作品区分开来。它们传递出界面是有响应、有活力、有品质的信号。Framer Motion和CSS过渡效果可以轻松实现这些效果。

当你向AI下提示词时，不要说"让它看起来更现代"。而要说"毛玻璃拟态卡片配合Bento网格布局、深色模式，以及悬停状态的微交互"。这才是具体的、可构建的设计方向。

在开始编码之前，将你的设计决策锁定在FRONTEND_GUIDELINES.md中。选择一两种风格，定义好你的调色板、间距比例、圆角值、阴影参数和动画时间，AI就会在文档足够完善的情况下保持一致性。如果这些内容没有被记录下来，每个组件看起来都会不一样，将会毫无一致性可言。

# 5：组件

组件是界面中可复用的部件。

把它想象成乐高积木。每一块积木就是一个组件。

将它们组合在一起，就能构建出完整的东西。

按钮是组件，导航栏是组件，展示产品的卡片是组件，表单也是组件——它由更小的组件（输入框、标签、按钮）组成。

为什么这对氛围编程很重要：

当你说"帮我构建一个落地页"时，AI必须自行决定要创建哪些组件。如果你不加以说明，它只能靠猜测。而它可能会把所有内容堆成一个乱成一团的巨型结构，而不是干净、可复用的独立模块。

更好的提示词：

> "构建一个落地页，包含以下组件：导航栏、英雄区域、功能网格（3张卡片）、用户评价轮播、行动号召区块、页脚。"

现在AI清楚地知道需要创建哪些模块。每个模块是独立的，可以单独编辑。这就是组件化思维的力量所在。

# 6：布局

布局决定了页面上各元素的位置。

每个网站都是盒子套着盒子。

这就是核心概念。

掌握了这一点……

你就理解了90%的网页设计。

主要的盒子包括：顶部的页眉/导航栏、中间的主要内容区域、旁边可选的侧边栏，以及底部的页脚。

在主要内容区域内，还有更多盒子：用于划分页面的区块（section）、控制宽度的容器（container）、将条目组织成行列的网格（grid），以及将相关内容归组的卡片（card）。

向 AI 描述布局时，可以这样说：

> "两列布局。左侧为侧边栏，宽度 250px。主内容区占据剩余空间。侧边栏固定，不随页面滚动。"

这就是完整的布局指令，AI 现在知道该构建什么了。

# 7：状态（State）

状态是会发生变化的数据。

当你点击一个按钮，某些事情随之发生——状态改变了。当你在表单中输入文字并看到内容出现——状态改变了。当你切换深色模式，颜色随之翻转——状态改变了。

状态是让你的应用充满生命力的原因。
没有状态，一切都是静态的。

没有任何东西会按预期响应。

常见的状态示例：菜单是打开还是关闭？用户是已登录还是已退出？购物车里有哪些商品？输入框中的文字是什么？当前是加载中还是已加载完成？操作是成功了还是失败了？

当你的按钮没有任何反应时，通常是状态问题。点击事件确实发生了，但没有任何东西通知应用去更新。

向 AI 描述交互行为时，可以这样说：

> "当用户点击这个按钮时，将弹窗状态设为打开。当他们点击弹窗外部时，将其设为关闭。"

现在 AI 知道该追踪哪个状态，以及何时改变它了。

# 8：样式（Styling）

样式决定了事物的视觉呈现。

CSS 是控制外观的语言。
颜色、间距、字体、尺寸、位置，都由它掌管。

Tailwind 是一套快捷系统。无需编写 CSS 文件，你只需直接在元素上添加类名。`bg-blue-500` 将背景设为蓝色，`text-xl` 放大文字，`p-4` 添加内边距。

设计令牌（Design tokens）是可复用的一致性数值。你的品牌蓝不只是某种蓝色，而是在任何地方都使用同一个十六进制色值。你的间距不是随意的，而是始终以 4px 为倍数递增。你的圆角在每张卡片上保持一致。你的阴影值在每个具有层级感的元素上完全相同。使用设计令牌帮助我减少硬编码的颜色值以及 UI 幻觉问题。

这正是业余应用与精良产品之间的差距所在。当每个组件都使用相同的设计令牌，你的应用会显得浑然一体。而当每个组件各自发明自己的数值，整体就像是五个不同的人拼凑出来的。

在你开始编码之前，把所有这些内容锁定在你的前端规范 `.md` 文件中：

你的调色板，包含主色、辅助色、背景色、表面色、文字色、边框色、成功色、错误色和警告色的精确十六进制色值。你的间距刻度（4px、8px、12px、16px、24px、32px、48px、64px）。你的字体栈，包含标题、正文和小字的字号。你的圆角数值。你的阴影定义。你的过渡时间曲线。

当 AI 拥有这份文档时，它生成的每一个组件都会保持一致。没有它，你将花费数小时手动修正那些本不应该存在的不一致，这些不一致本不该出现。

相信我，我曾经历过，真的很烦。

避开这些痛苦。

样式指令越具体，AI 猜测的空间就越小。"将背景设为 `#3B82F6`，内边距 16px，圆角 8px"，永远胜过"弄成蓝色、加点内边距"。

# 9：响应式设计（Responsive Design）

响应式意味着你的网站在所有屏幕尺寸上都能正常运作。

你的笔记本屏幕很宽，你的手机屏幕很窄。

同一个网站，不同的布局。

在大屏幕上，展示更多列；在小屏幕上，将内容垂直堆叠。在大屏幕上，展示完整导航栏；在小屏幕上，展示汉堡菜单。

断点是设计发生变化的屏幕宽度。移动端为 0–640px，平板端为 640–1024px，桌面端为 1024px 及以上。

移动优先意味着先为最小屏幕设计，再逐步为更大屏幕增加复杂度。这也是 Tailwind 默认的工作方式。不带前缀的样式适用于所有屏幕。带前缀的样式（如 `md:` 和 `lg:`）只在对应断点生效。因此 `flex flex-col md:flex-row` 表示在移动端纵向堆叠，在平板端及以上横向并排。

这不是个人偏好，而是一种策略。移动优先迫使你优先考虑内容美观性和极简主义。什么内容在小屏上是绝对必要的？那就是你的核心。其余的都是面向更大屏幕的渐进式增强。而当你被限制在这样的小尺寸内时，它也会推动你确保用户体验简洁易用、真正令人心动。

在 `FRONTEND_GUIDELINES.md` 中定义你的断点和响应式规则。"导航：768px 以下使用汉堡菜单，以上使用完整横向导航。网格：移动端单列，平板端两列，桌面端三列。字体大小：每个断点放大 15%。"当 AI 拥有这些已记录的规则后，它构建的每个组件都能正确响应每种屏幕尺寸，而无需你反复重申。

始终以移动优先的思维去思考。你的用户中可能有 50% 以上在使用手机。如果你只在笔记本上测试，你将为大多数用户交付一个体验糟糕的产品。

# 10: Pages vs Routes

页面是用户看到的内容。

路由是显示该页面的 URL。

`yoursite.com/` 显示主页，`yoursite.com/about` 显示关于页面，`yoursite.com/products/123` 显示产品 123。

路由可以是静态的（`/about` 始终显示相同的页面），也可以是动态的（`/products/[id]` 根据 id 显示不同的产品）。

当你向 AI 描述你的应用时：

> "我需要 4 个页面：主页（/）、关于（/about）、所有产品（/products）、单个产品（/products/[id]）"

这样 AI 就了解了完整的结构。

它会构建正确链接的导航，并在正确的位置创建正确的文件。

# 11: Frontend vs Backend

前端是用户看到并与之交互的部分，即运行在浏览器中的界面。

后端是幕后发生的一切：数据库、用户账户、数据处理，以及运行在服务器上的内容。

当你提交表单时：前端收集你的输入并发送到服务器，服务器进行验证和保存，服务器返回确认信息，前端显示成功提示。

对于简单的网站，你可能不需要后端——静态页面、无数据库、无账户系统。对于需要用户系统、数据存储或复杂逻辑的应用，则需要前后端兼备。

请提前告知 AI 你的需求。"这只是前端，仅是一个落地页"和"这需要一个带有用户账户和数据库的后端"会产生完全不同的输出结果。

# 12: APIs

API 是两个系统相互通信的方式。

你的前端需要从后端获取数据，通过 API 发起请求。如果你的应用需要天气数据，它通过天气服务的 API 获取。如果你的应用需要处理支付，它通过 Stripe 的 API 进行交互。

把 API 想象成一位服务员。
你告诉服务员你想要什么，
服务员去厨房取餐，然后把你的订单端回来。

常见模式：GET 用于获取数据，POST 用于发送数据，PUT 用于更新数据，DELETE 用于删除数据。

当你与 AI 交流时：

> "页面加载时，向 `/api/products` 发起 GET 请求，并将结果以网格形式展示。"

这样 AI 就清楚地知道该构建什么了。

# 13: Databases

数据库是你永久保存数据的地方。没有数据库，刷新页面后一切都会重置。用户注册了，一刷新，没了。商品加入购物车，一刷新，没了。

初学者常用选项：

Supabase 是最容易上手的。
免费套餐，文档完善，还自带认证功能。
如果你不确定用什么，就用 Supabase。

什么时候需要数据库？用户可以创建账号。用户可以保存自己的内容。你需要存储提交的数据。你有随时间增长的数据。

什么时候不需要数据库？静态网站，所有人看到的内容相同。没有用户交互的作品集。只通过表单服务收集邮箱的落地页。

与 AI 对话时：

> "使用 Supabase。我需要一个包含 email 和 password 的 users 表，以及一个包含 title、content 和 user_id 的 posts 表。"

这样 AI 就了解你的数据结构，能据此构建所有内容。

# 14：身份验证

身份验证就是登录/登出，也就是证明某人的身份。

这比看起来要难。密码需要加密，会话需要管理，令牌需要处理。很容易出错。

不要从头构建身份验证。使用现成的服务。Clerk 最简单，自带精美的开箱即用界面。如果你已经在使用 Supabase 作为数据库，Supabase Auth 也是个好选择。

与 AI 对话时举例：

> "使用 Clerk 进行身份验证。用户可以通过邮箱或 Google 注册。登录后跳转到仪表板。"

让服务处理复杂的部分，你只需将其接入即可。

# 15：文件类型

你会在代码库中看到很多文件。

以下是部分文件的实际含义：

.html 是网页的结构。.css 是样式规则。.js 是让页面具有交互性的 JavaScript。.jsx 是带有类 HTML 语法的 React 用 JavaScript。.ts 是 TypeScript，即带有类型的 JavaScript，可捕获错误。.tsx 是带 React 的 TypeScript。.json 是结构化数据。.md 是 Markdown，即格式化文本。.env 是环境变量和密钥。.gitignore 告诉 Git 跳过哪些文件。

最重要的一个：.env。这里存放 API 密钥、私密信息、密码。永远不要分享这个文件。永远不要将它提交到 Git。永远不要对它截图。如果你泄露了 .env，你就泄露了一切的访问权限，某个幸运的坏人会把你的 API 账单刷到几千美元。别犯这个错误。

# 16：文件夹结构

文件放在哪里很重要。
项目混乱会让 AI 困惑。

标准结构：

my-app/
├── src/
│   ├── app/           → 页面和路由
│   ├── components/    → 可复用的 UI 组件
│   ├── lib/           → 工具函数、辅助函数
│   └── styles/        → CSS 文件
├── public/            → 图片、静态文件
├── .env               → 密钥（永远不要分享）
├── CLAUDE.md          → AI 规则和上下文
├── progress.txt       → 会话追踪
├── PRD.md             → 产品需求文档
├── APP_FLOW.md        → 用户流程和导航
├── TECH_STACK.md      → 锁定的依赖项
├── FRONTEND_GUIDELINES.md → 设计系统
├── BACKEND_STRUCTURE.md   → 数据库和 API 规范
├── IMPLEMENTATION_PLAN.md → 分步构建顺序
├── package.json       → 依赖项
└── README.md          → 项目概览

当 AI 生成代码时，告诉它把代码放在哪里。"在 src/components/Button.tsx 中创建按钮组件。"

如果你不指定位置，AI 可能把文件放到任何地方，导致什么都无法正确连接。

# 17：实践中的文档系统

Markdown 不是可选项。
它是 AI 思考所用的语言。

每一个你编写的 .md 文件，都会成为 AI 能够读取、理解并遵循的参考文档。这正是"文档优先"方法之所以奏效的原因。

你写的文档不是给人看的。
你写的是给 AI 的约束规则。

以下是每份标准化 Markdown 文档在构建过程中的具体用途：

**PRD.md** 是你关于项目范围的唯一可信来源。当 AI 试图添加你没有要求的功能时，你把它拉回到 PRD。"只构建 PRD.md 中列明的内容。"在决定下一步构建什么时，你查阅 PRD。它在范围蔓延萌芽之前就将其扼杀。

**APP_FLOW.md** 是你在构建页面跳转和用户旅程时参考的文档。"严格按照 APP_FLOW.md 第 3 节的说明构建登录流程。"AI 于是掌握了该流程中的每一个页面、每一次跳转以及每一个错误状态。

**TECH_STACK.md** 在项目初始化时以及每当 AI 试图引入新依赖时被引用。"仅使用 TECH_STACK.md 中列出的包。未经询问不得添加新依赖。"这可以防止 AI 随意导入你未经审批的库。

**FRONTEND_GUIDELINES.md** 是 AI 在创建每个组件时都应参考的文档。你的颜色、间距、字体排版、组件模式、响应式规则，全部在此。"按照 FRONTEND_GUIDELINES.md 第 2 节的规范为该组件设置样式。"确保每个文件的设计保持一致。

**BACKEND_STRUCTURE.md** 定义你的数据层。"按照 BACKEND_STRUCTURE.md 第 2.1 节的定义创建 users 表。"AI 会严格按照你指定的 Schema 进行构建，而不是凭自己的理解随意发挥。

**IMPLEMENTATION_PLAN.md** 是你的执行序列。"我们正在执行 IMPLEMENTATION_PLAN.md 的第 4.2 步。仅构建这一步。"这可以防止 AI 跳步或乱序构建。

**CLAUDE.md** 是主配置文件。它位于你的项目根目录，Claude Code 每次启动会话时都会自动读取。其中包含来自上述六份文档的精炼规则：技术栈摘要、命名规范、文件结构、组件模式、禁止操作。把它想象成 AI 在执行任何操作之前加载的操作系统手册。

大多数人错过的关键一步是：**CLAUDE.md 是一份活文档**。每当 AI 犯错并被你纠正后，以这句话收尾："编辑 CLAUDE.md，确保你不会再犯同样的错误。"Claude 异常擅长为自己编写规则。随着时间推移，你的 CLAUDE.md 会成为一本自我进化的规则手册。错误率会明显下降，因为 AI 实际上是在将自己的纠错过程编码固化下来（这理想状态下正是你希望发生的事）。

更进一步，创建一个 **lessons.md** 文件。每次纠错之后、每次 PR 之后、每次调试会话之后，让 Claude 将导致问题的模式以及防止该问题的规则更新到 lessons.md 中。在你的 CLAUDE.md 中指向它："会话开始时检阅 lessons.md，了解与本项目相关的内容。"这样 AI 就能从它在你项目上的历史经验中学习。这个自我改进的闭环，正是一份优秀的 CLAUDE.md 与一份卓越的 CLAUDE.md 之间的分野。

CLAUDE.md 示例：

> 技术栈：Next.js 14、TypeScript、Tailwind CSS、Supabase。所有组件放在 src/components/ 下。使用带有 hooks 的函数式组件。所有 API 路由放在 src/app/api/ 下。永远不使用内联样式，始终使用 Tailwind。设计令牌：主色蓝 #3B82F6，背景色 #F9FAFB。移动端优先的响应式方案。参考文档：PRD.md、APP_FLOW.md、TECH_STACK.md、FRONTEND_GUIDELINES.md、BACKEND_STRUCTURE.md、IMPLEMENTATION_PLAN.md。每次会话开始时读取 progress.txt，完成任何功能后更新 progress.txt。每次会话开始时查看 lessons.md，每次纠错后更新它。

当 Claude Code 读到这些内容时，它会在创建的每一个文件中遵守这些规则，不会偏移，不会随意决策。纯粹的一致性。

Cursor 有自己的对应版本：.cursor/rules 文件。

概念相同，工具不同。

把你的项目规则放进 .cursor/rules/，Cursor 就会在所有模式下自动读取它们。如果你在同一个项目上同时使用 Cursor 和 Claude Code，请保持 CLAUDE.md 与 Cursor 规则文件同步。

相同的约束、相同的规范、相同的唯一事实来源。有些人维护一份，然后复制到另一处。有些人写一个共享规则文件，再从两边分别引用它。

两种方式都行得通。

关键在于，每一个接触你代码库的 AI 工具都遵循相同的规则。

progress.txt 是你的会话桥梁。每完成一个功能就更新它：

> 已完成：通过 Clerk 实现用户认证（登录、注册、Google OAuth）；带侧边栏导航的 Dashboard 布局；Products API 端点（GET /api/products）。进行中：产品详情页（/products/[id]），需要将前端连接到 API。下一步：购物车功能；使用 Stripe 结账。已知 Bug：点击链接后移动端导航不会关闭。

当你打开新终端、开启新的 Claude Code 会话、切换分支，或者隔了一周再回来时，AI 读取这个文件就能精确知道你在哪里。不会再有"我们上次做到哪了？"，不会再有重新搭建上下文的过程，不会再有第 69 次重新解释整个项目的情况。

这就是这套系统。规范文档定义要构建什么，CLAUDE.md 执行规则，progress.txt 在会话之间保存状态。三者合一，给 AI 提供构建项目所需的一切，让它不再凭空臆测。

你拥有的 Markdown 文档越多，AI 猜测的就越少。

AI 猜测的越少，你就越省心。

# 第十八章：工具及其使用方法

你不需要 50 种工具。你需要的就是这些。

但你需要正确地使用它们。

构建的不同阶段，使用不同的工具。

**Cursor** ——你的代码编辑器。原生 AI 驱动，为这套工作流而生。它能看到你的整个项目，理解文件之间的关系，并且可以同时编辑多个文件。

但 Cursor 并非只有一种形态。它有四种模式，而大多数人只用了其中一种：

**Ask 模式**是只读的。AI 读取你的代码库并回答问题，不修改任何内容。当你在探索不熟悉的代码、试图理解某些东西的工作原理，或者在动手之前规划下一步时，就用它。把它当成你的代码顾问。"这个函数是做什么的？""为什么这个组件会重新渲染？""如果我修改这个 schema，哪些地方会出问题？"Ask 模式是你行动之前思考的地方。

Plan模式是你在编码前进行架构设计的地方。你描述你想构建的内容，Cursor会创建一份详细的实现计划，包含具体步骤，向你提出澄清性问题，并能生成方案的可视化图表。在每个新功能开始时都使用它。"我需要给这个应用添加Stripe结账功能。制定一个计划。"审查计划，调整它，批准这些步骤。然后将这些步骤发送给Agent模式来执行。

Agent模式是主力干将。这是AI自主编写代码、编辑文件、运行终端命令、安装包并修复错误的地方。它会读取你的整个项目，遵循你的规则文件，并端到端地实现功能。当你说"构建仪表板页面"时，正是这个模式在完成工作。大多数氛围编码都在这里发生。

Debug模式是那个鲜为人知的模式。当你遇到顽固的bug时，Debug模式不会随机尝试修复。它会用运行时日志对你的代码进行插桩，生成多种关于问题所在的假设，要求你复现bug，测试其修复方案，并请你验证。这是一个内置于编辑器中的结构化调试循环。

Cursor内部的工作流程：通过Ask来理解 → 通过Plan来架构 → 通过Agent来构建 → 出问题时用Debug来排查。

Claude——无论是通过Claude.ai还是Claude Code。Claude是你的思维伙伴。将Claude用于深度思考：审视你的想法、撰写你的六份规范文档、规划架构、处理复杂的产品决策，以及起草你的CLAUDE.md。Claude是你进行提问、规划和写作的地方，这些产出会在之后为其他一切提供素材。

Claude Code运行在你的终端中，会自动从你的项目根目录读取CLAUDE.md。它无需你重复说明便会遵循你的规则。对于大型重构、文档密集型任务以及多文件架构变更，Claude Code是你的最佳工具。

Kimi K2.5——来自Moonshot AI的开源视觉编码模型。这是前端实现的专家。K2.5是一个原生多模态模型，这意味着它从一开始就在视觉和文本的融合训练下成长。你可以向它提供截图、视频或设计稿，它会生成与视觉效果高度匹配的可运行前端代码。布局、动画、交互、响应式行为，无所不能。其他模型只能近似还原你的设计，而K2.5能够复刻它。当你需要将设计转化为代码时，通过Kimi Code或在Cursor中使用模型选择器来使用Kimi K2.5。

你有定义了系统规范的FRONTEND_GUIDELINES.md，你有作为参考的截图，你需要像素级精准的实现。这正是K2.5的领域。

Codex——OpenAI的编码智能体。这是你的调试器和收尾工具。Codex在云端运行，可通过Codex CLI在你的终端中使用，也可以直接在你的IDE中使用。每个任务都会获得一个预装了你代码库的独立沙箱。Codex的与众不同之处在于它处理调试的方式：它读取你的代码库，追踪依赖关系，审查配置，并提出跨文件的修复方案。它可以运行你的测试，修复失败，并持续迭代直到一切通过。

在你的文件和架构构建完成后使用Codex。当结构已就位但某些地方出了问题，当你在发布前需要代码审查，当你想在不破坏现有功能的前提下重构，当你需要有人找出你遗漏的bug时。Codex是收尾者。

您还可以并行运行多个 Codex 任务，分别处理不同的 Bug 或功能。它以异步方式运行。启动任务，去做其他事情，回来查看结果。

**多工具工作流：**

**Claude 负责思考。** Claude 编写你的文档、规划架构、做产品决策。

这是你提问、规划、思考的地方。

**Cursor Agent 模式（或 Claude Code，或 Kimi K2.5）负责构建。** 它会根据计划实现功能、生成组件、将前端连接到后端。根据任务选择使用的模型：
- K2.5 用于视觉密集型前端工作
- Claude Code 用于架构和文档密集型工作
- Cursor Agent 用于一般性实现

**Codex 负责调试和收尾。** 针对你已构建的代码库运行它。让它发现 Bug、追踪故障、审查代码并提出修复方案。让它持续运行测试直到全部通过。然后，干净利落地发布。

**GitHub** —— 这是你的代码在云端的家，具备版本控制，每次更改都有记录。你可以回退到任意历史版本。如果你搞坏了什么，可以撤销。这是你技术栈中不可或缺的一环。

**Vercel** —— 用于部署。推送到 GitHub，Vercel 自动构建并部署你的代码。你会得到一个在线 URL，Vercel 的免费套餐非常慷慨。你的应用只需几分钟就能从你的电脑上线到互联网。

**Supabase** —— 用于数据库和身份验证。他们有免费套餐，设置简单。它处理后端事务，让你专注于产品本身。

**掌握这些工具。**
**理解何时使用每一个。**

能发布产品的人和卡在原地的人之间的区别，不在于他们使用哪个 AI 模型，而在于知道在合适的时机使用哪个 AI 模型。

# 18.5：高级工作流
（当你准备好了之后）

一旦你用这套基础系统构建了几个项目，以下这些技巧将成倍提升你的速度。这些内容直接来自专门构建 Claude Code 的从业者。

**使用 git worktrees 并行运行会话。** 这是最大的单项生产力解锁。与其一次只做一件事，不如启动 3 到 5 个 git worktree，每个都并行运行自己的 Claude Code 会话。一个 worktree 构建身份验证系统，另一个构建仪表板布局，第三个处理 API 端点。它们共享同一个代码库，但各自独立运行。你在它们之间来回切换，审查输出，批准更改，完成后合并。过去需要整整一天顺序完成的工作，现在只需几小时并行执行。给你的 worktree 命名，并设置 shell 别名，这样你可以一键在它们之间跳转。

**将 Plan 模式作为你的倍增器。** 你已经知道要使用 Cursor 的 Plan 模式。以下是让它更强大的方法：让一个 Claude 会话编写计划，然后启动第二个会话，让它以高级工程师的视角审查该计划。"审查这份实现计划。找出其中的空白、我遗漏的边缘情况，以及任何会出问题的地方。" 在写一行代码之前先修好计划。当实现过程中出现问题时，立刻停下来。不要继续硬撑。切换回 Plan 模式，从当前位置重新规划。同样，也要将 Plan 模式用于验证步骤，而不仅仅是构建。"规划如何验证这个身份验证流程能处理所有边缘情况。"

子代理处理复杂问题。当问题规模大到一个 Claude 会话会被上下文撑爆时，使用子代理。在你的请求末尾加上"use subagents"，Claude 就会启动若干专注的子会话，分别负责研究、探索和并行分析，同时保持主会话上下文窗口的整洁。每个子代理只负责一项任务。把它想象成把工作委派给一支团队，而不是事事亲力亲为。

自定义技能与斜杠命令。如果某件事你每天做超过一次，就把它变成可复用的技能或斜杠命令，并提交到 git。构建一个 /techdebt 命令，在每次会话结束时运行，用来发现并消灭重复代码。构建一个 context-sync 命令，把过去一周的 Slack、文档和 GitHub 动态汇聚成一份摘要，让 Claude 每次会话一开始就掌握完整信息。技能是你教 Claude 学会你工作流专属能力的方式，它们会在你接触的每个项目中持续累积复利。

自主修复 Bug。不要再手把手带着调试器走流程了。收到 Bug 报告时，把它粘贴给 Claude，说"修掉它"。CI 测试失败时，说"去修掉那些失败的 CI 测试"。不用解释怎么做。把日志、错误堆栈跟踪和失败测试指给 Claude 看，让它自己追踪问题、找到根因、解决问题。你的注意力零切换。Claude 在读取 Docker 日志、追踪分布式系统、修复你原本要花几个小时才能搞定的问题上，能力出人意料地强。

语音听写，获得更好的提示词。你说话的速度是打字的三倍，而你的提示词质量也会因此大幅提升。在 macOS 上，连按两次 fn 键即可开始听写。用聊天的方式描述你想要什么，把那些因为打字太慢而通常会略去的细节和背景都说出来。提示词越长、越详细，输出结果越好。语音是到达那个境界的捷径。

学习模式。当你想理解 AI 在做什么，而不仅仅是让它去做的时候，在 Claude Code 的配置中启用"Explanatory"（解释型）或"Learning"（学习型）输出风格。Claude 会解释它所做的每一项改动背后的推理逻辑。你也可以让 Claude 生成可视化 HTML 演示来解释陌生的代码，用 ASCII 图形绘制架构与协议，或者从新概念中提炼出间隔重复抽认卡。那些在构建的同时持续学习的人，终有一天会不再需要这份指南。

# 19: Git 与版本控制

Git 追踪你所做的每一处改动。

没有 git：你搞坏了某些东西却无法撤销，你搞不清楚到底改了什么，一个失误就能毁掉一切。

有了 git：每处改动都被保存，你可以回退到任意历史版本，你的代码存放在 GitHub 上，而不只在你的电脑里。

基本操作：

git add . 暂存你的改动。git commit -m "message" 附带描述保存改动。git push 上传到 GitHub。git pull 拉取最新改动。

在你 vibe coding 的时候，要勤提交。每完成一个可用的主要功能就提交一次："Added user login"（添加了用户登录）"Added product grid"（添加了商品网格）"Fixed checkout bug"（修复了结账 Bug）。如果你搞坏了什么，随时可以回退。

这与你的 progress.txt 系统相互配合。提交代码，更新 progress.txt，一并推送。现在 GitHub 上既有你的代码，也有你的上下文文件。下次会话时，拉取下来，读一遍 progress.txt，继续构建。

# 20: 环境变量与密钥

你的 API 密钥、数据库密码和各类密钥，永远不应该出现在你的公开或生产代码库中。

它们应放在 .env 文件里。

然后在你的代码中，通过 process.env.YOUR_KEY_NAME 访问它们。

规则：永远不要将 .env 提交到 git（将其添加到 .gitignore）。永远不要在与 AI 应用的对话或截图中粘贴 API 密钥。如果你这样做了，就默认它已经泄露。永远不要将密钥放在前端代码中，只放在后端。为开发环境和生产环境使用不同的密钥。

当你部署到 Vercel 时，请在 Vercel 的仪表盘设置中添加你的环境变量。它们不会自动从你本地的 .env 文件中同步过去。

如果你泄露了一个密钥，立即前往对应的服务将其吊销。

再创建一个新的。

# 21：部署

你的代码在自己的电脑上运行正常。
现在它需要在互联网上运行。

使用 Vercel 的流程：

1. 将代码推送到 GitHub

1. 将 GitHub 仓库连接到 Vercel

1. Vercel 自动构建并部署

1. 你会获得一个类似 your-app.vercel.app 的 URL

1. 在 Vercel 的仪表盘中添加你的环境变量

当某个功能在本地正常运行，但部署后出现问题时，请将 Vercel 的错误日志提供给 AI。"它在 localhost 上运行正常，但在 Vercel 上报错了。以下是 Vercel 日志中的错误："然后粘贴错误信息。

99% 的部署问题都是环境变量缺失或构建设置错误导致的。

# 22：读懂报错信息

报错不是羞辱，而是指引。

报错信息会准确告诉你哪里出了问题。大多数人会慌乱，然后忽略它。请不要这样做。

报错信息的结构：

TypeError: Cannot read property 'map' of undefined
    at ProductList (src/components/ProductList.tsx:15:23)

解读：TypeError 意味着你对某个东西的使用方式不对。"Cannot read property 'map' of undefined" 意味着你试图对一个不存在的东西调用 .map()。

ProductList.tsx:15:23 告诉你出错的具体文件和行号。

当你遇到报错时，把所有信息都提供给 AI：

> "我遇到了这个错误：[完整的错误信息]。以下是那一行的代码：[粘贴相关代码]"

你给 AI 提供的错误上下文越多，问题被修复的速度就越快。

# 23：调试循环

当某处出现问题时：

1. 读报错信息。认真地读。

1. 定位问题所在。哪个文件，哪一行。

1. 理解报错的含义。报错说哪里出了问题？

1. 检查显而易见的地方。拼写错误、缺少导入、变量名错误。

1. 给 AI 提供上下文。报错信息 + 代码 + 你预期的结果。

循环流程：AI 给你代码 → 你去尝试 → 出现问题 → 你粘贴报错 → AI 修复 → 重复，直到成功。

对于经过两三轮循环仍然存在的顽固 bug，请换用其他工具。使用 Cursor 的调试模式。它会生成多种假设，用运行时日志对你的代码进行埋点，并系统地逐步排查 bug，而不是靠猜测。或者启动 Codex。将 bug 描述提供给它，让它追踪你的整个代码库，找出根本原因，并持续迭代直到测试通过。Codex 特别擅长处理跨多个文件或涉及数据流的 bug，因为它会在提出修复方案之前先读取整个代码仓库。

这是正常现象。即使我们都希望"氛围编程"是一次就能搞定的事，但通常并非如此。它是迭代式的。真正的技能在于快速迭代并知道何时使用哪种工具，而不是完全避免迭代。

# 24：发布前的验证

发布之前，请检查：

这在手机上能用吗？真正用手机打开试试。在不同浏览器里能用吗？没有数据时会怎样，空状态有没有处理？数据错误时会怎样，错误状态有没有处理？网速慢时会怎样，加载状态存在吗？快速点击会不会让它崩溃？浏览器开发者工具里，敏感信息有没有被隐藏？

在回答这些问题之前，不要发布。
你的用户会找出你遗漏的每一个bug。

认真做好这个流程。

# 25：用AI来处理这一切

现在你已经掌握了这些词汇……

你需要用起来。

模糊的提示词：

> "给我做一个用户可以发帖的应用"

有文档支撑的具体提示词：

> "先阅读CLAUDE.md和progress.txt，然后执行IMPLEMENTATION_PLAN.md中的第4.2步。登录流程在APP_FLOW.md第3节中定义。

使用BACKEND_STRUCTURE.md第5节中的认证配置。所有样式按照FRONTEND_GUIDELINES.md执行。UI要与附上的截图保持一致。"

同一个想法。

输出质量却截然不同。

这种具体性不是额外的工作，它本身就是"工作"。前期定义得越清晰，后期调试的时间就越少。

# 26：如何读懂AI的输出

AI给你生成了一些代码。

你知道自己在看什么吗？

你不需要理解每一行代码，但你需要理解其结构。创建了哪些文件？它们各自做什么？它们之间如何连接？

当AI生成代码时，问这个问题："用通俗易懂的语言解释你刚刚构建了什么。每个文件是做什么的？它们是如何连接的？"

随着时间推移，你会开始识别模式。你会看到一条导入语句，就知道它在引入另一个文件。你会看到useState，就知道它在追踪某个会变化的东西。你会看到一个API调用，就知道它在获取数据。

这就是你从"凭感觉写代码"到真正成为开发者的路径。不是靠记忆语法，而是靠理解模式。

# 27：如何迭代

几乎没有人的第一版输出是完全正确的……

这没关系。

迭代流程：

1. AI构建第1版
1. 你测试它，找出问题所在
1. 具体描述问题所在（不是"坏了"，而是"提交按钮没有保存到数据库，错误信息如下"）
1. AI修复它
1. 再次测试
1. 重复

好的迭代方式："产品网格在桌面端显示4列，但我需要3列。卡片图片被拉伸了，应该使用object-cover。而且数据加载时没有loading状态。"

糟糕的迭代方式："看起来不对，修一下。"

永远要具体。

# 28：将大想法拆解成小块

AI面对宏大、模糊的需求时往往会崩掉。

"给我做一个完整的电商网站"大概率会产出一堆垃圾。

把它拆解成小块：

1. 搭建项目脚手架并安装依赖
1. 构建导航栏组件
1. 构建产品卡片组件
1. 构建产品网格页面
1. 连接数据库并获取产品数据
1. 构建单个产品页面
1. 添加购物车功能
1. 构建购物车页面
1. 接入Stripe完成结账

每个小块对应一次对话或一个任务。

每个小块在前一个的基础上构建，并且每个小块都可以独立测试。回想一下你玩乐高的岁月，这其实就是那回事。

这实际上就是你的IMPLEMENTATION_PLAN.md所做的事情。

上面那个列表，编号排列、有先后顺序，就是你的实施计划的确切格式。如果你在第2部分认真做了这项工作，这个拆解方案你早就写好了。

你不需要在写代码的过程中临时创建它。
你在开始之前就已经创建好了。

现在你只需要去执行它。
一步一步，按计划来。

告诉AI："按照 # 构建第5步。"

不是"构建下一个东西。"

精确性会复利叠加。

这与你的 progress.txt 文件息息相关。

每完成一个部分，更新进度。
开始下一个部分时，带着全新的上下文。

# 29：AI 并非万能工具

有些东西，你就是需要自己去学。

用 AI 来做的事：生成样板代码、编写重复逻辑、快速探索实现思路、结合上下文调试，以及将你的意图转化为代码。

需要自己学的东西：核心概念（本指南中的所有内容）、如何读懂 AI 生成的代码、如何发现 AI 的错误、如何在 AI 帮不上忙时自己调试，以及你所选技术栈的底层工作原理。

如果你把一切都托付给 AI，你就是在流沙上建房子。遇到一个奇怪的 bug，你就会卡住，然后越陷越深。如果 AI 解释出错而你信以为真，那……你就完了。所以也许，就是也许，现在把这些东西学会吧。

还有：很多时候，官方网站文档比 AI 的信息更好用。Stack Overflow 对具体报错有精准答案。文档网站提供权威信息。AI 擅长综合与生成，但当它失效时，知道如何检索官方文档和网站，才是那个没人提起的保底技能。而且 Claude 甚至可以从这些资源中自学它所需的一切。

# 30：范围意识与知道何时该停手

一份永无止境的功能清单，比烂代码更能杀死项目。

当以下条件满足时，你就完成了：核心功能可以运行、用户能够完成主要操作、常见流程不会崩溃、产品已部署且可访问。

你还**没完成**的情况：它"完美了"、每个边界情况都处理好了、拥有了你脑海中构想的所有功能、看起来和 Dribbble 上的设计一模一样。

先上线简化版，收集反馈。
然后，根据真实使用情况持续改进。

那个永远没发布的最佳应用，比不上那个已经上线的普通应用。

# 31：维护你构建的东西

你把它做出来了，而接下来你还需要不断修改它：

未来的你（或 AI）需要能看懂这些代码。这正是你的文档体系真正发挥价值的时候。

你的 README 解释了项目是什么。你的 CLAUDE.md 执行各项规则。你的 progress.txt 记录了已构建的内容和下一步计划。你的规范 Markdown 文档定义了产品的每一个方面，从需求到实施顺序。

当你三个月后重新回到代码时：

> "读取 CLAUDE.md、progress.txt 和 PRD.md。我在中断一段时间后重返这个项目。请对照 IMPLEMENTATION_PLAN.md，总结当前进展状况以及需要关注的内容。"

好的文档能让未来的氛围编程会话效率提升 10 倍。

糟糕的文档意味着从零开始。

保持依赖项更新，在令人困惑的代码部分写注释，使用一致的命名规范，把你的代码库当成一个 Airbnb 出租屋来对待——陌生人住进来需要知道东西放在哪里。

32：成本意识

API 调用要花钱。数据库要花钱。
托管可能要花钱。AI 工具要花钱。

免费套餐是存在的，而且相当慷慨。Vercel 免费，Supabase 免费，Clerk 免费（有限额），等等。

但当你扩展规模时，费用很可能就会出现。

关于工作流中的 AI 工具：Cursor Pro 涵盖大多数模型访问权限，是你的主要订阅。Claude Code 的使用通过你的 Anthropic 或 Claude 套餐计费。Codex 包含在 ChatGPT Plus、Pro 及更高套餐中。Kimi K2.5 是开源的，可通过 Kimi.com 免费使用，且 API 定价非常优惠。

第一天不需要所有付费套餐。从 Cursor Pro 加 Claude 或 Gemini Pro 3 开始。等工作流有需要了，再添加其他的。

清楚哪些是免费的，哪些会累积费用。AI API 调用（OpenAI、Anthropic）按 token 计费。数据库存储超出免费额度后开始收费。图片托管在规模扩大后也会产生费用。

从免费开始，按需扩展。

第一天不要为数百万用户做架构设计。

因为现实是，你很可能根本达不到那个量级。从小处做起。

# 33：安全基础

最低限度要做到：

永远不要在前端代码中暴露 API 密钥。始终在后端验证输入（不要信任任何来自浏览器的内容）。使用 HTTPS（Vercel 会自动处理）。保持依赖项更新（过时的包存在已知漏洞）。使用认证服务，而不是自己从头搭建。

你并不是在构建一个高安全级别的银行系统，但你也应该了解所有安全基础知识，以免发布的应用带有明显漏洞。

也别让自己在网上被嘲笑。

这是大多数人最不想经历的噩梦。

# 34：第三方服务

你不需要从头构建一切。
对于难啃的部分，直接接入服务。

认证：Clerk、Supabase Auth。处理登录、注册和会话。支付：Stripe。处理资金。数据库：Supabase、Firebase。处理存储。邮件：Resend、SendGrid。处理事务性邮件。文件上传：Uploadthing、Supabase Storage。处理媒体文件。

什么时候该接入服务：只要某个功能不是你的核心产品，就接入服务。你的核心产品是你正在构建的那个独特的东西，其他一切都是基础设施。

基础设施部分，用现有服务搞定。

# 35：资源、媒体与组件库

图片、字体、图标以及预构建组件。
从哪里获取，如何使用。

图标：Lucide React。免费、风格统一、易于使用。字体：Google Fonts。在布局文件中引入，全局使用。图片：Unsplash 用于素材图，产品截图用自己的，定制图可用 AI 生成。文件大小很重要：大图会拖慢你的网站速度，上传前先压缩，使用 Next.js Image 组件自动优化。

组件库是大多数初学者不知道的作弊码。与其从头构建每一个按钮、弹窗、下拉框和表单元素，不如使用一个库，开箱即用地给你提供精美、无障碍、可定制的组件。

shadcn/ui 是目前 Next.js 和 Tailwind 生态中的主流选择。它不是你作为依赖项安装的传统库，而是将组件源代码直接复制到你的项目中，也就是说你拥有这些代码，可以自由定制一切。按钮、对话框、下拉菜单、标签页、表单、数据表格，全部基于 Radix UI 原语，配合 Tailwind 样式构建。告诉 AI："使用 shadcn/ui 组件，用 `npx shadcn@latest init` 初始化，并添加我们需要的组件。"这能省去你数小时构建基础 UI 元素的时间，一开始就给你提供无障碍、生产级质量的组件。

把你的组件库选择记录在 TECH STACK .md 和 FRONTEND GUIDELINES .md 中，这样 AI 在每个页面上都会一致地使用它。

# 完整系统

你现在已经拥有了一切。

开始构建之前：

1. 运行审讯提示词，让 AI 对你的想法进行严酷的盘问。

1. 回答 AI 提出的每一个问题。

1. 使用文档生成提示词，创建你的六份核心文档：PRD.md、APP_FLOW.md、TECH_STACK.md、FRONTEND_GUIDELINES.md、BACKEND_STRUCTURE.md、IMPLEMENTATION_PLAN.md

1. 编写你的 CLAUDE.md，包含项目规则、对全部六份文档的引用，以及用于自我改进循环的 lessons.md

1. 创建 progress.txt，记录你的初始状态

1. 收集 UI 截图作为参考

1. 初始化 git 并推送到 GitHub

构建过程中：

1. AI 在每次会话开始时，首先读取 CLAUDE.md、progress.txt 和 lessons.md

1. 在 Cursor（或 Claude）中使用询问模式和规划模式，先完成架构设计再动手编码

1. 使用 Agent 模式、Claude Code 或 Kimi K2.5 来实现功能（根据任务匹配工具）

1. 以小块方式推进，每次只做一个功能

1. 编写具体且术语丰富的提示词，引用你的规范文档

1. UI 工作时使用截图作为参考

1. 每完成一个可运行的功能后提交到 git

1. 每完成一个功能后更新 progress.txt

1. 每次修正错误后，更新 CLAUDE.md 和 lessons.md，确保 AI 不再犯同样的错误

1. 架构搭建完成后，使用 Codex 进行调试、审查和收尾

1. 定期在移动端测试

1. 仔细阅读报错信息，不要慌张

发布前：

1. 检查移动端

1. 检查错误状态和空状态

1. 确认密钥已隐藏

1. 端到端测试主要用户流程

1. 检查性能（是否有卡顿？）

发布后：

1. 更新文档，反映已构建的内容

1. 定期更新依赖

1. 根据真实用户反馈持续迭代

1. 保持 progress.txt 和 lessons.md 的更新，供未来会话使用

1. 将重复的工作流程转化为可复用的技能和斜杠命令

这就是完整的系统。

Vibe coding 不是什么巫术魔法。它的本质是：细致的规划、完善的系统、充分的文档、精准的词汇，以及持续的迭代。你深度审视你的想法。你编写你的 Markdown 文档。你设置 CLAUDE.md、progress.txt 和 lessons.md，实现持久化记忆与自我改进。

你为每个阶段选用合适的工具：Claude 负责提问、思考和规划，Cursor 各模式负责构建，Kimi K2.5 负责视觉实现，Codex 负责调试和收尾。

你用具体的语言描述工作。
你在会话之间追踪进度。
你提交你的代码。然后你发布。

现在，AI 负责所有的打字。
而你负责所有的思考。

你已经没有任何借口了。

今天就去他妈的造点东西出来。

---

如果你读到了这里，你已经超越了 99% 会把这篇文章收藏起来、然后保证再也不会回来看的人。比他们做得更好。

注：我不是传统意义上的开发者。我是自学成才的。这份指南里的一切，都来自于用最笨的方法构建东西、把它搞坏、弄清楚原因、再把真正有效的方法记录下来的过程。如果有任何错误、遗漏或过时的内容，请告诉我。这是一份活文档，我宁愿修正它，也不愿让人在错误的建议上构建东西。

关注我（https://x.com/kloss_xyz）获取更多 AI、Vibe coding 和生成式 AI 相关内容。