企业官网建设流程全解析

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，避免两套约定打架。

3. 实操全流程：从安装到跑通第一个 Skills

3.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 安装和使用一个现成的 Skill

Skills 的安装方式取决于来源。如果是本地目录，直接放到 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 启动和登录类问题

这类问题最常见，我整理了一个速查表：

我踩过最深的一个坑是"打不开"——折腾了一下午，最后发现是安装路径里有个中文文件夹名。这种问题官方文档一般不写，但实际很常见，所以第一条就列出来。

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 后续还会带来什么变化，等实际用出体感了再聊。