Universal CLAUDE.md – Claude output token 63% 줄이기

Who Should Read

Claude Code를 자동화 파이프라인이나 에이전트 루프에서 대량으로 사용 중이고, Claude의 장황한 응답 때문에 토큰 비용이 늘거나 파싱이 어려운 백엔드/AI 개발자.

Core Mechanics

• 프로젝트 루트에 CLAUDE.md 파일을 하나 넣으면 Claude Code가 자동으로 읽어서 응답 방식을 바꿔준다. 코드 변경 없이 즉시 적용되는 방식이다.
• Claude는 기본적으로 'Sure!', 'Great question!', 'Absolutely!' 같은 서두 구문, 'I hope this helps!' 같은 마무리 문구, em dash(—)나 스마트 따옴표 같이 파서를 망가뜨리는 유니코드 문자, 질문 재확인, 요청하지 않은 제안 등을 출력한다. 이 프로젝트는 이런 패턴을 억제하도록 Claude에게 지시한다.
• 저자는 이 파일로 output token을 약 63% 줄였다고 주장하지만, 본인도 README에서 실제 Claude 비용의 대부분은 output이 아닌 input token에서 발생한다고 명시하고 있다. 즉 전체 비용 절감 효과는 제한적이다.
• 이 파일이 효과적인 상황: 대량 자동화 파이프라인(이력서 봇, 에이전트 루프, 코드 생성), 수백 번 반복되는 구조화된 작업, 일관된 파싱 가능한 출력이 필요한 팀 환경.
• 이 파일이 역효과를 낼 수 있는 상황: 짧은 단일 쿼리(파일 자체가 매번 context에 로딩되므로 net token 증가), output이 적은 대화, 복잡한 추론이 필요한 agentic 코딩 작업.
• 파일 내 주요 규칙 예시로는 '답변은 항상 1번째 줄에, 추론은 그 이후에', '이미 세션에서 확인된 정보는 반복하지 말 것', '존재하지 않는 파일 경로/함수명/API 시그니처를 만들어내지 말 것', '사용자가 틀린 사실을 말하면 세션 내 ground truth로 수용' 등이 있다.
• 벤치마크는 단일 프롬프트 기준 output token 수만 측정했으며, 응답의 정확도나 품질은 측정하지 않았다. 또한 agentic 루프나 대규모 코드베이스 작업에 대한 데이터는 포함되어 있지 않다.

Evidence

• 벤치마크의 신뢰성에 대한 강한 비판이 있었다. 'Always answer with one word'라는 단 하나의 프롬프트로도 이 벤치마크 수치를 뛰어넘을 수 있다는 지적이 나왔고, 실제로 누군가가 해당 레포 Issues에서 지시 없이 응답할 때 token 효율이 오히려 가장 높다는 결과를 측정해서 공유하기도 했다.
• LLM의 autoregressive 특성을 무시한 설계라는 기술적 비판이 있었다. '답변을 추론보다 먼저 출력하라'는 규칙에 대해, LLM은 앞서 생성한 토큰에 기반해 다음 토큰을 예측하는 구조이기 때문에 답변을 먼저 고정시켜버리면 이후 추론이 그 답변을 정당화하는 확증 편향(confirmation bias)이 된다는 반론이 제기됐다. thinking mode를 켜지 않으면 의미 없는 규칙이라는 설명도 있었다.
• '사용자가 틀린 사실을 말하면 세션 전체에서 ground truth로 수용하라'는 규칙이 위험하다는 의견이 있었다. 프롬프트에서 사용자가 실수로 잘못된 전제를 말했을 때 Claude가 끝까지 그것을 사실로 받아들이게 되어, 모델이 틀린 내용에 이의를 제기하는 능력을 완전히 잃게 된다는 우려다.
• OpenRouter의 실제 데이터를 인용한 댓글이 있었다. programming 카테고리 기준으로 input token이 93.4%, reasoning token이 2.5%, output token이 4.0%에 불과하다는 통계로, output을 줄여봐야 전체 비용에 미치는 영향이 미미하다는 점을 지적했다. 저자 본인도 README에서 이를 인정하고 있다.
• token 절감을 위한 대안 도구들도 소개됐다. Headroom(API context를 약 34% 압축하는 localhost proxy), RTK(git/npm/빌드 로그 같은 CLI 출력을 60~90% 압축하는 Rust CLI proxy), MemStack(Claude Code에 persistent memory를 부여해 매번 코드베이스를 다시 읽지 않게 하는 도구) 등이 언급됐다. 이 도구들은 output이 아닌 input token을 줄이는 방식이라 실제 비용 절감에 더 효과적일 수 있다.

How to Apply

• Claude Code를 사용하는 자동화 파이프라인(예: CI에서 코드 리뷰 자동화, 반복적인 문서 생성 등)에서 output 파싱이 잘 안 된다면, 프로젝트 루트에 CLAUDE.md를 추가해 em dash, 스마트 따옴표, 서두 구문 제거를 지시해볼 수 있다. 단, 정확도 저하 여부도 함께 모니터링해야 한다.
• output token 절감보다 실질적인 비용 절감을 원한다면, output보다 훨씬 큰 비중을 차지하는 input token 쪽을 공략하는 게 더 효과적이다. Headroom(context 압축 proxy)이나 RTK(CLI 출력 압축)처럼 input을 줄이는 도구를 먼저 검토하는 것이 우선순위에 맞다.
• Claude Code를 복잡한 agentic 코딩 작업(대규모 코드베이스 리팩토링, 여러 파일 수정 등)에 쓰고 있다면, 이 파일 적용을 신중하게 고려해야 한다. 커뮤니티에서는 Claude의 verbose한 중간 설명이 긴 컨텍스트에서 모델이 '길을 잃지 않도록' 도와줄 수 있다는 의견이 있어서, 적용 전후의 작업 완성도를 비교해보는 것이 좋다.

Code Example

# 프로젝트 구조
your-project/
└── CLAUDE.md  # 이 파일 하나만 추가

# CLAUDE.md 핵심 규칙 예시
## Communication Rules
- Answer is always line 1. Reasoning comes after, never before.
- No redundant context. Do not repeat information already established in the session.
- No sycophantic openers: never start with Sure, Absolutely, Great question, etc.
- No closing remarks: never end with I hope this helps or Let me know if you need anything.
- No em dashes (--), smart quotes, or Unicode characters that break parsers.

## Code Output Rules  
- Never invent file paths, function names, or API signatures.
- Do not add abstractions beyond what was explicitly requested.
- Do not restate the question before answering.

Terminology

관련 논문

• Claude Code에서 HTML을 출력 포맷으로 쓰는 이유: Markdown보다 나은 점들

  Claude Code 팀이 Markdown 대신 HTML을 LLM 출력 포맷으로 선호하기 시작한 이유와 그 실용적 장점을 정리한 글로, AI와 함께 문서/스펙/대시보드를 만드는 워크플로우에 직접적인 영향을 준다.

• 언제 투표하고 언제 다시 쓸까: Disagreement 기반 Test-Time Scaling 전략 라우팅

  모델 출력이 얼마나 일치하는지 보고 쉬운 문제엔 majority voting, 어려운 문제엔 문제 rewriting을 자동으로 선택해 정확도 3~7% 올리고 샘플링 비용도 줄이는 학습 불필요 프레임워크.

• Less Is More: Android 앱에 On-Device Small Language Model 통합할 때 실제로 겪는 엔지니어링 문제들

  Wordle 게임에 온디바이스 SLM(Gemma 4 E2B, Qwen3 0.6B)을 5일간 붙여보면서 발견한 5가지 실패 유형과 8가지 실용 해결책 정리

• 확장 가능한 Synthetic Data 생성을 위한 Dynamic Context Evolution

  VTS + Semantic Memory + Adaptive Prompt 3가지 메커니즘으로 구성된 프레임워크는 LLM 대량 synthetic data 생성 시 배치 간 중복·반복 현상을 완전히 제거한다.

• Karpathy 워크플로우에서 영감받아 사전 컴파일된 Wiki로 세션당 토큰 90%+ 절감

  사전에 정리된 코드베이스 Wiki를 활용하면 Claude 세션당 토큰 사용량을 90% 이상 줄인다.

• 3개월치 AI 생성 코드를 전부 삭제했다. 그리고 배운 것들.

  AI로 작성된 코드베이스를 70% 삭제 후 2주 만에 재작성하니 절반 크기로 줄어들면서 완전한 이해 가능성을 확보했다.

Related Resources

• https://github.com/drona23/claude-token-efficient
• https://github.com/drona23/claude-token-efficient/blob/main/BENCHMARK.md
• https://github.com/drona23/claude-token-efficient/issues/1
• https://aifoc.us/the-token-salary/
• https://github.com/chopratejas/headroom
• https://github.com/rtk-ai/rtk
• https://github.com/cwinvestments/memstack
• https://github.com/thedotmack/claude-mem
• https://github.com/ory/lumen