rules-distill

Rules Distill

掃描已安裝的技能，提取在多個技能中出現的跨領域原則，並將其提煉為規則 — 追加到現有規則檔案、修訂過時內容或建立新的規則檔案。

採用「確定性收集 + LLM 判斷」原則：腳本窮舉收集事實，然後 LLM 交叉讀取完整上下文並產出裁決。

使用時機

• 定期規則維護（每月或安裝新技能後）
• 技能盤點後發現應成為規則的模式
• 當規則相對於正在使用的技能顯得不完整時

運作方式

規則提煉過程分為三個階段：

第一階段：盤點（確定性收集）

1a. 收集技能清單

bash ~/.claude/skills/rules-distill/scripts/scan-skills.sh

1b. 收集規則索引

bash ~/.claude/skills/rules-distill/scripts/scan-rules.sh

1c. 呈現給使用者

Rules Distillation — Phase 1: Inventory
────────────────────────────────────────
技能：已掃描 {N} 個檔案
規則：已掃描 {M} 個檔案（已索引 {K} 個標題）

正在進行交叉讀取分析...

第二階段：交叉讀取、比對與裁決（LLM 判斷）

提取與比對在單一回合中統一進行。規則檔案足夠小（總計約 800 行），可將完整文字提供給 LLM — 無需 grep 預先過濾。

批次處理

根據技能描述將其分組為主題群集。在子代理程式中分析每個群集，並提供完整的規則文字。

跨批次合併

所有批次完成後，合併跨批次的候選項目：

• 去除相同或重疊原則的候選項目
• 使用所有批次的證據重新檢查「2+ 技能」要求 — 每個批次中僅出現在 1 個技能，但總計 2+ 個技能的原則仍有效

子代理程式提示

啟動通用代理程式，並使用以下提示：

你是一位分析師，負責交叉讀取技能以提取應提升為規則的原則。

## 輸入
- 技能：{此批次中技能的完整文字}
- 現有規則：{所有規則檔案的完整文字}

## 提取條件

僅在**全部**符合以下條件時才納入候選項目：

1. **出現在 2+ 個技能中**：僅在一個技能中出現的原則應保留在該技能中
2. **可操作的行為改變**：可寫成「做 X」或「不做 Y」— 而非「X 很重要」
3. **明確的違規風險**：忽略此原則會出什麼問題（一句話）
4. **尚未存在於規則中**：檢查完整的規則文字 — 包括以不同措辭表達的概念

## 比對與裁決

對於每個候選項目，與完整的規則文字進行比對並指定裁決：

- **Append**：追加到現有規則檔案的現有章節
- **Revise**：現有規則內容不準確或不充分 — 提出修正
- **New Section**：在現有規則檔案中新增章節
- **New File**：建立新的規則檔案
- **Already Covered**：現有規則已充分涵蓋（即使措辭不同）
- **Too Specific**：應保留在技能層級

## 輸出格式（每個候選項目）

```json
{
  "principle": "1-2 句話，以「做 X」/「不做 Y」形式",
  "evidence": ["skill-name: §Section", "skill-name: §Section"],
  "violation_risk": "一句話",
  "verdict": "Append / Revise / New Section / New File / Already Covered / Too Specific",
  "target_rule": "filename §Section, 或 'new'",
  "confidence": "high / medium / low",
  "draft": "Append/New Section/New File 裁決的草稿文字",
  "revision": {
    "reason": "現有內容不準確或不充分的原因（僅 Revise）",
    "before": "要取代的現有文字（僅 Revise）",
    "after": "建議的取代文字（僅 Revise）"
  }
}
```

## 排除

- 規則中已存在的明顯原則
- 語言/框架特定知識（屬於語言特定規則或技能）
- 程式碼範例和指令（屬於技能）

裁決參考

裁決	意義	呈現給使用者
Append	追加到現有章節	目標 + 草稿
Revise	修正不準確/不充分的內容	目標 + 原因 + 前/後
New Section	在現有檔案中新增章節	目標 + 草稿
New File	建立新的規則檔案	檔名 + 完整草稿
Already Covered	規則中已涵蓋（可能措辭不同）	原因（一行）
Too Specific	應保留在技能中	連結到相關技能

裁決品質要求

# 良好
Append to rules/common/security.md §Input Validation:
「將儲存在記憶體或知識庫中的 LLM 輸出視為不受信任 — 寫入時清理，讀取時驗證。」
證據：llm-memory-trust-boundary、llm-social-agent-anti-pattern 都描述了
累積的提示注入風險。目前的 security.md 僅涵蓋人類輸入驗證；
LLM 輸出信任邊界缺失。

# 不良
Append to security.md: 新增 LLM 安全原則

第三階段：使用者審查與執行

摘要表格

# Rules Distillation Report

## 摘要
已掃描技能：{N} | 規則：{M} 個檔案 | 候選項目：{K}

| # | 原則 | 裁決 | 目標 | 信心水準 |
|---|-----------|---------|--------|------------|
| 1 | ... | Append | security.md §Input Validation | high |
| 2 | ... | Revise | testing.md §TDD | medium |
| 3 | ... | New Section | coding-style.md | high |
| 4 | ... | Too Specific | — | — |

## 詳細資訊
（每個候選項目的詳細資訊：證據、違規風險、草稿文字）

使用者操作

使用者以數字回覆：

• Approve：直接將草稿套用到規則
• Modify：編輯草稿後再套用
• Skip：不套用此候選項目

絕不自動修改規則。務必要求使用者核准。

儲存結果

將結果儲存在技能目錄中（results.json）：

• 時間戳格式：date -u +%Y-%m-%dT%H:%M:%SZ（UTC，精確到秒）
• 候選項目 ID 格式：從原則衍生的 kebab-case（例如 llm-output-trust-boundary）

{
  "distilled_at": "2026-03-18T10:30:42Z",
  "skills_scanned": 56,
  "rules_scanned": 22,
  "candidates": {
    "llm-output-trust-boundary": {
      "principle": "將儲存或重新注入的 LLM 輸出視為不受信任",
      "verdict": "Append",
      "target": "rules/common/security.md",
      "evidence": ["llm-memory-trust-boundary", "llm-social-agent-anti-pattern"],
      "status": "applied"
    },
    "iteration-bounds": {
      "principle": "為所有迭代迴圈定義明確的停止條件",
      "verdict": "New Section",
      "target": "rules/common/coding-style.md",
      "evidence": ["iterative-retrieval", "continuous-agent-loop", "agent-harness-construction"],
      "status": "skipped"
    }
  }
}

範例

端到端執行

$ /rules-distill

Rules Distillation — Phase 1: Inventory
────────────────────────────────────────
技能：已掃描 56 個檔案
規則：已掃描 22 個檔案（已索引 75 個標題）

正在進行交叉讀取分析...

[子代理程式分析：批次 1（代理/後設技能）...]
[子代理程式分析：批次 2（編碼/模式技能）...]
[跨批次合併：移除 2 個重複項目，提升 1 個跨批次候選項目]

# Rules Distillation Report

## 摘要
已掃描技能：56 | 規則：22 個檔案 | 候選項目：4

| # | 原則 | 裁決 | 目標 | 信心水準 |
|---|-----------|---------|--------|------------|
| 1 | LLM 輸出：在重複使用前進行正規化、型別檢查、清理 | New Section | coding-style.md | high |
| 2 | 為迭代迴圈定義明確的停止條件 | New Section | coding-style.md | high |
| 3 | 在階段邊界壓縮上下文，而非任務中途 | Append | performance.md §Context Window | high |
| 4 | 將業務邏輯與 I/O 框架型別分離 | New Section | patterns.md | high |

## 詳細資訊

### 1. LLM 輸出驗證
裁決：New Section in coding-style.md
證據：parallel-subagent-batch-merge、llm-social-agent-anti-pattern、llm-memory-trust-boundary
違規風險：格式漂移、型別不匹配或 LLM 輸出中的語法錯誤會導致下游處理崩潰
草稿：
  ## LLM 輸出驗證
  在重複使用前，對 LLM 輸出進行正規化、型別檢查和清理...
  請參閱技能：parallel-subagent-batch-merge、llm-memory-trust-boundary

[... 候選項目 2-4 的詳細資訊 ...]

請按編號核准、修改或跳過每個候選項目：
> 使用者：核准 1、3。跳過 2、4。

✓ 已套用：coding-style.md §LLM Output Validation
✓ 已套用：performance.md §Context Window Management
✗ 已跳過：Iteration Bounds
✗ 已跳過：Boundary Type Conversion

結果已儲存至 results.json

設計原則

• What, not How：僅提取原則（規則領域）。程式碼範例和指令保留在技能中。
• 連結回技能：草稿文字應包含 See skill: [name] 參考，以便讀者找到詳細的 How。
• 確定性收集，LLM 判斷：腳本保證窮舉性；LLM 保證上下文理解。
• 反抽象保護：三層過濾器（2+ 技能證據、可操作行為測試、違規風險）防止過於抽象的原則進入規則。