클로드 코드 소스코드 유출로 알게 된 것들
내부 동작 분석으로 토큰 절약 & 스킬 설계를 최적화하는 5가지 발견
2026년 3월, 클로드 코드의 전체 소스코드가 npm source map을 통해 유출되었습니다. 트위터 유저 @Bugi952가 이 소스코드를 분석해서 발견한 내부 동작 원리와, 이를 활용한 스킬 설계 최적화 방법을 정리합니다.
⚡ 핵심 인사이트: "감으로 설계" → "내부 동작에 맞춰서 설계". 도구의 내부를 이해하면 사용법이 달라진다.
1. CLAUDE.md는 매 API 호출마다 통째로 주입된다
CLAUDE.md가 system prompt로 들어가는 줄 알았는데, 실제로는 user message로 매 호출마다 통째로 주입되고 있었습니다.
❌ 의미하는 것
CLAUDE.md가 길수록 매번 토큰을 낭비한다.
세션 종료 절차, 검증 게이트, 스킬 연계 규칙 같은 것들이 전부 여기 있으면 비용 폭탄.
✅ 해결 방법
세션 종료 로직 → /save 스킬로 분리
검증 게이트 → 각 스킬 안에 인라인
109줄 → 58줄로 다이어트
💡 원칙: CLAUDE.md에는 매 턴마다 필요한 것만 남기고, 나머지는 스킬이나 별도 파일로 분리하라.
2. 컴팩션은 "Compact Instructions" 섹션명을 기대한다
대화가 길어지면 클로드가 알아서 요약(컴팩션)하는데, 이때 CLAUDE.md에 Compact Instructions라는 정확한 이름의 섹션이 있으면 그 안의 지시를 참고합니다.
주의사항
🔹 보존 지시는 코드 강제가 아니라 모델한테 부탁 수준
🔹 보존할 항목을 명확하게 나열해야 효과가 있음
🔹 섹션 이름이 다르면 (예: "컴팩션 보호") 제대로 작동 안 할 수 있음
CLAUDE.md 적용 예시
## Compact Instructions
컴팩션 시 반드시 보존할 항목:
1. 현재 작업 목표와 진행 상태
2. 활성 스킬 이름과 모드
3. CONTEXT.md 파일 경로
4. 미완료 TODO 목록
5. 최근 결정 사항과 그 이유
6. 사용자가 명시한 제약 조건
7. 현재 브랜치와 커밋 상태
8. 에러 히스토리 (최근 3개)
9. 다음 단계 계획3. allowed-tools로 스킬별 도구 제한
스킬 frontmatter에 allowed-tools를 넣으면 해당 스킬에서 쓸 수 있는 도구를 제한할 수 있습니다.
❌ 제한 없을 때
글쓰기 모드에서 터미널 명령 실행 가능
저널 모드에서 웹 검색 가능
= 목적에 안 맞는 행동 발생
✅ 도구 제한 후
글쓰기 → Read, Write, Edit, Glob만
공부 → + WebSearch, WebFetch 추가
= 목적에 맞는 행동만 허용
스킬 frontmatter 예시
---
name: write
description: 글쓰기 모드
allowed-tools: [Read, Write, Edit, Glob]
---
# 글쓰기 스킬
...4. !command로 스킬 로드 시 파일 자동 주입
기존에는 스킬 실행 시 "CONTEXT.md 먼저 읽어"를 매번 시켜야 했습니다. Read 도구 호출 1~2회가 낭비되는 구조였죠.
해결: !cat으로 자동 주입
---
name: think
description: 심층 분석 모드
---
!cat CONTEXT.md
!cat GOALS.md
# Think 스킬
위 컨텍스트를 바탕으로 분석을 시작하세요...💡 !cat CONTEXT.md라고 써놓으면 스킬이 로드되는 순간 파일 내용이 프롬프트에 바로 들어감. Read 도구 호출 없이 즉시 컨텍스트 확보.
5. context: fork로 서브에이전트 격리
무거운 분석 작업이 메인 대화 컨텍스트를 잡아먹는 문제가 있었습니다. context: fork를 쓰면 별도 서브에이전트에서 실행되고, 결과만 메인으로 돌아옵니다.
❌ fork 없이
review 스킬이 전체 목표 대비 진행률을 분석
→ 메인 대화 컨텍스트를 많이 잡아먹음
→ 다른 작업에 영향
✅ context: fork 사용
별도 서브에이전트에서 실행
→ 결과만 메인으로 반환
→ 메인 컨텍스트 깔끔하게 유지
스킬 frontmatter 예시
---
name: review
description: 진행률 분석 및 리뷰
context: fork
---
# Review 스킬
전체 목표 대비 현재 진행 상황을 분석하세요...한눈에 보기
| # | 발견 | 실천 방법 |
|---|---|---|
| 1 | CLAUDE.md 매 턴 주입 | 최소화 필수 — 스킬로 분리하여 토큰 절약 |
| 2 | Compact Instructions | 정확한 섹션명 + 보존 항목 구체적 나열 |
| 3 | allowed-tools | 스킬별 도구 제한으로 목적 외 행동 차단 |
| 4 | !command 자동 주입 | 스킬 로드 시 파일 자동 로드 — Read 호출 절약 |
| 5 | context: fork | 무거운 분석은 서브에이전트로 격리 |
부록: token-diet 스킬
위 분석을 바탕으로 @Bugi952가 공개한 토큰 절약 스킬입니다.
📉 CLAUDE.md 19KB → 1.8KB 다이어트 (매 턴 약 4,000 토큰 절약)
🔀 모델 라우팅 / 캐시 최적화 가이드 포함
🩺 /token-diet으로 바로 진단
설치 (한 줄)
curl -sL https://raw.githubusercontent.com/bugbug9999/token-diet/main/SKILL.md \
-o ~/.claude/skills/token-diet/SKILL.md핵심 메시지
소스코드 분석 전: 감으로 설계
소스코드 분석 후: 내부 동작에 맞춰서 설계
도구의 내부를 이해하면 사용법이 달라집니다.