agents-md-">大模型时代，Skill 与 AGENTS.md 该做一次大扫除了

过去一年多，围绕智能编程工具的“上下文工程”形成了一个默认套路：给模型配置一堆 Skill（技能模块），再写一份长长的 AGENTS.md（项目级指令文件），把项目架构、数据库规范、部署流程、编码风格全部塞进去，恨不得让模型在动手前把整个工程手册通读一遍。

这套做法在早期模型上确实有效，因为那时的模型主动性差、指令遵循能力弱，不明确要求它去读文档，它大概率不会主动去看。但当模型迭代到指令遵循能力显著增强的一代之后，情况发生了根本性反转：模型开始认真执行你写的每一条规则，包括那些写得过宽、互相冲突、毫无必要的规则。

于是，曾经用来“兜底”的 Skill 和 AGENTS.md，正在变成拖慢任务、膨胀上下文、诱发幻觉的负资产。是时候做一次系统性的大扫除了。

一、问题的根源：模型变“听话”了，规则却没跟着变

要理解为什么旧配置会失效，先要理解模型能力变化带来的行为差异。

在指令遵循能力较弱的阶段，模型对上下文中的规则往往是“选择性执行”：写十条规则，可能只落实三四条，模糊的规则经常被忽略。开发者为了让关键规则生效，不得不采取“宁可多写、不可漏写”的策略——把所有可能相关的文档路径、检查步骤、参考规范全部写进指令，强制模型每次编辑前都读一遍。

而在指令遵循能力增强之后，模型对规则的执行变得严格且字面化。这本身是好事，但它同时暴露了旧配置的两个致命缺陷：

• 触发条件过宽：规则描述的适用范围远大于实际需要，导致 Skill 被频繁误触发；
• 规则冗余与冲突：多条规则覆盖同一场景，或彼此存在语义重叠，模型只能全部执行，无法自行裁剪。

结果就是：你只改了一个字符串常量，模型却把架构文档、数据库文档、部署文档完整读了一遍；你只调整了一个 ORM 模型字段，迁移 Skill 却被判定为“相关”而整体注入。Token 消耗上升、响应延迟增加、上下文中充斥着与当前任务无关的内容，幻觉概率随之上升。

二、典型反模式：两类最常见的“坏规则”

反模式一：Skill 的触发条件写成“领域描述”

很多 Skill 的描述类似这样：

# BAD：触发条件覆盖范围过大
description: Use when working with databases, queries, models, or persistence.

这段描述的问题在于，“databases / queries / models / persistence”几乎覆盖了后端开发的半壁江山。修改一个 ORM 模型的字段类型、修复一条普通查询语句、甚至只是重命名一个持久化对象，都可能被模型判定为“与数据库相关”，从而触发整个迁移 Skill——随之而来的是迁移规范、检查清单、历史参考资料一股脑进入上下文。

正确的做法是把触发条件从“领域”收紧到“具体动作”：

# GOOD：触发条件指向明确的任务动作
description: Use when adding or changing a database migration, or reviewing its rollout plan.

改写后的描述只在一个明确的任务场景下触发：新增或修改迁移、评审迁移上线方案。普通的数据模型调整、查询修复不会被误判，Skill 的注入频率大幅下降，上下文也就干净了。

这里的原则可以总结为一条：Skill 的 description 应该描述“什么任务需要它”，而不是“它属于哪个技术领域”。 领域描述天然宽泛，任务描述天然收敛。

反模式二：AGENTS.md 写成“每次必读清单”

另一类高频反模式出现在项目级指令文件中：

<!-- BAD：无条件强制读取 -->
Before every edit, read architecture.md, database.md, and deployment.md.

这条规则在早期是合理的——那时模型不会主动查找项目文档，只能靠硬性约束。但在强指令遵循模型上，它会变成字面意义上的“每次编辑前完整读取三个文档”。改一个字符串，读一遍；再改一处注释，再读一遍。三个文档的内容反复进入上下文，Token 成本成倍增长，上下文窗口被无关信息快速填满，模型对当前任务的注意力被稀释。

更合理的写法是把“无条件读取”改为“按需读取 + 明确条件”：

<!-- GOOD：按任务类型条件化加载 -->
- 涉及跨模块调用或分层结构调整时，先阅读 architecture.md。
- 涉及表结构变更或迁移脚本时，先阅读 database.md。
- 涉及发布流程、环境变量或回滚策略时，先阅读 deployment.md。
- 仅做局部逻辑修复或文案调整时，无需预先读取上述文档。

关键变化有三点：一是把“每次”改为“当……时”；二是为每份文档绑定明确的触发场景；三是显式声明“什么情况下不需要读”，给模型一个合法的跳过依据。

三、系统性清理方法：四步走

零散地改几条规则解决不了根本问题，建议按以下四个步骤做一次完整梳理。

第一步：盘点与归类

把当前所有 Skill 和 AGENTS.md 条目列出来，按“触发条件”归类。重点标记三类高风险条目：

• 触发条件使用领域名词而非任务动作的 Skill；
• 使用“每次”“始终”“所有情况下”等无条件量词的规则；
• 内容存在重叠、可能对同一场景重复生效的多条规则。

第二步：收紧触发边界

对每个 Skill，问一个问题：“在什么具体任务下，模型不加载它就会做错？” 答案就是触发条件。把答案写成一句可判定的任务描述，替换掉原来的领域描述。判定标准很简单：如果一条描述能让模型在“改一个字段”和“新增一次迁移”之间做出区分，它就是合格的。

第三步：消除冗余与冲突

同一场景只保留一条权威规则。如果两条规则语义重叠，合并为一条；如果两条规则存在冲突（例如一条要求“编辑前必读文档”，另一条要求“最小上下文原则”），必须明确优先级或删除其中一条。强指令遵循模型面对冲突规则时的典型反应是暂停并向用户确认，这在自动化流程中等同于任务阻塞。

第四步：建立按需加载机制

把大块参考资料从“常驻上下文”迁移到“按需检索”。具体做法包括：

• 将长篇规范拆分为独立文档，在 AGENTS.md 中只保留路径与触发条件；
• 对确实需要常驻的核心约束（如编码风格底线），压缩到尽可能短的篇幅；
• 定期审查上下文注入日志，识别高频但低价值的加载行为并优化。

四、验证与持续维护

清理不是一次性的。建议在调整后做一轮对照验证：选取若干典型任务（局部逻辑修改、字段调整、迁移新增、部署变更），观察模型在不同任务下的 Skill 触发情况与文档读取行为，确认触发边界符合预期。

同时把上下文配置纳入代码评审范围。当新增一个 Skill 或修改 AGENTS.md 时，评审重点不应只是“规则写得对不对”，更应是“触发条件够不够窄”“是否与既有规则重复”。上下文配置本质上也是代码，同样需要约束与迭代。

结语

模型能力的提升，改变的不只是“能做什么”，还有“该怎么配置”。当模型从“选择性执行”进化为“严格字面执行”，过去为弥补能力不足而堆叠的宽泛规则，就从保障变成了负担。Skill 和 AGENTS.md 的这次大扫除，核心不是删东西，而是把规则的粒度从“领域”精确到“任务”，把加载策略从“无条件常驻”转为“按需触发”。

少即是多——这句话在上下文工程里，从未像现在这样成立。