--- title: '12 项目与 Agent 工作区:结构与搭建' video_id: MxyRjL7NG18 part: 12 --- > 章节 12 / 37 · [[00-总览|课程总览]] · 起始 [1:34:54](https://youtu.be/MxyRjL7NG18?t=5694) ## 章节主旨 如何从零搭一个 agent 能读懂、能导航的项目工作区:核心是 DOE 框架 里 `directives` 与 `executions` 两个必需文件夹的分工,加上 `.env` 存密钥、描述性命名、以及 `claude.md`/`agents.md` 这类系统提示配置文件的放法。 ## 核心论点 1. **工作区搭建 = 给 agent 一次"入职教育"**——不只是建文件夹,而是把方法论与理由写进去让它理解。([[#1-搭工作区--给-agent-一次入职教育-13516|→ 详解1]]) 2. **DOE 结构只有两个必需文件夹:directives 与 executions**,其余(resources / tmp)按需加。(→ 详解2、详解3) 3. **directives 管"做什么"(markdown),executions 管"怎么做"(Python)**,二者机械对应、互相调用。([[#4-directives做什么markdownvs-executions怎么做python-13918|→ 详解4]]) 4. **密钥统一进 `.env`,不写进代码或指令**,换机器/分享时才能直接复制。([[#5-密钥统一进-env-13941|→ 详解5]]) 5. **系统提示配置文件全丢进项目根**——`claude.md`/`gemini.md`/`agents.md` 内容相同,哪个模型都能读。([[#6-系统提示配置文件全丢进项目根-14107|→ 详解6]]) ## 知识点详解 ### 1. 搭工作区 = 给 agent 一次"入职教育" [1:35:16](https://youtu.be/MxyRjL7NG18?t=5716) 创建工作区本身很简单——第一次打开这类 IDE 它就会提示你建一个。真正要做的是搭出一套文件夹结构,并给 agent 说明书,让它知道你为什么这样组织、背后是什么方法论。 Nick 把 `agents.md` 比作对 agent 的一整套"教育",跟他此刻对学员讲课是一回事:让它理解为什么用 DOE 框架、为什么这样干,而不是"raw dog"(裸上)硬塞任务。 类比是给新员工布置工位:得让他知道东西都放哪、基础文件夹和物件先备齐,有了这个结构他才能在里面发挥。一个组织良好的工作区,Nick 视为"essential(必备)"。 ### 2. 项目结构:directives 与 executions 两个必需文件夹 [1:37:59](https://youtu.be/MxyRjL7NG18?t=5879) 工作区名字随意。往下分两大文件夹:`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](https://youtu.be/MxyRjL7NG18?t=5889) 若有一批常规喂进去的参考物料,可加 `resources` 文件夹;子文件夹可再分 inputs / outputs / prompts / reference。 另一个常加的是 `tmp`(temporary)——agent 有时需要临时建文件当"草稿纸(scratch pad)"来干活。除此之外文件夹随你加,Nick 不强推某种唯一范式。 ### 4. directives(做什么/markdown)vs executions(怎么做/Python) [1:39:18](https://youtu.be/MxyRjL7NG18?t=5958) 分工的本质是"你做什么"与"你怎么做"的分离:directives 是 what,execution 脚本是 how——实际发生的事。 调用是机械对应的:你在某条 directive 里写"第三步,调用 `apify_scraper.py`",agent 读到就知道去调哪个 execution。`directives` 一般是 markdown(给文本做轻量标记),`executions` 通常是 Python(视情况而定)。 命名要描述性:抓线索的脚本就叫 `scrape_leads`,别缩成 `s_l`。字符 token 很便宜,文件名务必写清楚,agent 才知道什么住在哪。(→ [1:38:50](https://youtu.be/MxyRjL7NG18?t=5930)) ### 5. 密钥统一进 `.env` [1:39:41](https://youtu.be/MxyRjL7NG18?t=5981) 编程里通常不把密码、密钥、API key 直接写进代码,而是存到一个单独区域——程序员约定俗成叫 .env 文件。 指令里不要写"用这个 API key",而是写"从 `.env` 里取所有 API key"。这样逻辑上你日后想分享 directives,直接复制粘贴即可(云端实例的分享与搭建后面章节讲)。 至于为什么叫 `.env`、为什么有这些命名约定——Nick 说技术里有些东西就是历史沿袭(类比 JPEG 得名于几十年前一个组织),大家都用同一个广为人知的名字,改了别人反而看不懂。 ### 6. 系统提示配置文件:全丢进项目根 [1:41:07](https://youtu.be/MxyRjL7NG18?t=6067) 各模型对"系统提示"(注入在对话最顶端的内容)有各自约定的文件名:`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](https://youtu.be/MxyRjL7NG18?t=6167) 新手面对 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 临时读写、用完即弃的中间文件。 ## 自检问题 1. DOE 框架里哪两个文件夹是必需的?它们各自装什么、通常什么格式? **答案**:`directives`(装高层流程指令,markdown,管"做什么")与 `executions`(装对应脚本,Python,管"怎么做")。resources/tmp 是可选的。[1:37:59](https://youtu.be/MxyRjL7NG18?t=5879) 2. 为什么密钥要放 `.env` 而不写进 directive? **答案**:与代码/指令分离后,分享 directives 时可直接复制粘贴,不泄露也不需改写;指令里只写"从 `.env` 取 key"。[1:39:41](https://youtu.be/MxyRjL7NG18?t=5981) 3. 为什么 Nick 把 `claude.md`/`gemini.md`/`agents.md` 内容相同地全放进项目根? **答案**:各模型只认自家约定文件名,全放根目录且内容一致,用哪个模型都有同一份系统提示,互操作性最省事。[1:41:07](https://youtu.be/MxyRjL7NG18?t=6067)