Caveman 딥다이브
— "말 짧게 하면 왜 힘 세지냐" AI 에이전트 출력 압축 스킬

1프로젝트 한줄 요약

이 저장소가 대체 무엇인가.

README의 자기소개는 "A Claude Code skill/plugin (also Codex, Gemini, Cursor, Windsurf, Cline, Copilot, 30+ more) that makes agent talk like caveman — cuts ~75% of output tokens, keeps full technical accuracy. Brain still big. Mouth small." — "뇌는 여전히 크고, 입만 작다"는 표현이 이 프로젝트 전체를 한 줄로 요약한다.

실제로 뜯어보면 이 저장소는 하나의 프로그램이 아니라 7개의 스킬(caveman·caveman-commit·caveman-review·caveman-stats·caveman-compress·caveman-help·cavecrew) + 2개의 Claude Code 훅(SessionStart·UserPromptSubmit) + 1개의 MCP 미들웨어(caveman-shrink) + 1개의 크로스플랫폼 설치기(bin/install.js, 34개 에이전트 감지)로 이루어진 작은 생태계다. 리서치 결과, 겉보기엔 "농담 같은 스킬"이지만 심볼릭 링크 공격을 막는 심볼릭 링크 하드닝, 원자적 파일 쓰기, SHA-256 체크섬 검증 같은 보안 엔지니어링이 꽤 진지하게 들어가 있다 — 뒤에서 실제 코드로 확인한다.

2왜 주목받는가

69.4k★ 트렌딩 이유 · 밈 요소 · 실제 벤치마크의 정직성.

2026년 상반기 AI 코딩 에이전트 생태계에서 토큰 비용은 실제 통증 포인트다. Claude Opus 같은 고급 모델은 출력 토큰 1백만 개당 $75가 들고(caveman-stats.js의 가격표에서 확인됨), 긴 세션일수록 청구서가 눈덩이처럼 불어난다. caveman은 이 문제를 "AI가 원시인처럼 말하게 하면 된다"는 우스꽝스러운 프레이밍으로 포장했지만, 실제로는 진지한 프롬프트 엔지니어링 + 토큰 회계 문제를 다룬다 — 이 "밈과 실용의 낙차"가 폭발적 트렌딩의 1차 요인이다.

정직함이라는 차별점 — 다른 "프롬프트 치트시트"와 무엇이 다른가

숫자 하나가 아니라 네 가지 버전의 "절감율"

흥미로운 지점은 "몇 % 줄어드는가"라는 질문에 레포 스스로도 하나의 답을 안 준다는 것이다. skills/caveman/SKILL.md frontmatter는 ~75%, README 벤치마크 표와 caveman-stats.js의 하드코딩 값은 65%(범위 22~87%), CLAUDE.md는 절충해서 ~65-75%, 그리고 방법론이 더 엄격한 evals/는 terse 컨트롤 대비 중앙값 +50%(진짜 baseline 대비가 아님)를 말한다. 넷 다 "거짓"은 아니다 — 무엇과 비교했느냐(진짜 아무 지시 없음 vs "간결하게 답해" vs "너는 친절한 조수다")에 따라 달라지는 서로 다른 숫자일 뿐이지만, "정확히 65%"라고 외우면 곤란하다.

3기술 스택 전체 지도

JS 코어 + Python 압축엔진 + 셸/PowerShell 설치기 + Claude Code 훅/스킬/플러그인 + MCP 미들웨어.

4아키텍처 심화 분석

SKILL.md 주입 → 세션 훅 플래그파일 → 매 메시지 caveman 발화 → stats 토큰 집계 → statusline.

가장 핵심적인 질문은 "사용자가 /caveman을 안 쳐도 첫 메시지부터 원시인 말투가 나오는 이유"다. 답은 Claude Code의 SessionStart 훅이다. 아래는 실제 소스코드를 근거로 재구성한 전체 흐름이다.

① SessionStart 훅 — 세션 시작과 동시에 규칙 주입 + 플래그 파일 기록

.claude-plugin/plugin.json이 두 이벤트를 정확히 이렇게 바인딩한다(검증된 실제 파일):

{
  "hooks": {
    "SessionStart": [{ "hooks": [{
      "type": "command",
      "command": "node \"${CLAUDE_PLUGIN_ROOT}/src/hooks/caveman-activate.js\"",
      "timeout": 5
    }]}],
    "UserPromptSubmit": [{ "hooks": [{
      "type": "command",
      "command": "node \"${CLAUDE_PLUGIN_ROOT}/src/hooks/caveman-mode-tracker.js\"",
      "timeout": 5
    }]}]
  }
}

caveman-activate.js는 매 세션 시작마다 (1) skills/caveman/SKILL.md를 파일에서 직접 읽어 — 하드코딩된 사본이 아니라 원본 그대로 — (2) 지금 활성화된 레벨에 해당하는 표 행·예시만 걸러내고 (3) 그 결과를 표준출력으로 내보낸다. Claude Code 훅 규약상 SessionStart의 stdout은 사용자에게 안 보이는 숨은 시스템 컨텍스트로 주입된다 — 모델은 보지만 사람은 못 보는 채널이다.

// src/hooks/caveman-activate.js (핵심 로직 요약, 실제 코드 근거)
const flagPath = path.join(claudeDir, '.caveman-active');
const mode = getDefaultMode();               // env > repo config > user config > 'full'
safeWriteFlag(flagPath, mode);                // 심볼릭 링크 안전 원자적 쓰기 (아래 상세)

let skillContent = fs.readFileSync(
  path.join(__dirname, '..', 'skills', 'caveman', 'SKILL.md'), 'utf8'
);
// 활성 레벨 행만 필터링 후 출력 — 매 세션 6개 레벨 예시를 전부 보여주지 않음
output = 'CAVEMAN MODE ACTIVE — level: ' + modeLabel + '\n\n' + filtered.join('\n');
process.stdout.write(output);   // SessionStart 훅 stdout = 숨은 시스템 컨텍스트

② UserPromptSubmit 훅 — 매 메시지 재확인 + 자연어 트리거 + /caveman-stats 가로채기

이 훅은 사용자가 메시지를 보낼 때마다 실행된다. 두 가지 일을 한다. 첫째, "talk like caveman" 같은 자연어를 정규식으로 감지해 자동으로 모드를 켠다. 둘째 — 이게 6장의 핵심인데 — /caveman-stats가 감지되면 모델에게 프롬프트를 아예 전달하지 않고 Node 스크립트를 직접 실행해 그 결과를 사용자에게 돌려준다.

// src/hooks/caveman-mode-tracker.js — /caveman-stats 가로채기 (실제 코드)
const statsMatch = /^\/caveman(?::caveman)?-stats(?:\s+(.*))?$/.exec(prompt);
if (statsMatch) {
  const out = execFileSync(process.execPath,
    [statsPath, '--session-file', data.transcript_path], { timeout: 5000 });
  process.stdout.write(JSON.stringify({ decision: 'block', reason: out.trim() }));
  return;
}

③ 심볼릭 링크 방어 — "귀여운 스킬 레포"치고 이례적으로 진지한 보안 코드

플래그 파일(~/.claude/.caveman-active)은 경로가 예측 가능하다. 공격자가 이 경로를 ~/.ssh/id_rsa 같은 민감한 파일을 가리키는 심볼릭 링크로 미리 바꿔치기해 두면, statusline이나 훅이 그 내용을 읽어 터미널에 출력하거나 모델 컨텍스트에 흘려 넣을 위험이 있다. src/hooks/caveman-config.js의 safeWriteFlag()는 이를 정면으로 방어한다.

// src/hooks/caveman-config.js — 심볼릭 링크 안전 원자적 쓰기 (실제 코드)
const O_NOFOLLOW = fs.constants.O_NOFOLLOW || 0;   // 심볼릭 링크면 open() 자체가 실패
const flags = fs.constants.O_WRONLY | fs.constants.O_CREAT
            | fs.constants.O_EXCL | O_NOFOLLOW;
const fd = fs.openSync(tempPath, flags, 0o600);     // 임시파일에 먼저 씀
fs.writeSync(fd, String(content));
fs.renameSync(tempPath, realFlagPath);              // rename은 원자적 — 중간 상태 없음

// 읽을 때도 최대 64바이트 캡 + [a-z0-9-] 화이트리스트만 통과
const MAX_FLAG_BYTES = 64;   // 가장 긴 정상값 "wenyan-ultra"=12바이트, 여유만 둠

이 방어 로직은 우연이 아니다 — tests/test_symlink_flag.js의 헤더 주석에 "Covers fix for issue #207: safeWriteFlag refuses flag writes when ~/.claude is a symlink"라고 적혀 있다. 실제 신고된 보안 이슈를 고치며 만들어진, 회귀 테스트까지 딸린 진짜 코드라는 뜻이다.

④ /caveman-stats — "실측"과 "고정 승수"가 섞인 절감량 계산

caveman-stats.js가 하는 일을 정확히 둘로 나눠야 한다. (A) 진짜 실측: Claude Code 세션의 JSONL 트랜스크립트($CLAUDE_CONFIG_DIR/projects/**/*.jsonl)를 직접 파싱해 usage.output_tokens를 그대로 합산한다 — 이건 100% 실제 Anthropic API 사용량 메타데이터다. (B) 추정: "caveman 없이 썼다면 몇 토큰이었을까"는 실측이 아니라, 커밋된 벤치마크 1회 실행에서 나온 65%라는 고정 상수를 역산에 사용한다.

// src/hooks/caveman-stats.js — 실제 코드, 주석까지 그대로
// Mean per-task savings from benchmarks/results/*.json (avg_savings: 65 across
// 10 tasks, sonnet-4-20250514). Only 'full' has measured data.
const COMPRESSION = { 'full': 0.65 };

function deriveSavings({ outputTokens, mode }) {
  const ratio = COMPRESSION[mode];
  if (ratio == null) return { estSavedTokens: 0, estSavedUsd: 0 };  // lite/ultra/wenyan은 추정 안 함
  const estNormal = Math.round(outputTokens / (1 - ratio));   // 실측값을 0.35로 나눠 역산
  return { estSavedTokens: estNormal - outputTokens, ... };
}

중요한 건 이 도구가 스스로 정직하다는 점이다. 출력 문구에 항상 "Est."(추정)라는 접두어를 붙이고, full 외 모드에서는 "No savings estimate for '<mode>' mode — only 'full' has benchmark data."라고 명시하며, 하단에는 항상 "Savings est. from benchmarks/ (mean per-task). Actual varies by task."라는 면책 문구가 붙는다. 이번 세션에서 실제로 A/B 테스트를 돌린 게 아니라 "과거 벤치마크 평균을 지금 세션 실측 토큰 수에 적용한 값"이라는 걸 도구 스스로 밝히는 셈이다.

⑤ caveman-compress — 메모리 파일을 압축해 입력 토큰까지 절감하는 루프

4번까지가 "출력 토큰"을 줄이는 얘기였다면, /caveman-compress는 CLAUDE.md 같은 메모리 파일 자체를 압축해 매 세션 로드될 때 드는 입력 토큰까지 줄인다. 이건 정규식 치환이 아니라 진짜 Claude 모델 호출이다.

// skills/caveman-compress/scripts/compress.py — 실제 LLM 호출 코드
def call_claude(prompt: str) -> str:
    api_key = os.environ.get("ANTHROPIC_API_KEY")
    if api_key:
        client = anthropic.Anthropic(api_key=api_key)
        msg = client.messages.create(
            model=os.environ.get("CAVEMAN_MODEL", "claude-sonnet-4-5"),
            max_tokens=8192, messages=[{"role": "user", "content": prompt}])
        return strip_llm_wrapper(msg.content[0].text.strip())
    # API 키 없으면 로컬 Claude Desktop/CLI 인증을 그대로 재사용
    result = subprocess.run([shutil.which("claude") or "claude", "--print"],
                             input=prompt, text=True, capture_output=True, check=True)
    return strip_llm_wrapper(result.stdout.strip())

검증 단계는 단순 "비교"가 아니라 정확히 무엇이 깨졌는지까지 짚어낸다 — 코드블록 불일치, URL 유실/추가, 인라인 코드 개수 불일치(Counter 기반이라 "3개 중 2개만 남음" 같은 부분 손실도 잡는다)를 개별 항목으로 보고하고, 그 에러 리스트만 다시 Claude에게 보내 "이 항목만 고쳐, 재압축 금지"라고 지시한다. 2회 재시도 후에도 실패하면 원본 파일을 그대로 복원한다 — LLM 출력이 파일을 훼손할 가능성에 대한 방어가 촘촘하다.

⑥ caveman-shrink — MCP 미들웨어는 완전히 다른 구현 (LLM 없음, 순수 정규식)

이름은 비슷하지만 caveman-compress(Python, LLM 호출)와 caveman-shrink(Node, 순수 정규식)는 아키텍처가 근본적으로 다르다. caveman-shrink는 MCP(Model Context Protocol) 클라이언트와 업스트림 MCP 서버 사이에 끼어드는 stdio JSON-RPC 프록시다.

// src/mcp-servers/caveman-shrink/compress.js — 정규식으로 보호 구간 지정
const PROTECTED_PATTERNS = [
  /```[\s\S]*?```/g,          // 코드블록
  /`[^`\n]+`/g,               // 인라인 코드
  /\bhttps?:\/\/\S+/gi,       // URL
  /\b[\w.-]*[\/\\][\w.\/\\\-]+/g,  // 경로
];
// 보호 구간을 숫자 sentinel로 치환 → 나머지 산문만 압축 → 되돌려 붙임

README가 "compresses the same boundaries as the caveman skill"이라고 표현한 대로, 코드/URL/경로는 보호하되 나머지 산문(관사·인사치레·헤지 표현)만 정규식으로 걷어낸다는 점에서 caveman/SKILL.md의 규칙과 철학은 같지만 구현은 별개다 — LLM 호출 비용/지연 없이 MCP 툴 설명을 실시간으로 압축해야 하니 의도적으로 순수 기계적 구현을 택했다.

⑦ 4(6)단계 레벨 — lite / full / ultra / wenyan(3단계)

SKILL.md의 실제 표는 4단계가 아니라 6줄이다 — wenyan이 lite/full/ultra 세 하위 단계로 다시 나뉜다. CLI 명령에서 "wenyan"이라고만 쓰면 내부적으로 wenyan-full의 별칭으로 처리된다.

⑧ Auto-Clarity — 압축이 오히려 위험할 때는 스스로 끈다

SKILL.md는 압축이 안전과 충돌하는 지점을 명시적으로 정의한다: 보안 경고, 되돌릴 수 없는 작업의 확인, 순서가 헷갈릴 수 있는 다단계 작업(예: "migrate table drop column backup first" — 관사·접속사 없이는 순서가 불명확)에서는 caveman체를 자동으로 끄고 평범한 영어로 전환한 뒤, 위험 구간이 끝나면 다시 caveman체로 돌아온다. 이건 "무조건 짧게"가 아니라 "안전을 해치지 않는 선에서 짧게"라는 설계 원칙을 보여준다.

5디렉토리 구조 해부

7개 스킬 + 훅 + evals/benchmarks 이중 검증 + 멀티에이전트 배포.

6학습 포인트 (기술별)

이 저장소 하나로 배울 수 있는 것 + 실습 아이디어.

6-1. Claude Code 스킬 만들기 — "한 장의 Markdown이 코드"라는 감각

skills/caveman/SKILL.md는 프로그래밍 언어 코드를 단 한 줄도 쓰지 않고 모델의 행동을 완전히 바꾼다. frontmatter의 description이 트리거 조건("사용자가 'caveman mode', 'talk like caveman' 이라고 하면")을 정의하고, 본문이 실제 규칙이다. 좋은 스킬 작성의 핵심은 "무엇을 하지 마라"를 예시와 함께 명시하는 것 — SKILL.md는 "Not: '기꺼이 도와드리겠습니다...' / Yes: '인증 미들웨어 버그. 토큰 만료 체크가 < 아니라 <=. 수정:'"처럼 나쁜 예/좋은 예를 나란히 보여준다.

6-2. Claude Code 훅 — SessionStart/UserPromptSubmit으로 "항상 켜짐" 만들기

스킬만으로는 "매번 사용자가 트리거 문구를 말해야" 켜진다. caveman이 첫 메시지부터 자동으로 동작하는 비밀은 SessionStart 훅이 stdout으로 숨은 컨텍스트를 주입한다는 데 있다. 훅의 계약은 단순하다 — stdin으로 JSON을 받고, stdout으로 텍스트나 {"decision": ..., "reason": ...} 형태 JSON을 내보내면 된다.

// 최소 SessionStart 훅 예시 (caveman-activate.js 구조를 단순화)
#!/usr/bin/env node
process.stdout.write("항상 존댓말로 답하고 이모지는 절대 쓰지 마라.");
process.exit(0);
// .claude/settings.json 에 등록:
// "hooks": { "SessionStart": [{ "hooks": [{ "type": "command", "command": "node ./my-hook.js" }] }] }

6-3. 예측 가능한 경로에 파일 쓰기 — 심볼릭 링크 공격과 원자적 쓰기

~/.claude/.caveman-active처럼 경로가 고정된 파일에 반복적으로 쓰는 도구는 전부 이 문제를 마주한다: 로컬 공격자가 그 경로를 미리 심볼릭 링크로 바꿔치기하면? caveman은 O_NOFOLLOW 플래그(심볼릭 링크면 open 자체가 실패)로 열고, 임시 파일에 쓴 뒤 rename()으로 원자적으로 교체하는 패턴을 쓴다. 읽을 때도 크기 캡(64바이트)과 화이트리스트 정규식으로 방어한다.

6-4. MCP 미들웨어 패턴 — 프로토콜 프록시로 기존 서버를 감싸기

caveman-shrink는 MCP 클라이언트-서버 사이에 끼어 JSON-RPC 메시지를 가로채고 특정 필드만 수정한 뒤 그대로 전달한다. 이 패턴은 MCP뿐 아니라 어떤 stdio/JSON-RPC 기반 프로토콜에도 적용 가능한 범용 기법이다 — 원본 서버 코드를 전혀 건드리지 않고 동작을 확장한다는 게 핵심.

// caveman-shrink/index.js 구조 요약 — 이 패턴 자체가 학습 포인트
const upstream = spawn(args[0], args.slice(1));  // 원본 MCP 서버를 자식 프로세스로 띄움
upstream.stdout.on('data', chunk => {
  const msg = JSON.parse(line);
  if (msg.result?.tools) msg.result.tools.forEach(t => t.description = compress(t.description));
  process.stdout.write(JSON.stringify(msg) + '\n');  // 변형해서 클라이언트로 전달
});

6-5. 토큰 회계 — 실측과 추정을 명확히 구분해서 보여주기

caveman-stats.js는 좋은 선례를 보여준다: "이건 실제로 측정한 값"(JSONL에서 뽑은 output_tokens)과 "이건 과거 벤치마크 기반 추정치"(65% 고정 승수)를 코드 구조로도, 출력 문구로도 명확히 분리한다. 실무에서 비용/성능 대시보드를 만들 때 이 구분을 흐리면 사용자가 추정치를 실측으로 오해하기 쉽다.

6-6. 정직한 eval 설계 — baseline/terse/skill 3-arm 하니스

evals/가 주는 가장 중요한 교훈은 "무엇과 비교하느냐"가 숫자의 의미를 완전히 바꾼다는 것이다. "간결하게 답해"라는 지시만으로도 어느 정도 절감되므로, 스킬의 진짜 기여를 알려면 스킬 vs (스킬 없이 그냥 간결하게)를 비교해야 한다 — 스킬 vs 아무 지시 없음을 비교하면 "일반적인 간결함 요청"의 효과까지 스킬 덕분으로 착각하게 된다.

// evals/llm_run.py 구조 요약 — 3-arm 정의
arms = {
  "__baseline__": None,                                    # 시스템 프롬프트 없음
  "__terse__": "Answer concisely.",                        # 대조군 — 일반적 "간결히"
  "caveman": "Answer concisely.\n\n" + skill_md_text,       # 진짜 비교 대상
}
# 정직한 지표 = arms["caveman"] vs arms["__terse__"], baseline과 비교하면 "치팅"

6-7. 프롬프트로 출력 스타일을 강제하기 — 규칙 + 안전 예외 + 페르소나 자기지시 금지

SKILL.md의 스타일 강제 규칙에서 배울 점이 세 가지 있다. (1) "무엇을 뺄지" 구체적 목록(관사, filler 단어, 인사치레)을 나열한다. (2) 안전 예외(보안 경고·되돌릴 수 없는 작업 시 자동으로 정상 모드 복귀)를 명시한다. (3) "self-reference 금지" — "저는 지금 caveman 모드입니다" 같은 페르소나 자기설명을 하지 말라고 명시한다. 이 세 원칙은 "AI에게 특정 톤을 강제하는" 어떤 프롬프트에도 그대로 적용 가능하다.

7시스템 요구사항

Node ≥18 하나면 끝 — 진짜 다양성은 "지원 에이전트" 쪽에 있다.

지원 에이전트 매트릭스 — "자동 실행"과 "수동 트리거"는 다르다

README는 "30+ agents"라 하고 CLAUDE.md는 "40+"라 한다(양쪽 다 대략적 수치, 정확히는 bin/install.js의 PROVIDERS 배열에 하드 프로필 31개 + soft 프로필 3개 = 34개 정의). 중요한 건 숫자보다 "자동으로 켜지는가, 매번 사용자가 켜야 하는가"다.

8직접 해볼 수 있는 실습 과제

난이도별 5단계. 설치 → 레벨 실험 → 메모리 압축 → 나만의 훅/스킬 → MCP·평가 재현.

9관련 기술 심화 학습 로드맵

이 저장소를 출발점으로, 5주 코스.

10핵심 키워드 사전

본문에 나온 용어 빠른 참조.

11참고 링크

• GitHub: JuliusBrussee/caveman
• 공식 사이트: caveman.sh
• 설치 가이드: INSTALL.md
• 유지보수 아키텍처 문서: CLAUDE.md
• 평가 방법론: evals/README.md
• 벤치마크 스크립트: benchmarks/run.py
• caveman-shrink (MCP 미들웨어): src/mcp-servers/caveman-shrink
• caveman-code (자매 프로젝트, 전체 터미널 에이전트): JuliusBrussee/caveman-code
• Claude Code 공식 문서: docs.anthropic.com/claude-code
• Model Context Protocol 공식 스펙: modelcontextprotocol.io
• 인용 논문(arXiv, 레포 README 근거): arXiv:2604.00025 "Brevity Constraints Reverse Performance Hierarchies in Language Models"