Claude Code .claude 디렉터리: 무엇이 언제 읽히고 무엇이 쌓이기만 하나

홈의 ~/.claude/projects/를 열어 보면 경로가 이름이 된 폴더가 프로젝트 수만큼 쌓여 있습니다. 한 공개 이슈에는 대부분이 최근 한 달 치인 대화 기록이 423MB였다는 보고도 있어요. 그렇다고 ~/.claude를 통째로 지우면 로그인과 설정, 설치한 플러그인까지 함께 사라집니다.

헷갈리는 이유는 .claude 안에 성격이 다른 두 가지가 섞여 있어서입니다. 사람이 쓰고 Claude가 읽는 설정(CLAUDE.md·settings.json·skills/ 등)과, Claude가 쓰기만 하는 기록(대화 기록·프롬프트 기록·파일 스냅샷)이요.

용량이 문제라면 기록 쪽을 프로젝트 단위로 claude purge로 지우고, ~/.claude.json·~/.claude/settings.json·~/.claude/plugins/는 건드리지 마세요.

2026년 9월 21일 Anthropic 공식 문서를 기준으로 정리했고, 10월 12일에 Windows 11 · PowerShell 5.1과 Claude Code 2.1.296으로 폴더 이름 규칙, 세션 하나가 남기는 기록, claude purge, cleanupPeriodDays: 0을 직접 확인했습니다. 디스크가 실제로 찬 사례는 공개된 이슈를 인용했습니다.

.claude는 프로젝트 안(<프로젝트>/.claude/)과 홈(~/.claude/, Windows는 %USERPROFILE%\.claude) 두 곳에 있습니다. CLAUDE.md에 무엇을 적을지는 CLAUDE.md를 어디에 두고 무엇을 적어야 하는지 정리한 글에 따로 있습니다.

설정과 기록이 한 폴더에

~/.claude/projects/ 아래 폴더들은 Claude Code가 쓰는 기록이고, 같은 .claude 안의 settings.json은 사람이 쓰는 설정입니다. 둘은 수명도 다루는 법도 다릅니다.

묶음	누가 씀	대표 파일	어디에
팀과 공유하는 설정	사람	CLAUDE.md, rules/, settings.json, skills/, agents/, workflows/	프로젝트(커밋)·홈
개인 설정	사람	settings.local.json, ~/.claude.json, keybindings.json, themes/	커밋하지 않음
기록	Claude Code	projects/, history.jsonl, file-history/, debug/, 캐시	홈만

기록 쪽 경로는 모두 홈 ~/.claude 아래에 있습니다. 그래서 저장소를 아무리 깨끗하게 유지해도 홈 쪽은 따로 늘어나요.

같은 이름의 설정이 프로젝트와 홈 양쪽에 있으면 프로젝트 settings.json이 홈 것을 덮고, settings.local.json이 사람이 편집하는 파일 중 가장 높습니다. 그 위로 CLI 플래그와 조직의 관리 설정이 있고, 환경 변수 일부는 같은 뜻의 설정보다 앞서는데 변수마다 다릅니다.

홈의 CLAUDE.md·rules/·스킬·서브에이전트·워크플로는 모든 프로젝트에 적용됩니다.

프로젝트의 CLAUDE.md·rules/·settings.json·skills/·commands/·agents/·workflows/·output-styles/·.mcp.json·.worktreeinclude는 커밋 대상이고, settings.local.json은 Claude Code가 저장할 때 gitignore 처리합니다.

같은 키가 겹칠 때 어느 값이 이기는지는 설정 파일 네 개가 겹칠 때 어느 값이 이기는지에 있습니다.

설정은 언제 읽히나

설정 파일도 다 같은 때 읽히지 않습니다. 세션을 열기만 해도 읽히는 것과, 부르거나 조건이 맞을 때만 읽히는 것으로 나뉘어요.

시작 때 읽히는 파일: 매 세션의 고정 비용

파일	위치	읽히는 방식
CLAUDE.md	프로젝트 루트·.claude/, 홈	모든 세션 시작 때 컨텍스트로
rules/*.md(paths: 없음)	프로젝트·홈	시작 때
settings.json	프로젝트·홈	지시가 아니라 세션 설정
settings.local.json	프로젝트만	개인용 세션 설정
workflows/*.js	프로젝트·홈	시작 때, 파일마다 /<이름> 명령
output-styles/*.md	프로젝트·홈	시작 때, 고른 스타일이 모든 응답에
MEMORY.md(자동 메모리)	홈 projects/<프로젝트>/memory/	앞 200줄(25KB 상한)
~/.claude.json	홈	취향과 MCP 서버, /config·신뢰 확인 답을 되씀
keybindings.json, themes/*.json	홈	시작 때, 고치면 바로 반영
.mcp.json	프로젝트 루트	시작 때 서버 연결, 도구 스키마는 필요할 때

여기 두는 것이 늘수록 첫 질문을 던지기 전에 컨텍스트가 이미 찹니다. 자주 안 쓰는 지시라면 스킬이나 paths: 규칙으로 옮기는 게 낫습니다. 그 비용이 어디서 드러나는지는 컨텍스트가 찰 때 생기는 일과 관리 수단에 있습니다.

여기서 헷갈리기 쉬운 숫자 둘을 갈라 두겠습니다. CLAUDE.md는 200줄 미만을 권장할 뿐 더 길어도 전부 읽습니다(길면 잘 지키지 않을 수 있습니다). 상한은 4MiB이고 그보다 크면 건너뛰어요. 반면 200줄·25KB에서 잘리는 것은 자동 메모리의 MEMORY.md뿐입니다.

자동 메모리는 기본으로 켜져 있고, 프로젝트마다 ~/.claude/projects/<프로젝트>/memory/를 씁니다. 경로가 git 저장소에서 정해지므로 같은 저장소의 워크트리와 하위 폴더는 메모리를 공유하고, 다른 기기나 클라우드와는 동기화되지 않습니다.

부르거나 조건이 맞을 때만 읽히는 파일

파일	읽히는 때
rules/*.md(paths: 있음)	글롭에 맞는 파일이 컨텍스트에 들어올 때
하위 폴더의 CLAUDE.md	Claude가 그 폴더의 파일을 읽을 때
skills/<이름>/SKILL.md	/<스킬 이름>으로 부르거나 작업과 맞을 때
commands/*.md	/<커맨드 이름>을 입력할 때
agents/*.md	그 서브에이전트를 부를 때(자체 컨텍스트에서 실행)
agent-memory/<이름>/MEMORY.md	그 서브에이전트가 시작할 때 앞 200줄(25KB 상한)
자동 메모리의 주제 파일	관련 작업이 나올 때
.worktreeinclude	--worktree·EnterWorktree·isolation: worktree로 워크트리를 만들 때

표에 commands/와 skills/가 따로 있지만, 지금은 같은 메커니즘입니다. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md가 둘 다 /deploy를 만들고, 스킬은 보조 파일을 묶고 누가 호출할지 프런트매터로 정할 수 있어요.

새로 만든다면 저는 스킬 쪽을 권합니다. 기준은 스킬로 반복 작업을 묶는 기준에 있습니다.

기록은 30일 뒤 지워지지만, 남는 것도 있다

도입에서 말한 보고는 tbarkai가 2026년 7월 25일 이슈에 적은 것입니다. 자기 대화 기록 폴더가 423MB(파일 732개)였고 거의 전부 최근 한 달 치라 하루 약 13MB꼴이었다고 해요. 기록은 이렇게 늘어나는 자리입니다.

경로	쌓이는 것
projects/<프로젝트>/<세션>.jsonl	메시지·도구 호출·결과 전부
projects/<프로젝트>/<세션>/tool-results/	따로 뺀 큰 도구 출력
file-history/<세션>/	고치기 전 파일 스냅샷(체크포인트용)
history.jsonl	입력한 모든 프롬프트, 시각·프로젝트 경로
debug/, plans/, paste-cache/, image-cache/	디버그 로그, 플랜, 큰 붙여넣기, 첨부 이미지
shell-snapshots/	시작 때 캡처한 셸 설정, 정상 종료 때 삭제
backups/	~/.claude.json 이전 버전 최신 5개
stats-cache.json	/usage의 누적 집계

<프로젝트>는 작업 폴더 경로에서 영숫자가 아닌 문자를 -로 바꾼 이름이고, 200자를 넘으면 200자로 자른 뒤 전체 경로의 해시를 붙입니다.

Windows에서는 드라이브 문자 뒤의 콜론과 백슬래시가 둘 다 -가 되어 하이픈이 두 개 붙습니다. C:\work\my-repo에서 세션을 열어 보니 홈의 projects 폴더 안에 C--work-my-repo라는 폴더가 생기더라고요. 탐색기에서 찾을 때는 C--로 시작하는 이름을 보면 됩니다.

얼마나 빨리 쌓이는지도 재 봤습니다. 파일 한 줄만 고친 짧은 세션인데 대화 기록이 39줄, 약 245KB였어요. 도구를 부르고 파일을 읽는 일이 많은 평소 작업이라면 세션 하나가 몇 MB가 되는 게 이상하지 않습니다.

claude -p로 돌린 세션은 history.jsonl에 줄이 늘지 않았습니다. 이 파일은 직접 입력한 프롬프트를 모으는 곳이라 대화형으로 쓸 때 쌓입니다.

자동 정리는 cleanupPeriodDays(기본 30일, 최소 1)를 기준으로 세션 시작 뒤 백그라운드에서 돕니다. 보존 기간을 안전하게 판정할 수 있을 때만 돌고, claude -p --bare 세션에서는 돌지 않습니다(관리 설정이 값을 주면 그 값으로 돕니다).

기록을 끄려고 0을 넣는 건 피하세요. 최소값이 1이라 설정 검증에서 걸리는데, 그렇다고 실행이 막히지는 않습니다. 프로젝트 settings.json에 "cleanupPeriodDays": 0을 넣고 claude -p를 돌려 보니 오류 없이 답이 나왔고, 대화 기록도 그대로 새로 쌓였어요.

조용히 넘어가는 게 함정입니다. cleanupPeriodDays를 넣은 설정에 오류가 있으면 보존 기간을 판정할 수 없어 자동 정리가 멈춥니다.

경고는 /status에서 보이고, -p 실행에서는 아무 표시가 없었어요. 기록을 줄이려던 설정이 오히려 정리를 끄는 셈입니다. 오래 남기려면 3650 같은 큰 값을 쓰고, 기록 자체를 남기지 않으려면 아래 방법을 쓰세요.

자동 정리가 지우지 않는 것도 있습니다.

• history.jsonl, stats-cache.json: 사람이 지울 때까지 남습니다. 조직의 HIPAA 구성이 적용되는 세션이라면 history.jsonl에서도 보존 기간이 지난 줄이 지워집니다.
• sessions/: 실행 중인 세션을 감지하는 작은 파일입니다. 나이 기준이 아니라 세션이 끝날 때 지워지고, 남은 것은 다음 실행 때 정리됩니다.
• 자동 메모리: 메모리 파일은 지우지 않고, 폴더가 보존 기간 내내 비어 있었을 때만 폴더를 지웁니다. v2.1.228 이전에는 메모리 폴더 안의 하위 폴더를 기록으로 보고 오래된 파일을 지울 수 있었으니, 메모리 파일이 사라졌다면 버전을 올리고 /memory로 남은 것을 확인하세요.
• Claude Desktop·Cowork 기록: 그쪽에서 시작했거나 마지막으로 이어 간 세션은 나이와 무관하게 남습니다. 기간을 두려면 desktopSessionCleanupPeriodDays를 설정합니다(v2.1.248 이상). 관리 설정이 cleanupPeriodDays를 정했다면 그 기간이 적용됩니다.

대화 기록과 프롬프트 기록은 암호화되지 않고 OS 파일 권한만이 보호이므로, 도구가 .env를 읽거나 명령이 자격 증명을 출력하면 그 값이 .jsonl에 그대로 남습니다.

용량보다 이쪽이 더 신경 쓰인다면, 노출을 줄이는 방법은 이렇습니다.

1. cleanupPeriodDays를 낮춥니다.
2. desktopSessionCleanupPeriodDays로 Desktop·Cowork 기록에도 기간을 둡니다.
3. 환경 변수 CLAUDE_CODE_SKIP_PROMPT_HISTORY로 어느 모드에서든 기록을 쓰지 않게 합니다. 비대화형은 -p와 --no-session-persistence, TypeScript Agent SDK는 persistSession: false도 됩니다(Python SDK에는 대응 옵션이 없음).
4. 권한 규칙으로 자격 증명 파일 읽기를 막습니다.

다만 기록을 아예 안 남기면 그만큼 잃는 것도 있습니다. projects/가 없으면 과거 세션의 재개·이어가기·되감기를 못 해요.

지울 때는 claude purge로, 프로젝트 단위로

프로젝트 하나 분량을 지우는 전용 명령이 있습니다. Claude Code 2.1.288부터 이름이 claude purge이고, 전 이름 claude project purge도 안내 문구와 함께 동작합니다.

먼저 --dry-run으로 지울 목록만 보세요. 앞에서 세션을 열었던 C:\work\my-repo로 돌려 보니 이렇게 나왔습니다.

claude purge C:\work\my-repo --dry-run

Purge plan for C:\work\my-repo:

  dir:    %USERPROFILE%\.claude\projects\<프로젝트>
           project transcripts (.jsonl) and memory/

Dry run: 1 item(s) would be deleted.
shell-snapshots/ are not project-scoped and will not be touched
backups/ may still contain this project entry in old .claude.json snapshots (%USERPROFILE%\.claude\backups); at most 5 are kept and they rotate out automatically

목록이 맞으면 --dry-run을 빼고 다시 실행합니다. 확인을 물으면 y로 답하고, --yes를 붙이면 묻지 않고 지웁니다. 실행하니 Purged 1 item(s) for C:\work\my-repo.가 찍히고 그 폴더가 사라졌어요.

• 지우는 것: 그 프로젝트의 projects/ 대화 기록과 자동 메모리, 세션별 tasks/·debug/·file-history/, history.jsonl의 해당 줄, ~/.claude.json의 프로젝트 항목.
• 진행 방식: 삭제 계획을 먼저 보여 주고 y일 때만 지웁니다. --yes는 확인을 건너뛰고, 경로 대신 --all이면 모든 프로젝트를 정리하며 history.jsonl은 통째로 지웁니다.
• 남기는 것: 프로젝트 단위가 아닌 shell-snapshots/·backups/(계획 출력에서 경고), 그리고 그 세션에 붙여 넣은 이미지와 세션 스크래치패드. 둘은 Claude Code의 임시 폴더에 있어서, 이미지는 보존 기간이 지나면 자동 정리가 지우고 스크래치패드는 직접 지우거나 운영체제가 임시 폴더를 비울 때까지 남습니다.

손으로 지운다면 무엇을 잃는지는 알고 지우세요.

지우면	잃는 것
~/.claude/projects/	과거 세션 재개·이어가기·되감기, 모든 프로젝트의 자동 메모리
~/.claude/history.jsonl	위쪽 화살표 재호출, Ctrl+R 검색, ! 명령 자동완성
~/.claude/file-history/	과거 세션의 체크포인트 복원
~/.claude/stats-cache.json	/usage 누적 집계
debug/, plans/, image-cache/, session-env/, shell-snapshots/, backups/	드러나는 것 없음

~/.claude를 통째로 지우는 건 권하지 않습니다. 지우면 안 되는 파일까지 사라지거든요.

~/.claude.json, ~/.claude/settings.json, ~/.claude/plugins/에는 인증·설정·설치한 플러그인이 있습니다. .credentials.json(로그인 자격 증명), agent-memory/(서브에이전트 메모리), jobs/·daemon/(백그라운드 세션 상태)도 남겨 둘 파일이에요.

file-history/가 실제로 무엇을 되돌려 주는지는 체크포인트와 /rewind가 되돌리는 것과 못 되돌리는 것에 있습니다.

~/.claude.json이 깨져 시작 때 설정 오류가 나면(손으로 고칠지 기본값으로 되돌릴지 묻고, -p는 오류를 내고 종료), Claude Code가 깨진 파일을 ~/.claude/backups/.claude.json.corrupted.<타임스탬프>로 복사해 둡니다. 같은 폴더의 최근 5개 .claude.json.backup.<타임스탬프> 중 하나를 제자리로 복사하면 이전 상태로 돌아갑니다.

다른 사람들이 겪은 문제

아래는 공개된 GitHub 이슈에서 확인한 내용입니다. 네 건 중 세 건에서 가장 큰 자리는 projects/의 대화 기록이었고, 한 건은 file-history/였습니다.

보고	커진 자리	수치
kolkov, 2026-02-08	projects/·debug/·file-history/	2,707MB·734MB·188MB(합계 3,640MB)
tbarkai, 2026-07-25	대화 기록 폴더	423MB, 30일 넘은 것은 12MB
100401031, 2026-06-17	.jsonl 3개	약 726·705·704MB, projects 전체 약 3.1GB
brookcs3, 2025-10-22	file-history/	300GB

• kolkov(#24207)는 293GB 디스크가 0바이트까지 찼다고 보고했지만, 이 용량이 다른 이슈의 네이티브 애드온 누수(#23095, 본문 표기로 Windows에서 주당 약 20GB)와 임시 파일 누수(#8856) 위에 더해진 것이라고 적었으니 .claude 혼자 채운 것은 아닙니다. debug/에 “정리되지 않는다”고 적었지만 지금 문서는 debug/를 자동 정리 대상에 넣고 있고, 보고 당시 동작이 같았는지는 알 수 없습니다. not planned로 닫혔습니다.
• tbarkai(#81065)는 732개 파일 중 30일 넘은 것은 92개뿐이라 거의 최근 한 달 치였고, gzip -6으로 388MB를 137MB(65% 절감)로 줄일 수 있었다며 압축을 제안했습니다. 30일 정리가 제때 돌아도 보존 기간 안의 기록은 남으니 모순은 아니지만, 오래된 쪽이 적은 이유가 정리 때문인지 최근 사용이 몰려서인지는 알 수 없습니다. not planned로 닫혔습니다.
• 100401031(#69009)은 데스크톱 앱이 실행 10~12초 만에 V8 힙 부족으로 죽었는데, 700MB급 파일 세 개만 밖으로 옮기면 정상이고 되돌리면 재현됐다고 적었습니다(macOS, Claude Desktop 1.13576.0, 번들 Claude Code 2.1.177). 보통 대화 기록은 몇 MB라고 덧붙였고요. 닫혀 있습니다.
• brookcs3(#10107)는 macOS에서 한 파일의 버전이 v6638 이상 쌓였고 스냅샷 하나가 약 36MB였으며, 프로세스 하나가 118분 넘게 101.7% CPU를 쓰고 있었고 그걸 끄자 682MB로 줄었다고 보고했습니다. 중복으로 닫혔습니다.

두 건(#24207, #10107)은 디스크가 0바이트가 되거나 300GB에 이른 뒤에야 문제가 드러났습니다. 큰 붙여넣기와 대량 출력은 그대로 기록에 실린다는 점을 기억해 두세요.

마치며

.claude를 정리할 때 제일 먼저 할 일은 설정과 기록을 가르는 것이라고 봅니다. 시작 때 읽히는 설정은 매 세션의 고정 비용이니 가볍게 두고, 기록은 홈에만 쌓이면서 30일 뒤 지워지지만 history.jsonl처럼 남는 것이 있고 모두 평문이라는 걸 기억해 두세요. 지울 때는 claude purge로 프로젝트 단위로 지우고, ~/.claude.json·settings.json·plugins/는 남기면 됩니다.

지금 ~/.claude/projects/의 크기를 한 번 확인해 보세요. 크다면 claude purge <프로젝트 경로> --dry-run으로 지울 목록부터 보면 됩니다. 시작 때 들어오는 지시를 줄이고 싶다면 CLAUDE.md 작성법을 이어서 보세요.