1. 从焚决说起这次更新到底动了什么焚决这个词最近在开发者圈子里传得挺凶第一次看到的时候我还以为是哪个玄幻小说的功法名后来才反应过来这是圈内人对 Codex 一次重大版本更新的戏称——意思是烧掉旧规则、重写新玩法的那种级别。我前后折腾了大概两周时间把新版 Codex 的 AGENTS.md 机制、Skills 体系、以及围绕 GPT-6 Astra 的接入方式都摸了一遍踩了不少坑也攒了一些可以直接抄作业的经验这里一次性讲清楚。先把定位说清楚这篇内容适合三类人。第一类是刚听说 Codex 但还没装上的新手想知道它到底能干什么、值不值得花时间第二类是已经在用旧版 Codex、但被这次更新搞得有点懵的老用户尤其是那些发现原来的配置突然不生效的人第三类是想把 Codex 接入自己工作流比如前端开发、建模比赛、文档排版的进阶玩家关心 Skills 怎么写、怎么装、怎么组合。核心关键词我先摆出来Codex、AGENTS.md、Skills、GPT-6 Astra、CLAUDE.md。这几个词基本构成了这次更新的全部骨架。AGENTS.md 是新的上下文约定文件Skills 是可插拔的能力模块GPT-6 Astra 是新的模型底座CLAUDE.md 则是从另一个生态迁移过来的兼容层。理解这四者的关系比死记任何一条命令都重要。我个人的判断是这次更新最大的变化不是模型变强了而是**约定优于配置**的思路被彻底贯彻了。以前你要写一堆配置文件告诉工具我是谁、我在做什么、我要什么风格现在这些全部收敛到 AGENTS.md 一个文件里Skills 则负责把具体能力模块化。这个设计思路的转变才是焚决这个称呼的真正来源。2. 核心概念拆解AGENTS.md、Skills 与模型底座的关系2.1 AGENTS.md 到底是什么为什么它取代了一堆配置文件AGENTS.md 本质上是一个放在项目根目录的 Markdown 文件用来向 Codex 描述这个项目是什么、有哪些约定、你该怎么干活。听起来很像 README但它的读者不是人是模型。这一点非常关键——README 是给人看的讲究可读性AGENTS.md 是给模型看的讲究信息密度和指令明确性。我实测下来AGENTS.md 里最值得写的几类内容是项目技术栈和版本约束、目录结构约定、代码风格要求、常用命令构建、测试、lint、以及禁止事项。比如你写所有组件使用函数式写法禁止 class 组件模型在生成代码时就会严格遵守你写提交信息使用中文格式为类型: 描述它连 commit message 都会按这个来。为什么它比以前的配置文件好因为以前的配置是分散的——lint 规则在 .eslintrc格式化在 .prettierrc构建在 package.json模型要读一堆文件才能拼出全貌。现在收敛到一个文件模型一次读取就能建立完整上下文命中率明显提升。我做过对比测试同一个重构任务有 AGENTS.md 的情况下模型一次通过率大概能从六成提到八成以上。注意AGENTS.md 不是越长越好。我见过有人写了三千多行结果模型反而抓不住重点。经验值是控制在 200 行以内把最硬的约束放前面细节可以拆到子目录的 AGENTS.md 里做分层。2.2 Skills 体系把能力变成可插拔的积木Skills 是这次更新里我最喜欢的部分。简单说一个 Skill 就是一个封装好的能力包包含一段说明告诉模型这个技能干什么、什么时候用加上可选的脚本或资源文件。你可以把它理解成给模型装的插件——需要什么装什么不用就卸掉。Skills 的价值在于复用和隔离。举个例子你经常要做 LaTeX 排版那就写一个 latex-formatting skill里面写清楚排版规范、常用宏包、编译命令下次任何项目只要挂上这个 skill模型就自动懂你的排版习惯不用每次重复交代。再比如前端开发你可以做一个 frontend-conventions skill把组件命名、样式方案、状态管理约定全塞进去。Skills 的存放位置一般有两个全局目录对所有项目生效和项目目录只对当前项目生效。我的建议是通用能力放全局项目特有的放项目里。这样既保证一致性又不会让全局配置臃肿。2.3 GPT-6 Astra 与 CLAUDE.md模型底座和兼容层GPT-6 Astra 是这次更新配套的模型底座能力上主要提升在长上下文理解和多步任务规划上。实际体感是处理大型重构任务时它更少跑偏能记住更早之前交代的约束。不过要注意模型能力再强如果你的 AGENTS.md 写得含糊它照样会理解错——上下文质量决定输出质量这条铁律没变。CLAUDE.md 的存在则是一个兼容设计。很多团队之前已经在用 CLAUDE.md 作为上下文约定文件这次更新没有强制迁移而是让 Codex 也能识别这个文件名。如果你手上有一堆 CLAUDE.md不用急着改名Codex 会一并读取。但我的建议是新项目统一用 AGENTS.md老项目可以保留 CLAUDE.md避免两套约定打架。概念作用建议位置优先级AGENTS.md项目上下文与约定项目根目录高CLAUDE.md兼容旧约定的上下文文件项目根目录中Skills可插拔能力模块全局或项目目录高GPT-6 Astra模型底座无需手动配置高3. 实操全流程从安装到跑通第一个 Skills3.1 安装与环境准备Windows 和 macOS 的差异安装这一步看起来简单但坑不少。我分别在 Windows 桌面版和 macOS 上装过体验差异挺明显。Windows 这边官网下载安装包后直接双击注意安装路径不要带中文和空格我有个朋友装在我的文档下面结果启动时报路径解析错误排查了半天。安装完成后第一次启动需要登录登录入口在官网用邮箱注册即可。如果遇到auth token is unavailable这类提示八成是网络环境或者本地缓存的问题先清一下配置目录再重试。macOS 这边相对顺滑但要注意权限问题。如果装在系统目录下可能需要手动授权。另外如果你用包管理器安装记得确认版本号别装到旧版去了。提示安装完成后先跑一个最小验证——新建一个空目录放一个最简单的 AGENTS.md然后让 Codex 读一下确认它能正确识别。这一步能帮你提前排除 80% 的环境问题。3.2 写出第一个可用的 AGENTS.md我拿一个真实的前端项目举例。假设你有一个 React TypeScript 的项目AGENTS.md 可以这样写# 项目约定 ## 技术栈 - React 18 TypeScript 5 - 状态管理使用 Zustand - 样式使用 Tailwind CSS ## 代码风格 - 组件一律使用函数式写法 - 组件文件名使用 PascalCase - 工具函数使用 camelCase - 禁止使用 any必要时用 unknown 加类型守卫 ## 常用命令 - 开发npm run dev - 构建npm run build - 测试npm run test - 格式化npm run format ## 禁止事项 - 不要引入新的 UI 库 - 不要修改 vite.config.ts 除非明确要求这份文件不到 30 行但信息密度很高。模型读完就知道该用什么写法、跑什么命令、哪些红线不能碰。我实测下来有了这份约定模型生成的组件代码基本能直接过 lint省掉大量返工。3.3 安装和使用一个现成的 SkillSkills 的安装方式取决于来源。如果是本地目录直接放到 skills 目录下即可如果是从社区获取的一般是一个压缩包或者一个目录解压后放进对应位置。我建议先建一个专门的 skills 目录按功能分类存放方便管理。以图片生成 skills为例安装包解压后通常包含一个 SKILL.md描述文件和若干脚本。SKILL.md 里会写清楚这个技能的名称、触发条件、使用方式。你把它放到全局 skills 目录后重启 Codex它就能识别到这个能力。之后你在对话里提到生成一张配图模型就会自动调用这个 skill。这里有个细节很多人忽略Skill 的触发靠的是描述匹配所以 SKILL.md 里的描述要写得具体。如果你只写生成图片模型可能不确定什么时候该用如果你写当用户需要为文章生成配图、封面图、示意图时使用命中率就高很多。3.4 把 Codex 接入现有工作流接入工作流这一步不同场景差别很大。我挑两个典型场景说。第一个是前端开发。我的做法是在项目根目录放 AGENTS.md把组件规范、目录结构、API 约定全写进去然后挂一个 frontend-conventions skill 做补充。这样每次让 Codex 写组件它都会自动遵循约定我基本只需要 review 逻辑不用管格式。第二个是建模比赛比如华为杯这类。这类任务的特点是文档多、公式多、排版要求高。我的做法是写一个 latex-formatting skill把论文模板、公式规范、参考文献格式全封装进去再配一个 AGENTS.md 说明比赛的具体要求。这样模型在帮我写论文段落时排版和引用格式都能自动对齐省了大量手工调整的时间。4. 常见问题与排查技巧实录4.1 启动和登录类问题这类问题最常见我整理了一个速查表现象可能原因处理方式打不开、闪退安装路径含中文/空格重装到纯英文路径auth token is unavailable缓存损坏或登录态失效清除配置目录后重新登录登录后仍提示未授权网络环境异常检查网络重试登录版本过旧未更新到最新版官网下载最新安装包覆盖我踩过最深的一个坑是打不开——折腾了一下午最后发现是安装路径里有个中文文件夹名。这种问题官方文档一般不写但实际很常见所以第一条就列出来。4.2 上下文不生效类问题如果你发现 AGENTS.md 写了但模型不遵守先检查三件事文件名是否完全正确大小写敏感、文件是否在项目根目录、内容是否有冲突指令。我遇到过一种情况AGENTS.md 里写使用 Tailwind但 CLAUDE.md 里还留着旧的使用 styled-components两个文件同时被读取模型就懵了。新旧约定文件不要并存冲突内容这是血泪教训。还有一种情况是内容太长导致关键指令被淹没。解决办法是把最重要的约束放在文件最前面用加粗或者独立小节突出。模型对开头和结尾的内容注意力更高这是有实测依据的。4.3 Skills 不触发类问题Skill 装了但模型不用通常有三个原因描述不匹配、优先级冲突、或者 skill 本身有语法错误。排查顺序建议是先看 SKILL.md 的描述是否具体再看是否有多个 skill 功能重叠导致模型犹豫最后检查脚本是否能独立运行。我个人的经验是skill 描述里一定要写清楚什么时候用而不只是这是什么。比如这是一个 PDF 处理技能就不如当用户需要合并、拆分、提取 PDF 内容时使用本技能来得有效。4.4 模型输出质量类问题如果模型输出总是差一口气别急着怪模型先回头看看你的上下文。我总结了一个简单的判断标准如果模型犯的是格式类错误命名、缩进、风格那是 AGENTS.md 没写清楚如果犯的是逻辑类错误算法、架构那可能是任务描述本身不够明确需要拆解成更小的步骤。另外GPT-6 Astra 在长任务上表现更好但也不是万能。遇到特别复杂的重构我的做法是先让它出一个方案我 review 后再让它执行而不是一步到位。这种先规划后执行的模式成功率明显更高。5. 进阶玩法Skills 组合与工作流自动化5.1 把多个 Skills 串成流水线单个 skill 解决单点问题多个 skill 组合起来就能形成流水线。我自己的文档工作流是这样的先挂一个 outline skill 负责生成大纲再挂一个 writing skill 负责扩写最后挂一个 latex-formatting skill 负责排版。三个 skill 各司其职模型在每一步都知道该调用哪个。这种组合的关键是职责边界要清晰。如果两个 skill 都声称能写文档模型就会纠结。所以我在写 skill 描述时会刻意加上仅负责 XX 阶段这样的限定词避免重叠。5.2 用 AGENTS.md 做项目级人格设定除了技术约定AGENTS.md 还能用来设定模型的工作风格。比如你可以写回答尽量简洁不要过度解释、遇到不确定的地方先提问再动手、所有代码改动都要附带测试。这些软性约定看似不起眼但长期用下来能显著提升协作体验。我有个习惯每个新项目开始时先花十分钟写 AGENTS.md把这次项目的特殊要求写进去。这十分钟的投入后面能省下好几个小时的返工。这笔账怎么算都划算。5.3 团队协作中的约定同步如果是团队使用AGENTS.md 和 Skills 都应该纳入版本控制。这样每个人的本地环境都能保持一致不会出现我这边能跑你那边不行的情况。我的做法是把 AGENTS.md 提交到仓库Skills 则分成两部分通用 skill 放全局项目特有 skill 放仓库里的 .skills 目录通过软链接挂载。注意团队协作时AGENTS.md 的修改要走 review。我见过有人随手改了一行约定结果全组的代码风格都变了这种蝴蝶效应在多人项目里很常见。6. 我踩过的坑和几条实在建议先说几个具体的坑。第一个是不要迷信一键配置网上流传的各种配置模板直接抄过来往往水土不服因为每个项目的技术栈和约定都不一样。我的建议是拿模板当参考自己动手改一遍改的过程就是理解的过程。第二个是Skills 不要贪多。我一开始装了十几个 skill结果模型在触发时经常选错反而降低了效率。后来精简到五六个核心 skill命中率立刻上来了。Skill 的价值在于精准不在于数量。第三个是版本更新要留退路。这次焚决级别的更新改动面很大我建议在升级前先备份现有的 AGENTS.md 和 skills 目录。万一新版有兼容问题能快速回滚。我自己就吃过没备份的亏升级后发现某个自定义 skill 不兼容只能从头重写。最后分享一个我一直在用的小技巧给每个 skill 写一个最小验证用例。就是一段最简单的输入用来确认这个 skill 是否正常工作。每次更新或迁移后先跑一遍验证用例确认没问题再投入正式使用。这个习惯帮我省了无数次排查时间。这套东西说到底核心就一句话把重复交代的事情沉淀成文件把重复使用的能力封装成 skill。剩下的就是不断根据实际反馈去打磨。我现在的状态是新项目开工第一件事就是写 AGENTS.md这已经成了肌肉记忆。至于 GPT-6 Astra 后续还会带来什么变化等实际用出体感了再聊。
