## 提示词检查

AI Agent 提示词质量评估与改进的全面最佳实践集。基于实际提示词改进过程中积累的经验，系统化地涵盖了消除歧义、信息整合、强制力强化、追踪系统、持续改进等所有重要方面。

### 使用方法

```bash
# 检查提示词文件的质量
cat your-prompt.md
/check-prompt
"检查这个提示词的质量并提出改进建议"
```

### 选项

- 无 : 分析当前文件或选中的文本
- `--category <name>` : 仅检查特定类别 (structure/execution/restrictions/quality/roles/improvement)
- `--score` : 仅计算质量分数
- `--fix` : 自动修正建议
- `--deep` : 深度分析模式 (重点检查歧义性、信息分散、强制力)

### 基本示例

```bash
# 提示词整体质量评估
cat devin/playbooks/code-review.md
/check-prompt
"从 6 个类别评估这个提示词的质量，指出问题并提出改进方案"

# 深度分析模式
/check-prompt --deep
"重点检查歧义性、信息分散、强制力不足，提出根本性改进方案"

# 特定类别检查
/check-prompt --category structure
"从结构和清晰度角度检查这个提示词"

# 模糊表达检测与修正
/check-prompt --fix
"检测模糊表达并提出明确的修正建议"
```

---

## 核心设计原则

### 原则 1: 完全消除解释空间

- **绝对禁止**: "原则上"、"推荐"、"如果可能"、"根据情况"、"酌情判断"
- **必须使用**: "必须"、"绝对"、"严格遵守"、"无例外"、"强制"
- **例外条件**: 用数值严格限定 ("仅以下 3 个条件"、"除这 2 种情况外")

### 原则 2: 信息的战略性整合

- 相关重要信息完全整合到一个部分
- 在执行清单中总结全貌
- 彻底消除循环引用或分散

### 原则 3: 构建分级强制力

- 🔴 (执行停止级) → 🟡 (质量重要) → 🟢 (建议事项) 的明确层级
- 从推荐级逐步升级到必须级
- 明示违反时的影响程度和处理方法

### 原则 4: 确保可追踪性

- 所有执行结果可记录、验证
- 技术上防止虚假报告
- 成功/失败的客观判断标准

### 原则 5: 反馈驱动改进

- 从实际失败案例中学习
- 持续验证有效性
- 自动检测新模式

---

## 📋 全面检查项目

### 1. 📐 结构与清晰度 (配分: 25 分)

#### 1.1 指示优先级显示 (8 分)

- [ ] 🔴🟡🟢 优先级标记在所有重要指示上
- [ ] 执行停止级条件具体且明确定义
- [ ] 各优先级判断标准客观且可验证
- [ ] 优先级层级一致应用

#### 1.2 完全消除模糊表达 (9 分)

- [ ] **致命模糊表达**: "原则上"、"推荐"、"如果可能"为 0 个
- [ ] **强制表达使用**: 适当使用"必须"、"绝对"、"严格遵守"、"无例外"
- [ ] **例外条件数值限定**: "仅 3 个条件"等明确边界
- [ ] **消除判断余地**: 仅使用不可能多重解释的表达
- [ ] **消灭灰色地带**: 所有情况都有明确判断标准

#### 1.3 信息的战略性整合 (8 分)

- [ ] 完全解决重要信息在多处分散的问题
- [ ] 相关指示逻辑地整合到一个部分
- [ ] 执行清单完整总结全貌
- [ ] 不存在循环引用或无限循环

### 2. 🎯 可执行性 (配分: 20 分)

#### 2.1 具体步骤的完整性 (7 分)

- [ ] 所有命令示例实际可执行且已验证
- [ ] 环境变量、前提条件、依赖关系完整记录
- [ ] 错误处理方法具体且可执行
- [ ] 步骤顺序逻辑且必然

#### 2.2 确保可验证性 (7 分)

- [ ] 执行结果的成功/失败可客观判断
- [ ] 输出示例、日志格式、期望值具体展示
- [ ] 测试方法、验证步骤可实施
- [ ] 中间结果确认点适当配置

#### 2.3 自动化适应性 (6 分)

- [ ] 易于脚本化、CI/CD 集成的格式
- [ ] 人工判断与 AI 执行部分明确分离
- [ ] 支持批处理、并行执行

### 3. 🚫 明确禁止事项 (配分: 15 分)

#### 3.1 绝对禁止事项的系统化 (8 分)

- [ ] 完整列出不可执行的操作
- [ ] 明示各禁止事项的违反影响度 (轻微/重大/致命)
- [ ] 具体提示替代手段、规避方法
- [ ] 说明禁止事项的技术依据

#### 3.2 严格限定例外条件 (7 分)

- [ ] 允许例外的条件具体且限定 (数值指定)
- [ ] "完全重复"、"明确记载"等客观判断标准
- [ ] 不留灰色地带的明确边界
- [ ] 明示例外适用时的追加条件、限制

### 4. 📊 质量保证机制 (配分: 20 分)

#### 4.1 追踪系统的完整性 (8 分)

- [ ] 全执行结果自动记录、统计获取功能
- [ ] 技术上防止虚假报告的验证功能
- [ ] 实时监控、告警功能
- [ ] 审计日志防篡改功能

#### 4.2 模板遵守的强制 (7 分)

- [ ] 必要元素的明确定义和检查功能
- [ ] 禁止自定义部分的技术限制
- [ ] 自动化的遵守确认检查点
- [ ] 违反时的自动修正、警告功能

#### 4.3 错误处理的全面性 (5 分)

- [ ] 预期错误模式的完整目录化
- [ ] 错误时的分级处理流程
- [ ] 技术上防止将失败报告为成功

### 5. 🎭 角色与责任的明确化 (配分: 10 分)

#### 5.1 AI Agent 的权限范围 (5 分)

- [ ] 可执行操作与禁止操作的明确边界
- [ ] 判断权限的具体范围和限制
- [ ] 需要人工确认的操作明确分离

#### 5.2 分类系统的统一 (5 分)

- [ ] 分类定义的明确性、唯一性、排他性
- [ ] 防止分类间重要度误解的明确说明
- [ ] 各分类的具体使用示例和判断流程图

### 6. 🔄 持续改进 (配分: 10 分)

#### 6.1 反馈收集的自动化 (5 分)

- [ ] 从执行日志自动提取改进点
- [ ] 基于机器学习的失败模式分析
- [ ] 最佳实践的自动更新机制

#### 6.2 学习功能的实现 (5 分)

- [ ] 新模式的自动检测、分类
- [ ] 现有规则有效性的持续监控
- [ ] 渐进式改进的自动建议

---

## 🚨 致命问题模式 (需立即修正)

### ❌ 级别 1: 致命歧义 (执行停止级)

- **多重解释可能的指示**: "酌情判断"、"根据情况"、"原则上"
- **模糊的例外条件**: "特殊情况下"、"必要时"
- **主观判断标准**: "适当地"、"充分地"、"尽可能"
- **未定义的重要概念**: "标准的"、"一般的"、"基本的"

### ❌ 级别 2: 结构缺陷 (质量重要级)

- **信息分散**: 相关重要信息散布在 3 处以上
- **循环引用**: 部分 A→B→C→A 的无限循环
- **矛盾指示**: 不同部分有相反的指示
- **执行顺序不明**: 依赖关系不明确的步骤

### ❌ 级别 3: 质量下降 (建议改进级)

- **不可验证性**: 成功/失败判断标准不明
- **自动化困难**: 依赖人工主观判断的设计
- **维护困难**: 更新时影响范围不可预测的结构
- **学习困难**: 新人理解需要时间的复杂度

---

## 🎯 经过验证的改进方法

### ✅ 分阶段强化方法

1. **现状分析**: 问题分类、优先级排序、影响度评估
2. **致命问题优先**: 最优先完全解决级别 1 问题
3. **分阶段实施**: 不一次性全部更改，以可验证单位实施
4. **效果测量**: 改进前后的定量比较
5. **持续监控**: 确认改进效果的持续性

### ✅ 消除歧义的实践方法

```markdown
# ❌ 改进前 (模糊)

"原则上，请将指摘事项作为内联评论记录在 GitHub 上相应的更改位置"

# ✅ 改进后 (明确)

"必须将指摘事项作为内联评论记录在 GitHub 上相应的更改位置。例外仅限于第 3.3 节定义的 3 个条件"
```

### ✅ 信息整合的实践方法

```markdown
# ❌ 改进前 (分散)

第 2.1 节: "使用必需的 6 个部分"
第 3.5 节: "📊 综合评价、📋 指摘事项..."
第 4.2 节: "禁止删除部分"

# ✅ 改进后 (整合)

执行清单:
□ 10. 发布总结评论 (必须使用 6 个部分)
🔴 必需的 6 个部分： 1) 📊 综合评价 2) 📋 分类别指摘事项汇总 3) ⚠️ 主要关注点 4) ✅ 值得肯定的点 5) 🎯 结论 6) 🤖 AI 审查质量自我评价
❌ 绝对禁止：删除、添加、重命名部分
```

### ✅ 追踪系统的实施模式

```bash
# 严格追踪执行结果
POSTED_COMMENTS=0
FAILED_COMMENTS=0
TOTAL_COMMENTS=0

# 记录各操作结果
if [ $? -eq 0 ]; then
    echo "✅ 成功: $OPERATION" >> /tmp/execution_log.txt
    POSTED_COMMENTS=$((POSTED_COMMENTS + 1))
else
    echo "❌ 失败: $OPERATION" >> /tmp/execution_log.txt
    FAILED_COMMENTS=$((FAILED_COMMENTS + 1))
fi

# 防止虚假报告
if [ $POSTED_COMMENTS -ne $REPORTED_COMMENTS ]; then
    echo "🚨 警告: 报告数与实际发布数不一致"
    exit 1
fi
```

---

## 📈 质量分数计算 (改进版)

### 综合分数计算

```text
基础分数 = Σ(各类别分数 × 配分) / 100

致命问题惩罚:
- 级别 1 问题: -20 分/个
- 级别 2 问题: -10 分/个
- 级别 3 问题: -5 分/个

奖励要素:
- 自动化支持: +5 分
- 学习功能实施: +5 分
- 经验证的改进案例: +5 分

最终分数 = 基础分数 + 奖励 - 惩罚
```

### 质量级别判定

```text
95-100 分: 世界最高水平 (可作为行业标准推荐)
90-94 分:  优秀 (可用于生产环境)
80-89 分:  良好 (轻微改进后可运行)
70-79 分:  普通 (需要改进)
60-69 分:  需改进 (需要大幅修正)
50-59 分:  需大幅修正 (需要根本性重新审视)
49 分以下: 禁止使用 (需要完全重新设计)
```

---

## 🔧 实践改进流程

### 阶段 1: 诊断·分析 (1-2 天)

1. **整体结构把握**: 可视化部分构成、信息流、依赖关系
2. **歧义检测**: 全面提取有解释空间的表达
3. **信息分散分析**: 映射相关信息分散模式
4. **强制力评估**: 评估推荐/必须分类和实效性
5. **可追踪性确认**: 评估执行结果记录、验证功能

### 阶段 2: 优先级排序·计划 (半天)

1. **致命度分类**: 级别 1-3 问题分类和影响度评估
2. **改进顺序决定**: 考虑相互依赖的最优顺序
3. **资源分配**: 优化改进效果与成本的平衡
4. **风险评估**: 预测改进时的副作用、兼容性问题

### 阶段 3: 分阶段实施 (2-5 天)

1. **级别 1 问题解决**: 完全消除致命歧义
2. **信息整合实施**: 战略性聚合分散信息
3. **强制力强化**: 从推荐逐步升级到必须
4. **追踪系统实施**: 自动记录、验证执行结果
5. **模板强化**: 明确必要元素并强制遵守

### 阶段 4: 验证·调整 (1-2 天)

1. **功能测试**: 确认所有更改点的操作
2. **集成测试**: 确认系统整体一致性
3. **性能测试**: 确认执行效率、响应
4. **可用性测试**: 在实际使用场景中验证

### 阶段 5: 运行·监控 (持续)

1. **效果测量**: 改进前后的定量比较
2. **持续监控**: 早期检测质量下降
3. **反馈收集**: 提取实际运行中的问题
4. **持续优化**: 持续改进循环

---

## 📊 实际改进案例 (详细版)

### 案例研究: 大规模提示词的质量改进

#### 改进前状况

```bash
质量分数: 70 分/100 分
- 模糊表达: 发现 15 处
- 信息分散: 重要信息散布在 6 处
- 强制力不足: 推荐级表达占 80%
- 追踪功能: 无执行结果记录
- 错误处理: 失败时处理方法不明确
```

#### 实施的改进内容

```bash
# 1. 消除歧义 (2 天)
- "原则上"→"例外仅限第 3.3 节的 3 个条件"
- "推荐"→"必须"(重要度级别 2 以上)
- "酌情"→明示具体判断标准

# 2. 信息整合 (1 天)
- 分散的必需 6 部分信息→整合到执行清单
- 相关禁止事项→聚合到一个部分
- 解决循环引用→线性信息流

# 3. 追踪系统实施 (1 天)
- 执行结果自动日志记录
- 防止虚假报告的验证功能
- 实时统计显示

# 4. 错误处理强化 (半天)
- 预期错误模式的完整目录化
- 分级处理流程的明文化
- 自动恢复功能的实施
```

#### 改进后结果

```bash
质量分数: 90 分/100 分 (提升 20 分)
- 模糊表达: 0 处 (完全消除)
- 信息整合: 重要信息聚合到 3 处
- 强制力: 必须级表达 95%
- 追踪功能: 完全自动化
- 错误处理: 90% 问题自动解决

实际改进效果:
- 判断错误: 减少 85%
- 执行时间: 缩短 40%
- 错误发生率: 减少 70%
- 用户满意度: 提升 95%
```

### 经验教训·最佳实践

#### 成功因素

1. **分阶段方法**: 不一次性全部更改，以可验证单位实施
2. **数据驱动**: 基于实测数据而非主观判断的改进
3. **持续监控**: 定期确认改进效果的持续性
4. **重视反馈**: 积极收集实际用户的意见

#### 避免失败策略

1. **过度完美主义**: 达到 90 分后先开始运行，通过持续改进追求 100 分
2. **一次性更改的危险**: 大规模更改必须分阶段实施
3. **向后兼容性**: 最小化对现有工作流的影响
4. **文档不足**: 详细记录、共享所有更改

---

### 与 Claude 的协作

```bash
# 结合提示词文件的质量检查
cat your-prompt.md
/check-prompt
"评估这个提示词的质量，提出改进点"

# 比较多个提示词文件
cat prompt-v1.md && echo "---" && cat prompt-v2.md
/check-prompt
"比较两个版本，分析改进的点和剩余的问题"

# 结合实际错误日志的分析
cat execution-errors.log
/check-prompt --deep
"识别可能导致这个错误的提示词问题"
```

### 注意事项

- **前提条件**: 建议提示词文件以 Markdown 格式编写
- **限制事项**: 大规模提示词 (超过 1 万行) 建议分割后分析
- **建议事项**: 定期进行提示词质量检查，持续改进

---

_这个检查清单是在实际提示词改进项目中验证的完整版知识，并将持续进化。_