做第一个 Agent 前，要准备哪些东西

2026-08-14

上一篇我们聊了 Vibe Coding：你不需要一开始就会完整写代码，也可以和 coding agent 一起把一个小想法做成能跑的项目。

但真正准备动手时，很多人会卡在另一个地方：我到底该先装什么？代码应该放哪里？API Key 是什么？我要怎么开口让 AI 帮我做项目？

这些问题看起来零散，其实都属于同一件事：在请一位很会写代码的新同事帮忙之前，你要先把桌面收拾好，把钥匙、文件夹、工具和任务单准备出来。

这篇不追求把所有环境一次配到完美。我们的目标很简单：准备到足够开始第一个小 Agent 项目。

先知道你要准备的不是“全套工程能力”

新手最容易被准备工作吓住，是因为一搜教程就会看到很多词：编辑器、终端、Git、GitHub、Node.js、Python、虚拟环境、环境变量、API Key、包管理器、部署平台。

它们当然都有用，但第一天不需要全部掌握。

做第一个 Agent 前，你真正需要的是六样东西：

一个能打开项目、修改文件、运行命令的编辑器；
一个能保存版本、以后回滚的代码仓库；
一个能调用模型服务的 API Key；
一个清楚的项目文件夹；
一个能让程序跑起来的基础运行环境；
一份能让 coding agent 听懂的开工说明。

把这六样准备好，你就不是“对着 AI 说一句帮我做个 Agent”，而是已经把项目的地基铺出来了。

编辑器：你和项目待在一起的地方

编辑器不是只用来打字的。对 Vibe Coding 来说，它更像项目工作台：你能看到文件结构，打开终端，搜索代码，查看修改，并和 coding agent 一起推进。

常见选择有 VS Code、Cursor、Codex 这类工具。它们各有侧重点，但新手先不用纠结“哪个最好”。更重要的是选一个你愿意每天打开的，并熟悉几件基础操作：

打开一个项目文件夹；
新建、修改、删除文件；
在编辑器里打开终端；
搜索某个关键词；
看清哪些文件刚刚被改过；
复制完整报错，而不是只截最后一行。

如果你使用的是带 AI 能力的编辑器或 coding agent，最好从一开始就让它在项目文件夹里工作。不要把代码散落在桌面、下载目录和聊天窗口里。项目一旦变成多个文件，文件放在哪里就会变得很重要。

可以先记住一句话：编辑器是现场，不是记事本。你要在这里看结果、跑命令、检查改动，而不是只等 AI 在聊天里宣布“完成了”。

GitHub：不是炫技，是给项目留退路

很多新手会觉得 GitHub 是“程序员才需要的东西”。但从 Vibe Coding 的角度看，GitHub 最朴素的价值只有一个：保存项目的历史。

和 coding agent 协作时，项目经常会经历这些状态：

第一版能跑，但功能很粗糙；
第二版加了一个功能，却把原来能跑的地方改坏了；
第三版修好了报错，但你已经忘了前一版长什么样；
AI 一次改了很多文件，你不确定哪些改动应该保留。

这时候，版本记录就很重要。

Git 是本地的版本管理工具，GitHub 是把仓库放到网上的平台。你不需要第一天就理解 Git 的所有概念，但至少应该知道几件事：

一个项目最好对应一个仓库；
每次功能跑通后，可以保存一次版本；
改坏了，可以回头查看之前的状态；
以后部署、分享、换电脑继续做，GitHub 会很方便。

如果暂时还不熟 Git，也没关系。你可以让 coding agent 解释每一步命令的作用，再慢慢练。关键是不要长期只靠“复制整个文件夹”来保存版本。项目越往后走，这种方式越容易乱。

API Key：调用模型服务的钥匙

做 Agent 项目通常需要调用模型。API Key 就像你调用模型服务的钥匙：程序拿着这把钥匙，才能请求模型帮你生成、理解、总结或调用工具。

既然是钥匙，就有三条基本规矩。

第一，不要公开。不要把 API Key 发到公开聊天、文章、截图、GitHub 仓库或别人能看到的地方。

第二，注意额度。很多模型服务按调用量计费，或者有免费额度限制。刚开始做小项目时，应该先用小样例测试，不要一上来让程序循环调用几百次。

第三，把它放在配置里，而不是写死在代码里。常见做法是放到 .env 这类本地配置文件中，再把 .env 加进 .gitignore，避免被提交到 GitHub。

你可以把关系理解成这样：

代码：知道要去调用哪个模型服务
.env：保存你自己的 API Key
.gitignore：告诉 Git 不要把 .env 传到仓库
.env.example：告诉别人需要准备哪些配置，但不放真实钥匙

如果你还没完全理解这些文件，也可以直接让 coding agent 帮你设置，并要求它解释：

请把 API Key 放在 .env 里读取，不要写死在代码里。
同时创建 .env.example，说明需要哪些环境变量。
请确认 .gitignore 已经忽略 .env。

这不是多余的讲究。很多真实项目的安全问题，就是从“我先临时把 key 写进代码里，之后再改”开始的。

项目文件夹：让东西各归各位

一个项目不只是代码文件。哪怕是最小 Agent，也最好有一个清楚的文件夹结构。这样你和 AI 都知道：代码在哪里，说明在哪里，配置在哪里，输出结果放在哪里。

第一个小项目可以很简单，例如：

my-first-agent/
  README.md
  .gitignore
  .env.example
  src/
    main.py
  outputs/
  notes/
    ideas.md

这只是示例，不是规定。用 Node.js 时可能会有 package.json，用 Python 时可能会有 requirements.txt 或 pyproject.toml。重要的不是名字完全一样，而是职责清楚。

可以先这样理解：

README.md 写项目是做什么的、怎么运行、怎么验收；
.gitignore 写哪些本地文件不要提交；
.env.example 写需要准备哪些配置；
src/ 放主要代码；
outputs/ 放程序生成的结果；
notes/ 放想法、测试记录和暂时不确定的需求。

很多新手项目混乱，不是因为代码一开始就很难，而是因为所有东西都堆在一起：真实 key、测试输出、临时笔记、主程序、旧版本代码全在同一层。coding agent 看到这种现场，也更容易改错文件。

所以，第一天就给项目一个干净的房间。

运行环境：让电脑能真的执行程序

AI 写出代码，不等于你的电脑能运行代码。运行环境就是让程序真正动起来的基础工具。

常见小项目大多会从 Node.js 或 Python 里选一个。你不需要同时学两套。可以根据项目目标和自己的熟悉程度，让 coding agent 推荐：

我准备做一个最小 Agent 命令行工具。
我是新手，希望安装步骤少、代码容易读、方便本地运行。
请在 Python 和 Node.js 之间推荐一个，并说明理由。

无论选哪一个，都要弄清楚三件事：

如何检查本机是否已经安装；
如何安装依赖；
如何运行项目。

比如一个最小项目的 README 里，至少应该有类似这样的信息：

安装依赖：___
运行命令：___
示例输入：___
预期输出：___

这几行比“项目使用了先进架构”更重要。因为新手最先需要的不是架构感，而是能不能把第一版跑起来。

如果运行时报错，不要急着让 AI 重写整个项目。先把命令、系统环境、完整报错贴回去，让它判断是依赖没装、版本不对、配置缺失，还是代码逻辑问题。

开工说明：不要只说“帮我做一个 Agent”

准备好工具之后，真正决定第一轮能不能顺利的，是你给 coding agent 的开工说明。

“帮我做一个 Agent”太大了。AI 可能会自动脑补很多东西：网页界面、数据库、登录、复杂工具调用、部署脚本。结果第一版文件很多，你反而不知道怎么验收。

更好的开工说明应该包含六类信息：

背景：你为什么要做这个；
目标：第一版要完成哪件事；
输入：用户会给什么；
输出：程序应该返回什么；
限制：暂时不要做什么；
验收：怎样证明这一版算完成。

可以直接套这个模板：

我想做一个___。
它的使用场景是___。
用户输入___，希望输出___。

先做最小版本，只需要___。
暂时不要做___。

请一步一步生成项目，并告诉我：
1. 会创建哪些文件；
2. 如何安装依赖；
3. 如何运行；
4. 我应该用什么例子验收。

如果你要做“博客选题助手”，可以把模板填成这样：

我想做一个博客选题助手。
它的使用场景是：我想写技术博客，但经常不知道从哪个角度切入。
用户输入一个方向，比如“AI 工具入门”，希望输出 5 个选题。

先做最小命令行版本，只需要输出标题、目标读者、切入角度和 3 条大纲。
暂时不要做网页界面、登录、数据库和部署。

请一步一步生成项目，并告诉我：
1. 会创建哪些文件；
2. 如何安装依赖；
3. 如何运行；
4. 我应该用什么例子验收。

这段说明没有神秘技巧，但它让项目变小了，也让 AI 更难跑偏。

第一轮验收：先确认它能跑

很多人第一次和 AI 做项目时，会急着加功能。第一版刚能输出一点东西，就想加保存历史、好看界面、用户系统和分享链接。

先别急。

第一个 Agent 的第一轮验收，只要看几件事：

能不能按 README 安装依赖；
能不能用一条命令运行；
输入一个正常例子时，输出是否符合结构；
输入为空或太短时，程序是否给出友好提示；
输出不满意时，你是否知道该反馈哪一部分。

如果这几件事都过了，第一版就已经有价值。它可能不好看，也不完整，但它进入了“能观察、能反馈、能迭代”的状态。

这正是 Vibe Coding 的关键。你不是等所有准备都完美再开始，而是准备到足够安全、足够清楚、足够能跑，然后开始第一轮小实验。

开工前自检清单

动手前，可以快速过一遍这张清单：

我已经选好一个编辑器，并能打开项目文件夹；
我知道项目会放在哪个目录，不会散落在桌面；
我准备好了 GitHub 账号，或者至少知道后面要把项目放进仓库；
我知道 API Key 是私密信息，不会写进公开代码；
我准备让程序从 .env 读取 key，并提供 .env.example；
我知道这个项目准备用 Python、Node.js 或其他运行环境；
我能说清楚第一版的输入、输出和不要做什么；
我准备了一条可以验收的示例输入。

不用每一项都做到专家水平。能做到“知道它是什么、为什么需要、第一版怎么用”，就足够开始。

结尾

做第一个 Agent 前，真正要准备的不是一堆复杂技术，而是一套能让你和 AI 协作的基本现场：编辑器打开项目，GitHub 保存历史，API Key 安全放好，文件夹结构清楚，运行环境能跑，任务说明足够具体。

准备工作做得越清楚，coding agent 越像一个能帮上忙的新同事；准备工作越混乱，它越容易变成一个会写很多代码、但不知道你真正想要什么的人。

下一篇，我们就进入第一轮实战：用 Vibe Coding 做一个最小 Agent。项目会尽量小，从一个命令行版本开始，让它接收输入、生成结果，再通过几轮反馈慢慢变得可用。

本系列目录

这是「AI / Vibe Coding 新手系列」的第 3 篇，全系列共六篇：

延伸阅读（比本系列更偏工程化，建议跑通第一个 Agent 后再看）：从 Demo 到可交付：如何做一个 Agent 项目