03-AI开发手册

Nexus Studio 技术博客《Vibe Coding 实战》系列六篇总结

  • 来源：https://www.nexus-studio.cc/insights （Nexus Studio 官方技术博客「技术视野」栏目）
  • 系列名：VibeCoding（感觉编程）
  • 发布时间：2026-06-15，共 6 篇（序章＋第一～五章）
  • 适用读者：想用 AI 做小工具但不会编程的人；用过 AI 写代码但项目做到一半崩掉的人
  • 阅读时长：约 50 分钟（全系列合计）

一、序章：写给想用 AI 做点东西，但又不知道从哪开始的人

核心观点：Vibe Coding 的本质不是「躺平让 AI 全自动搞定」，而是表达、约束、验收三个关键词。

  • 表达：让 AI 明白你想要什么。不能只说「帮我做一个好看的管理工具」，要说「把指定文件夹里的照片按拍摄日期自动重命名，别的都不要」。说得越清楚，AI 干得越准。
  • 约束：给 AI 划红线。不许用哪些技术、不许改哪些文件、界面用什么颜色、版本锁死在哪个号——不立规矩，AI 就会「自由发挥」，项目离崩就不远了。
  • 验收：判断 AI 交出来的东西对不对。不需要会读代码，但要知道「点这个按钮应该弹出什么」「跑完应该看到什么结果」。你是老板，AI 是干活的。

为什么需要工程化管理：真正有用的东西通常一两句话说不清。一个「文件管理器」背后就有几十个问题：管什么文件？按什么规则分类？要不要搜索？数据存本地还是云端？——这些问题不回答，AI 就自己脑补，然后越改越乱，最后变成救不回来的「屎山」。

工程化 = 把大目标拆成小块，做完一块测一块。具体对应后面五章：

章节 解决什么问题 核心内容
第一章 动手之前想清楚什么 需求收敛、选对工具、锁住版本
第二章 怎么防止 AI「自由发挥」 四个坏毛病、规则文件怎么写、多工具适配
第三章 怎么自动生成规则文件 一段提示词搞定所有规矩
第四章 怎么一步步把代码写出来 拆任务、串行执行、机测＋手测、换窗口策略
第五章 正式写代码前的最后准备 清理模板、验证通信、打包验证、环境变量、Git 基础

一句话心态：表达清楚、划好红线、只管验收。

二、第一章：破冰与筹备——动手之前想清楚三件事

背景：AI 写代码有多快，翻车就有多猛。第三天打开电脑全是报错、让 AI 改按钮颜色它删了核心功能——根源是没在动笔前定规矩。

1. 先想清楚要做什么（需求收敛三步）

  • 别让 AI 自由发挥：模糊需求（「做一个好看的文件管理器」）会让 AI 自己脑补成分布式索引＋AI 语义搜索＋多端同步的「月球车」。
  • 第一步：自己先说清核心要啥——越具体越好、越少越好（「把指定文件夹照片按拍摄日期自动重命名，别的都不要」）。
  • 第二步：让 AI 帮想边界情况——磁盘满了怎么办？同名文件怎么处理？这是让 AI 排雷，不是加功能。
  • 第三步：砍掉所有「以后再说」的功能——先做 MVP（最小可行性产品），能跑能用比什么都强。

2. 选工具：挑 AI 最擅长的，别挑你觉得最酷的

AI 写代码的准确度取决于该技术在网上代码量的多少。避坑建议：

你想做什么 别选（AI 容易写错） 建议选（AI 写得准）
桌面软件界面 PySide6 / PyQt / 老旧 C++ 框架 用网页技术做界面（Tauri / Electron / pywebview）
写界面样式 纯 CSS / 复杂 CSS Modules Tailwind CSS
管理数据状态 各种小众状态管理库 最简单的方案（如 Zustand）
  • 桌面工具用「网页壳」：网页代码是互联网上数量最大的代码类型，AI 写网页界面最准。可选：Tauri 2.x（推荐，打包仅十几 MB）、Electron（体积大但生态成熟）、pywebview（后台全 Python 时最省事）。
  • 样式闭眼选 Tailwind CSS：样式直接写在标签上（bg-slate-950 text-white rounded-xl p-6），不用起类名、不用切文件，AI 一次写完基本不出错。

3. 锁版本：第一天就做，别等崩溃

  • 不锁版本的坑：Pillow 这种写法表示「每次装最新版」，某天新版本删了旧方法，项目就莫名启动不了。
  • NPM 项目：确保有 package-lock.json，每次让 AI 装新东西时提醒检查。
  • Python 项目：用 Poetry（自动生成锁文件）；用 requirements.txt 则写死版本号，如 Pillow==10.3.0。
  • 收尾必做：正式开干前先用几行代码做个「空壳程序」，打包成 .exe/.app 验证打包链路是通的——别等做三天后才发现打包不了。

三、第二章：给 AI 立规矩——不设规则的后果比你想象的严重

核心观点：AI 的「记忆」有限，对话越长越容易忘事（命名规范不遵守、乱建文件夹、改 bug 时删掉核心代码）。光靠聊天反复提醒不靠谱，要把规矩写成文件放在项目里，让 AI 每次写代码前先读一遍。

各工具规则文件位置

AI 编程工具 规则文件位置 模式
Trae 项目根目录 .trae/rules/ 文件夹 多文件
Cursor 项目根目录 .cursor/rules/ 文件夹 多文件
Claude Code 项目根目录 CLAUDE.md 单文件
Windsurf 项目根目录 .windsurfrules 单文件
Codex CLI 项目根目录 agents.md 单文件
Gemini CLI 项目根目录 GEMINI.md 单文件

（规则内容写法都一样，只是文件位置不同；多文件/单文件不用自己合并，第三章的提示词会让 AI 按所用工具自动适配。）

先管住 AI 的四个坏毛病（源自 Andrej Karpathy 的吐槽）

参考开源项目：https://github.com/multica-ai/andrej-karpathy-skills（含可直接使用的 CLAUDE.md 规则文件）

坏毛病 现象 规矩怎么写
不思考就动手 需求刚说完就狂写代码，方向全错 写代码前先用几句话说明打算怎么做、有无不确定之处，不说明白不准写
喜欢过度设计 让写个读文件功能，非要搞「支持未来分布式扩展」的架构 只解决当前问题，不许加「以后可能用到」的功能，代码越短越简单越好
改一处动全身 修 A 文件 bug 顺手改了 B、C 文件甚至核心逻辑 每次只改与当前问题直接相关的地方，改了什么、为什么改必须说清楚
写完不检查 代码一贴就说「搞定了」，一跑就报错 写完必须自检，并告诉你怎么验证（「运行后控制台应输出 xxx」）

规矩怎么写：别说废话，说具体

对 AI 来说「注意代码质量」等于没说，规则必须具体到没有歧义：

  • 锁版本：别写「请使用 React 和 TypeScript」→ 应写「本项目用 React 18.3.1 和 TypeScript 5.4.5，不许用其他版本，不许用这两个版本之后才有的新语法」
  • 锁颜色：别写「界面用好看的暗黑风格」→ 应写「所有背景用 bg-slate-950，卡片用 bg-slate-900，文字用 text-white，不许在代码里直接写颜色值，全部用 Tailwind 类名」
  • 锁目录：别写「注意保持目录整洁」→ 应写「工具函数放 src/utils/，组件放 src/components/，页面放 src/pages/，不许创建上面没列出的文件夹」

规则文件放多少

  • 基础规则（每个项目都要有）：① 开发行为准则（四个坏毛病）② 技术栈和版本 ③ 目录结构 ④ 常见避坑。
  • 扩展规则（按需开启）：做界面→界面规范（颜色/字体/组件风格）；涉及网络→接口规范；涉及存储→数据规范。
  • 规则不是越多越好，每多一条就多占 AI 的「脑容量」。简单项目基础四条就够。
  • 规则用大白话写，示例格式：适用范围 → 规则条目（改了什么/为什么改/怎么验证 → 不许碰无关文件 → 写完自检）。

四、第三章：让 AI 帮你写规则——一条提示词搞定所有规矩文件

核心观点：规则文件不用手写。把一段「生成规则的提示词」发给 AI，它会自动三步走：扫描对话 → 追问缺失信息 → 生成并写入规则文件。

三步流程

  1. 深度上下文扫描与追问：AI 扫描之前聊过的内容，提取业务目标、技术栈、架构痛点；把没说清楚的事（数据怎么存、界面深色浅色、错误怎么提示）列成清单问你，不会替你做决定。
  2. 动态规则架构规划：根据你的回答规划规则文件清单，等你确认（「确认，开始生成」）再继续。必选 4 个文件：01-人设与开发准则.md、02-技术栈与核心库.md、03-目录与架构规范.md、04-核心铁律与避坑.md；按项目属性动态追加：涉及前端→05-UI与组件规范.md、涉及通信→06-通信与数据获取规范.md、有全球化→07-i18n多语言规范.md、涉及复杂状态/DB→08-数据库与状态管理规范.md。
  3. 自动化执行与写入：确认后直接写入项目规则目录（.trae/rules/、.cursor/rules/ 或 CLAUDE.md 等），每个文件按「适用范围 → 规则条目（断言/示例/违规特征）」结构写，写完全部自审（版本号写死？够具体？有代码示例？可验证？）。

提示词结构（一段可直接复制使用的架构师提示词）

提示词由四部分构成，AI 会扮演「30 年全栈架构师」角色：

  • <identity>：设定 AI 为资深首席架构师，设计哲学是「约束先行」。
  • <core_mission>：明确任务——分析当前会话全部上下文，为后续编码 AI 构建「项目规则字典」并写入规则目录。
  • <behavioral_rules>（写作标准）：规则必须给具体代码示例/绝对路径；UI 必须用设计令牌（Design Token）；技术栈必须写死版本号；每条规则必须是可验证的断言（有明确的合规/违规判定标准）；AI 有权直接读写本地文件系统。
  • <workflow>：严格三步执行（扫描追问 → 规划清单 → 写入文件），每步输出交付物并等用户确认。

使用要点：在你已经和 AI 聊过项目需求之后，把提示词复制粘贴发过去，按它问的问题回答即可；不用理解每一行。提示词原文见 https://www.nexus-studio.cc/insights/vc3

生成之后的效果：规则目录躺好所有规则文件（AI 每次写码前自动读）、README.md 写清项目是干嘛的、目录干净整洁——你和 AI 的信息从此对齐。

五、第四章：正式开工——怎么让 AI 一步步把代码写出来

核心观点：「拆碎了做」是 Vibe Coding 不翻车的关键：把大项目拆成小块任务，串行执行、逐个验收。

1. 先写总纲 README.md

写任何代码之前，先让 AI 写一份 README：① 项目做什么、不做什么（把边界画清楚，AI 才不会自作主张加东西）；② 项目分成哪几个部分（界面层/核心逻辑层/配置层）。AI 糊涂时一句「去看 README」就能回过神来。

2. 拆任务：大需求切成小卡片

小任务标准：每个任务只做一件事，做完就能测试。「把前端界面和后端逻辑对接一下」太笼统；应拆成「做选择文件夹按钮 → 写读取图片文件名的功能 → 把两者串起来显示图片列表」。

任务卡片必含四要素：

  • 涉及哪些文件（一眼看出改动范围）
  • 代码示例（给 AI 参考，也方便对比检查）
  • 机测内容（如 npm run build 检查编译）
  • 用户测试用例（你手动怎么测，逐条列步骤）

让 AI 拆：跟 AI 说「根据 README 把项目拆成任务卡片，每个卡片包含涉及文件、代码示例、机测内容、用户测试用例，排好顺序生成 TODO.md」。

执行原则：串行执行——一次只做一个任务，做完测完再做下一个（并行多窗口可能改到同一文件互相覆盖）；每次只检查本次改动文件，不全量检查。

3. 怎么测试：机测＋手测

  • 机测（工具自动检查）：基础层每次跑——编译检查（npm run build / cargo build）、类型检查（npx tsc --noEmit）、格式检查（npm run lint），只看有没有报错；测试层按需——让 AI 顺手写测试脚本（Vitest/Jest/pytest），你只跑 npm run test 看结果。核心逻辑（文件处理、数据计算、格式转换）值得写测试，简单界面调整跑编译即可。
  • 手测（自己动手）：按卡片用例操作＋额外三种情况——走一遍主流程、故意使坏（空文件夹/怪文件名/快速连点）、回头测老功能（确认没被新代码弄坏）。机测＋手测都通过才算完成。

4. 进度追踪与换窗口

  • TODO 实时更新：每完成一个任务立刻让 AI 更新 TODO.md（打勾、标完成时间）——这是新窗口 AI 接手的依据。
  • 为什么要换窗口：AI 记忆有上限，聊太长会被「压缩」，导致上下文污染（垃圾信息干扰）和关键信息丢失（规则、结构、选型理由被丢掉）。当 AI 连续两次犯同样低级错误或不守规则时，就该换新窗口了。
  • 怎么换：开新窗口 → 说「看一下项目目录里的 TODO.md 和 README.md，从当前进度继续」。规则文件、TODO、README 会自动让新 AI 无缝接上，像搬了新工位但规章制度全带过来了。

六、第五章：搭脚手架——项目正式开始前的最后准备

核心观点：官方初始化命令（如 npm create tauri-app）生成的只是塞满示例的默认模板，直接在上面写业务代码会出各种莫名其妙的问题。正式开写前做好七件事：

1. 清理模板

让 AI 删掉官方示例代码和样例文件，只保留核心配置文件和项目骨架（package.json、tsconfig.json、tauri.conf.json 一个都不许动）。清理后是干干净净的「空壳」：能跑起来、入口只有 Hello World、无业务逻辑。项目越干净，AI 越不跑偏。

2. 验证通信链路

桌面工具分后端（干重活：读写文件、处理数据）和前端（显示界面），两者要能对话。让 AI 写最简单的测试：后端返回「通信测试成功」，前端显示出来。能看到这几个字说明链路通；这一步花几分钟，能避免后面几小时的排查。

3. 交互式命令自己手动跑

终端弹出选择题的命令（init/create/setup 之类，如「Choose your compiler: SWC / Babel」）AI 没法按键盘，自动跑会卡死整个开发工具。正确做法：让 AI 提前告诉你命令和每个选项选什么 → 你自己复制到终端手动运行 → 选完告诉 AI「搞定了」。遇到 AI 也没料到的选项，把终端内容贴给网页版 AI（DeepSeek/Claude/Gemini）用大白话问它该选哪个。

4. 路径别名

相对路径（../../../../components/Card）一旦移动文件就报错。设置别名：让 AI 配 @/ 代表项目根目录的 src/，以后所有引用写成 import Card from '@/components/Card'。一分钟搞定，避免无数路径报错。

5. 先打个包试试

趁项目是空壳（无业务代码）时打包验证链路最划算——成功说明链路通，后面打包出问题就能锁定在新加的代码上；做三天加了几十个文件后再打包，报错根本不知道哪来的。让 AI 告诉你要装什么打包工具、跑什么命令，你执行；成功后双击生成的 .exe/.app 能打开 Hello World 窗口即通过。打包失败在空壳阶段修比后期轻松十倍。

6. 别把秘密写进代码里（.env 环境变量）

真实事故：AI 把 API Key 直接写进代码，传到 GitHub 后密钥公开，新手收到账单炸弹。解决办法：把敏感信息挪到 .env 文件（带锁的抽屉），代码里只写 process.env.API_KEY 这样的引用；确保 .gitignore 已加上 .env。AI 创建好 .env 后，你手动把真实密钥填进去。铁律：.env 永远不要传到任何公开地方。

7. 给项目装个「后悔药」（Git 基础）

AI 可能把代码改崩，Git 就是后悔药。新手只需学三个操作：

操作 作用 对 AI 说的话
初始化（git init） 开始记录项目，只做一次 「请在项目根目录初始化 Git 仓库」
提交（git add . + git commit -m ...） 拍一张存档照片 「请帮我提交当前代码，commit message 写成：完成 XXX 功能」
回退 代码改崩了读档 「代码改坏了，请帮我回退到上一次提交的状态」

好习惯：每完成一个任务卡片就提交一次，项目里就有一连串存档点。分支、合并、rebase 不用学，剩下 90% 需求这三个操作覆盖。

七、整体方法论速览（一句话版）

  1. 序章：Vibe Coding = 表达清楚 ＋ 划好红线 ＋ 只管验收；复杂想法要工程化（想清楚→立规矩→拆任务→搭骨架）。
  2. 第一章：动手前收敛需求（砍掉「以后再说」）、选 AI 最熟的栈（网页壳＋Tailwind）、第一天就锁版本、先验证打包。
  3. 第二章：把规矩写成文件让 AI 每次先读；用规则治四个坏毛病（不思考/过度设计/乱改/不检查）；规则要具体到无歧义。
  4. 第三章：一条架构师提示词让 AI 自动扫描对话、追问缺口、规划并生成规则文件，你只需确认和回答。
  5. 第四章：先写 README 总纲 → 拆成含「涉及文件/代码示例/机测/手测」的任务卡片 → 串行执行 → 机测＋手测验收 → TODO 实时更新，聊太长就换窗口。
  6. 第五章：开工前七件事——清模板、验通信、交互命令手动跑、设 @/ 路径别名、先打包验证、.env 管密钥、Git 三个操作当后悔药。

贯穿全系列的一句话：你负责想清楚和把好关，AI 负责动手执行——你不是在「救火」，而是在带一个有施工图纸的工人盖楼。

本文档由 AI 助手根据 https://www.nexus-studio.cc/insights 六篇原文（发布于 2026-06-15）总结生成，内容版权归 Nexus Studio 所有。

posted @ 2026-08-23 18:43  LHX2018  阅读(10)  评论(0)    收藏  举报