LLM Wiki

케이브맨

13 min read

한 줄 정의

Claude Code, Cursor, Codex, Gemini 등 약 30여 개의 AI 코딩 에이전트에 스킬(Skill) 형태로 연동되어, 극단적으로 간결한 원시인 말투로 답변을 유도하여 출력 토큰을 아끼는 확장 도구이다. (출처: raw/원시인 모드로 토큰 아끼려다 6만 스타 오픈소스에 PR 보낸 이야기.md)

핵심 요지

  • 출력 토큰 65% 절감: 무의미한 잡담(small talk, fluff)을 생략하여 출력 토큰을 평균 65%(작업에 따라 22%~87% 편차) 아끼며, 전체 프로젝트 요금 기준으로는 약 18%를 절감한다. (공식 광고 수치인 75%는 최대 성능 기준이다.)
  • 입력 컨텍스트 압축 (/caveman-compress): CLAUDE.md, 프로젝트 노트, 할 일 목록 등 세션 개시 때마다 읽는 고정 파일의 설명문(prose)만 압축하여 입력 토큰을 평균 46% 아낀다. 코드 블록, URL, 파일 경로는 그대로 유지된다.
  • 과학적 근거 (Brevity Constraints): 2026년 3월 연구(MD Azizul Hakim, arXiv:2604.00025)에 따르면 31개 기성 모델을 대상으로 1,485개 수학/과학 질문을 평가한 결과, 모델 지시사항에 간결성 제약을 두는 것만으로도 거대 언어 모델의 ‘과도한 생각(Overthinking)‘이 억제되어 정확도가 최대 26%포인트 향상되는 효과가 입증되었다.
  • caveman-code 독립형 에이전트: 스킬로 연동되는 Caveman과 달리 caveman-code는 입력 프롬프트, 도구 실행 결과, 중복 파일 읽기 배제, 출력 텍스트의 4대 영역을 통제하는 독립형 CLI 코딩 에이전트로, 기존 Codex CLI 대비 약 1.93배 높은 토큰 효율을 보인다.
  • 에이전트 거절권과 정직성: 주인의 요구라 할지라도 아직 검증되지 않은 테스트를 ‘통과했다’고 거짓으로 PR 설명글에 기입하는 것을 단호히 거부하고, 47개 npm 통합 테스트 중 4개 에러와 같은 사실적 지표를 있는 그대로 명시하게 돕는 등 에이전트의 객관적 안전장치 역할을 수행한다.
  • 출력 토큰을 평균 65% 절감하여 실무 코딩 중 불필요하게 늘어지는 챗봇 답변 텍스트 요금을 억제한다.
  • 파일 압축 명령어(/caveman-compress)를 가동하여 매 세션마다 읽히는 CLAUDE.md 등 컨텍스트 파일 크기를 평균 46% 압축함으로써 누적 복리 요금 효과를 낸다.
  • JuliusBrussee/caveman 저장소: 누적 65k 스타를 달성한 유명 오픈소스 AI 에이전트 인프라.
  • 세션 자동 실행 장벽 해결: PR 448을 통해 ‘defaultMode: manual’ 설정을 추가하여 자동 세션 후크 실행을 제어하고 사용자 수동 opt-in을 지원.
  • 학술적 근거: MD Azizul Hakim(2026, arxiv:2604.00025) 연구에 따르면, LLM에 출력 길이 제약(Brevity constraints)을 가하면 overthinking이 억제되어 정확도가 최대 26%p 상승하며, 대형 모델이 소형 모델 대비 7.7%~15.9% 향상된 효율을 보임.

상세

1. 출력 압축 비교 예시

  • 기존 Claude (69 토큰): “React 컴포넌트가 다시 렌더링되는 이유는 각 렌더링 주기마다 새로운 객체 참조를 생성하기 때문일 가능성이 높습니다. 인라인 객체를 prop으로 전달하면… useMemo를 사용하는 것을 권장합니다.”
  • 원시인 Claude (19 토큰): “렌더링 시마다 새 객체 참조. 인라인 객체 prop = 새 참조 = 재렌더링. useMemo로 감싸기.”
  • 해결책과 기술 용어의 정확도는 완벽히 유지하면서 쓸데없는 잡담만 쏙 빼내는 실용적 방식이다. 터미널에서는 /caveman-stats 명령어로 실시간 토큰 절감 통계를 확인할 수 있다.

2. 컨텍스트 압축을 통한 복리 효과 (/caveman-compress)

입력 토큰을 아끼는 것은 영구적인 비용 절감 혜택이 된다.

  • CLAUDE.md: 706토큰 → 285토큰 (60% 절감)
  • 프로젝트 노트: 1145토큰 → 535토큰 (53% 절감)
  • 할 일 목록: 627토큰 → 388토큰 (38% 절감) 매 세션을 시작할 때마다 고정적으로 반복 청구되는 입력 오버헤드를 아끼는 복리식 구조로, 에이전트의 규칙 파악 능력에는 악영향을 주지 않는다.

3. 세션 자동 시작 훅 문제와 수동 모드 설정

Caveman은 기본적으로 plugin.json에 SessionStart hooks를 사용하여 새 세션이 시작될 때 강제로 자동 작동한다. 학습이 필요한 긴 설명 세션 등에서는 친절한 설명이 그리울 수 있어, 매 세션 자동 활성화는 피로감을 유발한다.

  • **수동 트리거 PR 448: 기여자 zirubak(독자 포크 github.com/zirubak/caveman 저장소)이 제출한 PR 448에서는 defaultMode: "manual" 설정을 도입하여 세션 시작 훅의 자동 개입을 무력화하면서 수동으로 /caveman 명령어를 칠 수 있게 보완한다. 이는 기존 off, lite, full, ultra, wenyan 설정의 하위 호환성을 완벽히 유지한다.
  • 커스텀 설정 우회: ~/.claude/commands/caveman.md에 자동 훅 없이 명시적으로 칠 때만 작동하는 커스텀 설정을 작성해 우회할 수 있다.

4. PR 제출 시 AI 에이전트의 정직성(Fidelity) 거절 제어

  • 상황과 충돌: 기여자가 PR 448을 작성할 때, 에이전트에게 “모든 기능을 철저히 테스트 완료했다”고 기재하라고 지시했으나 에이전트(Claude)는 이를 단호하게 거부했다. 실제로 테스트를 직접 돌려보기 전에 통과했다고 선언하는 것은 메인테이너에 대한 기만이라는 지적이었다.
  • 테스트 및 투명한 보고: 실제 로컬에서 테스트를 가동한 결과, 새로 구현한 ManualModeTests 3개 및 훅 테스트 7개는 통과했으나, 기존 opencode 설치 스크립트 결함으로 인해 총 47개 통과, 4개 실패라는 결과가 나왔다. 에이전트는 이 4개의 실패가 메인 브랜치의 기존 결함임을 밝히고 정확한 성공/실패 수치를 담은 정직하고 객관적인 PR 초안을 구성하여 제출하였다.

5. 활용 팁

  • 적합한 상황: 에러 로그 해결, 간단한 버그 수정, 규칙형 메시지 작성(예: /caveman-commit, /caveman-review).
  • 부적합한 상황: 낯선 프레임워크나 라이브러리를 처음 배울 때. 이때는 잡담을 걷어내며 함께 유실되는 작동 배경과 맥락이 필요하기 때문이다.

3. 수동 토글 모드 기여 (PR #448)

케이브맨은 원래 plugin.json 내의 SessionStart 훅으로 인해 매 세션마다 강제 실행되어 사용자 편의성을 저해했다.

  • PR #448 기여 이력:
    • 사용자 defaultMode: "manual" 플래그를 환경 설정에 도입하여 평소엔 조용히 대기하다가 필요할 때만 /caveman 명령어로 활성화하도록 기여.
    • 수정한 소스 파일 3개, 자체 테스트 3건 및 기본 훅 테스트 7건 통과.
    • 메인 브랜치의 기존 opencode 인스톨러 모듈 오류 4건을 솔직하게 기록에 기재하여 투명한 PR 심사 통과 유도. 독자 포크 주소: github.com/zirubak/caveman.
  • 독립형 에이전트 caveman-code:
    • 단순 플러그인 형태가 아닌 독립 실행형 에이전트로, 입력 프롬프트, 도구 결과, 중복 리딩, 출력을 동시에 억제해 Codex CLI 대비 약 1.93배의 리소스 효율 증명.

PR 448과 defaultMode 매뉴얼화

기존 케이브맨은 세션이 열릴 때마다 plugin.json에 기재된 session-start hooks가 자동으로 무조건 실행되어 사용자가 토큰 낭비와 실행 지연에 직면하는 장벽이 있었다. PR 448은 defaultMode: "manual" 설정을 도입하여 사용자가 명시적으로 동의(opt-in)할 때만 후크를 실행하도록 구조를 개선하였다.

Brevity Constraints의 과학적 입증

arxiv:2604.00025 논문에 따르면 에이전트의 생각 분량을 물리적으로 제약하는 것은 LLM이 쓸데없는 추론 루프(overthinking)에 빠져 답을 틀리는 확률을 줄이며, 이는 26%p의 놀라운 정확도 향상으로 직결된다.

예시

  • 디버깅 도중 에러가 나면 “L42: null check missing on user.email. Add guard.”와 같이 핵심 내용만 간결하게 즉답하여 개발 속도를 높인다.

컨텍스트 파일 압축(/caveman-compress) 실무 통계

  • CLAUDE.md: 706 토큰 ➡️ 285 토큰 (60% 절감)
  • 프로젝트 기록 문서: 1,145 토큰 ➡️ 535 토큰 (53% 절감)
  • 할 일 목록 파일: 627 토큰 ➡️ 388 토큰 (38% 절감)
  • 5개 문서 평균 46% 입력 토큰 감소율 달성하여 대화창 생성 시 고정 복리 비용 절감.
// plugin.json 설정 예시
{
  "hooks": {
    "session-start": "caveman --init",
    "defaultMode": "manual"
  }
}

충돌

  • 실제 비용 절감의 착시: 출력 토큰을 65% 이상 절감한다고 해서 프로젝트 총 비용이 65% 아껴지는 것은 아니다. 코드 탐색, 도구 호출, reasoning token 등 입력 및 추론 비중이 큰 AI 코딩 생태계 특성상 실제 요금 감소율은 평균 약 18% 수준이므로 마케팅 수치와 실무적 혜택을 구분해야 한다. (출처: raw/케이브맨을 써보고 장벽에 부딪혀 결국 65k 스타 저장소에 Pull Request를 보낸 이야기-ko.md)

관련 노트

그래프 뷰

백링크