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

• 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% 토큰 절감

수정되는 항목

커뮤니티 팁

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

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

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

프로필 구성

• 프로젝트 유형별로 다른 압축 수준 선택 가능
  프로필 적합 대상

  CLAUDE.md	범용
  profiles/CLAUDE.coding.md	개발·코드 리뷰·디버깅
  profiles/CLAUDE.agents.md	자동화·멀티에이전트 시스템
  profiles/CLAUDE.analysis.md	데이터 분석·리서치·리포팅

사용 방법

• 옵션 1 (범용) curl -o CLAUDE.md https://raw.githubusercontent.com/drona23/claude-token-efficient/…
• 옵션 2 (프로필 선택) git clone https://github.com/drona23/claude-token-efficient cp claude-token-efficient/profiles/CLAUDE.coding.md your-project/CLAUDE.md

• 옵션 3 (수동)

  • 저장소의 CLAUDE.md 내용을 직접 복사

오버라이드 규칙

• 사용자 명령이 항상 우선

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

기여 방법

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

검증 및 참고

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

라이선스

• MIT 라이선스, 자유로운 사용·수정·배포 가능