Rules Distill (규칙 증류)
설치된 스킬을 스캔하고, 여러 스킬에 걸쳐 나타나는 교차 원칙을 추출하여 이를 규칙으로 증류합니다. 즉, 기존 규칙 파일에 추가하거나, 오래된 내용을 수정하거나, 새로운 규칙 파일을 생성합니다.
"결정론적 수집 + LLM 판단" 원칙을 적용합니다: 스크립트는 사실을 빠짐없이 수집하고, LLM이 전체 컨텍스트를 교차 분석하여 판정을 내립니다.
사용 시기
- 정기적인 규칙 유지보수 (월 1회 또는 새 스킬 설치 후)
- 스킬 목록 검토 후 패턴이 발견되어 규칙으로 승격해야 할 때
- 현재 사용 중인 스킬에 비해 규칙이 불완전하다고 느껴질 때
작동 방식
규칙 증류 프로세스는 세 단계로 이루어집니다.
1단계: 인벤토리 (결정론적 수집)
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
────────────────────────────────────────
Skills: {N} files scanned
Rules: {M} files ({K} headings indexed)
Proceeding to cross-read analysis...
2단계: 교차 분석, 매칭 및 판정 (LLM 판단)
추출과 매칭은 단일 패스로 통합됩니다. 규칙 파일은 총 약 800줄로 충분히 작기 때문에 LLM에 전체 텍스트를 제공할 수 있으며, grep을 통한 사전 필터링이 필요하지 않습니다.
배치 처리
스킬을 설명에 따라 주제별 클러스터로 그룹화합니다. 각 클러스터를 하위 에이전트(subagent)에서 전체 규칙 텍스트와 함께 분석합니다.
배치 간 병합
모든 배치가 완료된 후, 배치 간 후보를 병합합니다:
- 동일하거나 중복되는 원칙을 가진 후보를 제거합니다
- 모든 배치의 증거를 결합하여 "2개 이상의 스킬" 요구 사항을 재확인합니다. 즉, 각 배치에서 1개 스킬에만 나타났지만 전체적으로 2개 이상의 스킬에서 발견된 원칙은 유효합니다.
하위 에이전트 프롬프트
범용 에이전트를 다음 프롬프트로 실행합니다:
당신은 스킬을 교차 분석하여 규칙으로 승격해야 할 원칙을 추출하는 분석가입니다.
## 입력
- 스킬: {이 배치의 스킬 전체 텍스트}
- 기존 규칙: {모든 규칙 파일의 전체 텍스트}
## 추출 기준
다음 조건을 **모두** 충족하는 경우에만 후보로 포함하십시오:
1. **2개 이상의 스킬에 나타남**: 하나의 스킬에만 있는 원칙은 해당 스킬에 남겨야 합니다.
2. **실행 가능한 행동 변화**: "X를 하라" 또는 "Y를 하지 말라" 형태로 작성 가능해야 하며, "X는 중요하다" 형태는 안 됩니다.
3. **명확한 위반 위험**: 이 원칙을 무시했을 때 무엇이 잘못되는지 한 문장으로 설명할 수 있어야 합니다.
4. **아직 규칙에 없음**: 전체 규칙 텍스트를 확인하십시오. 다른 표현으로 작성된 개념도 포함됩니다.
## 매칭 및 판정
각 후보에 대해 전체 규칙 텍스트와 비교하여 다음 판정 중 하나를 할당하십시오:
- **Append (추가)**: 기존 규칙 파일의 기존 섹션에 추가합니다.
- **Revise (수정)**: 기존 규칙 내용이 부정확하거나 불충분합니다. 수정안을 제시하십시오.
- **New Section (새 섹션)**: 기존 규칙 파일에 새 섹션을 추가합니다.
- **New File (새 파일)**: 새로운 규칙 파일을 생성합니다.
- **Already Covered (이미 포함됨)**: 기존 규칙에 충분히 포함되어 있습니다 (다른 표현이라도).
- **Too Specific (너무 구체적임)**: 스킬 수준에 남아 있어야 합니다.
## 출력 형식 (후보당)
```json
{
"principle": "'X를 하라' / 'Y를 하지 말라' 형태의 1-2문장",
"evidence": ["skill-name: §Section", "skill-name: §Section"],
"violation_risk": "한 문장",
"verdict": "Append / Revise / New Section / New File / Already Covered / Too Specific",
"target_rule": "파일명 §섹션, 또는 '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 | 규칙에 포함됨 (다른 표현 가능) | 이유 (1줄) |
| 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 보안 원칙 추가
3단계: 사용자 검토 및 실행
요약 테이블
# Rules Distillation Report
## Summary
Skills scanned: {N} | Rules: {M} files | Candidates: {K}
| # | Principle | Verdict | Target | Confidence |
|---|-----------|---------|--------|------------|
| 1 | ... | Append | security.md §Input Validation | high |
| 2 | ... | Revise | testing.md §TDD | medium |
| 3 | ... | New Section | coding-style.md | high |
| 4 | ... | Too Specific | — | — |
## Details
(후보별 세부 정보: 증거, 위반 위험, 초안 텍스트)
사용자 액션
사용자는 번호로 응답합니다:
- Approve: 초안을 그대로 규칙에 적용
- Modify: 적용 전에 초안 편집
- Skip: 이 후보는 적용하지 않음
절대로 규칙을 자동으로 수정하지 마십시오. 항상 사용자 승인이 필요합니다.
결과 저장
결과를 스킬 디렉토리에 저장합니다 (results.json):
- 타임스탬프 형식:
date -u +%Y-%m-%dT%H:%M:%SZ(UTC, 초 단위 정밀도) - 후보 ID 형식: 원칙에서 파생된 케밥-케이스 (예:
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
────────────────────────────────────────
Skills: 56 files scanned
Rules: 22 files (75 headings indexed)
Proceeding to cross-read analysis...
[Subagent analysis: Batch 1 (agent/meta skills) ...]
[Subagent analysis: Batch 2 (coding/pattern skills) ...]
[Cross-batch merge: 2 duplicates removed, 1 cross-batch candidate promoted]
# Rules Distillation Report
## Summary
Skills scanned: 56 | Rules: 22 files | Candidates: 4
| # | Principle | Verdict | Target | Confidence |
|---|-----------|---------|--------|------------|
| 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 |
## Details
### 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 세부 정보 ...]
각 후보를 승인, 수정 또는 건너뛰려면 번호를 입력하십시오:
> User: Approve 1, 3. Skip 2, 4.
✓ Applied: coding-style.md §LLM Output Validation
✓ Applied: performance.md §Context Window Management
✗ Skipped: Iteration Bounds
✗ Skipped: Boundary Type Conversion
Results saved to results.json
설계 원칙
- 무엇(What)이지, 방법(How)이 아님: 원칙(규칙 영역)만 추출합니다. 코드 예제와 명령어는 스킬에 남습니다.
- 역참조: 초안 텍스트에는
관련 스킬: [이름]참조를 포함하여 독자가 자세한 방법을 찾을 수 있도록 합니다. - 결정론적 수집, LLM 판단: 스크립트는 완전성을 보장하고, LLM은 컨텍스트 이해를 보장합니다.
- 추상화 방지 장치: 3단계 필터(2개 이상 스킬 증거, 실행 가능한 행동 테스트, 위반 위험)는 너무 추상적인 원칙이 규칙에 포함되는 것을 방지합니다.