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 skillAI 检测到相关需求就自动加载一步到位。社区里已经有人分享了大量现成 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请求库用 AxiosUI 组件库用 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 安装并使用第一个 SkillSkills 的安装方式取决于你用的具体 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 做几个小任务验证一下。配置这东西不验证等于没配。我见过太多人配完就直接上大任务结果出问题回头排查反而更费时间。花五分钟做冒烟测试能省你半小时的排查。
