.claude 디렉토리 탐색하기

.claude 디렉토리 탐색하기

Claude Code의 설정은 대부분 ~/.claude 디렉토리와 프로젝트의 .claude/ 폴더 안에 파일로 존재합니다. 어떤 파일이 언제 로드되고 어떤 역할을 하는지 이해하면, 커스터마이징을 올바른 위치에 넣을 수 있습니다. 이 문서는 "Choose the right file" 표와 파일 전체 레퍼런스, 그리고 Claude Code가 작업하며 자동으로 기록하는 애플리케이션 데이터까지 정리합니다.

출처: 공식문서

본문

이 탐색기가 보여주지 않는 것

이 탐색기는 직접 작성·편집하는 파일을 다룹니다. 일부 관련 파일은 다른 곳에 있습니다:

~/.claude에는 작업 중 Claude Code가 기록하는 데이터(대화 기록, 프롬프트 히스토리, 파일 스냅샷, 캐시, 로그)도 저장됩니다.

올바른 파일 고르기 (Choose the right file)

커스터마이징 종류마다 들어갈 파일이 다릅니다:

파일 레퍼런스 요약:

• CLAUDE.md — 매 세션 로드되는 지침 (프로젝트/전역, 커밋 ✓)
• rules/*.md — 주제 범위 지침, 선택적으로 경로 게이트 (Memory)
• settings.json — 권한·훅·env·모델 기본값 (프로젝트/전역, 커밋 ✓)
• settings.local.json — 개인 오버라이드, gitignore 대상 (프로젝트만)
• .mcp.json — 팀 공유 MCP 서버 (프로젝트만, 커밋 ✓)
• .worktreeinclude — 새 worktree로 복사할 gitignored 파일
• skills/<name>/SKILL.md — /name으로 호출·자동 호출되는 재사용 프롬프트 (커밋 ✓)
• commands/*.md — skills와 같은 메커니즘의 단일 파일 프롬프트 (커밋 ✓)
• output-styles/*.md — 응답 스타일 지침 (커밋 ✓)
• agents/*.md — 자체 프롬프트·도구를 가진 서브에이전트 정의 (커밋 ✓)
• workflows/*.js — /workflows로 저장된 동적 워크플로우 스크립트
• agent-memory/<name>/ — 서브에이전트의 영속 메모리 (커밋 ✓)
• ~/.claude.json — 앱 상태·OAuth·UI 토글·개인 MCP 서버 (전역만)
• projects/<project>/memory/ — Claude가 세션 간 스스로 적는 자동 메모리 (전역만)
• keybindings.json — 커스텀 키보드 단축키 (전역만)
• themes/*.json — 커스텀 컬러 테마 (전역만)

우선순위 주의: 관리형 설정(managed settings)이 모든 것을 덮어쓰며, CLI 플래그(--permission-mode, --settings)는 세션의 settings.json을 덮어씁니다. 일부 환경변수도 동등 설정보다 우선하지만 항목마다 다르므로 environment variables 레퍼런스를 확인하세요.

구성 트러블슈팅

설정·훅·파일이 적용되지 않으면 Debug your configuration의 검사 명령과 증상 우선 조회표를 참고하세요.

애플리케이션 데이터

~/.claude에는 세션 중에 기록되는 데이터가 있습니다. 이 파일들은 평문(plaintext)이며, 도구를 통과한 모든 것은 파일 내용·명령 출력·붙여넣은 텍스트 등 트랜스크립트로 디스크에 남습니다.

자동으로 정리되는 데이터

Claude Code는 아래 경로의 파일을 cleanupPeriodDays(기본 30일, 최소 1)보다 오래되면 자동 삭제합니다. 0으로 설정하면 검증 오류가 납니다.

• projects/<project>/<session>.jsonl — 전체 대화 트랜스크립트
• projects/<project>/<session>.orphaned-*.jsonl, .superseded-* — 덮어쓰거나 삭제하는 대신 보관해 둔 이전 트랜스크립트
• projects/<project>/<session>/subagents/ — 서브에이전트 대화 트랜스크립트
• projects/<project>/<session>/tool-results/ — 큰 도구 출력
• file-history/<session>/ — 편집 전 스냅샷 (checkpoint 복원용, 최근 100개 유지)
• plans/ — plan 모드 중 작성된 계획 파일
• debug/ — 세션별 디버그 로그 (--debug / /debug)
• paste-cache/ — 큰 붙여넣기 내용
• image-cache/<session>/ — 첨부 이미지
• uploads/<session>/ — 웹·모바일 앱에서 첨부한 파일
• session-env/ — 세션별 환경 메타데이터
• tasks/ — task 도구가 쓴 작업 목록
• shell-snapshots/ — 시작 시 캡처한 별칭·함수·쉘 옵션 (Bash 도구가 각 명령에 적용)
• backups/ — ~/.claude.json의 이전 버전 (최근 5개 + 파싱 실패본 1개 보관)
• feedback-bundles/, feedback/drafts/ — 피드백 아카이브
• usage-data/ — /insights 보고서
• todos/, statsig/, logs/ — 구버전 레거시 디렉토리(더 이상 작성 안 됨)

스윕을 건너뛰는 경우: claude -p --bare 모드, 또는 보존 기간을 안전하게 결정할 수 없을 때 스윕을 일시 중지합니다.

삭제할 때까지 유지되는 데이터

• history.jsonl — 입력한 모든 프롬프트(타임스탬프·프로젝트 경로 포함). 위-화살표 복귀·Ctrl+R 검색·! 쉘 완성에 사용
• stats-cache.json — /usage가 보여주는 토큰·비용 집계
• remote-settings.json — 서버 관리 설정의 캐시 사본(로그아웃 시 삭제)
• cache/changelog.md, policy-limits.json — 캐시

== 유지해야 할 상태 파일 ==

• .credentials.json — 로그인 자격증명
• agent-memory/ — 서브에이전트 메모리
• jobs/, daemon/ — 백그라운드 세션 상태

평문 저장 (Plaintext storage)

트랜스크립트와 히스토리는 저장 시 암호화되지 않습니다. OS 파일 권한이 유일한 보호 수단입니다. 노출을 줄이려면: cleanupPeriodDays를 낮추고, desktopSessionCleanupPeriodDays를 설정하며, CLAUDE_CODE_SKIP_PROMPT_HISTORY 환경변수를 설정하거나(비대화형에서는 --no-session-persistence 또는 SDK의 persistSession: false 사용), 권한 규칙으로 자격증명 파일 읽기를 차단하세요.

로컬 데이터 지우기

claude project purge <경로> 명령으로 한 프로젝트의 상태를 삭제합니다. 삭제 항목: projects/의 트랜스크립트·자동 메모리, 세션별 tasks/·debug/·file-history/, history.jsonl의 해당 프롬프트 줄, ~/.claude.json의 프로젝트 항목.

# 계획만 미리보기 (삭제 안 함)
claude project purge ~/work/my-repo --dry-run

# 확인 프롬프트로 삭제
claude project purge ~/work/my-repo

# 확인 생략 (스크립트용)
claude project purge ~/work/my-repo --yes

# 모든 프로젝트 한 번에 정리 (history.jsonl 전체 삭제)
claude project purge --all

경로를 생략하면 대화형 목록에서 프로젝트를 선택합니다. -i로 삭제 계획을 항목별로 진행합니다. shell-snapshots/·backups/는 프로젝트 범위가 아니므로 건드리지 않습니다.

삭제 시 잃게 되는 것: ~/.claude/projects/를 지우면 과거 세션의 resume·continue·rewind와 모든 프로젝트 자동 메모리를 잃습니다. ~/.claude.json, ~/.claude/settings.json, ~/.claude/plugins/는 인증·환경설정·설치 플러그인을 담고 있으므로 삭제하지 마세요.

더 알아보기

• Claude의 메모리 관리 (CLAUDE.md, rules, auto memory)
• 설정 구성 (permissions, hooks, env, model defaults)
• 스킬 생성하기
• 서브에이전트 구성하기