Rules Distill (규칙 증류)
설치된 스킬을 스캔하고, 여러 스킬에 공통으로 나타나는 교차 원칙을 추출하여 규칙 파일에 추가하거나, 오래된 내용을 수정하거나, 새로운 규칙 파일을 만듭니다.
'결정론적 수집 + LLM 판단' 원칙을 적용합니다. 스크립트가 사실을 완전히 수집하고, LLM이 전체 컨텍스트를 교차 분석하여 최종 판단을 내립니다.
사용 시점
- 정기적인 규칙 유지보수(월간 또는 새 스킬 설치 후)
- 스킬 목록 검토 후 규칙화해야 할 패턴이 발견되었을 때
- 현재 규칙이 사용 중인 스킬에 비해 불완전하다고 느낄 때
작동 방식
규칙 증류 프로세스는 세 단계로 진행됩니다.
1단계: 인벤토리 (결정론적 수집)
1a. 스킬 인벤토리 수집
bash ~/.claude/skills/rules-distill/scripts/scan-skills.sh
1b. 규칙 인덱스 수집
bash ~/.claude/skills/rules-distill/scripts/scan-rules.sh
1c. 사용자에게 제시
규칙 증류 — 1단계: 인벤토리
────────────────────────────────────────
스킬: {N}개 파일 스캔됨
규칙: {M}개 파일 ({K}개 헤딩 인덱싱됨)
교차 분석을 진행합니다...
2단계: 교차 분석, 매칭 및 평결 (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": "'X를 하라' / 'Y를 하지 말라' 형식의 1-2문장",
"evidence": ["skill-name: §Section", "skill-name: §Section"],
"violation_risk": "1문장",
"verdict": "Append / Revise / New Section / New File / Already Covered / Too Specific",
"target_rule": "파일명 §Section, 또는 'new'",
"confidence": "high / medium / low",
"draft": "Append/New Section/New File 평결에 대한 초안 텍스트",
"revision": {
"reason": "기존 내용이 부정확하거나 불충분한 이유 (Revise만 해당)",
"before": "교체될 현재 텍스트 (Revise만 해당)",
"after": "제안된 교체 텍스트 (Revise만 해당)"
}
}
```
## 제외
- 이미 규칙에 있는 명백한 원칙
- 언어/프레임워크별 지식 (언어별 규칙이나 스킬에 속함)
- 코드 예제 및 명령어 (스킬에 속함)
평결 참조
| 평결 | 의미 | 사용자에게 제시 |
|---|---|---|
| 추가 (Append) | 기존 섹션에 추가 | 대상 + 초안 |
| 수정 (Revise) | 부정확/불충분한 내용 수정 | 대상 + 이유 + before/after |
| 새 섹션 (New Section) | 기존 파일에 새 섹션 추가 | 대상 + 초안 |
| 새 파일 (New File) | 새 규칙 파일 생성 | 파일명 + 전체 초안 |
| 이미 포함됨 (Already Covered) | 규칙에 포함됨 (다른 표현일 수 있음) | 이유 (1줄) |
| 너무 구체적 (Too Specific) | 스킬에 남아 있어야 함 | 관련 스킬 링크 |
평결 품질 요구사항
# 좋은 예
rules/common/security.md §Input Validation에 추가:
"메모리나 지식 저장소에 저장된 LLM 출력을 신뢰하지 않는 것으로 취급하세요 — 쓰기 시 위생 처리, 읽기 시 검증."
증거: llm-memory-trust-boundary, llm-social-agent-anti-pattern 모두
누적된 프롬프트 인젝션 위험을 설명함. 현재 security.md는 사람 입력 검증만 다루고,
LLM 출력 신뢰 경계는 누락됨.
# 나쁜 예
security.md에 추가: LLM 보안 원칙 추가
3단계: 사용자 검토 및 실행
요약 테이블
# 규칙 증류 보고서
## 요약
스킬 스캔됨: {N} | 규칙: {M}개 파일 | 후보: {K}개
| # | 원칙 | 평결 | 대상 | 신뢰도 |
|---|-----------|---------|--------|------------|
| 1 | ... | 추가 | security.md §Input Validation | 높음 |
| 2 | ... | 수정 | testing.md §TDD | 중간 |
| 3 | ... | 새 섹션 | coding-style.md | 높음 |
| 4 | ... | 너무 구체적 | — | — |
## 세부사항
(후보별 세부사항: 증거, 위반 위험, 초안 텍스트)
사용자 액션
사용자는 번호로 응답합니다.
- 승인 (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
규칙 증류 — 1단계: 인벤토리
────────────────────────────────────────
스킬: 56개 파일 스캔됨
규칙: 22개 파일 (75개 헤딩 인덱싱됨)
교차 분석을 진행합니다...
[서브에이전트 분석: 배치 1 (에이전트/메타 스킬) ...]
[서브에이전트 분석: 배치 2 (코딩/패턴 스킬) ...]
[배치 간 병합: 중복 2개 제거, 배치 간 후보 1개 승격]
# 규칙 증류 보고서
## 요약
스킬 스캔됨: 56 | 규칙: 22개 파일 | 후보: 4개
| # | 원칙 | 평결 | 대상 | 신뢰도 |
|---|-----------|---------|--------|------------|
| 1 | LLM 출력: 재사용 전 정규화, 타입 검사, 위생 처리 | 새 섹션 | coding-style.md | 높음 |
| 2 | 반복 루프에 명시적 중단 조건 정의 | 새 섹션 | coding-style.md | 높음 |
| 3 | 단계 경계에서 컨텍스트 압축, 작업 중간이 아닌 때 | 추가 | performance.md §Context Window | 높음 |
| 4 | 비즈니스 로직과 I/O 프레임워크 타입 분리 | 새 섹션 | patterns.md | 높음 |
## 세부사항
### 1. LLM 출력 검증
평결: 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)이지, 방법(How)이 아님: 원칙(규칙 영역)만 추출합니다. 코드 예제와 명령어는 스킬에 남습니다.
- 역링크 제공: 초안 텍스트에
참조 스킬: [이름]을 포함시켜 독자가 자세한 방법을 찾을 수 있도록 합니다. - 결정론적 수집, LLM 판단: 스크립트는 완전성을 보장하고, LLM은 상황적 이해를 보장합니다.
- 추상화 방지 장치: 3단계 필터(2개 이상 스킬 증거, 실행 가능한 행동 테스트, 위반 위험)는 지나치게 추상적인 원칙이 규칙에 들어오는 것을 방지합니다.