🚫

.claudeignore — 불필요한 파일 읽기 차단

Claude Code

토큰 낭비 방지 + 민감 파일 보호

Claude Code는 작업 중에 프로젝트 파일을 읽는다. 그런데 node_modules/, 빌드 결과물, 대용량 데이터 파일, 민감 정보 파일까지 읽으면 컨텍스트 윈도우가 불필요한 토큰으로 낭비된다.

.claudeignore 파일을 프로젝트 루트에 만들면, 지정한 패턴의 파일을 Claude가 읽지 않는다. 문법은 .gitignore와 완전히 동일하다.

왜 필요한가?

토큰 절약 — 대용량 파일(로그, 데이터셋, 바이너리)을 읽으면 컨텍스트 윈도우가 금방 차버린다
보안 — .env, credentials, 시크릿 키 파일을 Claude가 읽지 못하게 차단
정확도 향상 — 불필요한 파일을 제외하면 Claude가 관련 파일에 더 집중할 수 있다
속도 개선 — 파일 검색 범위가 줄어들어 Glob/Grep 등이 더 빨라진다

.gitignore와의 관계

.gitignore에 이미 포함된 파일은 Claude도 기본적으로 무시한다. .claudeignore는 Git에는 추적되지만 Claude에게 보여주고 싶지 않은 파일에 사용한다. 예를 들어 대용량 fixture 파일이나 생성된 코드 파일은 Git에는 있지만 Claude가 읽을 필요는 없다.

.claudeignore 추천 템플릿

# === 대용량 / 불필요 ===
node_modules/
vendor/bundle/
tmp/
log/
coverage/
.git/

# === 빌드 결과물 ===
public/assets/
public/packs/
dist/
build/
*.min.js
*.min.css

# === 데이터 / 바이너리 ===
*.sql
*.sqlite3
*.dump
*.csv
*.xlsx
db/GeoLite2-*.mmdb
storage/

# === 민감 정보 ===
.env*
config/master.key
config/credentials/*.key

# === 생성된 코드 ===
db/schema.rb          # 마이그레이션으로 재생성 가능
yarn.lock             # 패키지 매니저가 관리
Gemfile.lock          # bundler가 관리

# === 미디어 ===
*.mp4
*.mp3
*.png
*.jpg
*.gif
*.pdf

.claudeignore vs .gitignore 차이

구분	.claudeignore	.gitignore
대상	Claude Code의 파일 읽기	Git의 파일 추적
용도	토큰 절약 + 보안	레포지토리 관리
관계	.gitignore에 있는 건 자동 무시 + 추가로 더 무시	Claude와 무관
예시 (차이)	`db/schema.rb` (Git 추적 O, Claude 불필요)	`node_modules/` (둘 다 무시)

효과

토큰 절약

불필요한 파일 읽기 차단 → 컨텍스트 윈도우 여유 확보

보안 강화

.env, 시크릿 키 등 민감 파일 Claude 접근 차단

검색 속도 향상

Glob/Grep 범위 축소 → 파일 탐색 빨라짐

사용 방법

1

프로젝트 루트에 .claudeignore 파일 생성

2

.gitignore와 동일한 문법으로 무시할 패턴 작성

3

대용량 파일, 빌드 결과물, 민감 파일, 불필요한 데이터를 추가

4

.claudeignore 자체는 Git에 커밋하여 팀과 공유 가능

Source

Anthropic Docs