你的 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 又变“聪明”了。其实它一直都很聪明，只是被你手上那把过期的钥匙锁住了门窗而已。
你的 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 又变“聪明”了。其实它一直都很聪明，只是被你手上那把过期的钥匙锁住了门窗而已。