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

Universal Claude.md – cut Claude output tokens

Mar 31, 2026•killme2008•View Original

TL;DR Highlight

프로젝트 루트에 CLAUDE.md 파일 하나를 추가하는 것만으로 Claude의 불필요한 장황함(sycophancy, 불필요한 서두·결말·제안 등)을 줄여 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

snippet

# 프로젝트 구조
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

sycophancyLLM이 사용자의 비위를 맞추기 위해 틀린 말에도 동의하거나 칭찬 일색으로 답하는 경향. 예를 들어 사용자가 잘못된 코드를 보내도 '정말 좋은 접근이에요!'라고 답하는 식이다.

autoregressiveLLM이 텍스트를 생성하는 방식으로, 앞서 생성한 단어(토큰)들을 보고 다음 단어를 예측하는 구조. 한번 출력한 내용이 이후 출력에 영향을 주기 때문에, 답변을 먼저 고정하면 이후 추론이 그 답변에 종속된다.

agentic loopLLM이 사람의 개입 없이 스스로 도구를 사용하고, 결과를 판단하고, 다음 행동을 결정하는 반복 사이클. Claude Code가 파일을 읽고, 수정하고, 테스트를 돌리는 과정이 대표적인 예다.

context windowLLM이 한 번에 참고할 수 있는 텍스트의 최대 분량. CLAUDE.md 파일은 매번 이 context에 포함되어 로딩되므로, 짧은 대화에서는 오히려 token을 더 쓰게 만든다.

out of distribution모델이 학습할 때 본 적 없는 패턴의 입력을 받았을 때를 말함. 기본 동작에서 너무 많이 벗어나도록 지시하면 모델이 예상치 못한 방식으로 동작할 수 있다.

ground truth학습이나 평가에서 '정답'으로 취급되는 기준 데이터. 이 파일의 규칙에서는 사용자가 수정한 내용을 세션 내 절대 기준으로 삼으라는 의미로 사용됐다.