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 万行) 建議分割後分析
- 建議事項: 定期進行提示詞質量檢查，持續改進
這個檢查清單是在實際提示詞改進項目中驗證的完整版知識，並將持續進化。