rules-distill

name	rules-distill
description	스킬을 스캔하여 횡단적 원칙을 추출하고 이를 규칙으로 정제합니다 — 규칙 파일에 추가, 수정 또는 신규 생성
origin	ECC

규칙 추출 (Rules Distill)

설치된 스킬들을 스캔하여 여러 스킬에 공통적으로 나타나는 횡단적 원칙(cross-cutting principles)을 추출하고, 이를 규칙으로 정제합니다. 기존 규칙 파일에 내용을 추가하거나, 오래된 내용을 수정하거나, 새로운 규칙 파일을 생성합니다.

"결정적 수집 + LLM 판단" 원칙을 적용합니다: 스크립트가 사실을 남김없이 수집하고, LLM이 전체 컨텍스트를 교차 검토하여 판정을 내립니다.

사용 시점

• 정기적인 규칙 유지보수 시 (매월 또는 새로운 스킬 설치 후)
• skill-stocktake 결과, 규칙으로 승격시켜야 할 패턴이 발견되었을 때
• 사용 중인 스킬들에 비해 규칙이 부족하다고 느껴질 때

동작 방식

규칙 추출 프로세스는 다음 세 단계로 진행됩니다.

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행 미만) 별도의 grep 필터링 없이 전체 텍스트를 LLM에 제공할 수 있습니다.

배치 처리 (Batching)

스킬 설명에 따라 주제별 클러스터로 그룹화합니다. 각 클러스터를 하위 에이전트(subagent)에서 전체 규칙 텍스트와 함께 분석합니다.

배치 간 병합 (Cross-batch Merge)

모든 배치가 완료되면 배치 간 후보들을 병합합니다:

• 동일하거나 겹치는 원칙을 가진 후보의 중복을 제거합니다.
• 모든 배치의 증거를 결합하여 "2개 이상의 스킬" 요건을 재확인합니다. (각 배치에서는 1개의 스킬만 해당하더라도 전체에서 2개 이상의 스킬이 발견되면 유효합니다)

하위 에이전트 프롬프트

다음 프롬프트를 사용하여 범용 에이전트를 실행합니다.

당신은 스킬들을 교차 검토하여 규칙으로 승격시켜야 할 원칙을 추출하는 분석가입니다.

## 입력
- 스킬: {이 배치에 포함된 스킬의 전체 텍스트}
- 기존 규칙: {모든 규칙 파일의 전체 텍스트}

## 추출 기준

다음 조건을 모두 만족하는 후보만 포함하세요:

1. **2개 이상의 스킬에서 발견됨**: 단 하나의 스킬에서만 발견되는 원칙은 해당 스킬에만 머물러야 합니다.
2. **실행 가능한 행동 변화**: "X는 중요하다"가 아니라 "X를 하라" 또는 "Y를 하지 마라" 형태로 작성될 수 있어야 합니다.
3. **명확한 위반 리스크**: 이 원칙을 무시했을 때 어떤 문제가 발생하는지 설명할 수 있어야 합니다 (1문장).
4. **기존 규칙에 없음**: 표현 방식이 다르더라도 동일한 개념이 이미 규칙에 있는지 전체 텍스트를 확인하세요.

## 매칭 및 판정

각 후보를 전체 규칙 텍스트와 비교하여 판정을 내립니다:

- **추가 (Append)**: 기존 규칙 파일의 기존 섹션에 추가
- **수정 (Revise)**: 기존 규칙 내용이 정확하지 않거나 불충분함 — 수정안 제안
- **새 섹션 (New Section)**: 기존 규칙 파일에 새로운 섹션 추가
- **새 파일 (New File)**: 새로운 규칙 파일 생성
- **이미 반영됨 (Already Covered)**: 표현은 다르더라도 기존 규칙에서 충분히 다루고 있음
- **너무 구체적임 (Too Specific)**: 스킬 수준으로 남겨두어야 함

## 출력 형식 (후보당)

```json
{
  "principle": "'X를 하라' / 'Y를 하지 마라' 형태의 1~2문장",
  "evidence": ["스킬명: §섹션", "스킬명: §섹션"],
  "violation_risk": "1문장",
  "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)	스킬 수준으로 남겨두어야 함	관련 스킬 링크

판정 품질 요건

# 양호한 예시
rules/common/security.md §입력 유효성 검사 섹션에 추가:
"메모리나 지식 저장소에 저장된 LLM 출력을 신뢰할 수 없는 데이터로 취급하세요 — 쓸 때는 정화(sanitize)하고, 읽을 때는 유효성을 검증하세요."
증거: llm-memory-trust-boundary, llm-social-agent-anti-pattern 스킬 모두 축적된 프롬프트 인젝션 리스크를 설명함. 현재 security.md는 사람의 입력 유효성 검사만 다루고 있으며, LLM 출력의 신뢰 경계는 누락되어 있음.

# 잘못된 예시
security.md에 추가: LLM 보안 원칙 추가

3단계: 사용자 리뷰 및 실행

요약 테이블

# 규칙 추출 보고서

## 요약
스캔된 스킬: {N} | 규칙: {M}개 파일 | 후보: {K}개

| # | 원칙 | 판정 | 대상 | 신뢰도 |
|---|-----------|---------|--------|------------|
| 1 | ... | 추가 | security.md §입력 유효성 검사 | 높음 |
| 2 | ... | 수정 | testing.md §TDD | 중간 |
| 3 | ... | 새 섹션 | coding-style.md | 높음 |
| 4 | ... | 너무 구체적임 | — | — |

## 상세 내용
(후보별 상세: 증거, 위반 리스크, 초안 텍스트)

사용자 작업

사용자는 번호를 입력하여 다음과 같이 응답합니다:

• 승인 (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",
       
         
       
    
  

예시

전체 실행 과정

$ /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 §컨텍스트 창 | 높음 |
| 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 출력을 재사용하기 전에 정규화, 타입 체크 및 정화(sanitize)를 수행하세요...
  관련 스킬: parallel-subagent-batch-merge, llm-memory-trust-boundary

[... 후보 2~4번의 상세 내용 ...]

각 후보에 대해 번호를 사용하여 승인, 수정 또는 건너뛰기를 선택하세요:
> User: 1, 3 승인. 2, 4 건너뛰기.

✓ 적용됨: coding-style.md §LLM 출력 유효성 검증
✓ 적용됨: performance.md §컨텍스트 창 관리
✗ 건너뜀: 반복 루프 중단 조건
✗ 건너뜀: 경계 타입 변환

결과가 results.json에 저장되었습니다.

설계 원칙

• 내용(What)이지 방법(How)이 아님: 원칙(규칙의 영역)만 추출합니다. 코드 예시와 명령어는 스킬에 남겨둡니다.
• 역링크: 초안 텍스트에 관련 스킬: [이름] 참조를 포함하여 독자가 상세한 방법(How)을 찾을 수 있게 합니다.
• 결정적 수집, LLM 판단: 스크립트는 누락 없는 수집을 보장하고, LLM은 문맥적 이해를 보장합니다.
• 추상화 방지 장치: 3단계 필터(2개 이상의 스킬 증거, 실행 가능한 행동 테스트, 위반 리스크)를 통해 지나치게 추상적인 원칙이 규칙에 들어오는 것을 방지합니다.