1. 从“焚决”说起：Codex 这次到底更新了什么
“焚决”这个词最近在开发者圈子里传得挺凶，乍一听像是玄幻小说里的功法秘籍，实际上它是社区对 Codex 一次重大能力升级的戏称——意思是这套组合拳打出来，能把之前积累的很多工作流“烧掉重来”。我第一时间跟进折腾了几天，从安装配置到 Skills 体系、AGENTS.md 上下文管理、再到和 Claude Code 的横向对比，踩了不少坑，也摸清了一些门道。这篇文章就把我这几天的实操记录完整摊开，给正在观望或者刚上手的朋友一个可直接抄作业的参考。
先把话说清楚：Codex 是 OpenAI 推出的编程智能体工具，支持命令行、IDE 插件和桌面端多种形态，核心能力是让 AI 直接在你的项目里读写文件、执行命令、跑测试、改代码。而这次所谓“焚决”的核心，其实是围绕AGENTS.md 上下文规范、Skills 技能体系、以及新模型接入这三件事展开的一整套工程化玩法。它解决的核心问题是：以前用 AI 写代码，你得反复贴上下文、反复解释项目结构、反复纠正它的习惯；现在通过 AGENTS.md 和 Skills，你可以把这些“隐性知识”固化下来，让 AI 每次进来就自动懂规矩、会干活。
适合谁看？如果你是前端、后端、算法、建模比赛选手，或者任何每天要跟代码打交道的人，这套东西能实打实省时间。哪怕你之前只用过网页版的对话式 AI 写代码，看完也能顺利迁移到智能体工作流。下面我按“整体设计思路 → 核心细节 → 实操过程 → 问题排查”的顺序展开，中间会穿插大量我自己的配置片段和踩坑记录。
2. 整体设计思路：为什么是 AGENTS.md + Skills 这套组合
2.1 从“每次重新解释”到“一次配置永久生效”
用过早期 AI 编程工具的人都懂那种痛苦：你打开一个新会话，AI 对你的项目一无所知，你得告诉它“这是 React 项目、用 pnpm 不用 npm、组件放 src/components、样式用 tailwind、测试用 vitest”。下次换个会话，同样的废话再说一遍。项目越大，这段“开场白”越长，长到你自己都懒得写，于是 AI 就开始瞎猜，猜错了你再纠正，来回拉扯。
AGENTS.md 这个文件就是来解决这件事的。它本质上是一个放在项目根目录的 Markdown 文件，里面写清楚项目的技术栈、目录结构、编码规范、常用命令、禁忌事项。Codex 在启动时会自动读取这个文件，把它作为系统级上下文注入。你可以把它理解成“给 AI 看的 README”——README 是给人看的，讲的是这个项目是什么；AGENTS.md 是给 AI 看的，讲的是你该怎么在这个项目里干活。
我实测下来，一个写得好的 AGENTS.md 能让 AI 首次生成代码的可用率从大概三成提升到七成以上。这个提升不是玄学，而是因为 AI 不再需要猜测你的意图和项目约定，它拿到的是一份明确的“作业要求”。
2.2 Skills 体系：把重复性任务封装成可复用技能
如果说 AGENTS.md 解决的是“懂项目”，那 Skills 解决的就是“会干活”。Skills 是一套技能封装机制，你可以把某个特定任务的操作流程、提示词、脚本、模板打包成一个 skill，之后 AI 遇到类似任务就能直接调用。
举个例子，我经常需要把一段 LaTeX 公式排版成规范格式。以前每次都要跟 AI 描述“用 amsmath 宏包、对齐用 align 环境、编号规则是这样”，现在我把这套流程写成一个 latex-format skill，AI 检测到相关需求就自动加载，一步到位。社区里已经有人分享了大量现成 skills，覆盖前端开发、数据处理、文档生成、建模比赛等场景，也有专门的 skills 市场可以淘。
这套设计的精妙之处在于分层：AGENTS.md 管全局约定，Skills 管具体任务，两者互不干扰又能叠加。全局的东西不重复写，任务的东西按需加载，上下文窗口的利用率一下就上去了。
2.3 为什么这次要强调“焚决”
我理解“焚决”这个说法，核心在于这次更新让旧的工作流需要重构。以前你可能靠一堆零散的提示词模板、靠手动贴上下文、靠记忆去纠正 AI，现在这套体系要求你把这些东西沉淀成文件。短期看是多了配置成本，长期看是质的飞跃。就像从“每次手写 SQL”到“用 ORM”，前期要学，后期真香。
另外这次还涉及新模型的接入讨论，社区里提到的 GPT-6 Astra 之类的说法，我个人的态度是：模型能力是变量，但 AGENTS.md 和 Skills 这套工程化方法是相对稳定的资产。模型换了，你的配置文件不用重写，这才是值得投入的地方。
3. 核心细节解析：AGENTS.md 到底该怎么写
3.1 文件位置与加载优先级
AGENTS.md 的加载遵循就近原则。我实测的规则大致是：项目根目录的 AGENTS.md 是基础，子目录里如果也有 AGENTS.md，进入该目录操作时会叠加子目录的配置。这个设计很合理，因为大项目里不同模块的规范可能不一样，比如前端目录要求用函数式组件，后端目录要求用特定的错误处理模式。
注意：文件名必须精确是
AGENTS.md，大小写敏感。我见过有人写成agents.md或者Agents.MD，结果死活不生效，排查半天。
除了项目级的，还有用户级的全局配置，一般放在用户主目录下，用来定义跨项目的个人偏好，比如“我总是用中文注释”“我偏好简洁的代码风格”。全局配置和项目配置冲突时，项目配置优先。
3.2 内容结构：五个必写模块
我摸索出一套比较通用的 AGENTS.md 结构，分五个模块，你可以直接拿去改：
第一块是项目概览。一两句话说明这个项目是干什么的，技术栈是什么。别写太长，AI 不需要读你的产品文档，它只需要知道“这是个 Next.js 14 的博客系统，用 App Router”。
第二块是目录结构。把关键目录列出来，说明每个目录放什么。比如src/app放路由页面、src/components放通用组件、src/lib放工具函数。这样 AI 新建文件时就知道该往哪放，不会乱丢。
第三块是编码规范。这是重头戏。包括命名约定（组件用 PascalCase、工具函数用 camelCase）、导入顺序、错误处理方式、注释语言。我一般还会写明“禁止使用 any 类型”“异步操作必须处理错误”这类硬性要求。
第四块是常用命令。开发、构建、测试、格式化的命令都列出来。AI 需要跑测试验证自己的改动时，会直接调用这些命令，写清楚了它就不会瞎试。
第五块是禁忌事项。明确告诉 AI 什么不能做，比如“不要修改 package.json 的依赖版本”“不要删除现有的测试文件”“不要动 .env 文件”。这一块能帮你避免很多意外。
3.3 一个真实可用的 AGENTS.md 示例
下面是我给一个前端项目写的 AGENTS.md，脱敏后分享出来：
# 项目概览 这是一个基于 React 18 + Vite + TypeScript 的管理后台。 状态管理用 Zustand，请求库用 Axios，UI 组件库用 Ant Design。 # 目录结构 - src/pages：页面组件，每个页面一个文件夹 - src/components：通用组件，按功能分子目录 - src/hooks：自定义 hooks - src/api：接口定义，按模块分文件 - src/utils：工具函数 # 编码规范 - 组件用函数式写法，禁止 class 组件 - 组件文件用 PascalCase，工具文件用 camelCase - 导入顺序：React 相关 → 第三方库 → 项目内部 → 样式 - 所有异步操作必须 try/catch，错误用 message.error 提示 - 注释用中文，复杂逻辑必须写注释 - 禁止使用 any，类型不明确时用 unknown 再收窄 # 常用命令 - 开发：pnpm dev - 构建：pnpm build - 测试：pnpm test - 格式化：pnpm lint:fix # 禁忌事项 - 不要修改 package.json 中的依赖版本 - 不要删除 src/api 下已有的接口定义 - 不要直接操作 localStorage，统一走 src/utils/storage.ts这份文件大概两百字，但信息密度很高。我实测下来，AI 拿到这份配置后，生成的代码基本能直接跑，改动的范围也很克制，不会到处乱动。
3.4 Skills 的封装逻辑与目录约定
Skills 的封装比 AGENTS.md 稍微复杂一点。一个 skill 通常是一个文件夹，里面至少有一个描述文件（说明这个 skill 是干什么的、什么时候触发）和具体的执行内容（可能是提示词模板、脚本、参考文档）。
我理解它的触发机制是这样的：AI 在处理任务时，会先扫描可用的 skills 列表，看当前任务和哪个 skill 的描述匹配，匹配上了就加载该 skill 的详细内容。所以 skill 的描述写得准不准，直接决定它能不能被正确触发。
提示：skill 的描述要写得“像任务本身”，而不是“像功能说明”。比如写“当用户要求把公式排版成 LaTeX 格式时使用”，比写“LaTeX 排版工具”更容易被触发。
社区里常见的 skills 源包括各种技能库网站和开源仓库，你可以直接下载别人的 skill 来用，也可以自己写。我建议新手先从现成的开始，用熟了再自己封装。
4. 实操过程：从零到跑通一条完整工作流
4.1 安装与环境准备
Codex 的安装方式有几种，我按平台分别说。命令行版本一般通过包管理器安装，Windows 用户可以用 winget 或者直接下安装包，macOS 和 Linux 用户用对应的包管理器。桌面版的话官网有下载入口，登录后就能用。
安装完成后第一件事是认证。命令行版本通常需要配置 API 密钥或者走登录流程。我遇到过codex auth token is unavailable这个报错，排查下来一般是两个原因：一是密钥没配对环境变量，二是登录态过期了。解决办法就是重新走一遍登录，或者检查环境变量名有没有写错。
注意：环境变量名大小写敏感，而且不同版本可能不一样，装完先看官方文档确认当前版本用哪个变量名。
Windows 桌面版安装时有个坑，就是路径里如果有中文或者空格，可能导致启动失败。我建议装到纯英文路径下，比如C:\tools\codex，省得后面折腾。
4.2 配置 AGENTS.md 并验证生效
装好之后，在项目根目录创建 AGENTS.md，把上面那套结构填进去。然后启动 Codex，随便让它做个小任务，比如“在 src/utils 下新建一个 formatDate.ts，实现日期格式化”。
验证生效的方法很简单：看它新建的文件放对位置没有、命名符合规范没有、有没有用你指定的错误处理方式。如果都对，说明 AGENTS.md 被正确读取了。如果它还是乱放文件，那就要检查文件名拼写、文件位置、以及是不是被更高优先级的配置覆盖了。
我一般会做一个“冒烟测试”：故意在 AGENTS.md 里写一条很显眼的规则，比如“所有新建文件头部加一行注释 // generated by codex”，然后让 AI 建个文件，看这行注释在不在。在就说明配置生效，不在就说明没读到。
4.3 安装并使用第一个 Skill
Skills 的安装方式取决于你用的具体 skill。有些是直接放到指定目录，有些是通过命令安装。以社区常见的做法为例，一般是在项目里建一个.codex/skills目录，把下载的 skill 文件夹放进去，重启 Codex 就能识别。
我拿一个“前端组件生成”的 skill 做演示。安装后，我让 Codex“生成一个用户列表组件，带分页和搜索”。它会自动加载这个 skill，按照 skill 里定义的模板生成组件，包括 props 定义、样式、以及配套的测试文件。整个过程我几乎没干预，生成完直接能跑。
这里有个经验：skill 不是越多越好。装太多会导致 AI 在触发时犹豫，甚至触发错误的 skill。我建议按项目需要装，一个项目控制在五到十个以内，定期清理不用的。
4.4 接入不同模型的配置方法
社区里讨论比较多的是 Codex 接入不同模型的问题。配置方式一般是在配置文件里指定模型名称和对应的接口地址。我实测下来，不同模型在代码生成上的风格差异挺明显的：有的偏保守，改动范围小；有的偏激进，喜欢重构。
注意：切换模型后，建议重新跑一遍冒烟测试，因为不同模型对 AGENTS.md 的遵循程度可能不一样。我遇到过某个模型对“禁止使用 any”这条规则执行得不严格，换回默认模型就正常了。
配置文件的位置一般在用户主目录下的隐藏文件夹里，具体路径看官方文档。改完配置记得重启，不然不生效。
4.5 和 Claude Code 的横向对比
既然热词里提到了 Claude Code，我也说说我的使用感受。两者在理念上很像，都支持项目级上下文文件和技能封装。差异主要在细节：Codex 的 AGENTS.md 生态目前更活跃，社区分享的模板多；Claude Code 的 CLAUDE.md 在长上下文处理上有自己的优势。
我的建议是不要纠结选哪个，两个都装，按任务类型切换。简单的重构和生成用 Codex，需要深度理解大段代码的用 Claude Code。工具是拿来用的，不是拿来站队的。
5. 常见问题与排查技巧实录
5.1 高频报错速查表
我把这几天遇到的报错整理成一张表，方便你对照排查：
| 报错信息 | 可能原因 | 解决办法 |
|---|---|---|
| codex auth token is unavailable | 密钥未配置或登录过期 | 重新登录或检查环境变量 |
| model is not supported | 模型名写错或该模型未开放 | 核对官方支持的模型列表 |
| cc switch local proxy failed | 本地代理配置冲突 | 检查代理设置，关闭冲突项 |
| codex 打不开 | 安装路径含中文或权限不足 | 换纯英文路径，用管理员权限 |
| skill 不触发 | 描述不匹配或目录放错 | 检查 skill 描述和存放位置 |
5.2 三个我踩过的坑
第一个坑是 AGENTS.md 写太长。我一开始恨不得把整个项目文档都塞进去，结果 AI 反而抓不住重点，生成质量下降。后来我精简到两百字左右，只留最关键的约定，效果立刻好转。上下文窗口是有限资源，别浪费在废话上。
第二个坑是 skill 之间互相干扰。我装了三个都涉及“代码生成”的 skill，结果 AI 每次触发都要在它们之间选，选错的概率不低。后来我合并成一个综合 skill，问题解决。同类 skill 只留一个，这是铁律。
第三个坑是忽略版本差异。Codex 更新挺频繁的，不同版本的配置格式、命令、甚至文件位置都可能变。我有次照着半年前的教程配，怎么都不生效，后来发现新版改了配置路径。养成看官方更新日志的习惯，能省很多时间。
5.3 性能与上下文优化技巧
如果你觉得 Codex 响应慢或者生成质量不稳定，可以试试这几个优化：
- 把 AGENTS.md 控制在合理长度，核心约定优先
- 定期清理不用的 skills，减少触发时的选择负担
- 大项目拆分多个 AGENTS.md，按目录就近配置
- 避免在单次会话里塞太多不相关的任务，一个会话专注一件事
我实测下来，做好这几点，响应速度和生成质量都有明显改善。尤其是最后一条，很多人喜欢在一个会话里从早干到晚，上下文越堆越乱，AI 的表现自然越来越差。该开新会话就开新会话。
5.4 建模比赛场景的特别说明
热词里提到“华为杯建模比赛好用的 codex skills”，我虽然没参加过这个具体比赛，但建模类任务的共性我了解。这类任务通常涉及数据处理、算法实现、图表生成、论文排版几个环节，每个环节都可以封装成 skill。
我的建议是：数据处理 skill 里写清楚数据格式约定和清洗规则；算法 skill 里指定常用的库和实现风格；图表 skill 里固定配色和尺寸规范；排版 skill 里定义 LaTeX 模板。这样比赛时你只需要描述问题，剩下的交给 skill 自动处理，能省下大量时间。
6. 我个人的使用体会与后续扩展方向
折腾这几天，我最大的感受是：AI 编程工具的门槛正在从“会不会写提示词”转向“会不会做工程化配置”。提示词是临时的，配置是持久的。你把 AGENTS.md 和 Skills 这套东西搭好，相当于给 AI 建了一套“入职培训手册”，之后不管换什么模型、接什么任务，它都能快速上手。
后续我打算继续深挖两个方向：一是把更多重复性工作封装成 skill，比如周报生成、代码审查、文档同步；二是研究多项目之间的配置复用，看看能不能做一套跨项目的通用配置模板。这两个方向如果跑通，效率还能再上一个台阶。
最后分享一个小技巧：每次配置完，别急着干正事，先让 AI 做几个小任务验证一下。配置这东西，不验证等于没配。我见过太多人配完就直接上大任务，结果出问题回头排查，反而更费时间。花五分钟做冒烟测试，能省你半小时的排查。
