agent-aide/docs/reference/为什么要更换到command+skill+专用处理程序.md

核心指引

一、问题背景

在AI辅助开发的实践中，存在几个普遍性问题：

1. 信息过载：每次交互都需要传递大量上下文，包括规则、流程、约束等，造成token消耗和注意力分散
2. 不确定性累积：自然语言描述的流程存在歧义，多次执行可能产生不同结果
3. 重复劳动：相似的操作模式反复出现，却每次都需要重新描述和执行
4. 认知负担：复杂流程的完整规则难以在单次对话中完整呈现和遵循

二、核心理念

2.1 渐进式披露

原则：信息按需加载，而非一次性全量呈现。

传统做法是在CLAUDE.md中堆积所有规则和流程说明，导致：

• 初始上下文臃肿
• 大部分规则在当前任务中并不需要
• 规则之间可能存在冲突或优先级不明

改进方向是将规则和流程封装为可调用的单元，仅在需要时触发加载。

2.2 确定性封装

原则：将可变过程转化为固定接口。

自然语言描述的操作存在解释空间，例如"更新状态记录"可能被理解为：

• 直接编辑CSV文件
• 追加新行
• 修改现有行
• 重建整个文件

通过程序封装，将这种不确定性消除：

• 输入：明确的参数
• 输出：确定的结果
• 过程：固定的逻辑

2.3 关注点分离

原则：流程编排与具体执行分离。

• Commands：负责"做什么"和"按什么顺序做"
• Skills：负责"怎么做"的具体实现

这种分离使得：

• 流程调整不影响具体实现
• 实现优化不改变流程结构
• 各部分可独立演进

三、Commands的意义与原理

3.1 本质定位

Commands是流程的触发器和编排器。

它不执行具体操作，而是：

1. 定义一个完整流程的阶段划分
2. 规定各阶段的执行顺序和转换条件
3. 指明每个阶段应调用的Skills
4. 处理异常和分支情况

3.2 设计原理

Commands通过Markdown文件定义，包含：

命令名称 → 触发入口
前置条件 → 执行门槛
流程阶段 → 状态机定义
阶段动作 → Skills调用指引
异常处理 → 分支和恢复策略

当用户调用一个Command时，AI获得的是一份结构化的执行指南，而非散落的规则片段。

3.3 价值体现

传统方式	Command方式
每次描述完整流程	一次定义，多次调用
流程步骤可能遗漏	阶段明确，不易遗漏
异常处理临时决定	预设异常处理策略
难以追踪执行进度	状态机明确当前位置

四、Skills的意义与原理

4.1 本质定位

Skills是操作的标准化封装。

它将一类具体操作：

1. 抽象为统一的接口
2. 隐藏内部实现细节
3. 提供确定性的输入输出
4. 减少执行过程中的信息噪声

4.2 设计原理

Skills通过SKILL.md定义接口，通过脚本实现逻辑：

接口定义（SKILL.md）：
  - 功能说明
  - 输入参数
  - 输出格式
  - 使用示例

实现脚本（*.py/*.sh）：
  - 参数解析
  - 业务逻辑
  - 结果输出
  - 错误处理

AI只需要知道"调用什么、传什么参数、期望什么结果"，无需关心内部如何实现。

4.3 价值体现

传统方式	Skill方式
直接操作文件/命令	调用封装接口
输出信息冗长	输出精简有效
错误处理不一致	统一错误格式
操作结果不确定	结果格式固定

五、协作模式

5.1 调用关系

用户 → Command → 流程阶段 → Skill → 脚本 → 结果
         ↓           ↓          ↓
      加载流程    状态流转    执行操作

5.2 信息流向

向下传递：

• Command向Skill传递必要的上下文参数
• Skill向脚本传递具体的操作参数

向上返回：

• 脚本返回执行结果（成功/失败/数据）
• Skill返回格式化的结果
• Command根据结果决定下一步流转

5.3 职责边界

层级	职责	不负责
Command	流程编排、状态管理、异常策略	具体操作实现
Skill	接口定义、参数校验、结果格式化	流程决策
脚本	具体逻辑执行	业务语义理解

六、设计原则

6.1 最小暴露原则

只暴露必要的接口和参数，隐藏实现细节。

反例：要求AI理解CSV文件格式并手动编辑 正例：提供update_status(task_id, status)接口

6.2 失败友好原则

预设失败场景的处理策略，而非依赖临时判断。

反例：遇到错误时"请自行判断如何处理" 正例：定义明确的错误码和对应的恢复动作

6.3 幂等性原则

相同输入产生相同结果，重复执行不产生副作用。

反例：每次执行都追加记录，导致重复数据 正例：基于唯一标识更新，存在则更新，不存在则创建

6.4 可观测原则

执行过程和结果应当可追踪、可验证。

反例：操作完成后无任何反馈 正例：返回结构化的执行报告，包含操作内容和结果

七、与传统方式的对比

7.1 上下文管理

方面	传统方式	Commands + Skills
规则存放	CLAUDE.md堆积	分散到各Command/Skill
加载时机	对话开始全量加载	调用时按需加载
更新维护	修改单一大文件	修改对应模块

7.2 执行过程

方面	传统方式	Commands + Skills
流程遵循	依赖AI记忆和理解	状态机强制约束
操作执行	自然语言描述	程序化调用
结果反馈	格式不固定	结构化输出

7.3 可维护性

方面	传统方式	Commands + Skills
流程修改	修改描述文本	修改状态机定义
操作优化	重写描述	修改脚本实现
问题定位	回溯对话历史	检查对应模块

八、适用场景判断

8.1 适合封装为Command的场景

• 包含多个有序阶段的复杂流程
• 需要状态追踪和异常恢复
• 会被重复执行的标准化流程
• 涉及多个Skills协作的编排任务

8.2 适合封装为Skill的场景

• 单一职责的具体操作
• 输入输出可明确定义
• 执行逻辑相对固定
• 需要减少信息噪声的操作

8.3 不适合封装的场景

• 一次性的探索性任务
• 高度依赖上下文判断的决策
• 需要灵活调整的创意工作
• 简单到不值得封装的操作

九、总结

Commands和Skills体系的核心价值在于：

1. 降低认知负担：将复杂流程分解为可管理的单元
2. 提高执行确定性：用程序逻辑替代自然语言描述
3. 减少信息噪声：只传递必要信息，隐藏实现细节
4. 增强可维护性：模块化设计便于独立演进

这不是要限制AI的能力，而是为AI提供更清晰的执行框架，使其能够更专注于真正需要智能判断的部分，而非在重复性的流程遵循上消耗注意力。