462 lines
13 KiB
Markdown
462 lines
13 KiB
Markdown
## 提示词检查
|
||
|
||
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 万行) 建议分割后分析
|
||
- **建议事项**: 定期进行提示词质量检查，持续改进
|
||
|
||
---
|
||
|
||
_这个检查清单是在实际提示词改进项目中验证的完整版知识，并将持续进化。_
|