章节主旨
如何从零搭一个 agent 能读懂、能导航的项目工作区:核心是 DOE 框架 里 directives 与 executions 两个必需文件夹的分工,加上 .env 存密钥、描述性命名、以及 claude.md/agents.md 这类系统提示配置文件的放法。
核心论点
- 工作区搭建 = 给 agent 一次”入职教育”——不只是建文件夹,而是把方法论与理由写进去让它理解。(→ 详解1)
- DOE 结构只有两个必需文件夹:directives 与 executions,其余(resources / tmp)按需加。(→ 详解2、详解3)
- directives 管”做什么”(markdown),executions 管”怎么做”(Python),二者机械对应、互相调用。(→ 详解4)
- 密钥统一进
.env,不写进代码或指令,换机器/分享时才能直接复制。(→ 详解5) - 系统提示配置文件全丢进项目根——
claude.md/gemini.md/agents.md内容相同,哪个模型都能读。(→ 详解6)
知识点详解
1. 搭工作区 = 给 agent 一次”入职教育” 1:35:16
创建工作区本身很简单——第一次打开这类 IDE 它就会提示你建一个。真正要做的是搭出一套文件夹结构,并给 agent 说明书,让它知道你为什么这样组织、背后是什么方法论。
Nick 把 agents.md 比作对 agent 的一整套”教育”,跟他此刻对学员讲课是一回事:让它理解为什么用 DOE 框架、为什么这样干,而不是”raw dog”(裸上)硬塞任务。
类比是给新员工布置工位:得让他知道东西都放哪、基础文件夹和物件先备齐,有了这个结构他才能在里面发挥。一个组织良好的工作区,Nick 视为”essential(必备)“。
2. 项目结构:directives 与 executions 两个必需文件夹 1:37:59
工作区名字随意。往下分两大文件夹:directives(指令)和 executions(执行)。
directives 里是一堆高层指令文件,如 scrape_leads.md、upwork_applybot.md——顶层信息都在这,例如”先问用户想抓哪些线索,拿到后再问用哪个平台”这种流程级描述。
executions 里放对应的实际脚本,如 apify_scraper.py、upwork_scraper.py、upwork_applier.py。DOE 里只有 directives 文件夹 和 executions 文件夹 这两个是必需的,别的框架有别的叫法。
3. 可选文件夹:resources 与 tmp 1:38:09
若有一批常规喂进去的参考物料,可加 resources 文件夹;子文件夹可再分 inputs / outputs / prompts / reference。
另一个常加的是 tmp(temporary)——agent 有时需要临时建文件当”草稿纸(scratch pad)“来干活。除此之外文件夹随你加,Nick 不强推某种唯一范式。
4. directives(做什么/markdown)vs executions(怎么做/Python) 1:39:18
分工的本质是”你做什么”与”你怎么做”的分离:directives 是 what,execution 脚本是 how——实际发生的事。
调用是机械对应的:你在某条 directive 里写”第三步,调用 apify_scraper.py”,agent 读到就知道去调哪个 execution。directives 一般是 markdown(给文本做轻量标记),executions 通常是 Python(视情况而定)。
命名要描述性:抓线索的脚本就叫 scrape_leads,别缩成 s_l。字符 token 很便宜,文件名务必写清楚,agent 才知道什么住在哪。(→ 1:38:50)
5. 密钥统一进 .env 1:39:41
编程里通常不把密码、密钥、API key 直接写进代码,而是存到一个单独区域——程序员约定俗成叫 .env 文件。
指令里不要写”用这个 API key”,而是写”从 .env 里取所有 API key”。这样逻辑上你日后想分享 directives,直接复制粘贴即可(云端实例的分享与搭建后面章节讲)。
至于为什么叫 .env、为什么有这些命名约定——Nick 说技术里有些东西就是历史沿袭(类比 JPEG 得名于几十年前一个组织),大家都用同一个广为人知的名字,改了别人反而看不懂。
6. 系统提示配置文件:全丢进项目根 1:41:07
各模型对”系统提示”(注入在对话最顶端的内容)有各自约定的文件名:claude.md 对应 Claude、gemini.md 对应 Gemini、cursor.md 对应 Cursor,而 agents.md 是通用回退项。
Nick 的做法是把这几个内容相同的文件全放进项目根,这样用哪个模型都有同一份配置——从 agents.md 复制到 claude.md/gemini.md/cursor.md。这种互操作性很简单。名字必须对:给 Claude 传 gemini.md 它不认、不会自动插入;传 claude.md 才会自动读入。
结构只需建一次,之后每个新项目 agent 都能直接用。Nick 甚至不再让人手动初始化——把 agents.md 给对方,让其 agent”照这个文件搭好我的工作区”,自动完成。
7. 三面板心智:别被界面吓退 1:42:47
新手面对 IDE 的菜单、面板、快捷键会 overwhelm(不知所措),Nick 类比新飞行员看驾驶舱仪表——不必一次学全。
只要抓住三样:左侧文件浏览器、中间编辑器、右侧 agent 聊天,就已经完成 80%,足以为自己的业务搭建和使用 Agentic 工作流。目标不是精通每个功能,而是熟练到 IDE 不拖你后腿。
术语
- directives——DOE 里的”指令”文件夹,存高层流程说明,一般为 markdown。
- executions——DOE 里的”执行”文件夹,存对应实际脚本,通常为 Python。
.env——存放 API key、密码等密钥的约定文件,与代码/指令分离。agents.md——通用的 agent 系统提示配置文件,作为各模型专属文件的回退。- tmp folder——给 agent 当临时”草稿纸”的临时文件夹。
- scratch pad——草稿纸,指 agent 临时读写、用完即弃的中间文件。
自检问题
- DOE 框架里哪两个文件夹是必需的?它们各自装什么、通常什么格式?
答案:
directives(装高层流程指令,markdown,管”做什么”)与executions(装对应脚本,Python,管”怎么做”)。resources/tmp 是可选的。1:37:59 - 为什么密钥要放
.env而不写进 directive? 答案:与代码/指令分离后,分享 directives 时可直接复制粘贴,不泄露也不需改写;指令里只写”从.env取 key”。1:39:41 - 为什么 Nick 把
claude.md/gemini.md/agents.md内容相同地全放进项目根? 答案:各模型只认自家约定文件名,全放根目录且内容一致,用哪个模型都有同一份系统提示,互操作性最省事。1:41:07