1. 一个被忽视的真相你的智能编码助手可能正在被历史资产拖垮如果你正在使用 Codex 这类智能编码助手并且已经用了一段时间大概率会遇到这样一种情况刚开始用的时候它给出的建议精准、简洁、直击要害但随着你不断往项目里添加 Skill 文件、不断丰富 AGENTS.md 的内容它的表现反而越来越差——回答变得啰嗦、建议开始跑偏、甚至在你明确指定了技术栈的情况下给出完全不相关的方案。很多人第一反应是模型退化了或者是不是换了底层模型但实际情况往往恰恰相反问题出在你自己积累的那些 Skill 和 AGENTS.md 上。你为提升效果而不断叠加的配置正在变成拖累它的负担。这个现象在圈子里已经有不少人讨论过但大多数讨论停留在感觉变差了的层面很少有人系统性地拆解过为什么曾经有效的 Skill 会变成负资产AGENTS.md 到底应该写多少什么内容该放进去、什么内容必须拿出去这篇文章就围绕这几个核心问题结合我自己的实操踩坑经历把这件事讲透。无论你是刚接触 Codex 的新手还是已经积累了几十个 Skill 文件的老用户下面这些内容都值得对照检查一遍。因为这个问题不解决你后面所有的调优努力都可能是在往错误的方向使劲。2. 先搞清楚 Codex 是怎么读你的项目的2.1 Skill 和 AGENTS.md 在上下文里到底占什么位置要理解为什么 Skill 和 AGENTS.md 会毁掉Codex 的表现必须先搞清楚一个底层机制上下文窗口是有限的而且不是所有位置的信息权重都一样。Codex 这类工具在响应你的请求时会按照一定的优先级把信息拼装进上下文。通常的顺序大致是系统级指令工具内置的你改不了AGENTS.md 或类似的项目级配置文件被激活的 Skill 文件内容当前对话历史你本次的具体请求这个顺序意味着一个关键事实AGENTS.md 和 Skill 的内容会占据上下文的前部位置而前部位置对模型输出的影响权重非常高。换句话说你写在 AGENTS.md 里的每一句话都在以一种高优先级的方式影响模型的判断。很多人没有意识到这一点把 AGENTS.md 当成了一个项目说明文档来写——项目背景、技术栈、目录结构、编码规范、部署流程、注意事项恨不得把整个 wiki 都塞进去。结果就是模型在还没看到你具体问题之前已经被一大堆背景信息洗脑了。2.2 为什么信息越多越好在这里是错的日常使用搜索引擎或者知识库时我们习惯性地认为信息越多越全面越好。但 Codex 的工作机制完全不同。它不是在检索信息而是在理解信息然后生成代码。当你往上下文里塞入大量信息时会发生几件事第一注意力被稀释。模型需要在所有输入信息之间分配注意力权重。你塞进去的内容越多每条信息分到的权重就越低。原本一条使用 TypeScript 严格模式的指令可能被充分执行但当上下文里同时存在二十条各种规范时这条指令的执行力度就会下降。第二冲突概率上升。你三个月前写的一条 Skill 说优先使用 class 组件上个月写的 AGENTS.md 说统一使用函数式组件两条信息同时存在时模型的行为就变得不可预测。它可能随机选一条也可能试图折中给出一个四不像的方案。第三过时信息污染。项目初期用的某个库后来被替换了但对应的 Skill 文件还留在目录里。模型看到这个 Skill 被激活就会按照旧库的 API 来生成代码而你实际项目里早就没有这个依赖了。我自己的一个项目就踩过这个坑早期用了一个状态管理库后来换成了另一个但旧的 Skill 文件忘了删。结果 Codex 在新代码里不断引用已经卸载的包每次都要手动纠正。查了半天才发现是那个残留的 Skill 在作祟。3. Skill 文件的熵增定律为什么越积越乱3.1 一个典型 Skill 的生命周期几乎每个 Skill 文件都会经历这样几个阶段阶段一精准有效。刚创建时它解决的是一个具体的、当前存在的问题。内容聚焦指令明确模型执行效果好。阶段二局部修补。用了一段时间后发现某些场景覆盖不到于是往里加条件分支。如果是 A 情况就这样如果是 B 情况就那样。文件开始变长。阶段三历史堆积。项目演进过程中部分内容已经过时但删了怕以后用到于是保留。新内容继续往上叠。文件越来越臃肿。阶段四负资产化。文件里同时存在有效指令、过时指令、互相矛盾的指令。模型每次读取都要处理这堆混乱信息输出质量明显下降。但因为这是我自己精心写的很少有人会怀疑是它的问题。这个生命周期几乎是无意识的。你不会在某一天突然决定我要把 Skill 搞乱而是在一次次就加一行先留着吧的决策中慢慢积累出了技术债务。3.2 什么样的 Skill 内容最容易变成负担根据我的观察和实际排查经验以下几类内容最容易从资产变成负债内容类型典型表现为什么变成负担过时的技术栈指令指定使用已替换的库或框架模型按旧 API 生成代码与实际项目不符过度具体的代码模板大段示例代码占用大量上下文且模型倾向于照搬而非理解模糊的风格偏好代码要优雅命名要清晰无法执行只稀释注意力重复的规范说明与 AGENTS.md 或其他 Skill 内容重叠信息冗余权重分散场景假设本项目主要用于 XXX 场景限制模型在其他场景下的发挥历史决策记录为什么当初选择方案 A对当前代码生成无直接帮助这张表建议你对照自己的 Skill 目录过一遍。我敢打赌至少有三成的内容属于上面这些类型。3.3 一个真实的排查案例前段时间帮一个朋友排查他的 Codex 表现问题。他的项目里积累了四十多个 Skill 文件覆盖了从代码风格到部署流程的方方面面。他的抱怨是最近 Codex 生成的代码总是带着一堆没用的注释而且老是引用一个我们已经不用的工具函数。排查过程很简单我让他把所有 Skill 文件的内容拼在一起统计了一下总字数——超过一万五千字。然后逐个检查发现有六个 Skill 文件引用了已经删除的工具函数有三个 Skill 文件之间关于错误处理方式的规定互相矛盾有十一个 Skill 文件的内容其实已经被 AGENTS.md 覆盖了真正在当下有效的、不可替代的 Skill 内容加起来不到三千字清理之后他的 Codex 表现立刻恢复到了刚配置时的水平。这个案例说明的问题很直接不是模型不行了是你喂给它的东西太多了。4. AGENTS.md 的正确写法少即是多4.1 AGENTS.md 应该承担什么角色很多人把 AGENTS.md 当成了项目说明书这是一个根本性的定位错误。AGENTS.md 的核心作用应该是告诉 Codex 在这个项目里工作时必须遵守的最小必要规则。注意关键词——最小必要。它不是文档不是 wiki不是知识库。它是一份工作守则而且是一份只包含如果不写模型就一定会做错的内容的守则。按照这个标准大部分 AGENTS.md 里至少有一半的内容是不该出现的。4.2 该写什么、不该写什么我总结了一个简单的判断标准每次想往 AGENTS.md 里加内容时问自己三个问题问题一不写这条模型会做错吗如果答案是可能会也可能不会那就不写。只写那些不写就一定会错的内容。问题二这条内容三个月后还有效吗如果答案不确定那就不写。AGENTS.md 应该只包含长期稳定的规则。问题三这条内容能不能用一句话说清楚如果需要一大段解释说明它可能不适合放在 AGENTS.md 里而应该放在项目文档中让人类去读。基于这三个问题我整理了一份对照表应该写进 AGENTS.md不应该写进 AGENTS.md必须使用的语言和版本项目背景介绍不可协商的命名约定详细的目录结构说明必须遵守的安全规则历史架构决策记录禁止使用的依赖或模式大段示例代码构建和测试命令模糊的风格偏好必须通过的检查项与代码生成无关的流程说明4.3 一个精简 AGENTS.md 的实际模板下面是我自己在用的一个 AGENTS.md 模板全文不到三百字但覆盖了所有不写就会错的内容# 项目工作规则 ## 语言与运行时 - 使用 TypeScript 5.xstrict 模式必须开启 - Node.js 版本不低于 20 - 包管理器统一使用 pnpm ## 代码规范 - 禁止使用 any必要时用 unknown 加类型守卫 - 组件统一使用函数式写法禁止 class 组件 - 异步操作统一使用 async/await禁止 .then 链式调用 ## 依赖限制 - 禁止引入新的状态管理库使用项目已有的方案 - 禁止使用已废弃的 internal 工具函数 ## 验证要求 - 提交前必须通过 pnpm lint 和 pnpm test - 新增函数必须有对应的单元测试这份模板的特点是每一条都是可执行的、明确的、不可协商的。没有尽量建议优先这类模糊词汇也没有任何背景说明或解释。模型读到这些内容时不需要理解只需要执行。对比一下你现在的 AGENTS.md如果长度超过五百字大概率有精简空间。5. 清理与重构的完整实操流程5.1 第一步全面盘点现有资产在动手清理之前先做一次完整的盘点。把项目里所有 Skill 文件和 AGENTS.md 的内容汇总到一起建议用一个简单的脚本或者手动整理成一份清单。盘点时需要记录以下信息文件名称和路径最后修改时间内容摘要一句话概括当前是否仍然有效是否与其他文件内容重叠这一步的目的是让你对自己到底喂了多少东西给 Codex有一个直观的认识。很多人做完这一步就会惊讶地发现自己积累的内容远超预期。5.2 第二步按有效性分类盘点完成后把所有内容分成四类第一类当前有效且不可替代。这些内容必须保留而且应该放在最合适的位置AGENTS.md 或独立 Skill。第二类当前有效但可以合并。多个 Skill 文件里分散的同类规则合并成一个。第三类已经过时。直接删除不要犹豫。如果担心以后用到可以备份到一个不参与加载的目录里。第四类模糊或无法执行。要么改写成可执行的明确规则要么删除。分类过程中有一个重要原则宁可删错不可留错。一条过时或矛盾的指令造成的损害远大于缺少一条指令。缺少指令时模型会按通用最佳实践来而错误指令会把它带偏。5.3 第三步重构与验证清理完成后按照下面的结构重新组织AGENTS.md只放全局性的、不可协商的规则Skill 文件按功能域拆分每个文件聚焦一个明确的场景项目文档所有背景说明、架构决策、流程描述都移到这里不参与 Codex 的上下文加载重构完成后不要急着继续开发。先做一轮验证用几个典型的编码任务测试 Codex 的表现对比清理前后的差异。如果清理有效你应该能明显感觉到输出变得更聚焦、更符合预期。5.4 建立定期清理机制清理不是一次性的工作。建议建立一个简单的定期检查机制每次项目技术栈发生变更时同步检查相关 Skill 文件每个月花十分钟扫一遍 Skill 目录删除明显过时的内容每次往 AGENTS.md 添加内容前先问自己那三个问题这个机制不需要很复杂关键是养成习惯。技术债务的可怕之处就在于它是无声积累的等到问题显现时往往已经积重难返。6. 常见问题与排查技巧实录6.1 怎么判断当前的问题是不是 Skill 或 AGENTS.md 引起的一个简单的判断方法临时清空所有 Skill 和 AGENTS.md只保留最核心的几条规则然后测试同样的任务。如果表现明显改善说明问题就出在这里。如果清空后表现没有变化那问题可能在别处——比如对话历史太长、任务描述本身有歧义、或者确实是模型能力边界。6.2 清理后效果没有改善怎么办有几种可能第一清理得不彻底。检查是否还有残留的 Skill 文件被加载或者 AGENTS.md 里是否还有隐藏的矛盾内容。第二问题不在配置而在对话历史。长对话积累的上下文同样会稀释注意力这时候需要开新对话。第三任务本身超出了模型能力范围。这时候再怎么调配置也没用需要拆解任务或换方案。6.3 常见问题速查表现象可能原因排查方向输出变得啰嗦上下文信息过载精简 AGENTS.md 和 Skill引用不存在的函数过时 Skill 残留检查并删除过时文件建议前后矛盾多条规则冲突合并去重消除矛盾忽略明确指令注意力被稀释减少上下文中的信息量表现时好时坏上下文内容不稳定检查是否有动态加载的内容代码风格漂移风格规则不明确或过多只保留最核心的风格规则6.4 几个容易踩的坑坑一把 Skill 当成知识库。Skill 是给模型执行用的不是给人阅读用的。任何仅供参考的内容都不应该出现在 Skill 里。坑二舍不得删。万一以后用到呢是技术债务的最大来源。用不到就是负担删掉。坑三一次加太多。每次只加一条规则测试有效后再考虑是否保留。批量添加会让你无法判断哪条有效、哪条有害。坑四忽略文件加载顺序。不同位置的配置文件权重不同把重要规则放在权重高的位置次要规则可以往后放或者干脆不放。坑五从不回顾。配置写完就不管了这是最危险的。项目在变配置也必须跟着变。7. 我个人的一些实操体会最后分享几个我在长期使用中总结的小经验不一定适用于所有人但值得参考。关于 Skill 的数量我的经验是单个项目的 Skill 文件不要超过五个每个文件的内容不要超过五百字。超过这个量级管理成本就会超过收益。如果发现需要更多 Skill 才能覆盖场景通常说明你的项目结构或者任务划分本身需要调整。关于 AGENTS.md 的长度我的标准是能一屏看完。如果需要在编辑器里滚动才能看完就说明太长了。一屏以内的内容模型能充分消化超出一屏效果就开始打折扣。关于更新频率我的做法是每次技术栈变更时同步清理每个月做一次快速扫描。不需要很频繁但必须定期。我见过太多项目配置写完之后就再也没动过等到出问题时已经积累了几十条过时规则。还有一个反直觉的发现有时候删掉一条规则效果比加十条还好。因为删掉的是干扰加上的可能是新的干扰。在调优 Codex 表现这件事上做减法往往比做加法更有效。如果你现在正被 Codex 表现下降的问题困扰不妨先别急着找新技巧、新配置而是回头看看自己积累的那些 Skill 和 AGENTS.md。很可能答案就在那里——不是要加什么而是要减什么。 
长河君 · 2026/10/10 9:51:52 · 阅读 1.2k Codex 智能编码助手性能下降？清理 Skill 与 AGENTS.md 历史资产
1. 一个被忽视的真相你的智能编码助手可能正在被历史资产拖垮如果你正在使用 Codex 这类智能编码助手并且已经用了一段时间大概率会遇到这样一种情况刚开始用的时候它给出的建议精准、简洁、直击要害但随着你不断往项目里添加 Skill 文件、不断丰富 AGENTS.md 的内容它的表现反而越来越差——回答变得啰嗦、建议开始跑偏、甚至在你明确指定了技术栈的情况下给出完全不相关的方案。很多人第一反应是模型退化了或者是不是换了底层模型但实际情况往往恰恰相反问题出在你自己积累的那些 Skill 和 AGENTS.md 上。你为提升效果而不断叠加的配置正在变成拖累它的负担。这个现象在圈子里已经有不少人讨论过但大多数讨论停留在感觉变差了的层面很少有人系统性地拆解过为什么曾经有效的 Skill 会变成负资产AGENTS.md 到底应该写多少什么内容该放进去、什么内容必须拿出去这篇文章就围绕这几个核心问题结合我自己的实操踩坑经历把这件事讲透。无论你是刚接触 Codex 的新手还是已经积累了几十个 Skill 文件的老用户下面这些内容都值得对照检查一遍。因为这个问题不解决你后面所有的调优努力都可能是在往错误的方向使劲。2. 先搞清楚 Codex 是怎么读你的项目的2.1 Skill 和 AGENTS.md 在上下文里到底占什么位置要理解为什么 Skill 和 AGENTS.md 会毁掉Codex 的表现必须先搞清楚一个底层机制上下文窗口是有限的而且不是所有位置的信息权重都一样。Codex 这类工具在响应你的请求时会按照一定的优先级把信息拼装进上下文。通常的顺序大致是系统级指令工具内置的你改不了AGENTS.md 或类似的项目级配置文件被激活的 Skill 文件内容当前对话历史你本次的具体请求这个顺序意味着一个关键事实AGENTS.md 和 Skill 的内容会占据上下文的前部位置而前部位置对模型输出的影响权重非常高。换句话说你写在 AGENTS.md 里的每一句话都在以一种高优先级的方式影响模型的判断。很多人没有意识到这一点把 AGENTS.md 当成了一个项目说明文档来写——项目背景、技术栈、目录结构、编码规范、部署流程、注意事项恨不得把整个 wiki 都塞进去。结果就是模型在还没看到你具体问题之前已经被一大堆背景信息洗脑了。2.2 为什么信息越多越好在这里是错的日常使用搜索引擎或者知识库时我们习惯性地认为信息越多越全面越好。但 Codex 的工作机制完全不同。它不是在检索信息而是在理解信息然后生成代码。当你往上下文里塞入大量信息时会发生几件事第一注意力被稀释。模型需要在所有输入信息之间分配注意力权重。你塞进去的内容越多每条信息分到的权重就越低。原本一条使用 TypeScript 严格模式的指令可能被充分执行但当上下文里同时存在二十条各种规范时这条指令的执行力度就会下降。第二冲突概率上升。你三个月前写的一条 Skill 说优先使用 class 组件上个月写的 AGENTS.md 说统一使用函数式组件两条信息同时存在时模型的行为就变得不可预测。它可能随机选一条也可能试图折中给出一个四不像的方案。第三过时信息污染。项目初期用的某个库后来被替换了但对应的 Skill 文件还留在目录里。模型看到这个 Skill 被激活就会按照旧库的 API 来生成代码而你实际项目里早就没有这个依赖了。我自己的一个项目就踩过这个坑早期用了一个状态管理库后来换成了另一个但旧的 Skill 文件忘了删。结果 Codex 在新代码里不断引用已经卸载的包每次都要手动纠正。查了半天才发现是那个残留的 Skill 在作祟。3. Skill 文件的熵增定律为什么越积越乱3.1 一个典型 Skill 的生命周期几乎每个 Skill 文件都会经历这样几个阶段阶段一精准有效。刚创建时它解决的是一个具体的、当前存在的问题。内容聚焦指令明确模型执行效果好。阶段二局部修补。用了一段时间后发现某些场景覆盖不到于是往里加条件分支。如果是 A 情况就这样如果是 B 情况就那样。文件开始变长。阶段三历史堆积。项目演进过程中部分内容已经过时但删了怕以后用到于是保留。新内容继续往上叠。文件越来越臃肿。阶段四负资产化。文件里同时存在有效指令、过时指令、互相矛盾的指令。模型每次读取都要处理这堆混乱信息输出质量明显下降。但因为这是我自己精心写的很少有人会怀疑是它的问题。这个生命周期几乎是无意识的。你不会在某一天突然决定我要把 Skill 搞乱而是在一次次就加一行先留着吧的决策中慢慢积累出了技术债务。3.2 什么样的 Skill 内容最容易变成负担根据我的观察和实际排查经验以下几类内容最容易从资产变成负债内容类型典型表现为什么变成负担过时的技术栈指令指定使用已替换的库或框架模型按旧 API 生成代码与实际项目不符过度具体的代码模板大段示例代码占用大量上下文且模型倾向于照搬而非理解模糊的风格偏好代码要优雅命名要清晰无法执行只稀释注意力重复的规范说明与 AGENTS.md 或其他 Skill 内容重叠信息冗余权重分散场景假设本项目主要用于 XXX 场景限制模型在其他场景下的发挥历史决策记录为什么当初选择方案 A对当前代码生成无直接帮助这张表建议你对照自己的 Skill 目录过一遍。我敢打赌至少有三成的内容属于上面这些类型。3.3 一个真实的排查案例前段时间帮一个朋友排查他的 Codex 表现问题。他的项目里积累了四十多个 Skill 文件覆盖了从代码风格到部署流程的方方面面。他的抱怨是最近 Codex 生成的代码总是带着一堆没用的注释而且老是引用一个我们已经不用的工具函数。排查过程很简单我让他把所有 Skill 文件的内容拼在一起统计了一下总字数——超过一万五千字。然后逐个检查发现有六个 Skill 文件引用了已经删除的工具函数有三个 Skill 文件之间关于错误处理方式的规定互相矛盾有十一个 Skill 文件的内容其实已经被 AGENTS.md 覆盖了真正在当下有效的、不可替代的 Skill 内容加起来不到三千字清理之后他的 Codex 表现立刻恢复到了刚配置时的水平。这个案例说明的问题很直接不是模型不行了是你喂给它的东西太多了。4. AGENTS.md 的正确写法少即是多4.1 AGENTS.md 应该承担什么角色很多人把 AGENTS.md 当成了项目说明书这是一个根本性的定位错误。AGENTS.md 的核心作用应该是告诉 Codex 在这个项目里工作时必须遵守的最小必要规则。注意关键词——最小必要。它不是文档不是 wiki不是知识库。它是一份工作守则而且是一份只包含如果不写模型就一定会做错的内容的守则。按照这个标准大部分 AGENTS.md 里至少有一半的内容是不该出现的。4.2 该写什么、不该写什么我总结了一个简单的判断标准每次想往 AGENTS.md 里加内容时问自己三个问题问题一不写这条模型会做错吗如果答案是可能会也可能不会那就不写。只写那些不写就一定会错的内容。问题二这条内容三个月后还有效吗如果答案不确定那就不写。AGENTS.md 应该只包含长期稳定的规则。问题三这条内容能不能用一句话说清楚如果需要一大段解释说明它可能不适合放在 AGENTS.md 里而应该放在项目文档中让人类去读。基于这三个问题我整理了一份对照表应该写进 AGENTS.md不应该写进 AGENTS.md必须使用的语言和版本项目背景介绍不可协商的命名约定详细的目录结构说明必须遵守的安全规则历史架构决策记录禁止使用的依赖或模式大段示例代码构建和测试命令模糊的风格偏好必须通过的检查项与代码生成无关的流程说明4.3 一个精简 AGENTS.md 的实际模板下面是我自己在用的一个 AGENTS.md 模板全文不到三百字但覆盖了所有不写就会错的内容# 项目工作规则 ## 语言与运行时 - 使用 TypeScript 5.xstrict 模式必须开启 - Node.js 版本不低于 20 - 包管理器统一使用 pnpm ## 代码规范 - 禁止使用 any必要时用 unknown 加类型守卫 - 组件统一使用函数式写法禁止 class 组件 - 异步操作统一使用 async/await禁止 .then 链式调用 ## 依赖限制 - 禁止引入新的状态管理库使用项目已有的方案 - 禁止使用已废弃的 internal 工具函数 ## 验证要求 - 提交前必须通过 pnpm lint 和 pnpm test - 新增函数必须有对应的单元测试这份模板的特点是每一条都是可执行的、明确的、不可协商的。没有尽量建议优先这类模糊词汇也没有任何背景说明或解释。模型读到这些内容时不需要理解只需要执行。对比一下你现在的 AGENTS.md如果长度超过五百字大概率有精简空间。5. 清理与重构的完整实操流程5.1 第一步全面盘点现有资产在动手清理之前先做一次完整的盘点。把项目里所有 Skill 文件和 AGENTS.md 的内容汇总到一起建议用一个简单的脚本或者手动整理成一份清单。盘点时需要记录以下信息文件名称和路径最后修改时间内容摘要一句话概括当前是否仍然有效是否与其他文件内容重叠这一步的目的是让你对自己到底喂了多少东西给 Codex有一个直观的认识。很多人做完这一步就会惊讶地发现自己积累的内容远超预期。5.2 第二步按有效性分类盘点完成后把所有内容分成四类第一类当前有效且不可替代。这些内容必须保留而且应该放在最合适的位置AGENTS.md 或独立 Skill。第二类当前有效但可以合并。多个 Skill 文件里分散的同类规则合并成一个。第三类已经过时。直接删除不要犹豫。如果担心以后用到可以备份到一个不参与加载的目录里。第四类模糊或无法执行。要么改写成可执行的明确规则要么删除。分类过程中有一个重要原则宁可删错不可留错。一条过时或矛盾的指令造成的损害远大于缺少一条指令。缺少指令时模型会按通用最佳实践来而错误指令会把它带偏。5.3 第三步重构与验证清理完成后按照下面的结构重新组织AGENTS.md只放全局性的、不可协商的规则Skill 文件按功能域拆分每个文件聚焦一个明确的场景项目文档所有背景说明、架构决策、流程描述都移到这里不参与 Codex 的上下文加载重构完成后不要急着继续开发。先做一轮验证用几个典型的编码任务测试 Codex 的表现对比清理前后的差异。如果清理有效你应该能明显感觉到输出变得更聚焦、更符合预期。5.4 建立定期清理机制清理不是一次性的工作。建议建立一个简单的定期检查机制每次项目技术栈发生变更时同步检查相关 Skill 文件每个月花十分钟扫一遍 Skill 目录删除明显过时的内容每次往 AGENTS.md 添加内容前先问自己那三个问题这个机制不需要很复杂关键是养成习惯。技术债务的可怕之处就在于它是无声积累的等到问题显现时往往已经积重难返。6. 常见问题与排查技巧实录6.1 怎么判断当前的问题是不是 Skill 或 AGENTS.md 引起的一个简单的判断方法临时清空所有 Skill 和 AGENTS.md只保留最核心的几条规则然后测试同样的任务。如果表现明显改善说明问题就出在这里。如果清空后表现没有变化那问题可能在别处——比如对话历史太长、任务描述本身有歧义、或者确实是模型能力边界。6.2 清理后效果没有改善怎么办有几种可能第一清理得不彻底。检查是否还有残留的 Skill 文件被加载或者 AGENTS.md 里是否还有隐藏的矛盾内容。第二问题不在配置而在对话历史。长对话积累的上下文同样会稀释注意力这时候需要开新对话。第三任务本身超出了模型能力范围。这时候再怎么调配置也没用需要拆解任务或换方案。6.3 常见问题速查表现象可能原因排查方向输出变得啰嗦上下文信息过载精简 AGENTS.md 和 Skill引用不存在的函数过时 Skill 残留检查并删除过时文件建议前后矛盾多条规则冲突合并去重消除矛盾忽略明确指令注意力被稀释减少上下文中的信息量表现时好时坏上下文内容不稳定检查是否有动态加载的内容代码风格漂移风格规则不明确或过多只保留最核心的风格规则6.4 几个容易踩的坑坑一把 Skill 当成知识库。Skill 是给模型执行用的不是给人阅读用的。任何仅供参考的内容都不应该出现在 Skill 里。坑二舍不得删。万一以后用到呢是技术债务的最大来源。用不到就是负担删掉。坑三一次加太多。每次只加一条规则测试有效后再考虑是否保留。批量添加会让你无法判断哪条有效、哪条有害。坑四忽略文件加载顺序。不同位置的配置文件权重不同把重要规则放在权重高的位置次要规则可以往后放或者干脆不放。坑五从不回顾。配置写完就不管了这是最危险的。项目在变配置也必须跟着变。7. 我个人的一些实操体会最后分享几个我在长期使用中总结的小经验不一定适用于所有人但值得参考。关于 Skill 的数量我的经验是单个项目的 Skill 文件不要超过五个每个文件的内容不要超过五百字。超过这个量级管理成本就会超过收益。如果发现需要更多 Skill 才能覆盖场景通常说明你的项目结构或者任务划分本身需要调整。关于 AGENTS.md 的长度我的标准是能一屏看完。如果需要在编辑器里滚动才能看完就说明太长了。一屏以内的内容模型能充分消化超出一屏效果就开始打折扣。关于更新频率我的做法是每次技术栈变更时同步清理每个月做一次快速扫描。不需要很频繁但必须定期。我见过太多项目配置写完之后就再也没动过等到出问题时已经积累了几十条过时规则。还有一个反直觉的发现有时候删掉一条规则效果比加十条还好。因为删掉的是干扰加上的可能是新的干扰。在调优 Codex 表现这件事上做减法往往比做加法更有效。如果你现在正被 Codex 表现下降的问题困扰不妨先别急着找新技巧、新配置而是回头看看自己积累的那些 Skill 和 AGENTS.md。很可能答案就在那里——不是要加什么而是要减什么。