智能体技能库与指令文件的系统清理指南

随着代码智能体从“补全代码”走向“执行多步任务”，团队往往会不断给它增加技能条目、项目说明、操作规范和参考资料。短期看，这些资产能提升任务完成率；长期看，它们也会形成新的工程负债：技能描述过宽导致误触发，指令文件越写越长导致关键约束被淹没，重复规则和过期规则互相冲突，最终让智能体看似“知道很多”，实际却容易忽略最关键的边界。

因此，所谓“大扫除”不是简单删文件，而是重新建立一套“触发—执行—验证—退出”的治理机制。清理的目标是让每条技能和每条指令都有明确职责、明确触发条件、明确验证方式和明确负责人，而不是让智能体在大量模糊上下文中自行猜测。

一、先理解问题：能力增强不等于上下文治理完成

智能体能力越强，越依赖外部技能与指令来约束行为。但每增加一条技能、一段说明、一个参考链接，都会占用上下文预算，并可能引入歧义。常见症状包括：

• 技能过度触发：描述范围过大，例如“处理数据库、查询、模型或持久化时使用”，会让普通查询修改也触发数据库迁移技能，后续迁移规则、检查步骤、参考资料一起进入上下文。
• 规则被忽略：指令文件里写了“没做 A 不能做 B”，但缺少执行流程和验证点，智能体仍可能跳过。
• 相似缺陷未扩散检查：修复一个缺陷后，没有要求检查同模块相似调用点，导致同类问题反复出现。
• 隐性假设未显式化：代码库文档中的前置条件没有被转化为可执行检查，模型只能靠猜测。
• 重复与冲突：全局指令、项目指令、技能说明三处重复同一规则，优先级却不清楚。
• 维护成本上升：技能没有负责人、没有复核周期，废弃后仍留在库中。

这些问题的本质是：技能库和指令文件被当成了“知识堆积区”，而不是“可执行工程资产”。清理时要像维护代码一样维护它们：有版本、有测试、有评审、有回滚、有下线。

二、明确清理对象：四类资产要分开治理

建议先把相关资产分成四类，避免混在一起处理：

1. 代理指令文件：稳定的项目硬约束、工作流程、禁止事项、验证命令和资料索引。
2. 技能条目：面向特定任务的能力包，包含触发条件、前置条件、执行步骤、输出格式和失败处理。
3. 参考资料：长文档、设计说明、排障手册等，原则上按需加载，不默认进入上下文。
4. 脚本与工具：静态检查、测试命令、迁移脚本、性能剖析脚本等，应通过命令或工具描述被调用，而不是在指令中粘贴大段代码。

治理原则可以概括为：指令管边界，技能管任务，资料管细节，脚本管执行。指令文件不应承担知识库职责，技能条目也不应塞入大量背景材料。长资料应通过索引按需加载，避免每次任务都携带无关上下文。

三、第一步：盘点资产与调用链路

大扫除的第一步不是删，而是盘点。建议为每条技能和每条指令建立清单，至少记录以下字段：

• 名称与职责：一句话说明它解决什么问题。
• 触发条件：何时使用，何时不要使用。
• 输入输出：需要哪些信息，输出什么结果。
• 依赖关系：依赖哪些脚本、资料、权限。
• 所属层级：全局、项目、任务临时层。
• 最近使用情况：调用频率、误触发记录、失败案例。
• 负责人和复核周期：谁维护，多久检查一次。
• 版本与回滚方式：变更后如何回退。

盘点时可以通过静态扫描找出重复关键词，通过调用日志找出高频误触发技能，通过失败案例找出“规则写了但没执行”的条目。重点不是追求数量完整，而是找出三类高风险资产：触发范围过宽的技能、长期未使用的技能、与硬约束冲突的指令。

四、第二步：收敛触发条件，解决过度触发

过度触发通常来自技能描述中的“大词”。例如“数据库、查询、模型、持久化”覆盖面太大，普通查询修改也可能被判定为相关任务。更合理的写法是把触发条件拆成“任务意图 + 操作对象 + 动作 + 排除项”。

示意配置如下：

name: database_schema_change
description: 仅在修改数据库结构、生成迁移脚本或变更持久化结构时使用
use_when:
  - 需要新增或删除表、字段、索引
  - 需要调整约束或数据回填方案
do_not_use_when:
  - 仅修改查询语句
  - 仅调整对象映射中的字段别名
preconditions:
  - 已阅读项目硬约束
  - 已准备回滚方案
outputs:
  - 变更步骤
  - 回滚步骤
  - 验证清单

这里的关键是显式写出“何时不要使用”。很多技能只写“何时使用”，模型就容易扩大解释；加入排除项后，触发边界会更清晰。对于性能分析类技能，也应写明适用对象，例如“仅在需要定位冷启动、吞吐下降或资源热点时使用”，并说明普通逻辑修改不应触发。技能描述越具体，上下文越干净。

五、第三步：精简代理指令文件，明确优先级

指令文件常见的问题是口号多、例外少、重复多、验证少。建议采用固定结构：项目目标、硬约束、工作流程、禁止事项、验证方式、资料索引、升级条件。每条规则尽量满足“对象、动作、条件、例外、验证方式”五要素。

示意结构如下：

# 智能体指令
## 硬约束
- 修改数据结构前必须给出回滚方案；缺失时停止并请求确认。
- 修复缺陷后必须检查同模块相似调用点；无法检查时说明原因。
## 工作流程
1. 定位相关约束与测试。
2. 做最小变更。
3. 运行指定验证并记录结果。
## 禁止事项
- 不得跳过验证直接提交。
## 资料索引
- 长文档放在独立资料中，按任务需要加载。

同时要明确优先级：安全合规高于数据一致性，数据一致性高于项目硬约束，项目硬约束高于技能建议，技能建议高于默认风格。发生冲突时，低优先级规则不得覆盖高优先级规则。指令文件应只保留稳定、跨任务必要的约束；临时经验应放入技能或任务说明，避免污染全局上下文。

六、第四步：建立评测与回归，防止清理后能力回退

清理不能只靠人工感觉。应为技能库建立小型评测集，至少包含四类样例：正例，应当触发；负例，不应触发；边界例，容易误判；失败复现例，曾导致规则被忽略。核心指标包括触发准确率、误触发率、任务成功率、上下文开销、人工干预次数和回归失败率。

示意伪代码如下：

cases = load_cases("skill_regression_cases")
for case in cases:
    result = agent.run(case.input, skills=candidate_skills)
    record(
        case_id=case.id,
        triggered=result.triggered_skills,
        tests_passed=result.tests_passed,
        context_cost=result.context_cost,
        interventions=result.human_interventions
    )
    assert result.triggered_skills == case.expected_skills
    assert result.tests_passed

建议采用“基线采集—候选清理—离线评测—小流量灰度—监控—回滚”的流程。每次新增或修改技能都跑评测，记录变更原因和效果。对于高风险技能，灰度期间要重点观察误触发和人工确认次数，避免清理后看似上下文变短，实际任务成功率下降。

七、第五步：补齐安全、权限与审计

技能越强，权限越要收紧。建议区分只读、写文件、执行命令、访问外部资源等权限；高风险操作需要人工确认。指令文件不得写入密钥或敏感信息，技能也不应隐式上传代码或数据。审计日志至少记录触发技能、输入摘要、关键输出、是否人工确认和最终结果，便于定位误触发和规则冲突。对长期未使用的技能设置归档机制，对高风险技能设置负责人和复核周期。

八、把大扫除变成持续机制

大扫除不应是一次性运动。建议建立准入和退出机制：新增技能前先检查是否已有可复用条目，触发条件是否可区分，是否有正负评测样例，是否有回滚方案；退出时检查是否长期未使用、误触发是否偏高、是否被新规则替代。可以按月或按季度做一次技能库复核，把误触发率、上下文开销和人工干预次数纳入看板。

最后可用一张检查清单收尾：

• 技能描述是否写明“何时使用”和“何时不要使用”？
• 是否存在重复、冲突或过期规则？
• 全局指令是否只保留稳定硬约束？
• 长资料是否按需加载而非默认注入？
• 是否有正例、负例和边界例评测？
• 是否有权限分级、审计和人工确认？
• 是否明确负责人、复核周期和下线流程？
• 是否有版本号和回滚方案？

智能体能力越强，越需要工程化治理。技能库和指令文件不是越多越好，而是越清晰、越可验证、越可维护越好。一次系统的大扫除，本质上是在为后续更复杂的任务建立可控的上下文边界。