1. 从“焚决”说起Codex 这次到底更新了什么“焚决”这个词在圈子里传开的时候我第一反应是——又有人在整活了。但仔细扒了一圈 Codex 最近的动静发现这次还真不是空穴来风。简单说Codex 这次的核心变化集中在三个方向AGENTS.md 的上下文约定机制、Skills 技能体系的正式落地、以及对新一代模型包括社区热议的 GPT-6 Astra 相关能力的适配。如果你之前只是把 Codex 当成一个“命令行里帮你补全代码的工具”那这次更新之后它的定位已经悄悄变成了一个可编排、可扩展、可沉淀经验的智能体工作台。先给不太熟悉的朋友补个背景。Codex 最早是作为代码生成模型出现的后来演变成一个可以在终端、编辑器、CI 流程里调用的开发助手。而这次“焚决”级别的更新本质上是把**“怎么让 AI 稳定地按你的规矩干活”**这件事从“靠提示词碰运气”升级成了“靠配置文件技能包来约束”。这里面最关键的两个抓手就是 AGENTS.md 和 Skills。AGENTS.md 你可以理解成给 AI 看的“项目说明书”。以前我们写 CLAUDE.md、.cursorrules 这类文件是为了告诉 AI 这个项目的技术栈、代码规范、目录结构。AGENTS.md 把这个思路标准化了——它不绑定某一个工具而是一个通用的约定文件Codex 会优先读取它来理解“在这个仓库里我应该怎么做事”。Skills 则是更进一步把“做某类事情的标准流程”打包成可复用的模块比如“生成一张配图”“做一次 LaTeX 排版”“写一个前端组件”调用的时候直接触发对应技能而不是每次从零描述。这套组合拳解决的是什么问题说白了就是一致性。你带过一个新人就知道最头疼的不是他不会写代码而是他每次写代码的风格、目录习惯、提交信息格式都不一样。AI 也一样没有约束的 AI 每次输出都像开盲盒。AGENTS.md Skills 就是给 AI 立规矩、发手册让它像个靠谱的老员工一样干活。这篇文章适合谁看如果你是刚接触 Codex 的新手我会带你从安装配置一路走到能跑通第一个 Skill如果你已经在用 Codex 但总觉得“它不太听话”那 AGENTS.md 和 Skills 这两块内容应该能帮你省下大量反复调提示词的时间如果你是在团队里推广 AI 编码工具的负责人那这套约定机制正好可以拿来统一团队的 AI 使用规范。2. 核心机制拆解AGENTS.md 与 Skills 到底怎么配合2.1 AGENTS.md给 AI 立规矩的那份“员工手册”很多人第一次听说 AGENTS.md 会懵我已经有 README 了为什么还要单独写一个给 AI 看的文件这里面的逻辑差异挺大的。README 是写给人看的重点是“这个项目是干嘛的、怎么跑起来”。AGENTS.md 是写给AI看的重点是“在这个项目里干活时你必须遵守哪些规则”。我实测下来AGENTS.md 里最值得写的几类信息包括技术栈与版本约束比如“本项目使用 Python 3.11禁止使用 3.12 才有的语法特性”“前端统一用 React 18 TypeScript不要引入 Vue 相关依赖”。AI 默认会用它训练数据里最常见的写法你不约束它就可能给你整出一个和你项目格格不入的方案。目录与命名约定比如“所有组件放在 src/components 下文件名用 PascalCase”“测试文件统一放在tests目录命名规则为 xxx.test.ts”。这条能极大减少 AI 把文件放错位置的情况。代码风格硬性要求比如“禁止使用 any 类型”“函数必须写返回类型注解”“提交信息遵循 Conventional Commits”。这些规则写进去之后AI 生成的内容会明显更贴合团队规范。禁止事项这一条特别重要。比如“不要自动修改 package.json 里的依赖版本”“不要删除现有的测试用例”“不要在没有明确要求的情况下重构代码”。AI 有时候会“热心过头”把不该动的地方也动了明确禁止能避免很多麻烦。写 AGENTS.md 有个心得规则要具体、可验证不要写空话。你写“代码要优雅”AI 根本不知道什么叫优雅你写“单个函数不超过 50 行超过就拆分”AI 就能执行。我一般建议团队把 Code Review 里最常提的那几条意见直接搬进 AGENTS.md效果立竿见影。2.2 Skills把重复劳动打包成“一键技能”如果说 AGENTS.md 是规矩那 Skills 就是工具箱。它的核心思路是把一类任务的完整流程封装起来需要的时候直接调用不用每次重新描述需求。举个例子假设你经常需要给项目生成配图。没有 Skills 的时候你得每次跟 AI 说“帮我生成一张图片风格要扁平化主色调是蓝色尺寸 1200x630内容是关于 XXX 的……”说十次就有十种结果。有了 Skills 之后你只需要调用“图片生成”这个技能它内部已经定义好了风格、尺寸、输出格式你只需要提供内容主题就行。Skills 的典型结构一般包含这几部分组成部分作用举例技能名称唯一标识调用时用image-gen触发条件什么情况下启用这个技能用户提到“生成配图”“做封面”输入参数需要用户提供什么主题、尺寸、风格偏好执行步骤具体怎么做调用图像接口、保存文件、返回路径输出规范结果长什么样输出 PNG命名规则 cover-xxx.png我见过不少人把 Skills 想得太复杂觉得要写很多代码。其实最简单的 Skill 就是一个 Markdown 文件里面用自然语言描述清楚“这个技能是干嘛的、怎么用、注意什么”。Codex 读取之后就能理解并执行。当然复杂一点的 Skill 可以包含脚本、模板文件、配置参数那就更像一个小型工具包了。2.3 两者配合的化学反应单独用 AGENTS.mdAI 知道规矩但不知道具体怎么执行某类任务单独用 SkillsAI 会执行任务但可能不遵守项目规范。两者结合才是完整的工作流。举个我自己的实际场景我在一个前端项目里同时配置了 AGENTS.md 和一个“组件生成”Skill。AGENTS.md 里规定了“组件必须用函数式写法、必须写 PropTypes、样式用 CSS Modules”。Skill 里定义了“生成组件时需要创建三个文件index.tsx、styles.module.css、index.test.tsx”。当我让 Codex 生成一个按钮组件时它会自动按 Skill 的流程创建三个文件同时按 AGENTS.md 的要求写函数式组件和 PropTypes。整个过程不需要我反复叮嘱一次到位。这就是这套机制的价值把“人脑里的隐性知识”变成“AI 可读取的显性规则”。团队里老员工的那些经验以前只能靠口口相传现在可以沉淀成文件让 AI 和新人都能直接复用。3. 实操落地从零配置一套可用的 Codex 工作流3.1 安装与环境准备别在第一步就卡住Codex 的安装方式根据你用的平台不太一样。终端用户一般通过包管理器安装编辑器用户则是在插件市场里找对应扩展。我建议新手先从终端版本入手因为终端版本的反馈最直接出了问题也容易排查。安装过程中最常见的几个坑我提前说一下权限问题在部分系统上全局安装需要管理员权限但直接用管理员权限装又可能导致后续调用时路径混乱。我的做法是优先用用户级安装实在不行再考虑全局。版本冲突如果你之前装过旧版本升级时最好先卸载干净再装新的。我遇到过旧版本残留的配置文件导致新版本读取异常的情况排查了半天才发现是历史遗留问题。网络环境安装和首次登录时需要能正常访问服务端。如果卡在登录环节先检查基础网络连通性别急着怀疑是工具本身的问题。安装完成后第一件事是验证版本和登录状态。终端里跑一下版本查询命令确认输出的是你预期的版本号。然后走一遍登录流程确保认证信息正确写入本地配置。这一步看起来简单但我见过太多人跳过验证后面出问题了又回头怀疑是配置写错了白白浪费时间。3.2 AGENTS.md 的编写实战从模板到落地我一般建议从一个小模板开始跑通了再逐步加规则。下面是我常用的一个起步模板结构# AGENTS.md ## 项目概述 - 技术栈React 18 TypeScript Vite - 包管理器pnpm - 测试框架Vitest ## 代码规范 - 所有组件使用函数式写法禁止 class 组件 - 必须写 TypeScript 类型禁止 any - 样式统一用 CSS Modules禁止内联样式 - 函数不超过 50 行超过必须拆分 ## 目录约定 - 组件src/components/ComponentName/ - 工具函数src/utils/ - 类型定义src/types/ ## 禁止事项 - 不要修改 package.json 中的依赖版本 - 不要删除现有测试用例 - 不要在没有要求的情况下重构代码 ## 提交规范 - 遵循 Conventional Commits - 提交信息用中文描述这个模板不算长但覆盖了最关键的几类约束。写完之后你可以故意让 Codex 做一个任务观察它是否遵守了这些规则。比如让它生成一个组件看它有没有用函数式写法、有没有写类型、文件放的位置对不对。如果发现它没遵守大概率是规则写得不够明确或者规则之间有冲突。有个细节值得注意AGENTS.md 的优先级高于 AI 的默认习惯但低于你在对话里的明确指令。也就是说如果你在对话里说“这次就用 class 组件写”AI 会听你的暂时覆盖 AGENTS.md 的规则。这个设计挺合理的既保证了默认一致性又保留了灵活性。3.3 写一个自己的 Skill以“LaTeX 排版”为例Skills 的编写没有想象中那么难核心是把流程说清楚。我拿“LaTeX 排版”这个场景来演示因为它在学术圈和论文写作里需求很大而且流程相对固定。一个 LaTeX 排版 Skill 大概长这样# Skill: latex-format ## 触发条件 用户提到“LaTeX 排版”“论文格式化”“生成 tex 文件”时启用。 ## 输入 - 文档内容Markdown 或纯文本 - 目标格式论文/报告/简历 - 是否需要参考文献 ## 执行步骤 1. 分析输入内容的章节结构 2. 根据目标格式选择对应的模板 3. 将内容转换为 LaTeX 语法 4. 处理特殊字符转义如 % $ # _ 等 5. 如果需要参考文献生成 bib 文件并配置引用 6. 输出完整的 .tex 文件 ## 输出规范 - 文件命名主题-日期.tex - 编码UTF-8 - 必须包含文档类声明和必要的宏包 ## 注意事项 - 中文内容需要配置 ctex 宏包 - 数学公式用 $...$ 或 $$...$$ 包裹 - 表格和图片需要指定位置参数写 Skill 的关键心得步骤要可执行不要写“适当处理”这种模糊描述。什么叫适当处理AI 不知道。你要写“将 替换为 将 % 替换为 %”它才能准确执行。另外Skill 里可以引用 AGENTS.md 的规则比如“输出文件放在项目根目录的 output 文件夹下”这样两个机制就联动起来了。3.4 验证与调试怎么知道配置生效了配置写完不是终点验证才是。我通常用三个测试来检查第一个测试是规则遵守测试。故意让 Codex 做一个 AGENTS.md 里明确禁止的事情看它会不会拒绝或者提醒你。比如 AGENTS.md 里写了“不要修改依赖版本”你就让它“帮我升级一下 React 版本”看它是直接改了还是先问你。第二个测试是技能触发测试。用 Skill 里定义的触发词去调用看它有没有按预期流程执行。比如 LaTeX Skill 的触发词是“LaTeX 排版”你就说“帮我把这段内容做 LaTeX 排版”观察它是否按步骤走完了整个流程。第三个测试是边界情况测试。给一些不太标准的输入看 Skill 会不会崩。比如给一段包含大量特殊字符的内容看它有没有正确处理转义。这一步能暴露很多隐藏问题。如果测试没通过排查顺序一般是先看 AGENTS.md 和 Skill 文件有没有语法错误比如 Markdown 格式问题再看规则之间有没有冲突最后看是不是 AI 的理解有偏差。大部分问题出在前两步。4. 常见问题与排查技巧实录4.1 配置类问题速查问题现象可能原因排查方法Codex 不读取 AGENTS.md文件位置不对或命名错误确认文件在项目根目录名称大小写正确Skill 不触发触发条件写得不够明确检查触发词是否覆盖了你的实际说法规则冲突导致行为异常多条规则互相矛盾逐条检查 AGENTS.md确保规则一致输出格式不符合预期输出规范描述模糊把输出要求写具体附上示例登录状态失效认证信息过期重新走登录流程检查本地配置4.2 那些文档里不会写的坑第一个坑AGENTS.md 不是越长越好。我一开始恨不得把所有规范都写进去结果发现 AI 反而抓不住重点。后来精简到最核心的十几条执行效果明显提升。规则太多AI 的注意力会被分散反而容易漏掉关键约束。第二个坑Skill 的触发词要覆盖口语化表达。你写触发条件是“生成图片”但用户可能说“做个封面”“配张图”“来张插图”。触发词覆盖不全Skill 就经常不触发。我的做法是把常见的同义表达都列进去宁可多列几个。第三个坑不同工具的配置文件会打架。如果你同时用多个 AI 编码工具每个工具都有自己的配置文件比如 CLAUDE.md、.cursorrules、AGENTS.md它们之间可能互相干扰。我的建议是统一用 AGENTS.md 作为主配置其他文件用引用或软链接的方式指向它避免维护多份内容。第四个坑Skill 更新后需要重新加载。改完 Skill 文件不是立刻生效的Codex 需要重新读取配置。我一般改完会重启一下会话确保新配置被加载。这个细节很小但不知道的话会以为改动没生效。4.3 性能与稳定性优化建议如果你发现 Codex 响应变慢或者行为不稳定可以从这几个方向排查上下文过长AGENTS.md 和 Skill 文件都会占用上下文窗口。如果文件太大留给实际任务的空间就少了。建议把不常用的 Skill 归档只在需要时加载。规则过于复杂条件判断太多的规则会让 AI 花更多时间“思考”。能简化的逻辑尽量简化。网络波动部分操作需要联网网络不稳定时会出现超时或中断。遇到这种情况先检查基础网络再重试。缓存问题有时候清理一下本地缓存能解决一些莫名其妙的问题。具体清理方法参考官方文档的缓存管理部分。5. 进阶玩法把 Codex 变成团队的基础设施5.1 团队协作中的 AGENTS.md 管理当团队里多个人都在用 Codex 时AGENTS.md 的管理就变成一个协作问题。我的经验是把 AGENTS.md 纳入版本控制和代码一起 Review。每次有人想加规则走正常的 PR 流程大家讨论后再合并。这样能避免规则随意膨胀也能保证规则的质量。另外可以按目录层级放多个 AGENTS.md。比如根目录放全局规则前端目录放前端专属规则后端目录放后端专属规则。Codex 会逐层读取就近的规则优先级更高。这个机制特别适合 monorepo 项目。5.2 Skill 的沉淀与复用Skill 最大的价值在于可复用。我建议团队建一个内部的 Skill 仓库把常用的技能都放进去新人入职直接拉下来就能用。常见的团队级 Skill 包括代码审查 Skill、提交信息生成 Skill、文档生成 Skill、测试用例生成 Skill。Skill 的版本管理也很重要。技能不是写完就一劳永逸的随着项目演进需要不断更新。我一般会给每个 Skill 标注版本号和更新日期方便追踪。5.3 与现有工具链的集成思路Codex 不是孤立存在的它可以和现有的工具链结合。比如和 CI 集成在 CI 流程里调用 Codex 做代码审查把 AGENTS.md 的规则作为审查标准。和编辑器集成在编辑器里配置 Codex 插件让 AGENTS.md 和 Skills 在编码时实时生效。和项目管理工具集成让 Codex 读取任务描述自动生成对应的代码框架。这些集成的核心思路都是一样的把 Codex 当成一个遵守规则的执行者而不是一个需要反复调教的聊天对象。规则越清晰集成越顺畅。5.4 关于新模型适配的观察社区里最近讨论比较多的新一代模型能力我实际体验下来的感受是模型本身的能力提升是一方面但真正决定输出质量的还是你给的约束和上下文。同一个模型有 AGENTS.md 约束和没有约束输出质量差距非常明显。所以与其追着新模型跑不如先把 AGENTS.md 和 Skills 这套机制用熟。模型会迭代但“把规则写清楚”这个方法论是长期有效的。我在实际使用中的一个体会是配置文件的维护成本远低于反复调提示词的成本。花一个小时写好 AGENTS.md后面几个月都能省下大量重复沟通的时间。这笔账怎么算都划算。