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