1. 一个被忽视的真相你的智能编码助手可能正在被“历史包袱”拖垮如果你正在用 Codex 这类智能编码助手写代码并且已经用了有一阵子大概率经历过这样的场景刚开始用的时候它给出的建议精准、简洁、直击要害你甚至觉得“这玩意儿真能替我干活”。但用着用着你发现它开始变得啰嗦、跑偏、答非所问有时候你只是让它改一个函数它却给你扯出一堆无关的规范说明甚至把你几个月前写过的某段废弃逻辑又翻出来塞进新代码里。很多人第一反应是“模型变笨了”或者“是不是降智了”。但根据我自己的实操经验以及和不少同行交流下来问题往往不在模型本身而在于你喂给它的上下文里堆积了大量过时的 Skill 定义和 AGENTS.md 配置。这些东西就像你电脑里那些“舍不得删但又从来不打开”的老文件表面上看是资产实际上在持续消耗模型的注意力预算干扰它对当前任务的判断。这篇文章就是要把这件事说透。我会从 Codex 这类工具的工作机制讲起拆解 Skill 和 AGENTS.md 到底在什么环节起作用为什么“越攒越多”反而会让输出质量断崖式下跌然后给出一套可落地的清理和重构方案。不管你是刚接触智能编码助手的新手还是已经攒了几十个 Skill 的老用户都能从中找到可以直接抄作业的操作步骤。2. 先搞清楚 Codex 是怎么“读”你的项目的2.1 上下文窗口不是无限大的收纳箱很多人对 Codex 这类工具有一个根本性的误解觉得它“什么都能记住”。实际上每次你发起一次请求模型能看到的只有当前这次请求里被塞进去的内容。这个内容的总量受限于上下文窗口的大小虽然现在主流模型的上下文窗口已经能做到很大但“能塞进去”和“能有效利用”是两码事。我打个比方上下文窗口就像一张办公桌。你可以把一堆文件都摊在桌上但桌子就这么大文件越多每份文件被翻到的概率就越低而且桌面越乱你找东西的速度就越慢。模型也是一样当你的 AGENTS.md 写了三千字再加上十几个 Skill 的定义文件它真正能分配给“理解你当前要改的这段代码”的注意力就被严重稀释了。更关键的是很多工具在组装上下文时并不是“按需加载”而是“一股脑全塞”。你项目根目录下有一个 AGENTS.md子目录下还有好几个再加上 Skill 目录里的一堆 Markdown 文件这些东西会在每次请求时被拼接进去。你以为你只是在问一个简单问题实际上模型收到的是一份冗长的“项目说明书合集”。2.2 Skill 和 AGENTS.md 各自扮演什么角色在展开讲“怎么毁掉”之前得先把这两个东西的定位说清楚。AGENTS.md 通常放在项目根目录或者某个子目录下作用是告诉 Codex“这个项目是干什么的、用什么技术栈、有哪些约定俗成的规矩”。比如你写“所有 API 返回必须用统一的 Response 包装类”“数据库操作一律走 Repository 层不允许在 Controller 里直接写 SQL”。它的本质是一份给模型看的“项目须知”。Skill 则更偏向“能力模块”。一个 Skill 可能定义了一组特定的操作流程比如“如何生成一个符合团队规范的 CRUD 模块”“如何按照设计稿还原一个页面组件”。它通常包含更详细的操作步骤、代码模板、检查清单。你可以把它理解成给模型看的“操作手册”。这两个东西在设计初衷上都是好的通过预先定义规则和流程减少每次沟通的成本让模型输出更符合团队规范。但问题在于它们都是“静态文件”而项目是“动态演进”的。你三个月前写的 AGENTS.md可能早就和现在的代码结构对不上了你半年前定义的某个 Skill里面的代码模板可能已经用了废弃的 API。2.3 过时配置是如何一步步污染输出的我拿一个自己踩过的坑来举例。之前我在一个项目里定义了一个 Skill叫“生成数据导出功能”。里面写了一套用某个旧版工具库做 Excel 导出的模板代码。后来项目升级那个工具库换了新版本API 完全变了。但我一直没去更新那个 Skill 文件。结果就是之后每次我让 Codex 帮我写导出相关的代码它都会优先参考那个 Skill 里的模板生成一堆已经跑不通的旧版调用。我一开始还纳闷明明我在对话里说了“用新版 API”怎么它还是给我旧代码后来才意识到Skill 文件里的内容在上下文里的权重很高模型会把它当成“项目既定规范”来遵守优先级甚至高于我在对话里的临时说明。这就是最典型的“历史包袱污染”过时的 Skill 和 AGENTS.md 内容会持续地把模型往错误的方向拽。你越攒越多污染源就越多最后模型的行为就变得完全不可预测。3. 三种典型的“被毁掉”场景与底层原因3.1 场景一指令冲突导致模型“精神分裂”这是最常见也最让人头疼的情况。你的 AGENTS.md 里写着“所有函数必须写 JSDoc 注释”但你最近新加的一个 Skill 里又写着“保持代码简洁避免冗余注释”。这两个指令直接矛盾。模型每次生成代码时都要在这两个规则之间“做选择”而它的选择往往是随机的或者取决于哪个文件在上下文里排得更靠前。我实测下来的感受是当存在指令冲突时模型的输出会变得非常不稳定。同一段代码你让它改两次可能一次带注释一次不带格式也飘忽不定。你以为是模型“抽风”其实是你的配置文件在打架。更深层的原因是模型在处理冲突指令时并没有一个明确的“优先级裁决机制”。它不会告诉你“我检测到两条规则矛盾请确认以哪条为准”。它只会默默地在内部做一个概率性的取舍而这个取舍过程对你来说是完全黑盒的。3.2 场景二上下文超载让关键信息被“淹没”第二个典型场景是你发现模型开始“忘记”一些很重要的事情。比如你明明在 AGENTS.md 里写了“项目使用 pnpm 而不是 npm”但模型还是给你生成 npm install 的命令。你可能会觉得“这么简单的事都记不住”原因很简单你的 AGENTS.md 太长了。当一份文件超过一定长度后模型对其中信息的提取能力会下降。尤其是当这份文件里混杂了大量“背景介绍”“历史沿革”“未来规划”这类和当前编码任务无关的内容时真正关键的那几条规则反而被埋在了噪音里。我做过一个粗略的测试把一份 500 字左右的 AGENTS.md 和一份 3000 字的 AGENTS.md 分别喂给同一个模型让它完成同样的编码任务。500 字版本下模型对关键规则的遵守率明显更高。3000 字版本下模型虽然“看到了”所有内容但在实际生成时很多规则被忽略了。这就像你给一个新同事写了一份三页纸的入职须知他可能还能记住重点但你写了三十页他翻都翻不完最后只能凭感觉做事。3.3 场景三Skill 之间的隐式依赖形成“死锁”第三个场景更隐蔽也更难排查。假设你有两个 SkillSkill A 负责“生成数据库模型”Skill B 负责“生成 API 接口”。Skill B 的定义里写着“API 接口的字段命名必须与数据库模型保持一致”。但 Skill A 最近更新了把某个字段从 user_name 改成了 username。Skill B 并不知道这个变化它的模板里还是 user_name。结果就是模型在同时参考这两个 Skill 时会生成字段名不一致的代码。你运行的时候报错回头查半天才发现是两个 Skill 文件之间的“隐式契约”被打破了。这种问题的根源在于Skill 文件之间没有版本管理和依赖追踪机制。它们就是一堆散落的 Markdown谁改了哪个、影响了哪些其他 Skill全靠人脑记。当 Skill 数量超过十个之后这种隐式依赖几乎不可能靠人工维护。4. 清理与重构让 Codex 重新变聪明的实操方案4.1 第一步给现有的 Skill 和 AGENTS.md 做一次“体检”在动手删任何东西之前先做一次全面的盘点。我建议你按下面的表格来梳理文件路径类型最后修改时间是否仍被引用内容是否与当前项目一致处理建议/AGENTS.md根配置2024-08是部分过时精简重写/src/AGENTS.md子配置2024-06是严重过时删除或合并/skills/export.mdSkill2024-03否已废弃直接删除/skills/crud.mdSkill2024-09是基本一致保留但精简这个表格的关键在于“是否仍被引用”和“内容是否与当前项目一致”这两列。很多 Skill 文件你其实早就不用了但它们还躺在目录里每次请求时照样被加载进去。这些就是纯粹的“死重”删掉它们没有任何副作用。注意在删除任何文件之前先确认你的工具是否支持“按需加载 Skill”。如果你的工具是每次请求都全量加载那删除无用文件的效果会非常明显。如果支持按需加载那重点应该放在“确保被加载的文件是准确的”上。4.2 第二步把 AGENTS.md 压缩到“一页纸”以内我的经验是根目录的 AGENTS.md 最好控制在 500 字以内。只保留那些“每次编码都需要知道”的信息。具体来说只写这几类内容项目使用的技术栈和版本比如“React 18 TypeScript 5 Vite”必须遵守的硬性规则比如“禁止使用 any 类型”“所有异步操作必须处理错误”目录结构的关键约定比如“组件放在 src/components页面放在 src/pages”常用的命令比如“开发用 pnpm dev构建用 pnpm build”至于“项目背景介绍”“业务逻辑说明”“历史决策记录”这些内容全部移出去放到单独的文档里不要塞进 AGENTS.md。模型不需要知道你的项目是给哪个客户做的、经历了多少次需求变更它只需要知道“怎么写代码能跑通、能符合规范”。我自己的做法是把 AGENTS.md 当成一份“给新入职工程师的快速上手卡片”而不是“项目百科全书”。这个心态转变很关键。4.3 第三步给 Skill 建立“版本标签”和“适用范围”Skill 不能一删了之因为有些确实是需要的。关键是要让每个保留的 Skill 都“职责单一、边界清晰”。我建议给每个 Skill 文件加上一个头部注释格式如下--- skill: crud-generator version: 2.1 last_updated: 2024-10-15 applies_to: src/modules/**/controller.ts depends_on: [database-schema] ---这个头部信息虽然模型不一定会“理解”但它对你自己的维护很有帮助。更重要的是你可以根据 applies_to 字段来判断这个 Skill 是否和当前任务相关。如果你的工具支持条件加载就可以根据文件路径来决定加载哪些 Skill避免无关 Skill 干扰。另外我强烈建议把 Skill 里的“模板代码”和“规则说明”分开。模板代码放在单独的代码片段文件里Skill 文件只写“什么时候用这个模板、用的时候要注意什么”。这样更新模板时不需要动 Skill 的逻辑描述减少出错概率。4.4 第四步建立定期清理机制清理不是一次性的工作。项目在演进Skill 和 AGENTS.md 也需要持续维护。我自己的做法是每个月固定花 15 分钟检查一遍 AGENTS.md 和所有 Skill 文件每次项目有重大架构调整时同步更新相关配置文件每季度做一次“大扫除”删除连续三个月没有被任何请求引用过的 Skill你可以在项目里加一个简单的脚本统计每个 Skill 文件的最后访问时间。如果某个文件超过 90 天没有被读取过就在下次清理时重点审查它。提示不要等到模型输出质量明显下降才去清理。就像你不会等到电脑卡死才去删垃圾文件一样定期维护才是保持工具高效运转的关键。5. 进阶技巧让 Skill 和 AGENTS.md 真正为你所用5.1 用“分层配置”替代“大一统文件”很多人习惯把所有规则都写在一个 AGENTS.md 里这在项目初期没问题但随着项目变大这个文件会越来越臃肿。更好的做法是分层根目录 AGENTS.md只写全局规则控制在 300 字以内各子目录 AGENTS.md写该目录特有的规则比如“这个目录下的组件必须用函数式写法”Skill 文件只写具体操作流程不写全局规则这样做的目的是让模型在處理某个具体任务时只需要加载和这个任务相关的配置而不是把整个项目的所有规则都塞进去。上下文越干净模型的注意力越集中输出质量自然越高。5.2 给 Skill 加上“反例”和“边界条件”大部分 Skill 文件只写了“应该怎么做”但没写“什么情况下不要这么做”。这导致模型有时候会“过度应用”某个 Skill。比如你定义了一个“生成 RESTful API”的 Skill模型可能会在你只想写一个内部工具函数时也硬套 RESTful 的那套模板。解决办法是在 Skill 里加上“不适用场景”的说明。比如## 不适用场景 - 内部工具函数不需要暴露 HTTP 接口 - 一次性脚本不需要考虑复用性 - 性能敏感的底层模块模板代码可能引入不必要的开销这些“反例”能帮助模型更准确地判断什么时候该用这个 Skill什么时候不该用。我实测下来加上边界条件后模型“乱套模板”的情况明显减少。5.3 用“任务类型”而非“文件类型”来组织 Skill很多人按文件类型来组织 Skill比如“React 组件 Skill”“Python 脚本 Skill”。但模型在实际工作中面对的是“任务”而不是“文件”。更好的组织方式是按任务类型来分“新增一个 API 接口”的 Skill“修复一个 bug”的 Skill“重构一段代码”的 Skill“写单元测试”的 Skill这样模型在接到一个任务时能更直接地匹配到对应的 Skill而不是在多个文件类型的 Skill 之间来回切换。任务导向的 Skill 组织方式也更符合人类工程师的工作习惯。6. 常见问题与排查技巧实录6.1 模型突然开始“胡说八道”怎么办如果你发现模型突然开始生成明显不合理的代码比如引用了不存在的库、调用了不存在的方法第一反应不应该是“模型坏了”而是检查最近有没有新增或修改过 Skill 和 AGENTS.md。很多时候问题就出在某个新加的配置文件和现有规则冲突了。排查步骤很简单把最近一周内修改过的 Skill 和 AGENTS.md 文件列出来逐个临时移除看模型输出是否恢复正常找到“肇事文件”后检查它和其他配置是否有矛盾这个方法我用了很多次基本上十分钟内就能定位到问题源头。6.2 模型“忘记”关键规则怎么处理如果模型频繁忽略某条你认为很重要的规则先别急着反复强调。先检查这条规则在 AGENTS.md 里的位置。如果它被埋在一大段文字中间模型很可能“看不到”。解决办法是把关键规则放在文件最前面并且用加粗或列表的方式突出显示。另外规则本身要足够具体。“写好的代码”这种模糊要求模型没法执行。“所有函数必须有明确的返回类型标注”这种具体要求模型才能准确遵守。6.3 Skill 数量多少算“太多”这个问题没有绝对答案但根据我的经验如果一个项目里同时生效的 Skill 超过 15 个模型的表现就会开始明显下降。这里的“同时生效”指的是在一次请求中被加载进去的 Skill 数量。如果你能做到按需加载那总数量可以更多但同时加载的数量最好控制在 5 个以内。一个实用的判断标准是如果你自己都记不清有哪些 Skill 了那对模型来说肯定也太多了。6.4 清理后模型变“笨”了是怎么回事有时候你删掉了一些 Skill反而觉得模型不如以前“聪明”了。这通常是因为你删掉了某些实际上还在用的规则只是你自己没意识到。解决办法是在删除之前先做好备份然后观察一周。如果确实发现某些场景下输出质量下降再把对应的 Skill 恢复回来但要做精简。清理的原则是“宁可少而精不要多而杂”。一个准确的小配置文件比十个过时的大文件更有价值。7. 我个人的实操体会这套清理方法我在三个不同规模的项目里都跑过一遍。最直观的感受是清理之后模型对当前任务的理解准确度明显提升生成的代码需要手动修改的地方少了很多。以前可能要来回沟通五六轮才能得到想要的结果现在基本上两三轮就能搞定。另一个意外收获是清理过程本身也帮我重新梳理了项目的规范。有些规则其实早就名存实亡了只是没人去删。借着清理 Skill 的机会把这些“僵尸规则”一并处理掉对整个团队的协作效率都有好处。最后分享一个小技巧我会在 AGENTS.md 的最后加一行“本文件最后审核日期YYYY-MM-DD”。每次看到这个日期超过一个月就提醒自己该做一次检查了。这个习惯看起来不起眼但确实能防止配置文件“悄悄腐烂”。