## 提示詞檢查

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 万行) 建議分割後分析
- **建議事項**: 定期進行提示詞質量檢查，持續改進

---

_這個檢查清單是在實際提示詞改進項目中驗證的完整版知識，並將持續進化。_