企业官网建设流程全解析

1. 从“焚决”说起：Codex 这次到底更新了什么

“焚决”这个词最近在开发者圈子里传得很凶，第一次看到的时候我还以为是哪个玄幻小说的功法名，后来才反应过来，这是社区对 Codex 一次重大能力升级的戏称——意思是“烧掉旧规则、重写新玩法”的那份决断。作为一个从早期就在用 Codex 做日常开发的人，我第一时间把这次更新里最核心的几块东西摸了一遍：AGENTS.md 的上下文约定、Skills 技能体系、以及围绕 GPT-6 Astra 这一代模型能力的适配。这篇文章不打算复述官方文档，而是把我自己踩过的坑、验证过的配置、以及那些文档里不会写的细节，一次性摊开讲清楚。

先说结论，方便你对号入座：如果你只是偶尔用 Codex 补全几行代码，这次更新对你影响不大；但如果你把 Codex 当成一个能独立跑任务、能读整个仓库、能按团队规范干活的“工程搭子”，那 AGENTS.md 和 Skills 这两样东西你必须搞明白，否则你会发现同样的模型，别人用起来像开了挂，你用起来还是那个只会写 for 循环的实习生。这篇文章适合三类人：刚接触 Codex 想系统上手的新手、已经在用但总觉得“差口气”的中级用户、以及想给团队搭建统一 AI 工作流的技术负责人。全文我会按“设计思路—核心细节—实操落地—问题排查”的顺序展开，每一块都尽量给到可以直接抄的配置和命令。

需要提前说明的是，下面涉及的具体参数、目录结构、配置片段，一部分来自我自己的实测，一部分是基于这类工具常见设计逻辑的合理推断。凡是推断的部分我都会明确标注，你照着做之前最好在自己的环境里验证一遍，别直接上生产。

2. 整体设计思路：为什么是 AGENTS.md + Skills 这套组合

2.1 从“提示词工程”到“上下文工程”的转向

早两年大家玩 AI 编程，核心动作是“写提示词”——把需求描述得越细越好，恨不得把整个需求文档塞进对话框。但用久了就会发现一个致命问题：提示词是一次性的，而项目是长期的。你今天跟模型解释了一遍“我们这个项目用 pnpm 不用 npm、组件必须走 design system、提交信息遵循 conventional commits”，明天开个新会话，它全忘了，你还得再讲一遍。这种重复劳动在个人项目里还能忍，在团队协作里就是灾难。

AGENTS.md 这个设计的本质，就是把“每次都要重复的上下文”从对话里抽出来，固化成一个仓库级别的约定文件。你可以把它理解成给 AI 看的 README——README 是给人看的，告诉人类这个项目怎么跑；AGENTS.md 是给 agent 看的，告诉它在这个仓库里应该遵守什么规则、用哪些工具、避开哪些坑。这个转向很关键：它把 AI 协作从“会话级”提升到了“仓库级”，一次配置，长期生效。

我实测下来最直观的感受是，配好 AGENTS.md 之后，模型犯“低级错误”的概率明显下降。以前它动不动就用 npm 命令，明明项目是 pnpm；以前它总把测试文件放到 src 目录下，明明约定是 tests 目录。这些不是模型笨，是你没告诉它。AGENTS.md 就是那个“告诉它”的地方。

2.2 Skills 解决的是“能力复用”问题

如果说 AGENTS.md 解决的是“规则”问题，那 Skills 解决的就是“能力”问题。这两者经常被混为一谈，其实定位完全不同。

举个生活化的例子：AGENTS.md 像是你给新员工发的《员工手册》，里面写着公司几点上班、报销流程怎么走、代码提交规范是什么；而 Skills 像是《岗位操作手册》，里面写着“做 PPT 的标准化流程”“处理客户投诉的五个步骤”“部署上线的检查清单”。前者是通用规则，后者是具体技能。

Skills 的核心价值在于把一套可复用的操作流程封装起来，让模型在需要的时候自动调用。比如你经常要做 LaTeX 排版，那就可以写一个 latex-formatting skill，里面定义好模板、编译命令、常见错误处理；下次你说“帮我把这份内容排成论文格式”，模型就知道去调用这个 skill，而不是从零开始瞎猜。社区里现在流传的 skills 已经覆盖了前端开发、图片生成、AI 漫剧、建模比赛等各个场景，本质上都是把“某类任务的专家经验”沉淀成了可调用的模块。

2.3 为什么这次更新值得单独拿出来讲

把 AGENTS.md 和 Skills 放在一起看，你会发现 Codex 这代产品的野心：它不再满足于做一个“更聪明的代码补全”，而是想成为一个“能理解项目、能执行任务、能积累经验”的工程 agent。GPT-6 Astra 这一代模型在长上下文和指令遵循上的提升，正好给了这套体系落地的技术基础——上下文够长，才能塞得下 AGENTS.md 和多个 skill 的定义；指令遵循够准，才能保证模型真的按你写的规则干活，而不是自由发挥。

所以这次“焚决”烧掉的，其实是过去那种“把 AI 当搜索引擎用”的旧习惯。新玩法是：你把项目规则写进 AGENTS.md，把常用能力封装成 Skills，然后让 Codex 在这个框架里自主干活。下面我就把这两块拆开，讲清楚具体怎么落地。

3. AGENTS.md 核心细节：写什么、怎么写、写在哪

3.1 AGENTS.md 的定位与加载逻辑

先说一个很多人搞混的点：AGENTS.md 和 CLAUDE.md 是什么关系？简单讲，它们都是“给 AI 看的项目约定文件”，只是面向的工具不同。CLAUDE.md 是 Claude Code 体系里的约定，AGENTS.md 是更通用的 agent 约定。现在不少项目会同时维护两份，或者用软链接指向同一个文件，避免重复维护。如果你团队里同时用多种 AI 编程工具，我的建议是以 AGENTS.md 为主，其他文件做软链或同步，这样规则只有一份源头，改起来不容易漏。

加载逻辑上，这类文件通常遵循“就近原则”：模型会从你当前工作的目录开始，逐级向上查找 AGENTS.md，把找到的内容合并进上下文。这意味着你可以在仓库根目录放一份全局规则，在某个子模块目录再放一份局部规则，模型进入那个子模块时会自动叠加局部规则。这个设计非常实用——比如 monorepo 里，根目录的 AGENTS.md 写通用规范，前端子目录的 AGENTS.md 写“组件必须用函数式写法”，后端子目录的写“所有接口必须加参数校验”，各管各的，互不干扰。

注意：不同工具对 AGENTS.md 的查找深度和合并策略可能不一样，有的只读最近一层，有的会全部叠加。上线前务必用一个小测试验证一下你所用版本的加载行为，别想当然。

3.2 一份能打的 AGENTS.md 应该包含哪些内容

我见过太多人把 AGENTS.md 写成“项目介绍”，洋洋洒洒几千字讲业务背景，结果模型该犯的错还是犯。问题出在：AGENTS.md 不是给人看的项目文档，是给模型看的操作指令。它应该短、准、可执行。我自己的模板通常包含这几块：

• 技术栈声明：用什么语言、什么包管理器、什么框架版本。比如“本项目使用 pnpm，禁止使用 npm 或 yarn”“React 18 + TypeScript 5，禁止使用 any”。
• 目录约定：源码放哪、测试放哪、文档放哪。模型对目录结构很敏感，写清楚能省很多事。
• 命令清单：安装依赖、启动开发、跑测试、构建、lint 的具体命令。这是最高频被调用的部分，一定要准确。
• 代码规范：命名风格、注释要求、提交信息格式。比如“提交信息遵循 conventional commits”“所有导出函数必须有 JSDoc”。
• 禁区清单：明确禁止的操作。比如“禁止直接修改 generated 目录下的文件”“禁止在测试里调用真实网络请求”。

这里有个经验：禁区清单比正面清单更重要。模型天生倾向于“多做”，你不告诉它什么不能碰，它就可能去改一些不该改的文件。我踩过最惨的一次坑，是模型自作主张重构了一个核心工具函数，结果把依赖它的十几个模块全搞挂了。从那以后，我的 AGENTS.md 里必有一条“未经明确指示，禁止重构现有函数签名”。

3.3 一个可直接抄的 AGENTS.md 模板

下面这份是我在中小型 TypeScript 项目里常用的模板，你可以按需删改：

# AGENTS.md ## 技术栈 - 语言：TypeScript 5.x，严格模式 - 包管理：pnpm（禁止 npm / yarn） - 框架：React 18 + Vite - 测试：Vitest ## 常用命令 - 安装依赖：pnpm install - 启动开发：pnpm dev - 跑测试：pnpm test - 构建：pnpm build - 代码检查：pnpm lint ## 目录约定 - 源码：src/ - 测试：tests/（与 src 结构镜像） - 组件：src/components/ - 工具函数：src/utils/ ## 代码规范 - 禁止使用 any，必要时用 unknown + 类型守卫 - 所有导出函数必须有 JSDoc 注释 - 提交信息遵循 conventional commits ## 禁区 - 禁止修改 src/generated/ 下的任何文件 - 禁止在测试中发起真实网络请求 - 未经明确指示，禁止重构现有函数签名

这份模板不长，但覆盖了模型最容易出错的几个点。你可以先照抄，跑一段时间后根据实际踩的坑往里加规则。AGENTS.md 是活的，不是写完就完事，每次模型犯了新错误，你就想“这条规则能不能写进去防止下次再犯”，慢慢就养出一份贴合自己项目的约定。

4. Skills 体系拆解：从安装到自研的完整路径

4.1 Skills 到底是什么，和普通提示词有何区别

很多人第一次听说 Skills，会以为就是“存起来的提示词”。不完全是。提示词是你临时敲进对话框的一段话，用完就没了；Skill 是一个有结构、有元信息、可被模型主动检索和调用的能力包。它通常包含三部分：描述（这个 skill 是干什么的、什么时候该用）、指令（具体怎么做的步骤）、以及可选的资源（模板文件、脚本、参考文档）。

区别在哪？我举个例子。你写一段提示词“帮我把这段内容排成 LaTeX 论文格式”，模型每次都要重新理解“论文格式”是什么样，可能这次用 article 类，下次用 report 类，格式不统一。但如果你有一个 latex-paper skill，里面明确定义了文档类、宏包、章节结构、参考文献格式，那模型每次调用都会产出一致的结果。Skill 的价值在于“标准化”和“可复用”，它把一次性的经验变成了可重复调用的资产。

社区里现在有大量现成的 skills 可以白嫖，覆盖前端开发、图片生成、AI 漫剧、建模比赛等场景。但我的建议是：先别急着装一堆，先想清楚你高频重复的任务是什么。装十个用不上的 skill，不如自己写一个天天用的。

4.2 安装现成 Skills 的几种方式

安装 skill 的方式取决于你用的工具和 skill 的来源。常见的有这么几种：

第一种是从社区仓库手动安装。很多 skill 以 GitHub 仓库的形式发布，你把它 clone 下来，放到工具约定的 skills 目录里就行。这个目录的位置各工具不同，有的在用户主目录下的隐藏文件夹，有的在项目根目录。具体路径建议查你所用工具的文档，别照搬别人的。

第二种是通过包管理器安装。部分工具支持用类似npx或内置命令的方式一键装 skill，这种方式最省事，但要注意版本兼容——有些 skill 是为特定模型版本写的，装到旧版本上可能不生效。

第三种是从 skill 市场或聚合站点获取。现在已经有专门收集 skills 的网站，按场景分类，你可以按需下载。用这类来源时要注意两点：一是看更新时间，太老的 skill 可能已经不适配新版本；二是看依赖，有些 skill 依赖特定的外部工具或 API，装之前先确认你环境里有。

提示：装完 skill 后，务必用一个简单任务测试它是否被正确加载和调用。我遇到过装完没生效、结果排查半天发现是目录放错的情况，白白浪费时间。

4.3 自己写一个 Skill：以 LaTeX 排版为例

现成 skill 再好，也总有覆盖不到你特定需求的时候。这时候自己写一个，其实没想象中难。我拿“LaTeX 排版”这个场景走一遍完整流程，你可以照着套到自己的场景里。

第一步，明确触发条件。想清楚什么情况下该用这个 skill。比如“当用户要求把内容排成学术论文格式时”。这个描述要写进 skill 的元信息里，模型靠它来判断何时调用。

第二步，拆解操作步骤。把你自己做这件事的流程写下来：确定文档类（article/report）、加载必要宏包（amsmath、graphicx、hyperref）、设置页面边距、组织章节结构、处理参考文献、编译命令。每一步都写清楚，别嫌啰嗦，模型需要的就是明确指令。

第三步，准备资源文件。把常用的模板、示例、编译脚本放进 skill 目录。比如一个template.tex作为起点，一个build.sh封装编译命令。这样模型调用时直接基于模板改，不用从零生成。

第四步，写清楚输出要求。比如“输出完整的 .tex 文件，不要省略任何宏包声明”“编译命令用 xelatex 而非 pdflatex，因为需要中文支持”。这些细节决定了产出能不能直接用。

一个最小可用的 skill 目录大概长这样：

latex-paper/ SKILL.md # 描述 + 指令 template.tex # 模板文件 build.sh # 编译脚本

SKILL.md 里写清楚“这个 skill 做什么、什么时候用、怎么做、输出什么”。写完自己跑几个测试用例，看看模型是不是按你预期的方式调用了。自研 skill 的迭代逻辑和 AGENTS.md 一样：用一次，发现一个问题，补一条指令，几轮下来就顺手了。

5. 实操落地：从零搭一套 Codex 工作流

5.1 环境准备与安装要点

先把基础环境搭起来。Codex 的安装方式根据你用的形态不同而有差异——有桌面版、有编辑器插件、也有命令行形态。Windows 用户如果装桌面版，注意安装路径别带中文和空格，这是很多工具的通病，带了容易出各种莫名其妙的错。

安装完成后第一件事是登录。登录环节最常见的两个问题是“打不开登录页”和“auth token is unavailable”。前者通常是网络环境或代理配置的问题，检查一下你的网络是否能正常访问所需服务；后者多半是凭证过期或缓存损坏，清一下本地凭证缓存重新登录一般能解决。如果反复失败，可以试试换一种登录方式（比如从浏览器登录换成设备码登录）。

装好之后，建议先跑一个最小任务验证环境：让它读一个文件、改一行代码、跑一次测试。这一步的目的是确认“模型能正常读写你的工作目录”，这是后面所有高级玩法的基础。如果这一步就不通，先别急着配 AGENTS.md 和 Skills，把基础打通再说。

5.2 把 AGENTS.md 接进工作流

环境通了之后，第一件事是在项目根目录创建 AGENTS.md。别一上来就写一大堆，先用我上面给的模板跑起来，然后在实际使用中逐步补充。

我的做法是：开一个新会话，让模型做一个典型任务，比如“给 utils 目录下的 date.ts 加一个格式化函数”。观察它的行为——它用了什么命令？把文件放哪了？命名风格对不对？每发现一个不符合预期的点，就往 AGENTS.md 里加一条规则。这样迭代三五轮，你的 AGENTS.md 就会变得非常贴合实际需求。

这里有个技巧：把 AGENTS.md 当成“错误日志的沉淀”。每次模型犯错，不要只是当场纠正，而是想“这个错误能不能通过规则预防”。能，就写进去。这样你的配置会越来越厚，但模型的出错率会越来越低。这比一次性写一份完美的 AGENTS.md 要现实得多，因为没人能预判所有坑。

5.3 配置 Skills 并验证调用

AGENTS.md 跑顺之后，开始接 Skills。先装一两个你最高频使用的，别贪多。装完做一次验证：给模型一个明确需要该 skill 的任务，看它是否主动调用。如果没调用，检查两件事——skill 的触发描述是否够清晰、skill 目录位置是否正确。

我实测下来，skill 不被调用的最常见原因是描述太模糊。比如你写“用于处理文档”，模型根本不知道什么时候该用；改成“当用户要求将内容转换为 PDF 格式的学术论文时使用”，命中率立刻上来了。所以写 skill 描述时，要站在模型的角度想：它在什么情境下会“想起”这个 skill？把那个情境描述清楚。

验证通过后，就可以在日常任务里放心用了。用一段时间后你会发现，有些 skill 用着用着就不顺手了——可能是需求变了，可能是发现更好的做法。这时候别将就，直接改 skill 内容，或者干脆重写一个。Skills 是为你服务的，不是反过来。

5.4 多工具协同：Codex 与其他工具的配合

现实工作中，你不太可能只用一种 AI 编程工具。可能 Codex 用来跑长任务，另一个工具用来做快速补全，还有的用来做代码审查。这时候 AGENTS.md 的“单一源头”优势就体现出来了——你维护一份规则，通过软链或同步让多个工具都能读到，避免规则不一致导致的混乱。

如果你同时用 Codex 和 Claude Code，可以维护一份 AGENTS.md，然后让 CLAUDE.md 软链指向它。这样改一处，两边都生效。同理，如果你用多个编辑器，也尽量让它们读同一份配置。规则的一致性比规则本身更重要，模型在不同工具里表现不一致，很多时候就是配置不同步导致的。

6. 常见问题与排查技巧实录

6.1 高频问题速查表

下面这张表是我和身边朋友实际遇到过的问题汇总，按现象、可能原因、解决方向整理，方便你快速定位：

6.2 几个文档里不会写的避坑经验

第一个坑：别让 AGENTS.md 无限膨胀。规则越多，模型遵循的负担越重，有时候反而会顾此失彼。我的经验是控制在合理长度内，把最高频、最致命的规则放前面，次要的往后放。如果一份 AGENTS.md 超过几百行，考虑拆分成根目录 + 子目录的多层结构。

第二个坑：Skill 之间会打架。如果你装了两个功能重叠的 skill，模型可能不知道该调哪个，结果两个都不用，或者用错。装之前先看看有没有功能重复的，有就留一个最好的，别贪多。

第三个坑：模型会“过度自信”。有时候它明明不确定，也会一本正经地给你一个错误答案。这时候 AGENTS.md 里可以加一条“遇到不确定的情况，先提问而不是猜测”。这条规则帮我避免了好几次“模型自作主张改错代码”的事故。

第四个坑：版本升级后配置可能失效。工具更新后，AGENTS.md 的加载逻辑、skill 的格式要求都可能变。每次升级后，花十分钟跑一遍验证任务，确认配置还生效。别等到出了大问题才发现。

6.3 关于 GPT-6 Astra 适配的几点观察

GPT-6 Astra 这一代模型在长上下文和指令遵循上的提升，是这套 AGENTS.md + Skills 体系能真正跑起来的前提。我实测下来的感受是：同样的配置，在新模型上遵循度明显更高。以前模型可能读了三遍规则还是我行我素，现在基本能做到“说一次就记住”。

但这也带来一个新问题：模型变“听话”了，你写的规则如果本身有问题，它也会忠实地执行错误指令。所以配置的准确性变得更重要了。以前模型会“自作聪明”地纠正你的小错误，现在它可能老老实实按你写的错规则走。这提醒我们，写 AGENTS.md 和 Skills 时要更严谨，别把错误经验固化进去。

另外，新模型对 skill 的调用判断也更准了。以前经常出现“该调用时不调用、不该调用时乱调用”的情况，现在命中率高了不少。这意味着你可以放心地把更多能力封装成 skill，让模型自主调度，而不用每次都手动指定。

7. 我个人的一点使用体会

折腾这套东西大半年，最大的感受是：AI 编程工具的上限，取决于你给它搭的框架。同样的模型，有人用起来像开了挂，有人用起来还是那个只会写样板代码的助手，差距不在模型本身，在于你有没有把项目规则和常用能力沉淀下来。

AGENTS.md 和 Skills 这套组合，本质上是在做一件事：把你的隐性经验显性化。你脑子里那些“这个项目该这么干、那个任务该那么做”的经验，以前只能靠每次对话重复传达，现在可以固化下来，让模型自动遵循。这个过程一开始有点麻烦，但一旦跑顺，回报是持续的。

如果你刚开始接触，我的建议是别追求一步到位。先把 AGENTS.md 建起来，跑几个任务，补几条规则；再挑一个最高频的场景写个 skill，用起来；然后慢慢扩展。这套东西是长出来的，不是设计出来的。等你用顺手了，回头看会发现，真正省下的时间不是模型帮你写的那几行代码，而是你不再需要反复解释“我们项目是这样的”。