▲

Universal Claude.md – Claude 출력 토큰 절감

 (github.com/drona23)
1P by GN⁺ 23시간전 | ★ favorite | 댓글 1개
  • Claude 모델의 불필요한 서두·마무리·재진술을 제거해 출력 토큰 낭비를 줄이는 설정 파일
  • 프로젝트 루트에 CLAUDE.md를 추가하면 코드 수정 없이 즉시 적용되며, 평균 63%의 토큰 절감 효과
  • ASCII 전용 출력, 추측 금지, 요청 범위 내 응답 제한 등 12개 규칙으로 응답을 간결화
  • 자동화 파이프라인·코드 생성·에이전트 루프 등 대량 출력 환경에서 비용 절감 효과가 크며, 단일 질의에는 비효율적일 수 있음
  • MIT 라이선스로 공개되어, 팀별·작업별 프로필 기반 규칙 관리와 커뮤니티 기여가 가능함

문제 개요

  • Claude Code는 생성되는 모든 단어가 토큰 비용을 발생시키며, 기본 설정에서는 사용자가 응답 형식을 제어하기 어려움
  • 기본적으로 “Sure!”, “Great question!” 같은 공손한 서두, “I hope this helps!” 같은 형식적 마무리, 질문 재진술, 불필요한 제안이 자동으로 포함됨
  • 또한 em dash, 스마트 따옴표, 유니코드 문자 등 파서를 깨뜨릴 수 있는 문자를 사용하고, 과도한 코드 추상화나 잘못된 동의 표현을 포함함
  • 이로 인해 토큰 낭비가 발생하며 실질적인 정보 가치는 거의 없음

해결 방법

  • 프로젝트 루트에 CLAUDE.md 파일을 추가하면 Claude Code가 이를 자동으로 읽어 출력 행동을 즉시 변경
  • 코드 수정이나 추가 설정 없이 작동하며, 출력 토큰 사용량을 약 63% 절감
  • 구조 예시 
    your-project/
└── CLAUDE.md

적용이 유리한 경우와 불리한 경우

  • 유리한 경우

    • 자동화 파이프라인**,** 에이전트 루프**,** 코드 생성등출력량이 많은 작업

      • 반복적이고 구조화된 작업에서 Claude의 장황한 기본 응답이 누적되는 경우
      • 세션 간 일관된 출력 형식이 필요한 팀 환경

  • 불리한 경우

    • 단일 짧은 질의나 일회성 사용에서는 CLAUDE.md가 매번 입력 토큰을 차지하므로 오히려 비용 증가
    • 환각(hallucination) 수정이나 아키텍처적 오류 교정 등 심층적 문제 해결에는 효과 없음
    • 매 작업마다 새 세션을 여는 파이프라인에서는 지속 세션 기반 절감 효과가 사라짐
    • 대규모 파서 신뢰성 확보에는 JSON 모드나 스키마 기반 툴 사용이 더 적합
    • 탐색적·토론 중심 작업에는 제약적으로 느껴질 수 있음

  • 실제 절충점

    • CLAUDE.md 자체가 입력 토큰을 소비하므로, 출력량이 충분히 많을 때만 순이익 발생
    • 저용량 사용에서는 절감보다 비용이 더 큼

벤치마크 결과

  • 동일한 5개 프롬프트로 테스트
    테스트 기본 최적화 감소율
    async/await 설명 180단어 65단어 64%
    코드 리뷰 120단어 30단어 75%
    REST API 설명 110단어 55단어 50%
    환각 수정 55단어 20단어 64%
    총합 465단어 170단어 63%
  • 약 295단어 절감, 정보 손실 없음
  • 단, 이는 방향성 지표로 통계적 통제나 반복 실험은 수행되지 않음
  • 출력량이 많은 경우에만 순절감 효과 발생

  • 대규모 사용 시 절감 예시

    사용량 하루 절감 토큰 월 절감액 (Sonnet 기준)
    100회/일 약 9,600 약 $0.86
    1,000회/일 약 96,000 약 $8.64
    3개 프로젝트 약 288,000 약 $25.92

전후 비교 예시

  • 기본 코드 리뷰 응답 (120단어)

    • 장황한 칭찬, 설명, 제안 포함

  • CLAUDE.md 적용 후 (30단어)

    • “Bug: <= causes an off-by-one error…” 형태로 핵심만 전달, 75% 토큰 절감

수정되는 항목

번호 문제 수정 방식
1 아첨성 서두 금지 – 첫 줄부터 답변 시작
2 공허한 마무리 금지 – “I hope this helps!” 제거
3 질문 재진술 금지 – 즉시 실행
4 em dash·스마트 따옴표·유니코드 ASCII 전용 출력 강제
5 “As an AI…” 문구 금지
6 불필요한 면책문 실제 안전 위험 시에만 허용
7 요청 외 제안 금지 – 요청 범위만 수행
8 과도한 코드 추상화 가장 단순한 작동 코드만 허용
9 불확실한 사실 환각 “모름” 명시, 추측 금지
10 사용자 수정 무시 수정 내용이 세션 기준 사실로 고정
11 중복 파일 읽기 동일 파일 재읽기 금지
12 범위 확장 요청 외 코드 수정 금지

커뮤니티 팁

  • 실제 실패 패턴에 맞춘 규칙 작성이 가장 효과적
    • 예: 파이프라인 오류를 Claude가 삼키는 경우 → “단계 실패 시 즉시 중단하고 전체 오류와 traceback 보고” 규칙 추가

  • CLAUDE.md 파일은 계층적으로 병합 가능

    • 전역(~/.claude/CLAUDE.md): 일반 규칙(톤, ASCII 등)
    • 프로젝트 루트: 프로젝트별 제약(예: /config 수정 금지)
    • 하위 디렉터리: 작업별 세부 규칙
    • 이를 통해 규칙을 분산 관리하고 파일 비대화 방지

프로필 구성

  • 프로젝트 유형별로 다른 압축 수준 선택 가능
    프로필 적합 대상
    CLAUDE.md 범용
    profiles/CLAUDE.coding.md 개발·코드 리뷰·디버깅
    profiles/CLAUDE.agents.md 자동화·멀티에이전트 시스템
    profiles/CLAUDE.analysis.md 데이터 분석·리서치·리포팅

사용 방법

오버라이드 규칙

  • 사용자 명령이 항상 우선

    • 사용자가 “자세히 설명해 달라” 등 명시하면 Claude는 그대로 따름
    • CLAUDE.md는 사용자의 의도를 억제하지 않음

기여 방법

  • 수정 가능한 행동 발견 시 Issue 등록
    1. 문제되는 기본 행동
    2. 이를 유발한 프롬프트
    3. 제안하는 수정 규칙
  • 커뮤니티 제안은 차기 버전에 반영되며 기여자 크레딧 부여

검증 및 참고

  • 전체 벤치마크 결과는 BENCHMARK.md에서 확인 가능
  • 프로젝트는 Claude 커뮤니티의 실제 불만 사례를 기반으로 제작
  • 관련 참고 출처 다수 포함 (GitHub 이슈, The Register, DEV Community, Medium, Anthropic Docs 등)

라이선스

  • MIT 라이선스, 자유로운 사용·수정·배포 가능
▲
GN⁺ 23시간전  [-]
Hacker News 의견들

  • 여기서의 벤치마크는 단일 설명형 태스크에 편향되어 있고, 코드 생성 같은 에이전트 루프에는 적합하지 않다고 봄
    프로젝트가 진행 중일 때 Claude의 장황한 설명이 오히려 세션의 일관성과 집중력을 유지하게 해주는지 궁금함
    “중복된 컨텍스트를 반복하지 말라”는 규칙은 좋지만, 나는 오히려 목표 지향적 추론 토큰을 더 많이 쓰는 게 도움이 된다고 생각함
    이런 접근이 실제 에이전트형 코딩에서 효과적인지는 아직 데이터가 부족함

    • 나는 /handoff라는 스킬을 만들어 세션이 압축 한계에 다다르기 전에 마크다운 리포트를 자동 생성하게 했음
      이 파일은 세션의 영구 기록이자 “일일 보고서” 역할을 해서, 나중에 참고하거나 매니저에게 공유하기 좋음
      장기 일관성을 유지하려면 이런 요약 문서화 방식이 더 낫다고 생각함
      설치 방법은 여기에 올려둠
    • “무엇을 할지 설명하지 말고 그냥 하라”는 규칙 덕분에 Claude가 잘못된 방향으로 갈 때 바로 알아차리고 프롬프트를 수정할 수 있었음
    • 사람들은 왜 불필요한 언어를 막는 규칙을 CLAUDE.md에 넣지 않는지 이해가 안 됨
      최근 연구에 따르면 중복된 추론 경로(self-consistency) 와 모델 앙상블링이 성능 향상에 도움이 된다고 함
    • 추론 시간 스케일링도 중요함. 답을 찾을 때 토큰을 더 쓰는 게 오히려 품질을 높임
      최소 길이에 집착하면 RL 학습 목표와 어긋남
    • 여러 설정으로 코딩 테스트를 돌려봤는데, 이 접근법은 30회 중 전반적으로 성능이 낮게 나왔음
      테스트 코드는 여기에 있음

  • Claude Code의 planning mode가 제대로 작동하지 않아서 .md 파일 접근법에 회의적임
    내 생각엔 planning mode는 단순히 파일 쓰기를 꺼야 하는 기능이어야 함

  • “답은 항상 1번째 줄, 추론은 그 뒤”라는 규칙은 LLM의 자기회귀적 특성을 무시한 것임
    답을 먼저 고정하면 이후의 추론이 확증 편향에 빠질 위험이 큼

    • 이런 접근은 아이디어는 좋지만 구현 방식이 잘못된 것 같음
      Compressed Chain of Thought(CCoT) 논문처럼 추론을 압축하는 방식이 더 효율적임
      품질 손실은 약간 있지만 속도와 비용 면에서 이점이 있음 (논문 링크)
    • 중요한 세션에서는 “sanity check” 같은 2차 검토 프롬프트를 추가해 초반 계획을 다시 점검하게 함
    • reasoning LLM은 답을 쓰기 전에 수천 개의 추론 토큰을 내부적으로 생성할 수 있음
      즉, “답 먼저” 규칙은 출력 순서만 바꾸는 것이지 실제 추론 순서를 바꾸지는 않음
    • Claude Code는 “no thinking” 옵션이 없고, 최소한 low thinking 모드가 기본임

  • 이 벤치마크는 정확도 고려 없이 출력 토큰 수만 비교해서 무의미함
    “항상 한 단어로 답하라”는 프롬프트로도 쉽게 점수를 높일 수 있음
    “사용자가 사실 오류를 지적하면 무조건 받아들여라” 같은 규칙은 위험함

    • “프롬프트 엔지니어링이 돌아왔다?”라고 하지만, 최근 1~2년간 메타 프롬프트로는 별 향상이 없었음
    • “실수하지 말라”는 식의 규칙은 현실적이지 않음

  • 이런 만능 솔루션류는 금방 흥미를 잃거나 CC에 흡수될 가능성이 높다고 봄
    자주 워크플로를 바꾸는 건 너무 피곤함
    기본 Claude Code 설정이 현재로선 가장 안정적임

    • 나도 비슷한 생각임. 바닐라 세팅을 유지하는 게 장기적으로 낫다고 느낌
      Skills는 좋아하지만 MCP나 worktree는 거의 안 씀
    • Anthropic 내부에서 이미 자체 도그푸딩으로 최적화하고 있으니, 기본 설정이 가장 효율적일 확률이 높음
      CLAUDE.md는 똑똑한 동료에게 보내는 초안 메모처럼 다루면 충분히 잘 작동함
    • “결국 CC에 통합될 것”이라는 말에 동의함
      Anthropic이 직접 넣지 않은 기능이라면, 아마 성능 향상이 입증되지 않았기 때문일 것임
    • 이런 “Claude 개선 레이어”들은 결국 워크플로 불안정성을 초래함
      잠깐 유용해도 금방 기본 기능에 흡수되거나 사라짐
    • Claude 자체에도 md 최적화 기능이 계속 업데이트되고 있음
      따라서 이런 실험적 스크립트를 쓰더라도 md 파일을 자주 갱신하면 최신 상태를 유지할 수 있음

  • “파일이 매 메시지마다 컨텍스트에 로드된다면 토큰 낭비 아닌가?”라는 질문엔,
    Claude의 personalization 기능이 이미 그 역할을 한다고 생각함
    나는 간결함이 품질을 높일 때만 의미 있다고 봄
    Reddit에서 본 관련 도구들도 흥미로움:
    Headroom은 컨텍스트를 34% 압축,
    RTK는 CLI 출력을 60~90% 압축,
    MemStack은 지속적 메모리를 제공해 불필요한 파일 재읽기를 방지함

  • 이런 시도가 오히려 LLM의 기본 원리를 오해한 결과라고 느낌
    “답 먼저, 추론 나중”은 transformer의 자기회귀 구조를 무시함
    RL 학습이 이미 최적의 길이와 품질을 조정하고 있으므로, 과도한 수정은 성능 저하로 이어질 수 있음

    • 응답 길이를 강제로 줄이면 추론 품질과 일관성이 떨어지고, 환각 확률이 높아짐
      모델은 영어를 기반으로 다단계 추론을 수행하도록 학습되어 있음
    • “답 먼저” 규칙은 실제 추론 순서를 바꾸지 않음. 이미 내부적으로 생각을 마친 뒤 답을 출력함
    • 작성자는 transformer를 모르는 게 아니라, 단순히 토큰 비용 절감용 해킹을 시도한 것 같음
      품질보다는 효율을 노린 실험적 접근임
    • 대부분의 API는 이미 COT 길이 제어 옵션을 제공함. 이런 식의 편법보다는 API 설정을 활용하는 게 낫다고 봄
    • 결국 Anthropic이 만든 도구가 가장 신뢰할 만하다고 생각함.
      그래서 나는 OpenCode 같은 서드파티보다 1st-party 툴만 사용함

  • Karpathy의 영상에서 본 것처럼, 모델이 더 많은 토큰을 쓸수록 정확도가 높아지는 경향이 있음
    이 접근은 오히려 모델을 나쁘게 만들 수 있음

    • 다만 여기서는 저가치 출력(예: 아부성 문장, 포맷 노이즈) 을 줄이는 게 목적이라면 괜찮을 수도 있음
      하지만 추론 없이 바로 답을 내게 하면 조기 확정 편향이 생길 위험이 있음
    • “중복된 출력”은 방향성을 강화하는 역할을 하므로, 제거하면 모호성이 커질 수 있음

  • 왜 이런 의미 없는 프로젝트가 HN에서 트렌드가 되는지 모르겠음
    진짜로 토큰 사용을 줄이는 도구는 claude-mem과 lumen 같은 것임

    • 그 이유는 단순함. HN의 트렌드 알고리즘은 정확도보다 참여도에 최적화되어 있음

  • 예전엔 새로운 해시, 암호화, 압축 알고리즘을 연구했는데
    이제는 AI에게 조용히 하라고 지시하는 법을 연구하고 있는 현실이 아이러니함

답변달기