# Show GN: CLAUDE.md 규칙을 훅으로 "컴파일"하는 Claude Code 플러그인

> Clean Markdown view of GeekNews topic #31658. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=31658](https://news.hada.io/topic?id=31658)
- GeekNews Markdown: [https://news.hada.io/topic/31658.md](https://news.hada.io/topic/31658.md)
- Type: show
- Author: [seob717](https://news.hada.io/@seob717)
- Published: 2026-07-21T21:39:16+09:00
- Updated: 2026-07-21T21:39:16+09:00
- Original source: [github.com/seob717](https://github.com/seob717/nunchi)
- Points: 1
- Comments: 0

## Topic Body

안녕하세요, Claude Code를 매일 쓰는 개발자입니다. CLAUDE.md가 커질수록 두 가지가 계속 거슬렸습니다.  
  
1. 규칙이 세션 시작(t=0)에 통째로 실리고, 정작 그 규칙이 필요한 순간은 수십 턴 뒤라는 것. 컨텍스트가 쌓이고 컴팩션이 한 번 지나가면 명시적 규칙이 흐릿한 배경으로 강등됩니다.  
2. `@docs/pr-rules.md` 같은 참조 문서는 매 세션 토큰을 선불로 내는데, 실제로 PR을 만드는 세션은 일부라는 것.  
  
그래서 규칙을 "세션 상단의 선언"이 아니라 **"액션에 결합된 이벤트 리스너"로 컴파일**하는 플러그인을 만들었습니다.  
  
`/nunchi:compile`이 CLAUDE.md와 참조 문서에서 규칙을 추출해 트리거(도구 + 정규식)를 붙인 룰 파일로 만들고, PreToolUse 훅이 `gh pr create` 같은 액션 직전에 원본 문서를 그 자리에서 읽어 배달합니다. 컴팩션이 지나가면 SessionStart 훅이 배달 상태를 리셋해서 다음 트리거 때 다시 배달합니다(재배달 실측 5/5). 모든 배달은 JSONL로 기록되어 `/nunchi:report`로 "어떤 규칙이 언제 발화했고 뭘 아꼈는지"를 봅니다.  
  
수치는 전부 사전등록 실험으로 레포에 공개돼 있습니다.  
  
- 세션 시작 토큰: 규칙 문서 8개(~76KB)를 @import에서 빼니 79,683 → 45,808 (−42.5%, ~34k 토큰). 문서 비용은 해당 액션이 실제로 발화한 세션에서만 지불.  
- 컴팩션 후 규칙 위반: 베이스라인(CLAUDE.md만) 3런 중 1회, 전체 실험을 통틀어 처음 관측된 위반이었는데 — 그 지점이 정확히 "컴팩션이 버린 @참조 문서 속 규칙"이었습니다. 단, 사전등록 게이트를 못 넘어 "JIT가 준수율이 더 높다"는 주장은 하지 않습니다 — 이건 아직 미검증이고 README에도 그렇게 써놨습니다.  
- 컴파일 품질: 실제 야생 CLAUDE.md 12개(airflow, next.js, supabase 등 166KB)에서 형식 유효 100%, 날조 0. recall은 적대적 gold 대비 35%로 낮고, 이것도 숨기지 않고 이슈로 추적 중입니다.  
- 한국어 문서 호환: 한국어 야생 CLAUDE.md 4개(pinpoint 포함)에서 형식 위반·과추출·날조 0, 금지 표현("절대 직접 커밋하지 않습니다")의 강도 판정 88%. 한국어로 CLAUDE.md 쓰는 분들을 위한 작성 가이드도 있습니다.  
  
기존 접근과의 차이: path-scoped rules는 "파일 읽기" 트리거고 nunchi는 "액션" 트리거입니다(둘은 공존하도록 설계). Context Mode/RTK류는 컨텍스트로 들어오는 출력을 압축하는 도구고, nunchi는 압축이 아니라 배달 시점을 스케줄링합니다. 토큰 절감은 부산물이고, 핵심은 **규칙이 액션 직전에 확실히 컨텍스트에 있고 그걸 로그로 증명할 수 있다**는 것입니다.  
  
현재 실사용자가 저 하나뿐이라, 다른 워크플로(모노레포, 다른 언어권 팀, 대형 CLAUDE.md)에서 어떻게 동작하는지 데이터가 필요합니다. 설치는 두 줄입니다:  
  
```  
/plugin marketplace add seob717/nunchi  
/plugin install nunchi@nunchi-marketplace  
```  
  
트리거 추론이 틀리는 지점, 정규식으로 안 잡히는 규칙 유형, 리포트에서 더 보고 싶은 것 — 어떤 피드백이든 감사히 받겠습니다.

## Comments



_No public comments on this page._