# 交代 · AGENTS.md、config 与 Skills · Codex · 多 Agent 的异步编码工作流 **作者** Aklman · **章节** 05 / 12 · **首发** 2026.08 · **语言** 中文为主, 中英双语 **原文** https://library.aklman.com/books/codex/05-agents-md **全书 markdown** https://library.aklman.com/books/codex/llms.md **上一章** https://library.aklman.com/books/codex/04-approvals/llms.md **下一章** https://library.aklman.com/books/codex/06-multi-agent/llms.md > 本章来自 Aklman · Library, 完整免费阅读。允许 AI 摘读、引用、问答; 转载请保留作者署名与原文链接 (CC BY-NC-ND 4.0, https://library.aklman.com/license)。 --- > 同一句话你跟它说了十遍:测试用这条命令、别碰那个目录、PR 要带说明。AGENTS.md 治这个 —— 它不是 Codex 私产,是六万多个开源仓库在用的开放标准,全局、仓库根、子目录逐层叠加,离当前目录最近的赢。config.toml 管机器上的默认:模型、沙箱、审批、MCP,一份配置三个本地面共用。重复的流程再往上沉一层:存成 Skill,$名字 唤起,用到才加载正文。这一章讲三层交代怎么分工 —— 事实进 AGENTS.md,默认进 config,流程进 skill,以及为什么「它自己攒的 memories」不能替你立规矩。 同一句话你跟它说了十遍:测试跑这条命令、别碰那个目录、PR 要带说明。别赌新对话会自己带回上次的交代 —— 必须生效的东西要写下来。Codex 有三层能写:事实和规范进 AGENTS.md,机器上的默认进 config.toml,重复的流程沉成 Skill。这一章讲三层怎么分工,以及一条容易被高估的边界:它自己攒的 memories,不能替你立规矩。 ### I · AGENTS.md:不是 Codex 私产,是开放标准 先纠正一个常见误解:AGENTS.md 不是 OpenAI 发明的私有格式。它是「一个引导编码 agent 的简单开放格式」,被六万多个开源项目使用,Cursor、Copilot、Devin、Warp、Gemini CLI 等一大票 agent 都读它。[^1]这意味着你为 Codex 写的这份交代,换个工具照样管用 —— 你投的时间不绑死在一家。但「最近的赢」要看具体实现:Codex 本地会话按项目根到**当前工作目录**加载一条链;GitHub review 才针对每个 changed file 找最近的 AGENTS.md。[^2] Codex 动手前先读它,发现链是分层叠加的:全局的 `~/.codex/AGENTS.md` 打底,然后从项目根往你启动 Codex 的当前目录逐层走,每个目录取一个文件、从根往下拼 —— 越靠近当前目录,越晚出现、覆盖越前面的。[^2]所以 monorepo 里根目录放全仓通用规矩,子服务放特殊规矩后,要从那个子服务目录启动 Codex,它才会进入那条链;别假设会话会按每个被改文件临时换规则。起步不用手写:CLI 里 `/init` 生成一份起草稿。[^6] _一份短而准的项目交代 —— 只写它猜不到的_ ```text title="AGENTS.md" ```markdown ## 怎么跑 - 装依赖用 pnpm,不是 npm - 测试:pnpm test;lint:pnpm run lint,开 PR 前必过 ## 别碰 - 不要改 migrations/,不要动格式化配置 - 生产配置从只读副本读,不写回 ## Review guidelines - 不要记录 PII - 确认鉴权中间件包住了每条路由 ``` ``` 写什么、写多少,官方的判断很干脆:短而准胜过长而空 —— 只收它读代码猜不到的东西(构建 / 测试命令、和默认不同的规范、禁区、踩过的坑)。[^6]什么时候加一行?一条好用的触发律:**Codex 同一个错犯第二次,就让它做个复盘、把教训写进 AGENTS.md**。[^6]文件长到臃肿就拆 —— 主文件保持精简,专门的细则放进子目录里更近的文件。上面那段 `Review guidelines` 不是摆设:第 10 章 GitHub 上的自动审查,读的正是它。 --- ### II · config.toml:机器上的默认 AGENTS.md 管「这个项目怎么回事」,config.toml 管「这台机器上 Codex 默认怎么做」—— 模型、沙箱档、审批策略、思考力度、MCP 服务器,都在这里定死一次,省得每次开会话重设。[^3]个人默认放 `~/.codex/config.toml`,项目特有的行为放项目里的 `.codex/config.toml`(且只在你信任那个项目时才加载)。优先级从高到低是:命令行标志 → 项目 config(越近越优先)→ profile → 用户 config → 系统 config → 内置默认。[^3] 和第 2 章的边界呼应:**同一台机器上的 CLI、IDE 扩展与桌面应用共用本地配置** —— 你在 `config.toml` 里定的模型和沙箱档,三个本地客户端一起受益。[^3]所以调它是一次性投资;但别把这句话外推到云端 / GitHub。也别把该长期钉住的默认反复在命令行里临时传 —— 标志留给一次性例外,持久偏好写进 config。 > config 现在还多管一层:全局 [agents] 默认与 .codex/agents/*.toml 自定义角色。它们不是 AGENTS.md 的替代品 —— 前者决定「派给谁、用什么模型与权限」,后者仍决定「这个项目必须怎么做」。第 6 章把这条分工完整展开。 --- ### III · Skills:把重复的流程沉成一个词 有些交代不是一句事实,是一整套多步流程:发版的检查清单、跑一份数据管道、按团队口吻写 changelog。这些沉成 **Skill**:一个目录加一份 `SKILL.md`(必含 name 和 description),旁边可放脚本和参考。[^4]它建立在开放的 agent skills 标准上,和 AGENTS.md 一样不绑死一家。关键在加载方式 —— progressive disclosure:Codex 平时只拿每个技能的名字和描述(初始清单至多占 2% 上下文),真决定用某个技能时才读它完整的正文。[^4]一份几百行的发版手册,平时几乎不占地方。 存好之后有两条入口:你打 `$名字` 显式唤起,或 Codex 按描述判定相关就隐式加载 —— 所以描述要写清「什么时候该用我」。[^4]位置分层,和记忆、配置一样:仓库里的 `.agents/skills` 随版本库共享,用户级 `~/.agents/skills` 跟着你走。[^4]如果你记得旧的「自定义 prompts」:已经弃用,一律改用 skills;要跨团队分发,再往上打包成 plugin。[^4] > 还有第四样东西也在记事 —— 但它不能替你立规矩。本地记忆(默认关闭)让 Codex 把先前工作里有用的上下文带进后续对话,方便,但官方把话说死了:**必须始终生效的团队指令,留在 AGENTS.md 或签入的文档里;记忆是有用的回忆层,不是那些必须永远适用的规则的唯一来源。**[^5]换句话说:记忆帮它「想起来」,AGENTS.md 让它「必须照办」—— 两件事,别指望记忆兜底规矩。 动手 · 给一个真项目铺三层交代: - **跑 /init,再手动删到「短而准」**: 让它生成起草稿,然后逐行问「删掉这行它会不会犯错」—— 不会就删。顺手加一段 Review guidelines,给第 10 章用。 - **把一个反复设的默认写进 config.toml**: 模型、沙箱档、思考力度,挑你每次都要调的那个,定死在 ~/.codex/config.toml。之后在同机编辑器或桌面应用里确认它也生效;再记住云端不读这份文件。 - **把重复第三次的流程存成第一个 skill**: 找一套你这周贴过两遍的多步流程,放进 .agents/skills/<名字>/SKILL.md,描述写清触发时机。下次 $名字 唤起。 > 事实进 AGENTS.md,默认进 config, > 流程沉成一个词 ## 引用与参考 01 · agents.md(标准站)—— 一句话定位「一个引导编码 agent 的简单开放格式」;称被六万多个开源项目使用,支持方包括 OpenAI Codex、Cursor、Jules、Devin、GitHub Copilot Coding Agent、Warp、Zed、opencode、Gemini CLI、Aider 等。标准站用「离被改文件最近的 AGENTS.md 赢」概括嵌套规则;具体发现方式由各 agent 实现,Codex 本地运行按项目根到当前工作目录加载,GitHub review 才按 changed file 找最近文件。截至 2026-08-05。 (agents.md) 02 · OpenAI Codex 文档 · Custom instructions with AGENTS.md —— Codex 动手前先读 AGENTS.md。发现链:全局 ~/.codex/AGENTS.md(或 AGENTS.override.md)→ 项目根往当前目录逐层走,每目录取一个文件(override > AGENTS.md > 回退名),从根往下拼接,越靠近当前目录越晚出现、因此覆盖更早的。默认上限 project_doc_max_bytes 32 KiB;撞上限可抬高上限或把指令拆到嵌套目录。截至 2026-08-05。 (OpenAI · AGENTS.md) 03 · OpenAI Codex 文档 · Config basics —— 个人默认在 ~/.codex/config.toml,项目覆盖在 .codex/config.toml(仅信任项目加载)。优先级(高到低):CLI 标志 / -c 覆盖 > 项目 config(越近当前工作目录越优先)> profile 文件 > 用户 config > 系统 config > 内置默认。常改项:model、approval_policy、sandbox_mode、model_reasoning_effort、personality、[features] 开关。同一台机器上的 CLI、IDE 扩展与 ChatGPT 桌面应用共用本地配置;cloud / GitHub 不读取这份用户文件。截至 2026-08-05。 (OpenAI · Config basics) 04 · OpenAI Codex 文档 · Build skills —— 技能建立在开放的 agent skills 标准(agentskills.io)上:一个目录加一份 SKILL.md(必含 name 与 description)加可选脚本 / 参考。progressive disclosure:Codex 先只拿每个技能的名字、描述、路径(初始清单至多占 2% 上下文或 8000 字符),决定用某个技能时才读它完整的 SKILL.md。触发:$名字 显式提及或 /skills,或按描述隐式匹配。位置分仓库 .agents/skills、用户 ~/.agents/skills、admin、系统内置。旧的自定义 prompts 已弃用,改用 skills;要跨团队分发则打包成 plugin。截至 2026-08-05。 (OpenAI · Build skills) 05 · OpenAI Codex 文档 · Memories —— 记忆让 Codex 把先前工作里有用的上下文带进后续工作;本地 Codex 记忆默认关闭,可在设置或 [features] memories = true 打开,/memories 按对话控制,存 ~/.codex/memories/ 的 markdown。原话:「把必须始终生效的团队指令留在 AGENTS.md 或签入的文档里,把记忆当成有用的回忆层,而不是那些必须永远适用的规则的唯一来源。」截至 2026-08-05。 (OpenAI · Memories) 06 · OpenAI Codex 文档 · Best practices —— 一旦某个 prompt 模式好用,就用 AGENTS.md 固化它。CLI 里 /init 是脚手架命令,生成一份起步 AGENTS.md,再照你团队实际的构建 / 测试 / 审查 / 发布方式改。官方判断:短而准的 AGENTS.md 胜过又长又空的;「当 Codex 同一个错犯第二次,让它做个复盘并更新 AGENTS.md」;文件太大就让主文件精简、把计划 / 代码审查 / 架构等拆成任务专用的 markdown 文件来引用。截至 2026-08-05。 (OpenAI · Best practices) --- *交代 · AGENTS.md、config 与 Skills · Codex · 多 Agent 的异步编码工作流 · Aklman 著 · CC BY-NC-ND 4.0 · https://library.aklman.com/books/codex/05-agents-md*