拒绝“氛围编程”失败：如何用文档驱动系统让 AI 代码助手真正交付

为什么你明明使用了最先进的 AI 编程工具（如 Cursor 或 Claude Code），却依然只能得到一堆无法运行的破碎代码？

核心答案只有一个：问题不在于 AI“幻觉”，而在于你作为操作者缺乏结构化的思维与约束。AI 是一个翻译器，它将你的意图转化为代码；如果你的意图模糊、缺乏约束，输出的结果必然是混乱的。通过建立一套严格的“文档优先”系统，将所有规范、流程和上下文预先固化，你就能彻底解决 AI 编程中的不确定性，真正实现软件的高效交付。

本文将深入探讨如何从混乱走向秩序，利用文档系统和特定的工具链，构建出真正可用的软件产品。

Coding setup
图片来源：Unsplash

为什么你的 AI 编程尝试总是失败？

你失败的根本原因在于你跳过了基础，试图用一句模糊的描述来换取一个完整的应用程序。

如果你不知道什么是组件、什么是状态、为什么页面在手机上会崩坏，你就无法准确地向 AI 描述你的需求。AI 在没有清晰上下文的情况下，只能靠“猜”来填补逻辑空白。每一次猜测都是错误的累积，最终导致系统崩溃。

必须改变的心态：AI 是翻译器，不是魔术师

AI 并不具备直觉，它只能处理你输入的信息。当你说“做一个类似 Airbnb 的网站”时，这个指令对于 AI 来说充满了巨大的变量：是用 React 还是 Vue？数据库选什么？用户权限怎么设计？颜色用什么？如果没有明确的约束，AI 会随意填充这些空白，导致代码结构松散，依赖冲突。

解决之道不在于优化提示词，而在于提升你对构建对象的理解，并将这种理解转化为 AI 能读懂的硬性规则。

深度反思：从“命令者”到“架构师”的转变

我以前也常犯这种错误，打开 Cursor 就开始聊天，指望它能帮我搞定一切。结果往往是生成了一堆看起来很炫酷但实际上根本跑不通的代码。后来我意识到，我把自己当成了发号施令的经理，而 AI 成了一个没有明确执行标准的新手员工。当我开始坐下来，先写清楚需求文档和规范时，项目质量发生了质的飞跃。这不仅仅是多做了工作，这是在为项目打地基。

什么是“文档优先”系统？

要想让 AI 输出高质量代码，你必须先建立一套完整的知识库，这套知识库由六个核心文档和两个会话文件组成。

这套系统的核心逻辑是：在编写任何一行代码之前，先通过文档确立“单一事实来源”。AI 编程工具能力很强但确定性很低，缺乏约束文档会导致 AI 产生幻觉，随意添加你未授权的功能或做出错误的架构决策。

核心文档一：产品需求文档 (PRD)

这是你与 AI 签订的“合同”。它必须包含：

  • 构建内容：具体是什么产品？
  • 目标用户：谁在使用它？
  • 功能列表：哪些功能在范围内，哪些明确排除在范围外？
  • 用户故事：用户在什么场景下做什么操作？
  • 成功标准：怎么做才算“完成”？

没有 PRD，你不是在开发软件，你只是在祈祷。

核心文档二：应用流程文档 (APP_FLOW.md)

用简单的英语或中文记录每一个页面和每一条用户导航路径。

  • 触发流程的操作是什么？
  • 一步步的决策点在哪里？
  • 成功时发生什么？错误时发生什么？
  • 屏幕清单与路由规则。

这能有效防止 AI 猜测用户如何在应用中移动，确保交互逻辑的一致性。

核心文档三：技术栈文档 (TECH_STACK.md)

严格锁定每一个依赖包的精确版本。
不要只写“使用 React”，因为 AI 可能会选择任意版本。你应该写明：“Next.js 14.1.0, React 18.2.0, TypeScript 5.3.3”。这样可以完全消除依赖项幻觉和随机的技术选型。

核心文档四：前端指南文档 (FRONTEND_GUIDELINES.md)

这是你完整的设计系统规范，包含：

  • 字体：字体系列与大小。
  • 色彩板：带有精确十六进制代码的主色、次色、背景色、边框色等。
  • 间距标度：如 4px, 8px, 16px 等倍数关系。
  • 布局规则：组件样式、响应式断点。
  • UI 库偏好：是否使用特定组件库。

这能彻底解决 AI 随机生成颜色和间距不一致的问题。

核心文档五：后端结构文档 (BACKEND_STRUCTURE.md)

定义数据层的每一个细节：

  • 数据库架构：每个表、每一列、类型和关系的定义。
  • 认证逻辑：如何验证身份。
  • API 端点契约：接口规则。
  • 存储规则与边缘情况。

如果你使用 Supabase，这里应包含精确的 SQL 结构。AI 将根据此蓝图构建后端，而不是基于它自己的假设。

核心文档六：实施计划文档 (IMPLEMENTATION_PLAN.md)

不要只写“构建应用”，要将其分解为：

  • 步骤 1.1：初始化项目。
  • 步骤 1.2：安装 TECH_STACK.md 中的依赖。
  • 步骤 1.3：创建文件夹结构。
  • 步骤 2.1：根据 FRONTEND_GUIDELINES.md 构建导航栏组件。

步骤越详细，AI 猜测的空间越小。

两个不可或缺的会话文件

除了上述六个文档，你还需要两个文件来维持会话的连续性和规则执行。

1. 规则文件 (.clauderules 或 .cursor/rules)

这是 AI 在每个会话开始时自动读取的第一个文件。它包含了该会话必须遵循的规则、约束、模式和上下文，例如：

  • 技术栈摘要。
  • 文件命名约定。
  • 组件模式（例如：使用带有 Hooks 的函数组件）。
  • 禁止的操作（例如：永远不要使用内联样式，必须使用 Tailwind）。
  • 设计系统令牌。

这就是你的 AI 针对特定项目的操作手册。在 Cursor 中，你可以将项目规则放在 .cursor/rules/ 目录下；在 Claude Code 中，放在根目录的 .clauderules 即可。

2. 进度跟踪文件 (progress.txt)

这是最容易被忽视但最重要的文件。由于 AI 在会话之间没有记忆，当你关闭终端或开启新聊天时，一切都会归零。progress.txt 充当了你的外部记忆桥。

文件内容示例：

已完成：
- 通过 Clerk 实现用户认证
- 带侧边栏导航的仪表板布局
- 产品 API 端点 (GET /api/products)

进行中：
- 产品详情页 (/products/[id])
- 需要连接前端到 API

下一步：
- 购物车功能
- 使用 Stripe 结账

已知 Bug：
- 移动端导航点击链接后不关闭

每次完成一个功能后，你都要虔诚地更新这个文件。每当开始新会话、切换分支或一周后回归项目时，AI 读取此文件，就能瞬间接续上你的工作进度，无需从头重新解释。

如何在写代码前对 AI 进行“审讯”？

在编写任何文档之前，必须先让 AI 彻底剖析你的想法。这是改变一切的关键步骤。

核心操作：使用以下提示词，强制 AI 进入“仅规划模式”：

“

“在编写任何代码之前，请进入仅规划模式，不断地审讯我的想法。不做任何假设。一直提问，直到没有任何假设为止。”

AI 应该问你的关键问题

如果 AI 没有主动问，你需要确保自己能回答这些问题：

  • 这是为谁服务的？
  • 用户采取的核心行动是什么？
  • 完成该行动后会发生什么？
  • 需要保存什么数据？
  • 需要显示什么数据？
  • 出错时怎么办？
  • 成功时怎么办？
  • 需要登录吗？需要数据库吗？需要在手机上工作吗？

实战案例：食谱分享应用

如果你在做一个食谱分享应用，审讯过程可能是这样的：

  • 用户：家庭厨师，想保存和分享食谱。
  • 核心行动：用户创建包含标题、配料表、步骤和照片的食谱。
  • 后续：食谱保存到个人资料并在公共信息流中可见。
  • 数据保存：食谱标题、配料（数组）、步骤（数组）、照片 URL、作者 ID、时间戳。
  • 数据展示：最近食谱的信息流、单个食谱详情页、用户自己的食谱集合。
  • 错误状态：上传失败、缺少必填字段、未经授权的编辑尝试。
  • 登录：是的，创建食谱需要登录。浏览是公开的。
  • 数据库：是的，用户表和带有外键关系的食谱表。
  • 移动端：是的，大多数用户会在做饭时通过手机添加食谱。

一旦审讯完成且你有了所有清晰答案，使用第二个提示词：

“

“根据我们的审讯，生成我的规范性文档：PRD.md, APP_FLOW.md, TECH_STACK.md, FRONTEND_GUIDELINES.md, BACKEND_STRUCTURE.md, IMPLEMENTATION_PLAN.md。使用我们对话中的答案作为素材。具体且详尽，不允许模棱两可。”

这样生成的文档就是你项目唯一的真理来源。

必须掌握的 Web 开发核心概念

如果你无法用专业术语描述需求，AI 就无法准确执行。以下是你在与 AI 交流时必须熟练掌握的概念。

1. UI 与 UX 的区别

  • UI (用户界面)：视觉层。颜色、字体、按钮形状、间距。
  • UX (用户体验)：感受层。是否直观？流程是否顺畅？用户是否会感到沮丧？

操作技巧：不要说“让它看起来更好”，要说“让它更容易使用”。更高级的做法是使用截图作为参考。找到你喜欢的应用界面（例如在 Framer 或 Dribbble 上），截图并发给 AI，提示“匹配此布局”或“使用此 UI 作为灵感”。AI 可以从截图中提取设计模式、间距和配色。目前 Google 的 Gemini 3 Pro 在这方面表现出色。

2. 组件化思维

组件是可复用的界面片段，就像乐高积木。按钮是组件，导航栏是组件，卡片是组件。
错误提示：“帮我建一个落地页。”
正确提示：“建立一个落地页，包含以下组件：导航栏、英雄区、功能网格（3 个卡片）、推荐轮播、CTA 区、页脚。”

3. 布局逻辑

网页就是“盒子套盒子”。掌握容器、网格、卡片的概念。
场景示例：

“

“双栏布局。左侧边栏宽 250px。主内容占据剩余空间。边栏固定，不滚动。”

4. 状态管理

状态是会改变的数据。点击按钮、切换暗色模式、提交表单都是状态的变化。
如果点击按钮没反应，通常是状态问题。
提示示例：“当用户点击此按钮时，将模态框状态设置为打开。点击外部时，将其关闭。”

5. 样式与设计令牌

CSS 控制外观，Tailwind 是 CSS 的快捷方式。设计令牌是可复用的固定值（如品牌色 #2563EB，间距 4px 的倍数）。
所有这些必须预先锁定在 FRONTEND_GUIDELINES.md 中，这样 AI 生成的每个组件才能保持一致，而不是每个文件都有随机的颜色和间距。

6. 响应式设计与移动优先

响应式意味着适配所有屏幕。移动优先意味着先为最小屏幕设计，再为大屏幕添加复杂性。
断点参考：

  • 移动端：0-640px
  • 平板：640-1024px
  • 桌面：1024px 以上

在文档中定义清楚：“导航栏在 768px 以下显示汉堡菜单，以上显示完整水平导航。”

7. 页面与路由

页面是用户看到的界面，路由是 URL。/ 显示首页，/about 显示关于页。区分静态路由和动态路由（如 /products/[id]）。

8. 前端与后端及 API

  • 前端：浏览器运行的界面。
  • 后端：服务器上的数据处理、数据库、逻辑。
  • API：前后端沟通的桥梁（像餐厅服务员）。

新手建议：

  • 简单站点（无数据库、无账户）：仅前端。
  • 复杂应用（用户数据、逻辑）：前端 + 后端。
  • 数据库推荐：Supabase（免费、简单）。
  • 认证推荐：Clerk（简单、UI 好看）或 Supabase Auth。

9. 安全与环境变量

.env 文件存储 API 密钥和密码。
铁律：永远不要将 .env 提交到 Git，永远不要在截图或聊天中泄露密钥。一旦泄露，立即在服务商处撤销并重新生成。

如何正确使用 AI 工具链？

不同的工具适合不同的阶段。不要试图用一把锤子解决所有问题。

1. Cursor：你的代码编辑器

Cursor 有四个核心模式，大多数人只用了一个：

  • Ask 模式：只读模式。用于理解代码、探索、规划。就像咨询顾问。
  • Plan 模式：架构先行。在写代码前生成详细的实施计划，甚至画出视觉图。适合每个新功能的开始。
  • Agent 模式：主力工兵。自主写代码、改文件、装包。这是“氛围编程”发生的主要场所。
  • Debug 模式：调试神器。遇到顽固 Bug 时，它会插入日志、生成假设、逐步测试，而不是盲目猜测。

工作流：Ask 理解 -> Plan 架构 -> Agent 构建 -> Debug 修复。

2. Claude：你的思考伙伴

无论是网页版还是 Claude Code，Claude 适合做“重思考”的工作：审讯想法、写六个核心文档、规划复杂架构。Claude Code 运行在终端，能自动读取 .clauderules，非常适合大型重构或文档密集型任务。

3. Kimi K2.5：视觉专家

这是 Moonshot AI 的开源视觉模型。当你有设计稿（截图、Mockup）需要像素级还原成代码时，使用它。它能处理布局、动画、交互，比文本描述精准得多。

4. Codex：调试与收尾者

OpenAI 的 Codex 适合作为调试器和代码审查员。它在沙箱中运行，能追踪依赖关系、运行测试并修复 Bug。当架构已定但东西跑不通时，用 Codex 来收尾。

多工具协作流

  • Claude 负责思考和写文档。
  • Cursor Agent (或 Claude Code/Kimi K2.5) 负责具体构建。
  • Codex 负责调试和最终通过测试。

高级工作流：当基础熟练后

如果你想将速度提升数倍，可以尝试以下高级技巧：

1. 并行会话与 Git Worktrees

不要一次只做一件事。开启 3-5 个 git worktrees，每个运行独立的 Claude Code 会话。一个做认证，一个做布局，一个做 API。它们共享仓库但独立工作，最后合并。这能将原本一整天的工作压缩到几小时。

2. 计划模式的力场倍增

在实施前，不仅让一个 Claude 写计划，再开启第二个会话扮演“首席工程师”来审查计划：“找漏洞、找边缘情况、找会崩的地方”。修复计划后再写代码。

3. 自动化 Bug 修复

收到 Bug 报告或 CI 测试失败时，直接发给 Claude：“修复它”。不要解释怎么做。让它去读日志、追根溯源、解决它。

4. 语音口述提示

你说话的速度是打字的三倍，且细节更丰富。在 Mac 上使用语音输入（按两下 Fn 键），像对话一样详细描述你的需求。这通常能产生更好的代码输出。

部署、验证与迭代

代码写完了只是开始，能跑起来并交付才是终点。

1. Git 与版本控制

Git 记录每一次更改。习惯：每完成一个能运行的功能就提交一次。

  • git add .
  • git commit -m "Added user login"
  • git push

2. 部署流程

使用 Vercel 进行部署是最简单的：

  1. 推送代码到 GitHub。
  2. 将 GitHub 仓库连接到 Vercel。
  3. Vercel 自动构建并部署。
  4. 在 Vercel 仪表板中添加环境变量（注意：这不会从本地 .env 自动转移）。

常见问题：本地能跑，线上报错。99% 的原因是缺少环境变量或构建设置错误。把 Vercel 的错误日志发给 AI 修复。

3. 验证清单

在发货前，必须确认：

  • 在真机上测试了吗？
  • 空数据状态（Empty State）处理了吗？
  • 错误状态处理了吗？
  • 慢网络时的加载状态呢？
  • 快速点击会弄坏应用吗？
  • 密钥真的没泄露吗？

4. 阅读错误信息

不要恐慌，错误信息就是说明书。

  • TypeError：你用错了东西。
  • Cannot read property ‘map’ of undefined：你试图对不存在的东西使用 .map()。
  • 文件名:行号：直接告诉你去哪里修。

5. 迭代的艺术

好的迭代：“产品网格在桌面端显示 4 列，但我需要 3 列。卡片图片被拉伸了，应该用 object-cover。获取数据时没有加载状态。”
坏的迭代：“看起来不对，修一下。”

把大想法拆成小块（LEGO 积木），一步步执行。这就是 IMPLEMENTATION_PLAN.md 的作用。

Debugging process
图片来源：Unsplash

结论：重新定义你与 AI 的协作关系

如果你读完了这篇指南，还是无法交付软件，那问题出在努力程度，而不是信息缺失。

“氛围编程”不是靠一句咒语变出代码，而是靠一套严谨的系统来驾驭巨大的算力。当你建立了文档优先的思维，掌握了这些工具和概念，你就不再是一个只会发号施令的旁观者，而是一个能够指挥 AI 军团构建宏伟软件的指挥官。

从今天开始，不要只写一句“帮我做个 App”。坐下来，打开你的编辑器，写下第一个 PRD.md。这才是真正的高级工程师该做的。

实用摘要 / 操作清单

为了让你快速上手，以下是关键步骤的精简清单：

项目启动前

  1. 审讯想法：用 AI 提问自己，直到没有任何假设。
  2. 生成文档：让 AI 基于审讯结果生成 6 个核心文档。
  3. 锁定规则：创建 .clauderules 文件，确立技术栈和命名规范。
  4. 初始化跟踪：创建 progress.txt，记录起始状态。

编码过程中

  1. 引用文档：每次提示 AI 时，引用具体的文档章节（例如：“按照 FRONTEND_GUIDELINES.md 第 2 节设计”）。
  2. 分步执行：按照 IMPLEMENTATION_PLAN.md 一步步来，每次只做一个步骤。
  3. 即时更新：每完成一个功能，立即更新 progress.txt 并提交 Git。
  4. 善用工具：用 Plan 模式架构，用 Agent 模式构建，用 Debug 模式排错。

部署与维护

  1. 保护密钥：确保 .env 在 .gitignore 中，且仅在服务器端配置。
  2. 真机验证：必须在移动端和不同浏览器上测试。
  3. 日志驱动：遇到部署错误，直接把 Vercel 日志丢给 AI。

一页速览

  • 核心理念：文档优先，代码在后。
  • 关键文档：PRD, App Flow, Tech Stack, Frontend Guidelines, Backend Structure, Implementation Plan。
  • 记忆辅助：.clauderules (规则), progress.txt (进度)。
  • 工具组合：Claude (思考/文档) + Cursor Agent (构建) + Codex (调试)。
  • 必知概念：UI/UX, 组件, 状态, 响应式设计, API, 数据库, 环境变量。
  • 黄金法则： specificity (具体性) > everything else。具体得让 AI 无从猜测。

常见问题 (FAQ)

1. 为什么 AI 总是生成我不想要的依赖包？
因为你没有在 TECH_STACK.md 中锁定精确版本。AI 会自由发挥，导致版本冲突。

2. 每次打开新窗口 AI 都忘了之前的上下文怎么办？
利用 progress.txt 文件。这是你在不同会话之间的外部记忆桥，确保每次新会话开始前都指示 AI 读取它。

3. 如何让生成的界面和我的设计稿一模一样？
使用截图作为参考输入，并使用擅长视觉的模型（如 Kimi K2.5 或 Gemini 3 Pro），同时在 FRONTEND_GUIDELINES.md 中定义好所有设计令牌。

4. 遇到顽固 Bug 该怎么办？
不要手动修。切换到 Cursor 的 Debug 模式，或者使用 Codex。把错误日志和代码一起丢给它，让它去追踪依赖和假设根因。

5. 我是一个完全的新手，能直接上手这套系统吗？
可以，但建议先花时间理解文中所列的基础概念（如组件、状态、API）。如果你不知道自己在构建什么，文档也没法帮你。

6. 是否必须使用 Git？
是的。没有版本控制，你就失去了“撤销”的能力。一旦代码崩坏，你将无法回退。在每完成一个功能后提交代码是最佳实践。

7. 部署时本地能用但线上报错，最常见的原因是什么？
绝大多数情况是环境变量（.env）没有在部署平台（如 Vercel）上配置，或者构建命令不匹配。检查 Vercel 的设置面板。

8. .clauderules 和 progress.txt 应该放在哪里？
放在你项目的根目录下。大多数 AI 工具（如 Claude Code）会自动检测并读取根目录下的配置文件。