246 lines
7.0 KiB
Markdown
246 lines
7.0 KiB
Markdown
# 核心指引
|
||
|
||
## 一、问题背景
|
||
|
||
在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提供更清晰的执行框架，使其能够更专注于真正需要智能判断的部分，而非在重复性的流程遵循上消耗注意力。
|