gh-wasabeef-claude-code-cookbook-plugins-zh-cn/commands/check-prompt.md

提示词检查

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

✅ 消除歧义的实践方法

# ❌ 改进前 (模糊)

"原则上，请将指摘事项作为内联评论记录在 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 天)

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. 持续优化: 持续改进循环

---

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

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

改进前状况

质量分数: 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%

经验教训·最佳实践

成功因素

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

避免失败策略

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

---

与 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 万行) 建议分割后分析
• 建议事项: 定期进行提示词质量检查，持续改进

---

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