你的 Codex 最近是不是变“笨”了明明模型还是同一个代码却越写越别扭甚至开始一本正经地执行一些早就被废弃的命令。我前段时间就踩了这个坑折腾了两天最后发现罪魁祸首不是模型本身而是我自己当初精心准备的 Skill 和 AGENTS.md——这些配置文件一旦过期杀伤力远比你想的大。这篇就来聊聊它们是怎么一步步“毁掉”Codex 的以及怎么排查、清理和重建一套靠谱的配置体系适合所有重度使用 AI 编程代理的开发者参考。1. 为什么过时的 Skill 和 AGENTS.md 会“毁掉”Codex1.1 先搞明白 Skill 和 AGENTS.md 到底是什么先说清楚这两个东西。AGENTS.md 是放在项目根目录或子目录里的指令文件本质上是给 AI 编程代理看的一份“项目说明书”。它告诉 Codex 这个项目用什么语言、跑什么命令、代码结构长什么样、有哪些不该碰的坑。你可以把它理解成新人入职时拿到的那本岗位手册——只不过读者不是人是 AI 代理。Skill 的概念类似但更抽象一些它通常是存放在 Codex 配置目录下的一个技能包比如某个文件夹里带一份 SKILL.md里面描述了一套专门的工作流程或领域知识。当对话场景跟某个技能匹配Codex 就会把这份技能描述注入上下文让它按照这套方法来处理问题。听起来很合理对吧问题恰恰出在“合理”这两个字上。只要项目在演进、依赖在升级、目录结构在调整这些配置文件就会慢慢失真。一旦失真它们就不再是助理而是干扰源。我见过最典型的情况一个项目从构建工具 A 迁到了构建工具 B但 AGENTS.md 里还写着工具 A 的启动命令。于是每次让 Codex 启动服务它都会毫不犹豫地尝试并不存在的命令然后对着报错发愣。你以为它变蠢了其实它就只是严格遵循了一个已经过时的规矩。这种时候你不去怪那本“过期的岗位手册”反而怪“新员工”不行这明显是冤枉了它。1.2 过时配置如何悄悄拉低 Codex 的实际表现过时配置的影响不是一步到位的而是一层层往上堆。第一个影响是上下文污染。Codex 的上下文窗口是有上限的不管多大终归是有限资源。你塞进去一堆早就不成立的描述、失效路径、废弃约定真正有用的信息就被挤掉了。就好比你让一个人读一本 200 页的说明书其中 150 页都描述的是旧版本系统他自然没精力记住那 50 页真正要紧的内容。第二个影响是指令冲突。项目里可能同时存在多份 AGENTS.md根目录一份、子模块一份彼此之间的规则还互相踩脚。旧配置说“必须使用某旧库”新代码里已经完全没有这个库。Codex 发现两边对不上最典型的结果就是反复纠结、生成一堆没用的中间步骤或者干脆干脆按照旧规则硬来。配置越多矛盾越多它的决策成本就越高。第三个影响是错误示范被放大。Codex 会把 AGENTS.md 和 Skill 里的内容当作“最高可信度输入”。一旦里面写了已经废弃的 API 用法它在生成代码时就会默认这是权威做法。于是你看到的不是你想要的现代写法而是夹杂着一堆历史语法、老掉牙的依赖名和过期的目录路径。最麻烦的是以上几种情况会形成恶性循环。Codex 依据错误配置生成代码你因为代码不对来回纠正纠正的内容被模型理解后又可能被解释成“项目更进一步的变化”于是下一次生成时它更倾向保留错误的骨架。所以你越努力调教它它表现越“顽固”直到你把配置本身清理干净循环才会终止。2. 动手排查怎么找出正在干扰你的元凶2.1 先从项目里的 AGENTS.md 开刀排查的第一站永远是 AGENTS.md因为它离代码最近影响也最直接。不要只盯着根目录看子目录里的 AGENTS.md 同样不容忽略。我在实际排查时习惯先跑一个命令把所有相关文件找出来find . -name AGENTS.md -type f拿到完整清单后我建议你别急着读内容先看三个信息文件最后修改时间、该目录对应的代码模块是否发生了重大变更、文件里引用的命令和路径目前是否真实存在。随后我会做一次对照实验。挑一个你最常用的任务指令比如“帮我跑测试”或“把服务启动起来”在保留 AGENTS.md 的情况下让 Codex 执行一次并记录结果然后临时把这份文件改名备份再执行一次相同指令。两次结果对比往往立竿见影。我遇到过一份 AGENTS.md 里写的是老旧的构建步骤Codex 连续三次都在尝试一个已经不存在的脚本路径。我把文件移走之后它一秒钟就识别出了真实入口问题瞬间消失。还有一种容易被忽略的情况多个 AGENTS.md 之间存在嵌套覆盖逻辑。不同工具的加载策略不太一样但普遍规律是子目录文件会补充或调整上级文件的部分规则。如果你的子模块文件写的是“本目录使用旧的导出格式”而根目录文件写的是“全项目统一使用新导出格式”这种上下级冲突很难直接发现。排查时建议按目录层级逐个看把每份文件的“约束类句子”单独摘出来对比看有没有互相打架。2.2 Skill 目录里的“僵尸技能”Skill 的排查比 AGENTS.md 更隐蔽因为它的生效逻辑不是简单的“读取文件”而是按场景匹配。Codex 也许只在少数任务里重点考虑技能内容但它一旦命中影响范围就非常大。我先说一个高频翻车点技能目录里堆了一堆“僵尸技能”。这些技能曾经在某个阶段很管用但后来对应的工作流完全变了只有技能文件没被更新。举例来说你之前给 Codex 配过一个“旧版数据处理流程”技能里面写的字段名、依赖库甚至编码规范都已经是历史残留。等某次对话涉及到类似文本时Codex 一看到语义沾边就把这份技能注入了上下文结果整段回答都在围着几个不存在的参数打转。怎么判断哪些技能是僵尸我的经验是做一次“负载测试”把所有技能名列出来随机让 Codex 处理 10 个不同类型的日常任务看哪些技能的名字被主动匹配。如果连续 5 个任务下来某个技能一次都没被引用只有两种可能——要么你的任务范围确实和它无关要么它在当前项目里已经没有任何存在意义。另外也要检查技能内容里的命令是否还跑得通。很多技能会把一个完整流程写进 SKILL.md包括一连串 shell 命令。轻则 404重则整个流程彻底失效。你可以把技能里的命令提取出来逐个验证一遍。凡是提示“command not found”或“已废弃”的要么替换成新命令要么直接把技能标记为弃用。我自己的习惯是给技能文件加一个简单的“体检表”在文件末尾记录最近一次验证日期和验证结果。这样至少能知道这份技能上次确认可用是什么时候。时间越久优先级越低被清理的可能性自然就更高。3. 清理与重建一套可落地的配置整理方案3.1 断舍离删除、归档、合并三原则找到问题文件之后接下来的动作不能太粗暴。不能因为一份 AGENTS.md 过时了就直接删掉很多时候里面还有几条目前仍然有效的规则只是被大量过期内容淹没了。我的处理顺序是“三步走”先分区再归类最后动手。先看文件里的内容能否拆成独立的几段再把仍然有效的片段保留下来最后决定整个文件的去留。具体有三条原则可参考删除内容跟当前项目完全无关或者已有新文件完全覆盖了它的职责。删之前先备份别做裸奔操作。归档内容本身还有价值但当前项目用不上。我的做法是挪到一个专用于历史存档的目录比如archive/AGENTS.md.2024.md不放回 Codex 会扫描的默认路径里。合并两份或多份文件的内容高度重叠尤其常见于不同子模块维护了各自版本的通用规范时。这种就直接合并成一份顶层 AGENTS.md子目录里只保留与自身逻辑强相关的规则减少重复和歧义。实际操作的时候我一般会先把所有候选文件复制到一个临时目录用 diff 对比相邻版本之间的差异量。差异越大说明项目变化越剧烈对应的配置文件越需要重写。差异小的可能只是补几句话就能继续用没必要整个推翻。3.2 重写一份高信噪比的 AGENTS.md重写 AGENTS.md 时最忌讳的就是“总结过往”。它应该是一份展望当前和未来的真相文件而不是项目历史博物馆。写之前你先梳理几个核心问题项目里最常执行哪 5 个命令有没有绝对不能动的目录或工具Codex 上次出错的方向是什么这些问题的答案才是配置文件的骨架。我写 AGENTS.md 时习惯按这套模板走项目身份用一两句话说明这是什么东西避免 Codex 把上下文理解偏。常用命令明确列出测试、启动、构建、格式化的真实命令。这几个是出现频率最高的也是最容易误导 AI 的。架构地图用简短列表指出核心目录和它们各自负责什么让 Codex 在拆解问题时少走弯路。绝对禁区写清楚哪些操作不要做比如“不要直接修改生成文件”“不要使用旧版配置接口”。决策记录如果某些代码风格或技术选型是有意为之简明记录原因帮助 Codex 理解你的意图而不是盲目照搬外部常见写法。一个关键技巧是控制篇幅。我不建议把 AGENTS.md 写成超过一百行的长文因为 Codex 不擅长在大量文本中精确提取核心规则。它更需要的是短、清晰、可执行的内容。你宁愿让它只记住三条最关键的命令也别让它淹没在十条花哨但互相矛盾的建议里。下面是我偏好的一个片段示例# 项目某跨平台系统 ## 常用命令 - 安装依赖: pnpm install - 单元测试: nx run test - 启动开发服务: npm run dev - 构建产物: npm run build ## 目录说明 - packages/core/ 核心业务逻辑不要在其中引入平台相关库 - packages/web/ 浏览器端实现 - packages/desktop/ 桌面端实现 ## 注意 - 不修改 scripts/generated/ 下的任何文件 - 生成代码统一使用 Result 风格返回值 - 遇到依赖版本冲突时先查看 docs/dependency.md 再决定方案这样一份文件信息密度极高每一条都是可执行的规则Codex 读起来不累执行起来也不容易跑偏。3.3 给 Skill 建立版本意识与更新规范Skill 的问题往往是“写了一次再也没管过”。因为它在配置目录里安安静静躺着平时不太会被注意到。我建议给每个 SKILL.md 加一个头部队列至少包含版本号、更新日期、适用范围和作者。举个例子--- name: legacy-data-migration version: 3.1.0 updated: 2025-06-12 scope: 老数据迁移场景 deprecated: false ---有了这个头部你在目录里扫一眼就能快速判断哪些技能该被清理。版本号的意义尤其大如果你每更新一次技能就升一次版本那么当 Codex 表现异常时你可以快速定位到“上一次更新后是否引入了新的问题”而不是对着无版本的文件干瞪眼。更新 Skill 内容后我强烈建议立刻做一轮验证对话。比如你修改了迁移技能的命令就用一个最小数据集真正跑一遍流程确认每一步都能复现。别以为改个描述很简单——你改的是给 AI 看的行为准则不改测试就发布等同于改完权限配置不重新登录验证早晚会出事。另外Skill 描述里最好主动写上“禁止执行”的条目。比如旧的迁移流程里有一些已废弃的中间步骤直接在 SKILL.md 里写「不要执行步骤 X因为schema已经由新模块自动完成」。这比单纯删掉描述更安全因为 Codex 有时会依据外部知识“脑补”出一些已废弃的流程节点你明确写清禁区反而能堵住这类自动发挥。4. 维护机制让配置库保持健康4.1 让配置变更也遵循变更评审流程很多团队在代码变更上大谈 Code Review却把 AGENTS.md 和 Skill 当成写一次就永不变化的东西。这不合理。配置文件直接影响 AI 代理的行为引发的问题往往隐蔽且滞后比普通代码 bug 更难排查。所以我把它们纳入跟代码一样的评审流程。实际操作很简单把 AGENTS.md 和技能文件的修改作为常规 commit 提上分支跟代码改动一起走评审。评审清单可以固定为四项——是否跟当前项目结构一致、是否每个命令都可执行、是否有重复或互相矛盾的规则、是否引入了会误导 Codex 的背景性描述。我见过一次评审救回一个项目的情况。某次迭代准备加一条“所有异步任务必须用某项队列库”评审时发现这条规则被同时写进了根目录 AGENTS.md 和某个子模块文件里且两者描述的触发条件不一致。如果没被拦下来Codex 在不同场景下就会产生两套行为。评审最大的价值不在于找错字而是挡掉这种跨文件的隐性冲突。4.2 建立定期配置体检节奏再好的文件也会随时间失去意义。项目重构、依赖升级、人员流动都会让配置内容逐渐失真。我建议把“配置体检”变成一种固定节奏而不是出了问题才去查。我自己设定的是每两周用半天时间做一次“配置健康扫描”每次就干三件事跑一遍所有 AGENTS.md 里列出的命令确认没有失效项核对 Skill 目录里每个技能的最后验证日期超过一个月的标记为待审查用一次小型探索性任务实测配置效果观察 Codex 是否还会被隐藏旧规则约束。当然不是所有人都能保证每两周抽出半天。如果你工作节奏很快至少也要做到“项目变更关键节点后必须体检”比如切换构建工具、升级框架版本、或者重构过核心目录结构的那个迭代。这种节点是最容易让配置瞬间过时的。长线来看配置维护更像对待技术债你可以先欠着但利息会越滚越大。早日把配置体检写进例行流程看起来多花了一点时间实际省掉的排查时间远超过投入。5. 常见问题与避坑实录5.1 常见症状与快速排查速查表这段时间我积攒了不少实际踩坑记录整理成一张速查表按症状查原因再找对策效率会高很多症状可能原因快速处置Codex 重复执行已经废弃的命令AGENTS.md 里残留旧启动/构建命令注释掉可疑规则后实测确认后删除或替换指令优先级混乱新写规则不生效多层级 AGENTS.md 之间规则冲突按目录层级核对文件统一合并到根目录技能完全不触发或频繁误触发Skill 名称描述不清晰或范围过宽重写 SKILL.md 名称与适用范围缩小匹配边界生成代码风格明显“老气”Skill 中记录了历史依赖和旧版 API对照当前依赖清单重写技能内的示例代码同一规则在对话中被反复重复根目录与子目录内容互相覆盖删除重复条目让每条规则只出现在一处更新配置之后反而更混乱删除过猛有效规则被一并清除用备份文件 diff找回被误删的规则片段这张表我不能保证覆盖所有场景但它至少帮你提供了一个排查方向。如果你也遇到了某种诡异行为先别急着换模型翻翻配置文件大概率能发现问题。5.2 几个反直觉的实战经验最后分享几条听起来不太合常理、但实际非常适用的经验。第一条是“写得越多越糟”。我以前总觉得 AGENTS.md 写得越详细越好后来发现完全不是。Codex 面对 200 行规则时明显不如面对 30 行时准确。太长的文件容易让它在执行时“逐条理解”最后可能为了迎合某一条边缘规则而把主任务带偏。现在的我写 AGENTS.md 的态度是能删则删每留下一条就一定要有足够的理由。第二条是“同一个规则不要重复两遍”。很多人喜欢在根目录写一遍规则又在子模块里写一遍强调。这种做法在人的世界里是加强记忆在 Codex 的世界里就是制造歧义。一旦两处措辞稍有出入它就面临“到底听哪个”的问题。我的原则是每条规则只出现一次位置放在最贴近作用范围的那一层。第三条是“从零重建往往比重写更有效”。如果你发现某份 AGENTS.md 已经连续修补了五次每次都是往上叠补丁那最理性的决定不是继续修订而是删掉重写。因为通过叠加产生的文件往往保留了大量已经失效的隐性假设直接推倒重来反而能逼你重新梳理真实规则。我上次处理一份纠结了两周的旧文件时就是直接备份后重拟效果出乎意料地好。第四条更有点反直觉不是所有更新都需要写进配置。有些项目约定只是暂时的比如某个目录只是因为当前迭代临时存在下个月就会重构。这种信息写进 AGENTS.md 只会增加未来的维护负担。配置要沉淀的永远是“跨时间稳定的规则”而不是临时的状态快照。一点个人体会我在实际整理这些配置时最大的感受是AI 编程代理的表现瓶颈很多时候并不在模型本身而在我们喂给它的“规则环境”是否干净。你给 Codex 一份过时的 SKILL.md它就会认真执行一个已经没有任何意义的流程你留一份互相矛盾的 AGENTS.md它就会在每次决策时都平白多绕一段路。别总抱怨 AI 变笨了先回头看看那些你自己亲手写的配置文件还跟不跟得上项目变化。定期体检、敢于删除、重写高信噪比的规则文件这套习惯做下来你会明显感觉到 Codex 又变“聪明”了。其实它一直都很聪明只是被你手上那把过期的钥匙锁住了门窗而已。