1. 从“焚决”说起这套东西到底在解决什么问题“焚决”这个词最近在圈子里传得很凶乍一听像是某种玄学功法其实它指的是围绕 Codex 这套 AI 编程代理工具把AGENTS.md、Skills、模型接入这几块拼起来的一整套高效工作流。我最早接触 Codex 的时候也是被各种配置、模型名、代理报错折腾得够呛后来慢慢摸清了门道才发现真正拉开效率差距的不是模型本身有多强而是你有没有把“上下文约定”和“技能库”这两件事做扎实。先把话说在前头这篇内容适合两类人。一类是刚装上 Codex、还在纠结codex auth token is unavailable或者cc switch local proxy failed while handling codex endpoint /responses这类报错的新手另一类是用了一段时间但总觉得 AI 输出“差点意思”、想通过 AGENTS.md 和 Skills 把输出质量拉上一个台阶的老手。我会从整体设计思路讲到具体配置再到踩过的坑尽量让你看完就能动手。核心关键词先摆出来Codex、AGENTS.md、Skills、CLAUDE.md、GPT-6 Astra。这几个词基本构成了当前 AI 编程代理工作流的主干。Codex 是执行主体AGENTS.md 和 CLAUDE.md 是给代理看的“项目说明书”Skills 是可复用的能力模块而 GPT-6 Astra 这类新模型则是驱动这一切的引擎。理解它们之间的关系比死记某个命令重要得多。我个人的判断是未来一年会不会写 AGENTS.md、会不会挑 Skills会像当年会不会写.gitignore一样成为区分“能用”和“用得好”的分水岭。所以这篇东西我尽量往深了写。2. 整体设计思路为什么是 AGENTS.md 加 Skills 这套组合2.1 代理类工具的通病上下文一多就“失忆”任何用过 AI 编程代理的人都有体会你让它改一个函数它改得挺好你让它同时改五个文件、还要遵守团队的命名规范它就开始胡来。根本原因在于代理每次对话能“看到”的上下文是有限的而项目里的隐性规则——比如“所有 API 请求必须走统一的 request 封装”“组件文件名用大驼峰”——这些它根本不知道。传统做法是每次对话都手动贴一遍规则累且容易漏。AGENTS.md 的出现就是为了解决这个把项目级的约定、目录结构、常用命令、禁忌事项写成一个文件放在仓库根目录代理每次启动自动读取。这就像给新来的同事发一份《项目上手须知》而不是每次口头交代。2.2 AGENTS.md 和 CLAUDE.md 的分工很多人搞不清这俩的区别。简单说AGENTS.md 是通用约定CLAUDE.md 是给特定代理的补充说明。在实际项目里我通常这样分工AGENTS.md 写所有代理都该遵守的东西技术栈、目录规范、构建命令、测试命令、代码风格。CLAUDE.md 写针对性的偏好比如“回答用中文”“改动前先列计划”“不要自动执行数据库迁移”。这样设计的好处是换代理工具时AGENTS.md 可以原样复用只需要调整 CLAUDE.md。我见过有人把两者写成一模一样的内容纯属浪费维护起来还容易不同步。2.3 Skills 的本质把“一次性提示词”变成“可复用能力”Skills 这个概念刚出来的时候我也没太在意觉得不就是提示词模板吗。用了一段时间才明白它的价值在于结构化和可发现性。一个 Skill 通常包含名称、描述、触发条件、具体指令、可选的示例。当代理判断当前任务匹配某个 Skill 的描述时会自动加载它的指令。举个例子你有一个“LaTeX 排版”的 Skill里面写清楚了公式怎么写、参考文献怎么排、图表标题放哪。以后你只要说“帮我把这段内容排成论文格式”代理就会自动调用这个 Skill而不是每次都要你重新描述一遍排版要求。这就是从“每次重新教”到“一次教好、反复用”的转变。2.4 模型层GPT-6 Astra 这类新引擎意味着什么模型是底层引擎Skills 和 AGENTS.md 是方向盘和说明书。GPT-6 Astra 这类新模型带来的最大变化我观察下来有两点一是长上下文下的指令遵循更稳以前写了一大段 AGENTS.md模型读到后面就忘了前面现在明显改善二是工具调用的判断更准什么时候该读文件、什么时候该跑命令误判少了。但要注意模型再强你给它喂的上下文是垃圾输出也是垃圾。这就是为什么我一直强调 AGENTS.md 和 Skills 的写法比模型选型更重要。下面进入具体细节。3. 核心细节解析AGENTS.md 与 Skills 怎么写才有效3.1 AGENTS.md 的结构模板与写作要点我试过很多种写法最后沉淀下来一个相对稳定的结构你可以直接抄# 项目说明 ## 技术栈 - 前端React 18 TypeScript Vite - 后端Node.js Express - 包管理pnpm ## 目录结构 - src/components通用组件 - src/pages页面级组件 - src/utils工具函数 ## 常用命令 - 安装依赖pnpm install - 启动开发pnpm dev - 运行测试pnpm test - 构建pnpm build ## 代码规范 - 组件文件名用大驼峰如 UserCard.tsx - 工具函数用小驼峰如 formatDate.ts - 所有网络请求必须走 src/utils/request.ts ## 禁忌 - 不要修改 package.json 里的依赖版本 - 不要自动执行数据库迁移命令 - 提交前必须跑通测试写这个文件有几个要点。第一命令要写全别只写pnpm test要写清楚在哪个目录执行。第二禁忌要具体写“不要乱改代码”没用要写“不要修改 X 文件里的 Y 配置”。第三保持更新项目结构变了就改否则代理会按过时的规则干活。提示AGENTS.md 不要写太长控制在 100 行以内。太长了模型反而抓不住重点把最关键的规则放前面。3.2 Skills 的编写从“能用”到“好用”一个 Skill 写得好不好看三点描述是否精准、指令是否可执行、边界是否清晰。我拿一个“前端组件生成”的 Skill 举例--- name: 前端组件生成 description: 当需要创建新的 React 组件时使用自动生成符合项目规范的组件文件 --- ## 指令 1. 组件文件放在 src/components 下文件名用大驼峰 2. 使用函数式组件 TypeScript 3. Props 必须定义 interface命名为组件名 Props 4. 样式优先使用 CSS Modules文件名与组件同名 5. 导出使用默认导出 ## 示例 输入创建一个用户卡片组件 输出生成 UserCard.tsx 和 UserCard.module.css这里的关键是description字段。代理就是靠这个判断“当前任务要不要用这个 Skill”。所以描述要写清楚什么时候用而不是“这个 Skill 是干嘛的”。我见过有人写“description: 一个组件生成工具”这种描述代理根本判断不出来该不该调用。3.3 模型接入与常见报错的处理思路热词里有一堆报错比如codex auth token is unavailable、cc switch local proxy failed while handling codex endpoint /responses。这些我基本都踩过。说几个通用的排查思路认证类报错先检查 token 是否过期再看环境变量有没有正确注入。很多时候是复制粘贴时多了空格。代理转发类报错检查本地代理服务的端口是否被占用配置文件里的 endpoint 路径是否写对。/responses这个路径对不上是高频问题。模型不支持类报错比如提示某个模型名不支持通常是模型名拼写错误或者当前接入方式不支持该模型。这时候要么换模型名要么换接入方式。排查这类问题的通用方法是先看日志再简化配置。把配置砍到最小可运行状态再一点点加回来比对着报错瞎猜快得多。3.4 关于“接入 DeepSeek”这类需求的说明热词里有“codex 接入 deepseek”这属于模型接入的范畴。思路是Codex 支持配置不同的模型端点你只要把端点地址、模型名、认证信息配对就能切换底层模型。但要注意不同模型对指令的遵循程度不一样你为 GPT-6 Astra 写的 AGENTS.md换到别的模型上可能需要调整措辞。我的建议是换模型后先跑几个典型任务观察输出是否符合预期再决定要不要微调上下文文件。4. 实操过程从零搭一套可用的工作流4.1 环境准备与安装安装这块Windows 桌面版和命令行版我都用过。命令行版更灵活桌面版对新手友好。安装完成后第一件事是验证codex --version能输出版本号说明装好了。然后配置认证信息这一步最容易出问题。我的经验是认证信息不要写在代码里用环境变量或者独立的配置文件避免误提交。4.2 初始化 AGENTS.md在项目根目录创建 AGENTS.md按 3.1 的模板填。填完后启动一次代理随便问一个和项目相关的问题看它有没有正确引用文件里的规则。比如你问“这个项目的测试命令是什么”它应该能答出pnpm test。如果答不出来说明文件没被读到检查文件名和位置。4.3 安装和配置 SkillsSkills 的安装方式取决于你用的工具。常见做法是把 Skill 文件放在指定目录比如.codex/skills/或类似路径。安装后用skills 列表之类的命令确认能被识别。然后做一次触发测试给一个明确匹配某个 Skill 描述的任务看代理有没有调用它。我踩过的一个坑是Skill 的description写得太宽泛导致代理在不该调用的时候也调用。比如一个“代码审查”的 Skill描述写成“用于代码相关任务”结果代理连写新代码时都去调它。后来改成“当需要对已有代码进行质量检查时使用”就正常了。4.4 完整工作流演示假设我要在一个 React 项目里新增一个“订单列表”页面。流程是这样的启动代理它自动读取 AGENTS.md知道项目用 React TypeScript组件放 src/components。我说“帮我创建一个订单列表页面”。代理判断这匹配“前端组件生成”Skill加载其指令。代理按 Skill 要求生成 OrderList.tsx 和 OrderList.module.css放在正确目录。代理按 AGENTS.md 要求用 request.ts 封装数据请求。生成完成后代理提示我跑测试。整个过程我只需要说一句话剩下的规则都由文件承载。这就是这套工作流的价值。4.5 参数与配置的选择依据配置里有几个参数值得说。比如上下文窗口大小设太小了 AGENTS.md 读不全设太大了浪费资源。我的经验是按 AGENTS.md 加 Skills 总长度的 1.5 倍来设留出余量给对话内容。再比如超时时间网络请求类的任务设长一点纯代码生成设短一点。这些参数没有标准答案取决于你的项目规模和网络环境。我的建议是先用默认值跑遇到问题再调别一上来就追求“最优配置”。5. 常见问题与排查技巧实录5.1 高频报错速查表报错信息可能原因排查方向auth token is unavailabletoken 未配置或过期检查环境变量、重新登录local proxy failed代理端口占用或路径错误检查端口、核对 endpointmodel is not supported模型名错误或接入方式不支持核对模型名、换接入方式代理不读 AGENTS.md文件名或位置错误确认根目录、文件名大小写Skill 不触发description 不精准改写描述明确使用场景5.2 独家避坑技巧第一个坑AGENTS.md 里的命令要写绝对路径或明确目录。我遇到过代理在错误目录执行命令导致报错。后来所有命令都加上cd xxx 前缀问题消失。第二个坑Skills 不要贪多。我一开始装了二十多个 Skill结果代理判断触发时经常选错。后来精简到常用的五六个准确率明显提升。Skill 不在多在于每个都精准。第三个坑换模型后一定要重新测试。不同模型对同一段 AGENTS.md 的理解可能不同。我换到新模型后发现它对“不要自动执行迁移”这条理解成了“不要执行任何命令”导致该跑的命令也不跑了。调整措辞后才正常。第四个坑版本更新后检查配置兼容性。工具更新有时会改配置格式旧配置可能失效。我习惯在更新后先跑一个最小任务验证。5.3 关于“Skills 市场”和“常用 Skills 源”的看法现在有一些 Skills 分享站点可以下载别人写好的 Skill。我的态度是可以参考但不要直接拿来用。因为每个项目的规范不一样别人的 Skill 里可能写死了他们的目录结构。正确做法是下载后按自己项目改一遍重点是学习别人怎么组织指令和描述。5.4 学习 Skills 开发的路径建议如果你想自己写 Skill我的建议是从“重复三次以上的任务”入手。任何你反复交代代理做的事情都值得写成一个 Skill。先写最简单的版本用起来再根据实际效果迭代。别一上来就追求大而全的 Skill那种往往用不起来。6. 影响范围与后续扩展方向6.1 这套工作流适合哪些场景从我的实践看这套东西在几类场景下收益最明显多人协作的项目统一规范、长期维护的项目规则沉淀、重复性高的任务Skill 复用。反过来如果是一次性的小脚本写 AGENTS.md 的投入产出比就不高。6.2 团队协作中的落地建议在团队里推这套东西最大的阻力不是技术是习惯。我的做法是先自己用起来把效果做出来再在代码评审时展示“用了 AGENTS.md 后代理输出质量的变化”。用事实说话比开会宣讲管用。另外AGENTS.md 应该纳入版本控制和代码一起评审这样规则才不会腐化。6.3 后续可以怎么扩展一个方向是把 Skills 和 CI 流程结合比如提交前自动跑一个“代码规范检查”的 Skill。另一个方向是给不同角色写不同的 AGENTS.md比如前端和后端各一份代理根据任务类型加载。这些我还在摸索有进展再分享。我个人在实际操作中的体会是这套工作流的核心不是工具本身而是你有没有把项目里的隐性知识显性化。AGENTS.md 和 Skills 只是载体真正值钱的是你对项目的理解。把理解写下来代理才能帮你干活。最后分享一个小技巧每次代理输出不符合预期时别急着改提示词先想想是不是 AGENTS.md 里少写了一条规则。大多数时候问题出在规则缺失而不是模型不行。