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

> Clean Markdown view of GeekNews topic #28077. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=28077](https://news.hada.io/topic?id=28077)
- GeekNews Markdown: [https://news.hada.io/topic/28077.md](https://news.hada.io/topic/28077.md)
- Type: GN+
- Author: [neo](https://news.hada.io/@neo)
- Published: 2026-04-01T09:55:22+09:00
- Updated: 2026-04-01T09:55:22+09:00
- Original source: [github.com/drona23](https://github.com/drona23/claude-token-efficient)
- Points: 2
- Comments: 1

## Topic Body

- 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` | 데이터 분석·리서치·리포팅 |

### 사용 방법
- **옵션 1 (범용)**
  ```bash
  curl -o CLAUDE.md https://raw.githubusercontent.com/drona23/claude-token-efficient/main/CLAUDE.md
  ```
- **옵션 2 (프로필 선택)**
  ```bash
  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 라이선스**, 자유로운 사용·수정·배포 가능

## Comments



### Comment 54289

- Author: neo
- Created: 2026-04-01T09:55:22+09:00
- Points: 1

###### [Hacker News 의견들](https://news.ycombinator.com/item?id=47581701) 
- 여기서의 벤치마크는 **단일 설명형 태스크**에 편향되어 있고, 코드 생성 같은 **에이전트 루프**에는 적합하지 않다고 봄  
  프로젝트가 진행 중일 때 Claude의 장황한 설명이 오히려 세션의 **일관성과 집중력**을 유지하게 해주는지 궁금함  
  “중복된 컨텍스트를 반복하지 말라”는 규칙은 좋지만, 나는 오히려 목표 지향적 추론 토큰을 더 많이 쓰는 게 도움이 된다고 생각함  
  이런 접근이 실제 **에이전트형 코딩**에서 효과적인지는 아직 데이터가 부족함
  - 나는 `/handoff`라는 스킬을 만들어 세션이 압축 한계에 다다르기 전에 **마크다운 리포트**를 자동 생성하게 했음  
    이 파일은 세션의 영구 기록이자 “일일 보고서” 역할을 해서, 나중에 참고하거나 매니저에게 공유하기 좋음  
    장기 일관성을 유지하려면 이런 **요약 문서화 방식**이 더 낫다고 생각함  
    설치 방법은 [여기](https://news.ycombinator.com/item?id=47581936)에 올려둠
  - “무엇을 할지 설명하지 말고 그냥 하라”는 규칙 덕분에 Claude가 잘못된 방향으로 갈 때 바로 알아차리고 프롬프트를 수정할 수 있었음
  - 사람들은 왜 **불필요한 언어**를 막는 규칙을 CLAUDE.md에 넣지 않는지 이해가 안 됨  
    최근 연구에 따르면 **중복된 추론 경로(self-consistency)** 와 **모델 앙상블링**이 성능 향상에 도움이 된다고 함
  - **추론 시간 스케일링**도 중요함. 답을 찾을 때 토큰을 더 쓰는 게 오히려 품질을 높임  
    최소 길이에 집착하면 RL 학습 목표와 어긋남
  - 여러 설정으로 코딩 테스트를 돌려봤는데, 이 접근법은 30회 중 전반적으로 **성능이 낮게 나왔음**  
    테스트 코드는 [여기](https://github.com/adam-s/testing-claude-agent)에 있음

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

- “답은 항상 1번째 줄, 추론은 그 뒤”라는 규칙은 **LLM의 자기회귀적 특성**을 무시한 것임  
  답을 먼저 고정하면 이후의 추론이 **확증 편향**에 빠질 위험이 큼
  - 이런 접근은 아이디어는 좋지만 구현 방식이 잘못된 것 같음  
    **Compressed Chain of Thought(CCoT)** 논문처럼 추론을 압축하는 방식이 더 효율적임  
    품질 손실은 약간 있지만 속도와 비용 면에서 이점이 있음 ([논문 링크](https://arxiv.org/abs/2412.13171))
  - 중요한 세션에서는 “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](https://github.com/chopratejas/headroom)은 컨텍스트를 34% 압축,  
  [RTK](https://github.com/rtk-ai/rtk)는 CLI 출력을 60~90% 압축,  
  [MemStack](https://github.com/cwinvestments/memstack)은 **지속적 메모리**를 제공해 불필요한 파일 재읽기를 방지함

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

- Karpathy의 영상에서 본 것처럼, 모델이 더 많은 토큰을 쓸수록 **정확도가 높아지는 경향**이 있음  
  이 접근은 오히려 모델을 나쁘게 만들 수 있음
  - 다만 여기서는 **저가치 출력(예: 아부성 문장, 포맷 노이즈)** 을 줄이는 게 목적이라면 괜찮을 수도 있음  
    하지만 추론 없이 바로 답을 내게 하면 **조기 확정 편향**이 생길 위험이 있음
  - “중복된 출력”은 방향성을 강화하는 역할을 하므로, 제거하면 **모호성**이 커질 수 있음

- 왜 이런 **의미 없는 프로젝트**가 HN에서 트렌드가 되는지 모르겠음  
  진짜로 토큰 사용을 줄이는 도구는 [claude-mem](https://github.com/thedotmack/claude-mem)과 [lumen](https://github.com/ory/lumen) 같은 것임
  - 그 이유는 단순함. HN의 **트렌드 알고리즘은 정확도보다 참여도**에 최적화되어 있음

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