新手也能快速上手的防“史山”快乐编程指南（Codex篇）

该节由 IX 编写

Laziness,Impatience,Hubris:The Three Great Virtues of a Programmer———Larry Wall（Perl语言） 懒惰、急躁、傲慢，是程序员的三大美德——拉里·沃尔（Perl语言之父）

欢迎来到该指南，未来的编程领域大神。是不是正在对着“大创”（指被大卡车创大学生创新创业项目）头大，想用 AI 帮忙，却只能打开豆脚豆包或者迪普西克DeepSeek 老师（亦或是其他 AI 工具），发出简单的指令，却收到一大堆无用且不明所以的教学；又或是你已经初步了解过 Vibe Coding（氛围编程），但是苦恼于如何使用（没有尝试，以及已经尝试但是写出来一坨不可明状的“史山”），以及该死的网络配置（如何帅气的、安全的使用网络代理）？别慌，看完本篇指南，你将掌握一套“宇宙究极无敌科学修仙”大法，用 AI ——咱们只用 Codex（本章涉及到的 Vibe Coding 工具），系统地、优雅地、不翻车地将那坨不可明状的史变成可运行的、可演示的项目。

核心思想：你不是在和AI聊天，你是在“建立规则”

新手最容易掉进的坑：容易把 AI 当许愿机。“豆包豆包，给我做个电商网站！”然后得到一堆乱七八糟的代码和无效的教学。

正确姿势：把 AI 当作一个能力超强但需要精准导航的新同事。什么意思？简单来讲，就是你有一个聪明绝顶的朋友，他非常乐于助人，你经常找他帮忙写作业，但是他只能听懂“帮我把高数 9.2 章中的第一小题的 2～8 写了”，听不懂“诶，主播主播，帮我把数学作业写了呗？” AI 是工具，不是完完全全的一个人，它只能听懂详细的步骤，而不是一个模糊不清的命令。所以，你的任务，就是在他开工前，给他一本厚厚的《项目执行手册》（也就是我们待会要写的文档）。这本手册越细，他产出“屎山”的概率就越低。（只是概率变低了，而不是说没有概率产出）

就像 Perl 之父说的，“懒惰”，指的不是躺平不动，而是指让你尽最大的努力去减少总的精力消耗。我们前期准备的愈充分，后期需要修改的部分就愈少。

---

第一步：工具的选择与预防诈骗

1. 主力工具：Codex

• 是什么：是由 CloseAIOpenAI 打造的一个强大的 AI 编程助手，能深度理解你的代码库，帮你写代码、解 BUG、写文档。
• 为什么推荐新手只用它：功能全面，从规划到编码到调试都能干。避免在多个 AI 间反复横跳，导致精神分裂。本教程所有操作都假定你在使用 Codex。
• 如何下载：我不造啊。

2. 辅助工具：

• 一个代码编辑器（比如 Zed，VSCode 等），由于是面向新手的指南，这里推荐使用 VSCode（Visual Studio Code），微软商店就能下载，或者可以从官网下载。
• Git（有关 Git 是什么、Git 怎么使用等等问题，大家可以在 Bilibili 上自行了解学习，在此就不过多赘述¹）

第二步：初期的一些配置

VScode中文设置以及Codex插件的安装

打开 VScode，点击“新建文件”或者选择点击“打开”找到自己已经建好的文件，这时候点击左侧单独一列的扩展按钮（四个正方形那个），在搜索栏搜索Codex，安装对应的插件，这时候右侧栏“聊天”旁边就会多出一个“CODEX”的选项。点击后就可以使用Codex（当然，目前还是使用不了）。

如何配置 Codex

打开 Codex，你会发现有两种方式进行认证。一种是登陆 ChatGPT 账号，另一种是填写 API 密钥。如果你购入了官方的 Free/Plus/Team 等账户，你应该使用第一种方式认证。如果你是购入的中转站，抑或是你很有钱使用官方的 API，你应该选择第二种。官方的配置不必多说，只需要按照引导来即可。这里给使用第三方中转站的提供一个简单的教程。

WIP

第三步：核心工作流 —— “文档优先”魔法

记住这个流程：写文档 → 定规则 → 小步走。这是避免“屎山”的终极心法。

阶段A：榨干你的想法 （xm想法）

在你写任何一行代码之前，先和Codex进行一场“灵魂拷问”。

你应该做什么：

1. 在你喜欢的电脑中任意的位置，新建一个项目文件夹（起名就不必多说了吧……对吧？）
2. 在 VSCode 里面打开这个文件夹（你之后的各种乱七八糟的文件都将存放在这个文件夹中）
3. 在配置好的 Codex 的对话框中，新建一个任务，对 Codex 说：

版本一：“Codex，你好。我有一个大创项目的初步想法，但我需要你以‘项目顾问’的身份，对我进行一场无情的‘审问’，帮助我澄清所有模糊的点。我的初步想法是：【在这里用一段话描述你的项目，比如：我想做一个校园内的二手教材流转小程序，学生可以拍照发布旧书，其他人可以浏览和购买】。请开始你的提问，问题越细致、越尖锐越好，涵盖功能、用户、技术实现、运营等所有方面。我会逐一回答。”

版本二：“在写任何代码之前，请在‘Planning模式’下对我的项目想法进行无休止的审问。不要做任何假设。不断提问，直到没有任何模糊之处剩下。我的项目想法是：[用一段话描述你的App，例如：我想做一个让用户能创建、分享和发现食谱的社区App]。”

（以上两个版本任取一个喜欢的即可）

Codex 会做什么：

它会化身“杠精”，问你几十个问题：例如：目标用户是谁？核心功能是什么？需要哪些数据？前后端如何交互？错误如何处理？（不一定，我就被提问了103个问题） 你的任务是耐心回答每一个问题。这个过程会重复好多次，遇到不确定的问题，你可以借助其他AI，让它们帮你回复这个问题，不要担心花费时间很多，这个过程也是帮助你更好的了解和搭建自己项目的整体框架。所有问答，都是你后续写正式文档的宝贵素材。

切记这个过程会很痛苦，但是一定要坚持下来！

阶段B：创建你的“项目规范”

“审问”结束后，指挥 Codex 帮你生成以下 6 个 Markdown 文件。它们是你的“项目宪法”，AI必须严格遵守。

如何向Codex描述每个文件（你可以直接复制下面的话给Codex，两个版本请自行选择，本质上是没什么区别其实）：

“基于我们刚才的审问对话，请为我生成完整的项目规范文档。包括以下六个Markdown文件，要具体、详尽、无歧义：

简单版本：（推荐使用）

1. PRD.md​ (产品需求文档)：定义产品愿景、用户故事、功能列表、成功标准和非目标。
2. APP_FLOW.md​ (应用流程文档)：用纯英文描述每个页面和用户导航路径，包括触发条件、步骤、成功/错误状态。
3. TECH_STACK.md​ (技术栈文档)：锁定所有包、依赖、API和工具的确切版本（例如：Next.js 14.2.0, React 18.2.0, TypeScript 5.4.0, Tailwind CSS 3.4.0, Supabase等）。
4. FRONTEND_GUIDELINES.md​ (前端指南)：定义完整的设计系统，包括调色板（十六进制代码）、字体、间距刻度、组件库（如shadcn/ui）、响应式断点规则。
5. BACKEND_STRUCTURE.md​ (后端结构文档)：定义数据库模式（每张表、列、类型、关系）、API端点合约、认证逻辑。
6. IMPLEMENTATION_PLAN.md​ (实施计划文档)：创建一个详细的、逐步的构建序列（例如：步骤1.1 初始化项目，步骤1.2 安装依赖...步骤2.1 构建导航栏组件...）。”

详细版本：（不推荐使用，废话太多了，什么，你问我为什么要放这个详细版本？当然是水字数）

1. PRD.md (产品需求文档)

“请根据我们刚才的头脑风暴问答，撰写一份正式的PRD.md。它需要包含：1. 项目概述（一句话说清是啥）；2. 目标用户（是谁用）；3. 核心功能列表（尽可能详细，比如‘用户注册登录’、‘发布商品’、‘带关键词搜索的浏览页面’）；4. 非功能性需求（比如‘页面响应要快’、‘移动端体验要好’）。”

2. APP_FLOW.md (应用流程文档)

“现在，请为我们规划的应用绘制‘用户旅程图’。创建一份APP_FLOW.md，描述一个典型用户从打开应用到最后完成交易，会经历哪些页面（如：启动页 -> 首页 -> 商品详情页 -> 聊天窗口），每个页面能点击哪里、跳转到哪。用列表或简单图表描述。”

3. TECH_STACK.md (技术栈文档)

“请为我们的项目锁定技术选型。创建TECH_STACK.md，明确写出：1. 前端用什么框架和UI库？（新手强推：Vue3 + Vite + Tailwind CSS + Element Plus/ DaisyUI，组合简单好看） 2. 后端用什么语言和框架？（新手强推：Node.js + Express 或 Python + Flask） 3. 数据库用啥？（新手强推：SQLite 或 Supabase） 4. 需要哪些关键依赖包？请务必指定具体大版本，例如：Vue: ^3.3.0, Tailwind: ^3.4.0。”

4. FRONTEND_GUIDELINES.md (前端指南)

“请定义我们的设计系统。创建FRONTEND_GUIDELINES.md，包括：1. 主色、辅助色、成功/警告/错误色的色值（给HEX码，如#3b82f6）；2. 用的字体（优先系统默认，如system-ui）；3. 间距规范（如基础单位8px）；4. 按钮、输入框的默认样式。可以去看看​ Tailwind UI或​ DaisyUI找点灵感，选一套你喜欢的风格告诉我。”

5. BACKEND_STRUCTURE.md (后端结构文档)

“请设计我们的后台骨架。创建BACKEND_STRUCTURE.md，定义：1. 数据库需要哪些表？（例如users表、books表，每个表有哪些字段）；2. 我们需要哪些API接口？（例如GET /api/books获取列表，POST /api/books发布新书），写出每个接口的地址、方法（GET/POST）和大致功能。”

6. IMPLEMENTATION_PLAN.md (实施计划)

“最后，请将整个项目拆解成可执行的小任务。创建IMPLEMENTATION_PLAN.md，列出从0到1的构建步骤，例如：第一步：初始化项目，安装依赖；第二步：搭建前端主框架和路由；第三步：实现用户登录注册页面；第四步：实现发布商品页面… 每一步都应该足够小，可以在1-2个小时内完成并测试。”

恭喜！ 走到这一步，你已经完成了50%的任务，因为上述的文档定义了 “做什么”和“怎么做”。现在，可以站起身来活动一下，喝口水，休息0.5s几分钟，让我们接着向下走。

（什么，聪明的你居然发现了上述文档只有6个，那么还有一个文档在哪呢？不然你猜为什么我会让你只休息0.5s，邪恶的笑容）

阶段C：创建AI的“上帝之眼”—— CODEX.md

这是整个流程的灵魂文件，是Codex每次和你聊天时的“上岗培训手册”，也是上述文档中缺少的那一个文档。在项目根目录创建 CODEX.md。

这个文件怎么写：你可以直接让Codex整合上面6个文件的核心内容，生成一份“工作须知”。

“请根据我们已制定的规范文档，为我创建一个CLAUDE.md文件。它应包含：

• 项目技术栈摘要。
• 文件命名和存放位置的约定（如：所有组件放在src/components/）。
• 必须遵循的编码模式（如：使用函数组件和Hooks）。
• 设计系统令牌的引用（如：主色使用#3B82F6）。
• 明确禁止的操作（如：禁止使用内联样式）。
• 要求AI在每次会话开始时，必须首先阅读progress.txt和lessons.md（如果存在）。
• 列出所有需要参考的规范文档（PRD.md, APP_FLOW.md等）。”

这时候Codex应该会询问你是否生成缺失的progress.txt和lessons.md，大胆同意就行。 或者，如果Codex没有询问，你也可以自己向Codex提要求：

在项目根目录创建一个progress.txt文件。 初始内容可以写：“项目开始。已完成：规范文档（PRD.md, APP_FLOW.md, TECH_STACK.md, FRONTEND_GUIDELINES.md, BACKEND_STRUCTURE.md, IMPLEMENTATION_PLAN.md）和 CODEX.md。待办：见IMPLEMENTATION_PLAN.md步骤1。” 创建一个空的lessons.md文件，用于记录开发过程中遇到的错误和学到的规则。

再次恭喜！ 这次是真真切切的把AI写代码的前置工作都准备好了，这次是真的可以休息一会，或者，强大的你现在充满充满了决心 （UT误入），那我们正式开始使用Vibe Coding。

第四步：开搞！如何科学地向AI“下命令”（核心重点）

现在，一切准备就绪。每次打开项目，Codex都会先读CODEX.md，了解全部上下文。你的沟通方式将发生质变：

项目初始化与设置

初始化项目与仓库

正确示范 错误示范：

“做个首页。”

正确示范（基于文档的精确指令）：

“请按照TECH_STACK.md中的技术栈和IMPLEMENTATION_PLAN.md中的步骤1，为我初始化项目。请使用正确的包管理器命令创建项目结构，并安装所有指定的依赖。完成后，请更新progress.txt，记录已完成‘项目初始化与依赖安装’。”

看到区别了吗？你的指令变得：

1. 有据可依：时刻引用已制定的文档（CODEX.md， XXX.md）。
2. 精准定位：明确到哪个文件.
3. 步骤清晰：绑定IMPLEMENTATION_PLAN.md，一步一个脚印。
4. 有始有终：要求更新progress.txt，为下次对话保存记忆。
5. 学习整理：有lessons.md，可以记录学习编程中出现的错误。

开发与构建（循环迭代）

这是核心的“氛围编码”阶段，你将循环执行“计划-构建-测试-记录”的步骤。

分步执行实施计划（通用模板）：

直接复制粘贴给Codex：

“请首先阅读CODEX.md和progress.txt以获取上下文。接下来，请执行IMPLEMENTATION_PLAN.md中的步骤 [X.Y]。在构建时，请严格遵守FRONTEND_GUIDELINES.md中的设计规范，并参考APP_FLOW.md中的流程描述。完成后，请更新progress.txt文件。”(X,Y指的是数字，例如：1.1、1.2这种）

补充（UI部分的设计）

示例（构建登录页面）：

“请构建登录页面。UI设计参考我附带的截图，采用玻璃拟态风格。功能流程请完全按照APP_FLOW.md第3节‘用户登录流程’的描述。组件样式请遵循FRONTEND_GUIDELINES.md。使用TECH_STACK.md中指定的认证服务（Clerk/Supabase Auth）。完成后，更新progress.txt。”

同样的，如果你看到好看的UI，也可以截图发送给Codex让它帮忙设计出一模一样的UI，至于如何向Codex执行这个指令，想必看到这的你，已经不再是那个只会用简单语句给AI下达指令的人了。（如果实在不知道的话，你也可以找个其他AI给你生成一段仿照图片中UI风格的指令，再发送给Codex）

测试与调试循环

当出现问题时：

1. 阅读错误信息：复制完整的错误日志。
2. 提供完整上下文给Codex：

“我遇到了一个错误。错误信息是：[粘贴完整错误]。相关的代码文件是[文件路径]，代码如下：[粘贴相关代码片段]。我期望的行为是[描述期望]。请分析并修复。”

每次纠正后： 让AI更新lessons.md和CODEX.md，防止同样错误再次发生。

“这个错误是因为组件未正确导入。请将这条规则加入CODEX.md，并更新lessons.md记录此次教训。”

第五步：测试、发布与维护

发布前验证

你该做什么： 在部署前，进行完整测试。

检查清单（可让AI协助）：

• 在真实手机和不同浏览器上测试。
• 测试空数据、错误数据、网络缓慢的状态。
• 检查是否有任何敏感信息（如API密钥）被意外提交或暴露在前端。
• 运行IMPLEMENTATION_PLAN.md中的核心用户流程。

后续迭代与维护

你该做什么： 基于用户反馈和PRD.md中的规划，继续开发新功能。

如何开始新会话： 每次打开项目，第一件事就是让AI阅读上下文。

“请首先阅读CODEX.md、progress.txt和lessons.md。我刚刚回到这个项目。请根据IMPLEMENTATION_PLAN.md和progress.txt的进度，总结当前状态并建议下一步。”

保持更新： 定期更新依赖，维护progress.txt和项目文档。

核心沟通原则（再次强调）

向AI描述文件和提要求时，牢记以下公式：

“上下文 + 具体指令 + 约束条件”

• 上下文： 请先阅读CODEX.md和progress.txt。
• 具体指令： 请构建用户个人资料页面。
• 约束条件： 该页面需包含头像、用户名、个人简介编辑功能。UI请严格遵循FRONTEND_GUIDELINES.md中的设计令牌，用户数据模型请参考BACKEND_STRUCTURE.md中的‘users’表。交互逻辑请遵循APP_FLOW.md第5节。

切记：永远避免模糊的指令（如“让它更好看”），而是使用具体的、文档化的词汇（如“将按钮的背景色改为FRONTEND_GUIDELINES.md中定义的品牌主色#3B82F6，并添加悬停微交互效果”）。

终极焚决

你不是在“驯服”一个AI。你是在学习如何系统性地思考，并用最先进的工具，将你的思考变成现实。​ 这套方法，能让你在AI的辅助下，从一个“我有一个好主意”的梦想家，变成一个“我把它做出来了”的实干家。

现在，深呼吸，打开你的 VSCode，创建一个新的文件夹（或者选择你之前就已经创建好的文件夹），然后对 Codex 说出那句魔法般的开场白：“Hello World” “Codex，你好，我有一个大创项目的初步想法……”

希望本篇指南能帮到你，未来的创造者！记住，规划越细，翻车越远，越不容易写出史山代码。

作者的后话

咳咳……既然你都看到这儿了，那咱就唠点实在的。

郑重声明： 本指南是本人啃完那篇著名的 《Why You Suck at Vibe Coding》 （以及喝了三杯咖啡） 后，结合自己踩坑的血泪史，用毕生所学总结出来的“生存手册”。你可以理解为——这是一个刚学会爬的编程菜鸟，在尝试给其他大佬写 《如何优雅地编程》 的教程。

所以，如果你在阅读过程中发现：

• 某个术语解释得像是用脚写的
• 某段逻辑绕得能当迷宫玩
• 或者某个示例模板让 Codex 跑起来像中了邪……

别怀疑，这绝对是我的问题，我是飞舞喵，不是你的问题！

但请务必告诉我，我会跪着改。骗你的，我不会改的，但是可以让原罪跪着改²

最后的最后： 如果本文真的帮到了你，请在心里默念三声“主播真是个天才”。

（同时也欢迎大家在群里或者私信联系我相关问题.不过话先放这，我很菜的喵）

Footnotes

1. 校对注：其实是懒得写了，晚些时候可能在指南中继续编写 Git 的教程 ↩

2. 校对注：？ ↩