# 核心指引

## 一、问题背景

在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提供更清晰的执行框架，使其能够更专注于真正需要智能判断的部分，而非在重复性的流程遵循上消耗注意力。