1. 从“焚决”说起Codex 这次到底更新了什么“焚决”这个词最近在开发者圈子里传得很凶第一次看到的时候我还以为是哪个玄幻小说的功法名后来才反应过来这是社区对 Codex 一次重大能力升级的戏称——意思是“烧掉旧规则、重写新玩法”的那份决断。作为一个从早期就在用 Codex 做日常开发的人我第一时间把这次更新里最核心的几块东西摸了一遍AGENTS.md 的上下文约定、Skills 技能体系、以及围绕 GPT-6 Astra 这一代模型能力的适配。这篇文章不打算复述官方文档而是把我自己踩过的坑、验证过的配置、以及那些文档里不会写的细节一次性摊开讲清楚。先说结论方便你对号入座如果你只是偶尔用 Codex 补全几行代码这次更新对你影响不大但如果你把 Codex 当成一个能独立跑任务、能读整个仓库、能按团队规范干活的“工程搭子”那 AGENTS.md 和 Skills 这两样东西你必须搞明白否则你会发现同样的模型别人用起来像开了挂你用起来还是那个只会写 for 循环的实习生。这篇文章适合三类人刚接触 Codex 想系统上手的新手、已经在用但总觉得“差口气”的中级用户、以及想给团队搭建统一 AI 工作流的技术负责人。全文我会按“设计思路—核心细节—实操落地—问题排查”的顺序展开每一块都尽量给到可以直接抄的配置和命令。需要提前说明的是下面涉及的具体参数、目录结构、配置片段一部分来自我自己的实测一部分是基于这类工具常见设计逻辑的合理推断。凡是推断的部分我都会明确标注你照着做之前最好在自己的环境里验证一遍别直接上生产。2. 整体设计思路为什么是 AGENTS.md Skills 这套组合2.1 从“提示词工程”到“上下文工程”的转向早两年大家玩 AI 编程核心动作是“写提示词”——把需求描述得越细越好恨不得把整个需求文档塞进对话框。但用久了就会发现一个致命问题提示词是一次性的而项目是长期的。你今天跟模型解释了一遍“我们这个项目用 pnpm 不用 npm、组件必须走 design system、提交信息遵循 conventional commits”明天开个新会话它全忘了你还得再讲一遍。这种重复劳动在个人项目里还能忍在团队协作里就是灾难。AGENTS.md 这个设计的本质就是把“每次都要重复的上下文”从对话里抽出来固化成一个仓库级别的约定文件。你可以把它理解成给 AI 看的 README——README 是给人看的告诉人类这个项目怎么跑AGENTS.md 是给 agent 看的告诉它在这个仓库里应该遵守什么规则、用哪些工具、避开哪些坑。这个转向很关键它把 AI 协作从“会话级”提升到了“仓库级”一次配置长期生效。我实测下来最直观的感受是配好 AGENTS.md 之后模型犯“低级错误”的概率明显下降。以前它动不动就用 npm 命令明明项目是 pnpm以前它总把测试文件放到 src 目录下明明约定是 tests 目录。这些不是模型笨是你没告诉它。AGENTS.md 就是那个“告诉它”的地方。2.2 Skills 解决的是“能力复用”问题如果说 AGENTS.md 解决的是“规则”问题那 Skills 解决的就是“能力”问题。这两者经常被混为一谈其实定位完全不同。举个生活化的例子AGENTS.md 像是你给新员工发的《员工手册》里面写着公司几点上班、报销流程怎么走、代码提交规范是什么而 Skills 像是《岗位操作手册》里面写着“做 PPT 的标准化流程”“处理客户投诉的五个步骤”“部署上线的检查清单”。前者是通用规则后者是具体技能。Skills 的核心价值在于把一套可复用的操作流程封装起来让模型在需要的时候自动调用。比如你经常要做 LaTeX 排版那就可以写一个 latex-formatting skill里面定义好模板、编译命令、常见错误处理下次你说“帮我把这份内容排成论文格式”模型就知道去调用这个 skill而不是从零开始瞎猜。社区里现在流传的 skills 已经覆盖了前端开发、图片生成、AI 漫剧、建模比赛等各个场景本质上都是把“某类任务的专家经验”沉淀成了可调用的模块。2.3 为什么这次更新值得单独拿出来讲把 AGENTS.md 和 Skills 放在一起看你会发现 Codex 这代产品的野心它不再满足于做一个“更聪明的代码补全”而是想成为一个“能理解项目、能执行任务、能积累经验”的工程 agent。GPT-6 Astra 这一代模型在长上下文和指令遵循上的提升正好给了这套体系落地的技术基础——上下文够长才能塞得下 AGENTS.md 和多个 skill 的定义指令遵循够准才能保证模型真的按你写的规则干活而不是自由发挥。所以这次“焚决”烧掉的其实是过去那种“把 AI 当搜索引擎用”的旧习惯。新玩法是你把项目规则写进 AGENTS.md把常用能力封装成 Skills然后让 Codex 在这个框架里自主干活。下面我就把这两块拆开讲清楚具体怎么落地。3. AGENTS.md 核心细节写什么、怎么写、写在哪3.1 AGENTS.md 的定位与加载逻辑先说一个很多人搞混的点AGENTS.md 和 CLAUDE.md 是什么关系简单讲它们都是“给 AI 看的项目约定文件”只是面向的工具不同。CLAUDE.md 是 Claude Code 体系里的约定AGENTS.md 是更通用的 agent 约定。现在不少项目会同时维护两份或者用软链接指向同一个文件避免重复维护。如果你团队里同时用多种 AI 编程工具我的建议是以 AGENTS.md 为主其他文件做软链或同步这样规则只有一份源头改起来不容易漏。加载逻辑上这类文件通常遵循“就近原则”模型会从你当前工作的目录开始逐级向上查找 AGENTS.md把找到的内容合并进上下文。这意味着你可以在仓库根目录放一份全局规则在某个子模块目录再放一份局部规则模型进入那个子模块时会自动叠加局部规则。这个设计非常实用——比如 monorepo 里根目录的 AGENTS.md 写通用规范前端子目录的 AGENTS.md 写“组件必须用函数式写法”后端子目录的写“所有接口必须加参数校验”各管各的互不干扰。注意不同工具对 AGENTS.md 的查找深度和合并策略可能不一样有的只读最近一层有的会全部叠加。上线前务必用一个小测试验证一下你所用版本的加载行为别想当然。3.2 一份能打的 AGENTS.md 应该包含哪些内容我见过太多人把 AGENTS.md 写成“项目介绍”洋洋洒洒几千字讲业务背景结果模型该犯的错还是犯。问题出在AGENTS.md 不是给人看的项目文档是给模型看的操作指令。它应该短、准、可执行。我自己的模板通常包含这几块技术栈声明用什么语言、什么包管理器、什么框架版本。比如“本项目使用 pnpm禁止使用 npm 或 yarn”“React 18 TypeScript 5禁止使用 any”。目录约定源码放哪、测试放哪、文档放哪。模型对目录结构很敏感写清楚能省很多事。命令清单安装依赖、启动开发、跑测试、构建、lint 的具体命令。这是最高频被调用的部分一定要准确。代码规范命名风格、注释要求、提交信息格式。比如“提交信息遵循 conventional commits”“所有导出函数必须有 JSDoc”。禁区清单明确禁止的操作。比如“禁止直接修改 generated 目录下的文件”“禁止在测试里调用真实网络请求”。这里有个经验禁区清单比正面清单更重要。模型天生倾向于“多做”你不告诉它什么不能碰它就可能去改一些不该改的文件。我踩过最惨的一次坑是模型自作主张重构了一个核心工具函数结果把依赖它的十几个模块全搞挂了。从那以后我的 AGENTS.md 里必有一条“未经明确指示禁止重构现有函数签名”。3.3 一个可直接抄的 AGENTS.md 模板下面这份是我在中小型 TypeScript 项目里常用的模板你可以按需删改# AGENTS.md ## 技术栈 - 语言TypeScript 5.x严格模式 - 包管理pnpm禁止 npm / yarn - 框架React 18 Vite - 测试Vitest ## 常用命令 - 安装依赖pnpm install - 启动开发pnpm dev - 跑测试pnpm test - 构建pnpm build - 代码检查pnpm lint ## 目录约定 - 源码src/ - 测试tests/与 src 结构镜像 - 组件src/components/ - 工具函数src/utils/ ## 代码规范 - 禁止使用 any必要时用 unknown 类型守卫 - 所有导出函数必须有 JSDoc 注释 - 提交信息遵循 conventional commits ## 禁区 - 禁止修改 src/generated/ 下的任何文件 - 禁止在测试中发起真实网络请求 - 未经明确指示禁止重构现有函数签名这份模板不长但覆盖了模型最容易出错的几个点。你可以先照抄跑一段时间后根据实际踩的坑往里加规则。AGENTS.md 是活的不是写完就完事每次模型犯了新错误你就想“这条规则能不能写进去防止下次再犯”慢慢就养出一份贴合自己项目的约定。4. Skills 体系拆解从安装到自研的完整路径4.1 Skills 到底是什么和普通提示词有何区别很多人第一次听说 Skills会以为就是“存起来的提示词”。不完全是。提示词是你临时敲进对话框的一段话用完就没了Skill 是一个有结构、有元信息、可被模型主动检索和调用的能力包。它通常包含三部分描述这个 skill 是干什么的、什么时候该用、指令具体怎么做的步骤、以及可选的资源模板文件、脚本、参考文档。区别在哪我举个例子。你写一段提示词“帮我把这段内容排成 LaTeX 论文格式”模型每次都要重新理解“论文格式”是什么样可能这次用 article 类下次用 report 类格式不统一。但如果你有一个 latex-paper skill里面明确定义了文档类、宏包、章节结构、参考文献格式那模型每次调用都会产出一致的结果。Skill 的价值在于“标准化”和“可复用”它把一次性的经验变成了可重复调用的资产。社区里现在有大量现成的 skills 可以白嫖覆盖前端开发、图片生成、AI 漫剧、建模比赛等场景。但我的建议是先别急着装一堆先想清楚你高频重复的任务是什么。装十个用不上的 skill不如自己写一个天天用的。4.2 安装现成 Skills 的几种方式安装 skill 的方式取决于你用的工具和 skill 的来源。常见的有这么几种第一种是从社区仓库手动安装。很多 skill 以 GitHub 仓库的形式发布你把它 clone 下来放到工具约定的 skills 目录里就行。这个目录的位置各工具不同有的在用户主目录下的隐藏文件夹有的在项目根目录。具体路径建议查你所用工具的文档别照搬别人的。第二种是通过包管理器安装。部分工具支持用类似npx或内置命令的方式一键装 skill这种方式最省事但要注意版本兼容——有些 skill 是为特定模型版本写的装到旧版本上可能不生效。第三种是从 skill 市场或聚合站点获取。现在已经有专门收集 skills 的网站按场景分类你可以按需下载。用这类来源时要注意两点一是看更新时间太老的 skill 可能已经不适配新版本二是看依赖有些 skill 依赖特定的外部工具或 API装之前先确认你环境里有。提示装完 skill 后务必用一个简单任务测试它是否被正确加载和调用。我遇到过装完没生效、结果排查半天发现是目录放错的情况白白浪费时间。4.3 自己写一个 Skill以 LaTeX 排版为例现成 skill 再好也总有覆盖不到你特定需求的时候。这时候自己写一个其实没想象中难。我拿“LaTeX 排版”这个场景走一遍完整流程你可以照着套到自己的场景里。第一步明确触发条件。想清楚什么情况下该用这个 skill。比如“当用户要求把内容排成学术论文格式时”。这个描述要写进 skill 的元信息里模型靠它来判断何时调用。第二步拆解操作步骤。把你自己做这件事的流程写下来确定文档类article/report、加载必要宏包amsmath、graphicx、hyperref、设置页面边距、组织章节结构、处理参考文献、编译命令。每一步都写清楚别嫌啰嗦模型需要的就是明确指令。第三步准备资源文件。把常用的模板、示例、编译脚本放进 skill 目录。比如一个template.tex作为起点一个build.sh封装编译命令。这样模型调用时直接基于模板改不用从零生成。第四步写清楚输出要求。比如“输出完整的 .tex 文件不要省略任何宏包声明”“编译命令用 xelatex 而非 pdflatex因为需要中文支持”。这些细节决定了产出能不能直接用。一个最小可用的 skill 目录大概长这样latex-paper/ SKILL.md # 描述 指令 template.tex # 模板文件 build.sh # 编译脚本SKILL.md 里写清楚“这个 skill 做什么、什么时候用、怎么做、输出什么”。写完自己跑几个测试用例看看模型是不是按你预期的方式调用了。自研 skill 的迭代逻辑和 AGENTS.md 一样用一次发现一个问题补一条指令几轮下来就顺手了。5. 实操落地从零搭一套 Codex 工作流5.1 环境准备与安装要点先把基础环境搭起来。Codex 的安装方式根据你用的形态不同而有差异——有桌面版、有编辑器插件、也有命令行形态。Windows 用户如果装桌面版注意安装路径别带中文和空格这是很多工具的通病带了容易出各种莫名其妙的错。安装完成后第一件事是登录。登录环节最常见的两个问题是“打不开登录页”和“auth token is unavailable”。前者通常是网络环境或代理配置的问题检查一下你的网络是否能正常访问所需服务后者多半是凭证过期或缓存损坏清一下本地凭证缓存重新登录一般能解决。如果反复失败可以试试换一种登录方式比如从浏览器登录换成设备码登录。装好之后建议先跑一个最小任务验证环境让它读一个文件、改一行代码、跑一次测试。这一步的目的是确认“模型能正常读写你的工作目录”这是后面所有高级玩法的基础。如果这一步就不通先别急着配 AGENTS.md 和 Skills把基础打通再说。5.2 把 AGENTS.md 接进工作流环境通了之后第一件事是在项目根目录创建 AGENTS.md。别一上来就写一大堆先用我上面给的模板跑起来然后在实际使用中逐步补充。我的做法是开一个新会话让模型做一个典型任务比如“给 utils 目录下的 date.ts 加一个格式化函数”。观察它的行为——它用了什么命令把文件放哪了命名风格对不对每发现一个不符合预期的点就往 AGENTS.md 里加一条规则。这样迭代三五轮你的 AGENTS.md 就会变得非常贴合实际需求。这里有个技巧把 AGENTS.md 当成“错误日志的沉淀”。每次模型犯错不要只是当场纠正而是想“这个错误能不能通过规则预防”。能就写进去。这样你的配置会越来越厚但模型的出错率会越来越低。这比一次性写一份完美的 AGENTS.md 要现实得多因为没人能预判所有坑。5.3 配置 Skills 并验证调用AGENTS.md 跑顺之后开始接 Skills。先装一两个你最高频使用的别贪多。装完做一次验证给模型一个明确需要该 skill 的任务看它是否主动调用。如果没调用检查两件事——skill 的触发描述是否够清晰、skill 目录位置是否正确。我实测下来skill 不被调用的最常见原因是描述太模糊。比如你写“用于处理文档”模型根本不知道什么时候该用改成“当用户要求将内容转换为 PDF 格式的学术论文时使用”命中率立刻上来了。所以写 skill 描述时要站在模型的角度想它在什么情境下会“想起”这个 skill把那个情境描述清楚。验证通过后就可以在日常任务里放心用了。用一段时间后你会发现有些 skill 用着用着就不顺手了——可能是需求变了可能是发现更好的做法。这时候别将就直接改 skill 内容或者干脆重写一个。Skills 是为你服务的不是反过来。5.4 多工具协同Codex 与其他工具的配合现实工作中你不太可能只用一种 AI 编程工具。可能 Codex 用来跑长任务另一个工具用来做快速补全还有的用来做代码审查。这时候 AGENTS.md 的“单一源头”优势就体现出来了——你维护一份规则通过软链或同步让多个工具都能读到避免规则不一致导致的混乱。如果你同时用 Codex 和 Claude Code可以维护一份 AGENTS.md然后让 CLAUDE.md 软链指向它。这样改一处两边都生效。同理如果你用多个编辑器也尽量让它们读同一份配置。规则的一致性比规则本身更重要模型在不同工具里表现不一致很多时候就是配置不同步导致的。6. 常见问题与排查技巧实录6.1 高频问题速查表下面这张表是我和身边朋友实际遇到过的问题汇总按现象、可能原因、解决方向整理方便你快速定位现象可能原因解决方向登录页打不开网络环境异常检查网络连通性换登录方式auth token is unavailable凭证过期或缓存损坏清除本地凭证缓存后重新登录模型不遵守 AGENTS.md 规则文件位置不对或规则太模糊确认加载路径把规则写具体Skill 装完不生效目录放错或描述不清核对目录重写触发描述模型乱改文件禁区清单缺失在 AGENTS.md 补充禁止项长任务中途跑偏上下文超限或指令冲突拆分任务检查规则是否矛盾命令执行报错环境变量或依赖缺失检查 PATH 和依赖安装输出格式不稳定缺少输出约束在 skill 或 AGENTS.md 里明确格式6.2 几个文档里不会写的避坑经验第一个坑别让 AGENTS.md 无限膨胀。规则越多模型遵循的负担越重有时候反而会顾此失彼。我的经验是控制在合理长度内把最高频、最致命的规则放前面次要的往后放。如果一份 AGENTS.md 超过几百行考虑拆分成根目录 子目录的多层结构。第二个坑Skill 之间会打架。如果你装了两个功能重叠的 skill模型可能不知道该调哪个结果两个都不用或者用错。装之前先看看有没有功能重复的有就留一个最好的别贪多。第三个坑模型会“过度自信”。有时候它明明不确定也会一本正经地给你一个错误答案。这时候 AGENTS.md 里可以加一条“遇到不确定的情况先提问而不是猜测”。这条规则帮我避免了好几次“模型自作主张改错代码”的事故。第四个坑版本升级后配置可能失效。工具更新后AGENTS.md 的加载逻辑、skill 的格式要求都可能变。每次升级后花十分钟跑一遍验证任务确认配置还生效。别等到出了大问题才发现。6.3 关于 GPT-6 Astra 适配的几点观察GPT-6 Astra 这一代模型在长上下文和指令遵循上的提升是这套 AGENTS.md Skills 体系能真正跑起来的前提。我实测下来的感受是同样的配置在新模型上遵循度明显更高。以前模型可能读了三遍规则还是我行我素现在基本能做到“说一次就记住”。但这也带来一个新问题模型变“听话”了你写的规则如果本身有问题它也会忠实地执行错误指令。所以配置的准确性变得更重要了。以前模型会“自作聪明”地纠正你的小错误现在它可能老老实实按你写的错规则走。这提醒我们写 AGENTS.md 和 Skills 时要更严谨别把错误经验固化进去。另外新模型对 skill 的调用判断也更准了。以前经常出现“该调用时不调用、不该调用时乱调用”的情况现在命中率高了不少。这意味着你可以放心地把更多能力封装成 skill让模型自主调度而不用每次都手动指定。7. 我个人的一点使用体会折腾这套东西大半年最大的感受是AI 编程工具的上限取决于你给它搭的框架。同样的模型有人用起来像开了挂有人用起来还是那个只会写样板代码的助手差距不在模型本身在于你有没有把项目规则和常用能力沉淀下来。AGENTS.md 和 Skills 这套组合本质上是在做一件事把你的隐性经验显性化。你脑子里那些“这个项目该这么干、那个任务该那么做”的经验以前只能靠每次对话重复传达现在可以固化下来让模型自动遵循。这个过程一开始有点麻烦但一旦跑顺回报是持续的。如果你刚开始接触我的建议是别追求一步到位。先把 AGENTS.md 建起来跑几个任务补几条规则再挑一个最高频的场景写个 skill用起来然后慢慢扩展。这套东西是长出来的不是设计出来的。等你用顺手了回头看会发现真正省下的时间不是模型帮你写的那几行代码而是你不再需要反复解释“我们项目是这样的”。