13 KiB
13 KiB
提示词检查
AI Agent 提示词质量评估与改进的全面最佳实践集。基于实际提示词改进过程中积累的经验，系统化地涵盖了消除歧义、信息整合、强制力强化、追踪系统、持续改进等所有重要方面。
使用方法
# 检查提示词文件的质量
cat your-prompt.md
/check-prompt
"检查这个提示词的质量并提出改进建议"
选项
- 无 : 分析当前文件或选中的文本
--category <name>: 仅检查特定类别 (structure/execution/restrictions/quality/roles/improvement)--score: 仅计算质量分数--fix: 自动修正建议--deep: 深度分析模式 (重点检查歧义性、信息分散、强制力)
基本示例
# 提示词整体质量评估
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 问题
- 分阶段实施: 不一次性全部更改，以可验证单位实施
- 效果测量: 改进前后的定量比较
- 持续监控: 确认改进效果的持续性
✅ 消除歧义的实践方法
# ❌ 改进前 (模糊)
"原则上，请将指摘事项作为内联评论记录在 GitHub 上相应的更改位置"
# ✅ 改进后 (明确)
"必须将指摘事项作为内联评论记录在 GitHub 上相应的更改位置。例外仅限于第 3.3 节定义的 3 个条件"
✅ 信息整合的实践方法
# ❌ 改进前 (分散)
第 2.1 节: "使用必需的 6 个部分"
第 3.5 节: "📊 综合评价、📋 指摘事项..."
第 4.2 节: "禁止删除部分"
# ✅ 改进后 (整合)
执行清单:
□ 10. 发布总结评论 (必须使用 6 个部分)
🔴 必需的 6 个部分： 1) 📊 综合评价 2) 📋 分类别指摘事项汇总 3) ⚠️ 主要关注点 4) ✅ 值得肯定的点 5) 🎯 结论 6) 🤖 AI 审查质量自我评价
❌ 绝对禁止：删除、添加、重命名部分
✅ 追踪系统的实施模式
# 严格追踪执行结果
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
📈 质量分数计算 (改进版)
综合分数计算
基础分数 = Σ(各类别分数 × 配分) / 100
致命问题惩罚:
- 级别 1 问题: -20 分/个
- 级别 2 问题: -10 分/个
- 级别 3 问题: -5 分/个
奖励要素:
- 自动化支持: +5 分
- 学习功能实施: +5 分
- 经验证的改进案例: +5 分
最终分数 = 基础分数 + 奖励 - 惩罚
质量级别判定
95-100 分: 世界最高水平 (可作为行业标准推荐)
90-94 分: 优秀 (可用于生产环境)
80-89 分: 良好 (轻微改进后可运行)
70-79 分: 普通 (需要改进)
60-69 分: 需改进 (需要大幅修正)
50-59 分: 需大幅修正 (需要根本性重新审视)
49 分以下: 禁止使用 (需要完全重新设计)
🔧 实践改进流程
阶段 1: 诊断·分析 (1-2 天)
- 整体结构把握: 可视化部分构成、信息流、依赖关系
- 歧义检测: 全面提取有解释空间的表达
- 信息分散分析: 映射相关信息分散模式
- 强制力评估: 评估推荐/必须分类和实效性
- 可追踪性确认: 评估执行结果记录、验证功能
阶段 2: 优先级排序·计划 (半天)
- 致命度分类: 级别 1-3 问题分类和影响度评估
- 改进顺序决定: 考虑相互依赖的最优顺序
- 资源分配: 优化改进效果与成本的平衡
- 风险评估: 预测改进时的副作用、兼容性问题
阶段 3: 分阶段实施 (2-5 天)
- 级别 1 问题解决: 完全消除致命歧义
- 信息整合实施: 战略性聚合分散信息
- 强制力强化: 从推荐逐步升级到必须
- 追踪系统实施: 自动记录、验证执行结果
- 模板强化: 明确必要元素并强制遵守
阶段 4: 验证·调整 (1-2 天)
- 功能测试: 确认所有更改点的操作
- 集成测试: 确认系统整体一致性
- 性能测试: 确认执行效率、响应
- 可用性测试: 在实际使用场景中验证
阶段 5: 运行·监控 (持续)
- 效果测量: 改进前后的定量比较
- 持续监控: 早期检测质量下降
- 反馈收集: 提取实际运行中的问题
- 持续优化: 持续改进循环
📊 实际改进案例 (详细版)
案例研究: 大规模提示词的质量改进
改进前状况
质量分数: 70 分/100 分
- 模糊表达: 发现 15 处
- 信息分散: 重要信息散布在 6 处
- 强制力不足: 推荐级表达占 80%
- 追踪功能: 无执行结果记录
- 错误处理: 失败时处理方法不明确
实施的改进内容
# 1. 消除歧义 (2 天)
- "原则上"→"例外仅限第 3.3 节的 3 个条件"
- "推荐"→"必须"(重要度级别 2 以上)
- "酌情"→明示具体判断标准
# 2. 信息整合 (1 天)
- 分散的必需 6 部分信息→整合到执行清单
- 相关禁止事项→聚合到一个部分
- 解决循环引用→线性信息流
# 3. 追踪系统实施 (1 天)
- 执行结果自动日志记录
- 防止虚假报告的验证功能
- 实时统计显示
# 4. 错误处理强化 (半天)
- 预期错误模式的完整目录化
- 分级处理流程的明文化
- 自动恢复功能的实施
改进后结果
质量分数: 90 分/100 分 (提升 20 分)
- 模糊表达: 0 处 (完全消除)
- 信息整合: 重要信息聚合到 3 处
- 强制力: 必须级表达 95%
- 追踪功能: 完全自动化
- 错误处理: 90% 问题自动解决
实际改进效果:
- 判断错误: 减少 85%
- 执行时间: 缩短 40%
- 错误发生率: 减少 70%
- 用户满意度: 提升 95%
经验教训·最佳实践
成功因素
- 分阶段方法: 不一次性全部更改，以可验证单位实施
- 数据驱动: 基于实测数据而非主观判断的改进
- 持续监控: 定期确认改进效果的持续性
- 重视反馈: 积极收集实际用户的意见
避免失败策略
- 过度完美主义: 达到 90 分后先开始运行，通过持续改进追求 100 分
- 一次性更改的危险: 大规模更改必须分阶段实施
- 向后兼容性: 最小化对现有工作流的影响
- 文档不足: 详细记录、共享所有更改
与 Claude 的协作
# 结合提示词文件的质量检查
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 万行) 建议分割后分析
- 建议事项: 定期进行提示词质量检查，持续改进
这个检查清单是在实际提示词改进项目中验证的完整版知识，并将持续进化。