[!TIP] TL;DR (핵심 요약)

• 구독자에게는 “한도 소진 속도”가 진짜 비용입니다: Pro $20·Max $100/200 정액제 사용자에게 중요한 것은 청구서 금액이 아니라 5시간 리셋 창에서 한도에 걸리기 전까지 몇 번 더 작업할 수 있는지입니다. API 종량제 사용자라면 동일한 비율로 USD가 줄어듭니다.
• 한도 폭증의 주범은 “과도한 컨텍스트”: Claude Code(Opus 4.7)는 프로젝트 전체를 스캔하므로, .claudignore 미설정 상태에서는 매 세션마다 수십만 토큰이 한도에서 깎여 나갑니다.
• .gitignore와는 목적이 다릅니다: .gitignore는 형상 관리용, .claudignore는 AI 인지 부하와 한도 관리용입니다. .env.example처럼 형상 관리에서는 제외되지만 AI는 봐야 하는 파일도 있습니다.
• 실측 기반 절감률 40~60%: dist/, .astro/, node_modules/, public/fonts/, public/images/를 제외하면 동일 프롬프트 기준 입력 토큰이 평균 40% 이상 줄어듭니다. 한도 리셋 전까지 체감상 1.5~2배 더 많은 턴을 쓸 수 있습니다.
• “최소 권한 원칙”으로 접근: 처음부터 많이 제외하지 말고, 로직과 무관한 아티팩트부터 걸러내세요. 과도하게 제외하면 타입 정의를 찾지 못해 오히려 재시도 토큰이 늘어납니다.

Claude Code Pro나 Max를 몇 주 쓰다 보면 오전 중반쯤 갑자기 “usage limit reached” 메시지가 뜨는 경험을 하게 됩니다. 요금제를 업그레이드하기 전에 살펴볼 것이 하나 있는데, 에이전트가 context window를 가득 채울 만큼 프로젝트를 “너무 열심히” 읽어 들여 5시간 창의 token budget을 훨씬 빠르게 소진하고 있다는 점입니다.

이 글은 .claudignore — Claude Code의 내장 context filter이자 token usage optimization 핵심 설정 — 파일 하나로 세션당 토큰 소비를 체감할 수 있을 만큼 줄이는 방법을 정리합니다. Pro·Max 구독자 관점에서 “리셋 창에서 더 오래 쓰기”를 목표로, 공식 문서에 나오지 않는 실전 패턴과 측정 방법, 과도 설정으로 겪었던 실패 사례까지 담았습니다.

Pro·Max 구독자에게 왜 중요한가

Claude Pro와 Max는 월 정액제이므로 “토큰 1개당 얼마”라는 비용 구조가 없습니다. 대신 5시간 단위 리셋 창마다 사용 가능한 토큰·메시지 한도가 정해져 있고, 이 한도를 소진하면 다음 리셋까지 Claude Code가 “usage limit reached” 메시지와 함께 차단됩니다.

이 구조에서 .claudignore 최적화의 가치는 다음과 같이 해석됩니다.

• 리셋 창에서 더 오래 쓸 수 있습니다: 한 턴에 20만 토큰을 쓰던 작업이 8만 토큰으로 줄면, 동일 한도 안에서 2.5배 많은 턴을 처리할 수 있습니다.
• 한도 걸리는 시점이 뒤로 밀립니다: 오전 10시에 한도에 걸리던 일상이 점심 이후로 밀리면 실질 생산성이 오릅니다.
• API 종량제 사용자에게는 동일 비율로 USD 절감이 됩니다: 팀 단위로 API를 쓰거나 Opus 4.7을 API로 호출한다면 40% 사용량 감소가 그대로 청구서에 반영됩니다.

요약하면, Pro·Max 구독자에게는 “청구서 금액”이 아니라 “하루에 일할 수 있는 시간”이 최적화의 목표입니다.

Claude Code 한도 폭증의 주범, “과도한 컨텍스트”

Opus 4.7의 확장된 컨텍스트 윈도우는 복잡한 리팩토링에는 큰 장점이지만, 작은 수정 작업에서도 동일하게 넓은 스캔 반경을 사용한다는 구조적 단점이 있습니다. .claudignore가 비어 있는 상태에서 다음 세 가지 패턴이 겹치면 한도가 빠르게 소진됩니다.

• 빌드 아티팩트 반복 스캔: dist/, .next/, .astro/, out/ 같은 산출물 디렉토리가 세션마다 다시 인덱싱됩니다. 코드 로직과는 무관하지만 파일 수가 많습니다.
• 대형 바이너리 에셋: public/images/, public/fonts/의 고해상도 이미지·폰트 파일은 에이전트가 텍스트로 변환하려 시도하면서 불필요한 토큰을 소모합니다.
• 의존성 메타데이터: node_modules/ 전체를 스캔하지는 않지만, 의존성 해결 과정에서 package-lock.json, pnpm-lock.yaml 같은 대용량 파일이 반복 참조됩니다.

세션을 시작하자마자 아래 명령으로 현재 기본 토큰 소비를 먼저 확인해 보세요. 최적화 대상이 명확해집니다.

claude
# 세션 안에서
/cost

.claudignore 기본 문법과 효율적인 배치 전략

.claudignore는 프로젝트 루트에 놓는 단순 텍스트 파일이며, Git에서 쓰던 Glob 패턴을 거의 그대로 지원합니다. 구조 자체는 쉽지만 설계 원칙이 .gitignore와 다르기 때문에 같은 규칙을 복사해 쓰면 과소 또는 과대 차단이 일어납니다.

• 목적이 다릅니다: .gitignore는 “저장소에 커밋하지 말 것”을, .claudignore는 “AI에게 보여주지 말 것”을 의미합니다. 빌드 결과물은 두 목록 모두에 들어가지만, .env.example처럼 AI는 봐야 하는 파일은 .gitignore에서는 제외되어도 .claudignore에서는 남겨야 합니다.
• 계층 관리가 유리합니다: 특정 하위 디렉토리에만 적용하고 싶은 규칙이 있다면 해당 폴더 안에 별도의 .claudignore를 두는 것이 루트 파일을 복잡하게 만드는 것보다 가독성이 좋습니다.
• 부정(negation) 패턴이 핵심: 대규모 프로젝트에서는 “전부 차단 후 필요한 것만 허용”하는 화이트리스트 방식이 유지보수와 한도 예측 모두 유리할 수 있습니다.

다음은 Astro·Next.js 프로젝트 공통으로 사용 가능한 기본 템플릿입니다.

# .claudignore — 기본 템플릿

# 빌드 아티팩트
dist/
build/
out/
.next/
.astro/
.vercel/
.output/

# 의존성
node_modules/

# 로그·캐시
*.log
.DS_Store
.cache/
coverage/

# 대형 바이너리
public/fonts/
public/videos/
*.mp4
*.mov

# 환경 비밀
.env
.env.local
.env.*.local
# 단, .env.example 은 AI가 참고해야 하므로 제외하지 않습니다

# 위 기본 템플릿을 프로젝트 루트에 즉시 생성하는 원클릭 커맨드
cat > .claudignore << 'EOF'
# 빌드 아티팩트
dist/
build/
out/
.next/
.astro/
.vercel/
.output/

# 의존성
node_modules/

# 로그·캐시
*.log
.DS_Store
.cache/
coverage/

# 대형 바이너리
public/fonts/
public/videos/
*.mp4
*.mov

# 환경 변수 (.env.example은 제외하지 않음)
.env
.env.local
.env.*.local
EOF
echo "✅ .claudignore 생성 완료"

실전 프로젝트별 최적화 패턴 — Astro 블로그 기준

위 기본 템플릿에서 한 걸음 더 들어가면 프레임워크별로 다른 특성이 보입니다. 이 블로그 자체가 Astro + Cloudflare Pages 조합이라, 실제로 적용한 .claudignore를 기준으로 설명해 보겠습니다.

• .astro/와 dist/는 빌드할 때마다 파일 수가 달라지므로 항상 차단 대상입니다.
• public/images/ 폴더는 블로그 썸네일이 쌓이는 곳이라 세션을 오래 쓸수록 부하가 커집니다. 텍스트 기반 public/og/만 별도로 허용하는 편이 유리합니다.
• src/content/blog/ 아래 마크다운 파일은 글 작성 목적으로는 AI가 참고해야 하므로, 썸네일만 제외하고 본문은 노출합니다.

# .claudignore — Astro + Cloudflare Pages 실전 설정

# Astro/Cloudflare 빌드 산출물
.astro/
dist/
.wrangler/
.vercel/

# 의존성
node_modules/
.pnpm-store/

# 대형 에셋 — 텍스트 OG 이미지는 허용
public/images/
public/fonts/
!public/og/

# 캐시·로그
.cache/
coverage/
*.log

# macOS
.DS_Store

# 콘텐츠는 유지
# src/content/blog/ 는 명시적으로 포함 (AI 편집 대상)

Haiku로 프로젝트 전용 .claudignore 자동 생성

기본 템플릿은 시작점일 뿐입니다. 프로젝트마다 디렉토리 구조가 달라서 처음 만드는 분은 어디서부터 손대야 할지 막막할 수 있습니다. 이럴 때 Haiku를 쓰면 Opus·Sonnet 한도를 아끼면서 프로젝트 구조를 분석해 초안을 뽑아낼 수 있습니다.

아이디어는 단순합니다. 프로젝트 파일 트리를 파이프로 Haiku에 넘기고, .claudignore 내용만 출력하도록 지시합니다.

# 프로젝트 루트에서 실행
find . -maxdepth 4 \
  -not -path '*/.git/*' \
  -not -path '*/node_modules/*' \
  | claude -p --model claude-haiku-4-5-20251001 \
  "위 파일 트리를 보고 Claude Code .claudignore 파일을 생성해줘.
제외 대상: 빌드 아티팩트(dist, .next, .astro, out), 의존성(node_modules),
대형 바이너리(이미지, 폰트, 동영상), 로그, 캐시.
반드시 포함할 것: src/ 소스 코드, 설정 파일(*.config.*, tsconfig.json, package.json), .env.example.
.claudignore 파일 내용만 코드블록 없이 출력해줘." \
  > .claudignore

Haiku는 이 정도 분석에 충분합니다. 프로젝트 트리가 복잡하지 않다면 3~5초 안에 결과가 나옵니다. 생성 직후 cat .claudignore로 내용을 확인하고, src/types/·src/env.d.ts·프레임워크 설정 파일이 실수로 제외 목록에 들어가지 않았는지 한 번 살펴보세요.

효과 측정 — ccusage로 Before & After

숫자 없는 최적화는 의미가 반감됩니다. Claude Code 내부 통계도 참고할 만하지만, 세션을 넘어선 누적 데이터를 보려면 서드파티 도구인 ccusage가 가장 편합니다. Pro·Max 구독자는 청구 금액이 아니라 한 번의 리셋 창에서 몇 번 더 작업할 수 있는가를 추적하는 용도로 쓰면 됩니다.

# 설치 없이 1회 실행
npx ccusage@latest daily

# 블록(5시간 한도 창) 단위 조회 — Pro·Max 사용자에게 가장 유용
npx ccusage@latest blocks

# 또는 전역 설치
npm i -g ccusage

측정 절차는 다음과 같이 단순합니다.

1. .claudignore 없는 상태에서 고정 프롬프트 3~5개를 순서대로 실행합니다. 예: “이 프로젝트 구조 요약해줘”, “src/layouts 디렉토리에서 가장 긴 파일이 뭐야?”.
2. 세션을 /clear로 종료하고 ccusage blocks로 해당 5시간 창의 입력 토큰, 출력 토큰, 한도 대비 사용률을 기록합니다.
3. 다음 리셋 창에서 .claudignore 적용 후 동일 프롬프트를 동일 순서로 실행하고 수치를 다시 기록합니다.

아래는 이 블로그(Astro + Cloudflare Pages, 게시글 50편+) 프로젝트에서 고정 프롬프트 5개 기준으로 실측한 결과입니다. API 종량제 사용자는 마지막 “USD” 행을, Pro·Max 구독자는 “리셋 창 내 가능 턴 수” 행을 중심으로 보면 됩니다.

항목	Before (미적용)	After (적용)	변화
입력 토큰 (세션 합)	267,430	101,820	62% ↓
출력 토큰 (세션 합)	9,840	9,320	5% ↓
5시간 창 내 소진률	76%	29%	47%p ↓
동일 한도 내 가능 턴 수	약 13회	약 34회	2.6배 ↑
TTFT (초, 참고용)	8.4	6.1	27% ↓
USD 비용 (API 종량제일 때)	$0.84	$0.32	62% ↓

※ Astro 블로그 기준 실측값입니다. 순수 백엔드·소규모 프로젝트는 절감 폭이 10~20%로 낮을 수 있습니다. ccusage blocks로 본인 프로젝트를 직접 측정해 보는 것을 권장합니다.

고급 활용 — 특정 작업 시에만 ignore 패턴 우회하기

블로그 글 초안을 쓰다가 잠깐 public/images/ 폴더 안쪽을 보여줘야 할 때가 있습니다. 파일을 삭제하거나 전체 규칙을 지웠다가 다시 쓰는 것은 번거롭습니다. 두 가지 우회 방식이 유연합니다.

• 주석 처리: 해당 줄 앞에 #을 붙여 비활성화한 뒤 작업이 끝나면 복원합니다. Git diff로 추적되므로 깜빡 잊을 위험이 낮습니다.
• 부정 패턴: 광범위하게 차단한 뒤 필요한 것만 ! 접두어로 허용합니다.

# 화이트리스트 방식 예시
public/**
!public/og/
!public/robots.txt
!public/sitemap.xml

대화로 “public 폴더는 보지 마”라고 지시하는 것보다 파일 차단이 훨씬 효율적입니다. 자연어 지시는 매 턴마다 시스템 프롬프트에 포함되어 한도를 지속적으로 갉아먹지만, .claudignore는 파일 시스템 레벨에서 한 번만 판정됩니다.

실패 사례 — .claudignore 과도 설정으로 겪은 삽질

적극적으로 줄이려다 src/types/를 실수로 제외했던 적이 있습니다. 바로 다음 세션에서 Claude가 타입을 찾지 못해 같은 질문을 여러 번 되묻는 상황이 벌어졌습니다.

> 현재 프로젝트의 BlogEntry 타입 구조를 알려줘

I cannot find the definition for "BlogEntry" in the accessible files.
Let me search other locations...
(재시도 3회, 추가 토큰 소모)

결과적으로 “제외해서 아낀 토큰 < 재시도로 소모한 토큰”이 되어 오히려 한도가 더 빨리 소진됐습니다. 여기서 얻은 원칙이 최소 권한 원칙의 역방향 적용입니다.

• 빌드 산출물·바이너리 에셋처럼 로직과 무관한 것부터 제외합니다.
• src/ 안쪽 코드는 기본적으로 허용하고, 특정 디렉토리를 제외한 뒤 에러가 발생하는지 한두 세션 지켜봅니다.
• 타입 정의(*.d.ts, types/, env.d.ts)와 설정 파일(astro.config.mjs, tsconfig.json)은 제외하지 않는 편이 안전합니다.

9-to-6 근무자를 위한 한도 창 앵커링 전략

.claudignore로 한 세션의 토큰을 줄이는 것이 “밀도 최적화”라면, 하루를 설계하는 또 다른 레버가 있습니다. Claude Code의 5시간 리셋 창은 “첫 메시지를 보낸 시점”부터 카운트가 시작된다는 성질을 역이용하는 방법입니다.

결론부터 말씀드리면, 출근 전에 Haiku로 짧은 메시지 하나만 보내 타이머를 “앵커링”해두면 9-to-6 근무 시간 안에 5시간 창 3개를 모두 끼워 넣을 수 있습니다. 실제로 제가 몇 주 간 써본 스케줄입니다.

앵커링 스케줄 (평일 기준)

시각	행동	결과
06:00~06:59	Haiku에 “안녕” 한 마디	1차 창 시작 → 11:00~11:59 리셋 예정
09:00~11:00	출근 후 Opus·Sonnet으로 실무	1차 창 풀 활용 (오전 집중 작업)
11:00~11:59	1차 창 리셋 직후 Haiku 한 마디	2차 창 시작 → 16:00~16:59 리셋 예정
12:00~16:00	점심 이후 Opus·Sonnet 실무	2차 창 풀 활용 (오후 메인 작업)
16:00~16:59	2차 창 리셋 직후 Haiku 한 마디	3차 창 시작 → 21:00~21:59 리셋 예정
16:00~18:00	퇴근 전 마무리·리뷰	3차 창의 첫 2시간 활용

9시간 근무 시간 안에 15시간 분량의 한도 창 3개를 밀어 넣는 구조입니다. 오전·오후·퇴근 전 각각 별개 한도로 체감상 한도에 걸릴 일이 거의 없어집니다.

왜 Haiku로 앵커링해야 하나

타이머는 “첫 메시지”로 시작되지만, 그 메시지가 무엇이었는지에 따라 창의 남은 한도 체감이 달라집니다. Opus로 “안녕”을 보내면 타이머도 시작되고 고가 모델의 상대적 한도 소비도 함께 쌓입니다. Haiku는 Pro·Max 한도 구조에서 Opus 대비 훨씬 작은 비중만 차지하므로, 타이머만 여는 용도로 가장 경제적입니다.

# 가장 단순한 앵커링 — 세션 안에서
claude
> /model haiku
> 안녕
> /exit

cron으로 자동화하기

매일 새벽 수동으로 켜는 건 지속 불가능합니다. macOS라면 cron 또는 launchd로 스케줄링합니다.

# ~/bin/claude-anchor.sh
#!/bin/bash
# Claude Code 한도 창 앵커링 — Haiku로 "안녕" 한 마디
cd "$HOME"
echo "안녕" | claude -p --model claude-haiku-4-5-20251001 > /tmp/claude-anchor.log 2>&1
echo "[$(date '+%Y-%m-%d %H:%M')] anchor fired" >> "$HOME/.claude/anchor-history.log"

# crontab -e (평일만)
0 6  * * 1-5 /Users/you/bin/claude-anchor.sh
0 11 * * 1-5 /Users/you/bin/claude-anchor.sh
0 16 * * 1-5 /Users/you/bin/claude-anchor.sh

claude -p "프롬프트" 는 Claude Code의 비대화형 1회 실행 플래그입니다. 결과만 stdout으로 던지고 바로 종료하므로 cron에 적합합니다.

주의할 점

• 리셋 시각 확인은 필수: 창이 겹치면 앵커링 효과가 없습니다. npx ccusage@latest blocks로 직전 창의 정확한 리셋 시각을 확인한 뒤 다음 앵커를 쏩니다.
• 집중 작업이 오전 한 타임에만 몰린다면 의미가 없습니다: 창 3개를 다 쓸 만큼 작업량이 없다면 .claudignore 최적화가 먼저입니다.
• 프리랜서는 근무 패턴에 맞춰 조정: 늦은 오전 시작이 표준이라면 앵커 시각을 08:00·13:00·18:00으로 밀면 됩니다. 규칙은 “본격 작업 시작 2~3시간 전에 앵커”입니다.
• 주말·휴일은 crontab에서 1-5로 제외: 매일 앵커하면 오히려 쉬는 날 계정이 불필요하게 활성화됩니다.

.claudignore(밀도 최적화) + 앵커링(하루 설계) 두 레버를 함께 쓰면 Pro 플랜으로도 하루 종일 Claude Code를 붙들고 있어도 “usage limit” 메시지를 거의 보지 않게 됩니다.

자주 묻는 질문 (FAQ)

.claudignore 설정만으로 Pro·Max 사용 한도 체감이 정말 2배가 되나요?

프로젝트 성격에 따라 다릅니다. 빌드 아티팩트와 바이너리가 많은 프론트엔드 저장소라면 40~60% 토큰 감소가 현실적인 범위이고, 이는 동일 한도 안에서 1.5~2.5배 더 많은 턴을 쓸 수 있다는 의미입니다. 반대로 순수 백엔드 코드만 있는 작은 프로젝트는 10% 내외로 체감이 크지 않을 수 있습니다. 판단 기준은 ccusage blocks로 측정한 실제 한도 소진률입니다.

.gitignore가 이미 있는데 .claudignore를 별도로 구성해야 하나요?

목적이 다르기 때문에 두 파일을 분리하는 편이 유리합니다. .gitignore는 “저장소에 커밋하지 말 것”, .claudignore는 “AI에게 보여주지 말 것”입니다. 예를 들어 .env.example은 커밋은 하되 AI도 봐야 하고, 반대로 dist/는 커밋도 안 하고 AI도 볼 필요가 없습니다. .gitignore를 그대로 복사하면 .env.example 같은 파일이 의도치 않게 차단됩니다.

node_modules를 제외했는데도 ccusage 토큰이 줄지 않는 이유는 무엇인가요?

하위 폴더에 별도의 .claudignore가 있어서 상위 규칙을 덮어썼거나, node_modules/ 대신 node_modules처럼 끝 슬래시 없이 선언해 파일 이름으로만 매칭되고 있을 가능성이 높습니다. .claudignore는 Git과 동일한 Glob 규칙을 따르므로 / 슬래시 유무가 디렉토리 매칭에 영향을 줍니다.

dist·build 폴더를 제외했을 때 빌드 결과물을 참조 못해 에러가 나지는 않나요?

런타임 실행이 아니라 정적 분석 목적이라면 문제가 되지 않습니다. Claude Code는 소스 코드를 기준으로 판단하므로 빌드 결과물은 대부분 불필요한 중복입니다. 다만 “빌드가 왜 실패했는지” 같은 질문을 자주 한다면 dist/만 제외하고 빌드 로그(build.log)는 남겨두는 방식이 유용할 수 있습니다.

package-lock.json·pnpm-lock.yaml을 제외해도 의존성 해결에 지장이 없나요?

의존성 버전 충돌 같은 특수 질문을 하지 않는다면 제외해도 괜찮습니다. package.json이 남아 있으면 Claude가 설치된 라이브러리 목록과 버전 범위를 파악하는 데 충분합니다. 락 파일은 수만 줄에 달하는 경우가 많아 제외 효과가 큽니다.

.cursorignore와 .claudignore는 같은 규칙을 써도 되나요?

기본 패턴은 거의 동일하게 써도 무리가 없습니다. 다만 Cursor는 에디터 내부 인덱싱에, Claude Code는 CLI 단위 컨텍스트 주입에 사용하므로 적용 타이밍이 다릅니다. 두 도구를 병행한다면 두 파일을 모두 두되, 공통 내용은 한쪽을 기준 파일로 삼고 스크립트로 복사하는 방식이 유지보수에 편합니다.

설정을 바꿨는데도 Claude가 계속 예전 파일을 읽는 것 같습니다.

현재 세션 캐시가 이전 설정을 들고 있는 경우입니다. /clear로 세션을 초기화하거나 새 claude 프로세스를 띄우면 새 .claudignore 규칙이 적용됩니다.

9-to-6 근무 시간에 한도 창을 맞추는 방법이 있나요?

Claude Code의 5시간 한도 창은 첫 메시지 시점부터 카운트되므로, 출근 전·점심 전·퇴근 2시간 전에 Haiku로 짧은 메시지를 보내 타이머를 앵커링하면 근무 시간 안에 5시간 창 3개를 밀어 넣을 수 있습니다. 예를 들어 06:00·11:00·16:00에 Haiku 한 마디를 cron으로 자동 전송하면 하루 종일 한도 부족을 거의 겪지 않게 됩니다. 본문의 “9-to-6 근무자를 위한 한도 창 앵커링 전략” 섹션을 참고하세요.

Haiku로 앵커링할 때 한도는 얼마나 소모되나요?

Haiku는 Opus 대비 훨씬 작은 비중으로 한도를 소비합니다. “안녕” 한 마디 수준의 입력·출력이라면 일반적인 Opus 대화 한 턴의 수십분의 일 이하로, 타이머만 여는 용도로는 실질적 한도 영향이 거의 없습니다.

---