.claude 디렉토리 탐색

Claude Code가 CLAUDE.md, settings.json, hooks, skills, commands, subagents, workflows, rules, auto memory를 읽는 위치입니다. 프로젝트의 .claude 디렉토리와 홈 디렉토리의 ~/.claude를 탐색합니다.

Claude Code는 프로젝트 디렉토리와 홈 디렉토리의 ~/.claude에서 지침, 설정, skills, subagents, 메모리를 읽습니다. 프로젝트 파일을 git에 커밋하여 팀과 공유합니다. ~/.claude의 파일은 모든 프로젝트에 적용되는 개인 설정입니다.

Windows에서 ~/.claude는 %USERPROFILE%\.claude로 확인됩니다. CLAUDE_CONFIG_DIR을 설정하면, 이 페이지의 모든 ~/.claude 경로가 대신 해당 디렉토리 아래에 있습니다.

대부분의 사용자는 CLAUDE.md와 settings.json만 편집합니다. 저장소에 이미 다른 코딩 에이전트용 AGENTS.md가 있는 경우, Claude Code는 CLAUDE.md 대신 해당 파일을 읽을 수 있습니다. 디렉터리의 나머지는 선택 사항입니다. 필요에 따라 스킬, 규칙, 서브에이전트를 추가합니다.

디렉토리 탐색

트리의 파일을 클릭하여 각 파일이 무엇을 하는지, 언제 로드되는지, 예제를 확인합니다.

표시되지 않는 항목

탐색기는 작성하고 편집하는 파일을 다룹니다. 관련된 몇 가지 파일은 다른 위치에 있습니다.

~/.claude는 또한 작업할 때 Claude Code가 작성하는 데이터를 보유합니다. 트랜스크립트, 프롬프트 기록, 파일 스냅샷, 캐시, 로그입니다. 아래의 애플리케이션 데이터를 참조하세요.

올바른 파일 선택

다양한 종류의 사용자 정의는 다양한 파일에 있습니다. 이 표를 사용하여 변경 사항이 어디에 속하는지 찾습니다.

파일 참조

이 표는 탐색기가 다루는 모든 파일을 나열합니다. 프로젝트 범위 파일은 .claude/ 아래의 리포지토리에 있습니다 (또는 CLAUDE.md, .mcp.json, .worktreeinclude의 경우 루트에 있음). 전역 범위 파일은 ~/.claude/에 있으며 모든 프로젝트에 적용됩니다.

[!NOTE]

이 파일에 입력한 내용을 재정의할 수 있는 여러 가지가 있습니다.

• 조직에서 배포한 관리형 설정은 설정 우선순위의 예외를 제외하고 모든 설정 파일과 --settings 값보다 우선합니다.
• --permission-mode 또는 --settings와 같은 CLI 플래그는 해당 세션에 대해 settings.json을 재정의합니다.
• 일부 환경 변수는 동등한 설정보다 우선하지만, 이는 다양합니다. 각각에 대해 환경 변수 참조를 확인하세요.

전체 순서는 설정 우선순위를 참조하세요.

파일 이름을 클릭하여 위의 탐색기에서 해당 노드를 엽니다.

파일별 프론트매터 필드

Skills, command 파일, subagents, output styles, 그리고 rules는 파일 상단의 YAML 프론트매터에서 구성을 읽으며, 각각은 자신의 필드 집합을 허용합니다. 이 표는 각 파일의 필드 이름을 나열하고 이들을 설명하는 참조로 연결합니다.

플러그인에서 제공되는 Agents는 subagent 필드의 부분 집합을 준수합니다.

설정 문제 해결

설정, hook, 파일이 적용되지 않으면, 설정 디버그에서 검사 명령과 증상 우선 조회 표를 참조하세요.

애플리케이션 데이터

작성한 설정 외에도 ~/.claude에는 Claude Code가 세션 중에 작성하는 데이터가 저장됩니다. 이 파일들은 평문입니다. 도구를 통과하는 모든 것은 디스크의 트랜스크립트에 기록됩니다: 파일 내용, 명령 출력, 붙여넣은 텍스트.

트랜스크립트에는 Claude Code가 사용자의 메시지와 함께 모델에 보내는 내용도 포함될 수 있습니다:

• 시스템 프롬프트
• 도구 정의
• 요청 매개변수
• CLAUDE.md와 같이 로드한 지침 파일

자동으로 정리됨

Claude Code는 cleanupPeriodDays보다 오래된 아래 경로의 파일들을 삭제합니다. 보존 기간을 안전하게 결정할 수 있는 한 말입니다. 기본값은 30일이고 최소값은 1입니다. 0으로 설정하면 유효성 검사 오류가 발생합니다. 동일한 나이 기준이 고아 worktrees의 자동 제거에도 적용됩니다.

sessions/의 세션 파일, 자동 메모리, Claude Desktop 및 Cowork 트랜스크립트는 각각 자체 보존 규칙을 따릅니다:

• sessions/: 실행 중인 각 세션에 대해 하나의 작은 파일을 보유합니다. 동시 세션 및 충돌을 감지하는 데 사용됩니다. 나이 기반 스윕의 일부가 아닙니다: Claude Code는 세션이 종료될 때 각 파일을 제거하고 다음 시작 시 충돌 남은 것을 정리합니다.

• 자동 메모리: 스윕은 프로젝트의 자동 메모리 디렉토리 projects/<project>/memory/의 메모리 파일을 삭제하지 않습니다. Claude Code는 전체 보존 기간 동안 비어 있었던 경우에만 해당 디렉토리를 제거합니다. v2.1.228 이전에는 스윕이 메모리 디렉토리 내의 폴더를 세션 데이터로 취급하고 그 아래의 오래된 파일을 삭제할 수 있었습니다.

• Claude Desktop 및 Cowork 트랜스크립트: Claude Code는 Claude Desktop 또는 Cowork에서 시작하거나 가장 최근에 계속한 세션의 트랜스크립트를 나이에 관계없이 유지합니다. 이 트랜스크립트에 나이 제한을 주려면 desktopSessionCleanupPeriodDays를 설정하세요. Claude Code v2.1.248 이상 필요; 이전 버전은 cleanupPeriodDays 후에 삭제합니다.

  다음 중 하나에 해당하면 Claude Code는 대신 cleanupPeriodDays 후에 이 트랜스크립트를 삭제합니다:

  • 관리형 설정이 cleanupPeriodDays를 설정한 경우
  • HIPAA 구성이 세션에 적용되는 경우

Claude Code는 다음 경우에 나이 기반 스윕을 건너뜁니다:

• Bare mode: --bare로 claude -p를 실행할 때, Claude Code는 해당 세션에서 스윕을 실행하지 않습니다.
• 일시 중지된 스윕: Claude Code가 보존 기간을 안전하게 결정할 수 없으면 보존 정리 스윕을 일시 중지합니다. retention_sweep 이벤트는 이를 일시 중지하는 각 구성을 나열합니다. 원인이 읽거나 구문 분석할 수 없는 설정 파일이거나 cleanupPeriodDays 또는 desktopSessionCleanupPeriodDays가 명시적으로 설정된 설정 오류인 경우, Claude Code는 설정 오류를 수정할 때까지 /status에 경고를 표시합니다. 관리 설정이 cleanupPeriodDays를 제공하면 Claude Code는 어느 경우든 관리 값에서 스윕을 실행합니다.

조직의 머신이 설정한 보존 기간으로 스윕을 실행하는지 확인하려면 보존 스윕 확인을 참조하세요.

세션 스크래치패드 디렉토리

스크래치패드는 Claude Code가 Claude에게 제공하는 세션별 디렉토리입니다. 임시 파일용입니다: 중간 결과, 도우미 스크립트, 프로젝트에 속하지 않는 초안. Claude가 무언가를 "스크래치패드에 저장했다"고 말하면 파일이 거기에 있습니다. Claude는 /tmp 대신 이를 사용하며 권한 프롬프트 없이 파일을 생성, 편집 및 읽을 수 있습니다.

스크래치패드는 ~/.claude 대신 Claude Code의 임시 디렉토리 아래에 있습니다. 플랫폼별로 현재 세션의 경로를 찾으세요:

• macOS: /private/tmp/claude-<uid>/<project>/<session-id>/scratchpad/
• Linux: /tmp/claude-<uid>/<project>/<session-id>/scratchpad/, 또는 시스템이 설정한 경우 $TMPDIR 아래의 동일한 형태
• Windows: %TEMP%\claude\<project>\<session-id>\scratchpad\

<project>는 문자와 숫자 이외의 모든 문자가 -로 바뀐 작업 디렉토리 경로입니다. 예를 들어 -Users-you-my-project. CLAUDE_CODE_TMPDIR을 설정하면 트리가 대신 해당 디렉토리 아래로 이동합니다. Hook은 현재 세션의 경로를 scratchpad_dir로 받습니다.

스크래치패드 파일은 세션의 트랜스크립트만큼 오래 지속됩니다: 보존 스윕은 트랜스크립트를 삭제할 때 디렉토리를 삭제하고, claude purge는 임시 디렉토리를 건드리지 않습니다. 디렉토리가 시스템 임시 위치 아래에 있으므로 운영 체제도 이를 정리할 수 있습니다. 예를 들어 재시작 시. Claude가 거기에 작성한 것을 유지하려면 Claude에게 프로젝트로 이동하도록 요청하세요.

세션은 다음 모두가 유지될 때만 스크래치패드를 갖습니다:

• API 키가 아닌 claude.ai 계정으로 로그인했습니다
• 세션은 Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry가 아닌 Anthropic API를 사용합니다
• enableArtifact가 false로 설정되지 않았습니다

삭제할 때까지 유지됨

달리 명시된 행을 제외하고, 보존 정리 스윕은 아래 경로를 제거하지 않으며 Claude Code는 사용자가 삭제할 때까지 이를 유지합니다.

유지해야 할 상태 파일

사용하는 기능에 따라 ~/.claude/에는 애플리케이션 데이터 아래 표에 나열되지 않은 파일도 저장됩니다. 그중 캐시 및 잠금 파일은 안전하게 삭제할 수 있습니다. 다음 상태 파일은 유지하세요:

• .credentials.json: 사용자의 로그인 자격증명
• agent-memory/: subagent 메모리
• jobs/ 및 daemon/: background session 상태

평문 저장소

트랜스크립트 및 히스토리는 저장 시 암호화되지 않습니다. OS 파일 권한만이 유일한 보호입니다. 도구가 .env 파일을 읽거나 명령이 자격증명을 인쇄하면 해당 값이 projects/<project>/<session>.jsonl에 기록됩니다. 노출을 줄이려면:

• cleanupPeriodDays를 낮춰 Claude Code가 트랜스크립트를 유지하는 기간을 단축하세요
• desktopSessionCleanupPeriodDays를 설정하여 Claude Desktop 및 Cowork 트랜스크립트에도 나이 제한을 주세요
• CLAUDE_CODE_SKIP_PROMPT_HISTORY 환경 변수를 설정하여 모든 모드에서 트랜스크립트 및 프롬프트 히스토리 작성을 건너뛰세요. 비대화형 모드에서는 대신 -p와 함께 --no-session-persistence를 전달하거나 TypeScript Agent SDK에서 persistSession: false를 설정할 수 있습니다. Python SDK에는 동등한 옵션이 없습니다.
• 권한 규칙을 사용하여 자격증명 파일의 읽기를 거부하세요

로컬 데이터 지우기

claude purge를 실행하여 Claude Code가 한 프로젝트에 대해 보유한 상태를 삭제합니다. 다음을 삭제합니다:

• projects/ 아래의 트랜스크립트 및 자동 메모리
• 세션별 tasks/, debug/ 및 file-history/ 항목
• history.jsonl의 일치하는 프롬프트 라인
• ~/.claude.json의 프로젝트 항목

프로젝트의 세션에서 붙여넣거나 첨부한 이미지 및 각 세션의 스크래치패드는 ~/.claude 대신 Claude Code의 임시 디렉토리 아래에 저장되므로 purge는 이를 제거하지 않습니다. 보존 스윕은 cleanupPeriodDays보다 오래되면 이미지를 삭제합니다. purge된 세션의 스크래치패드는 삭제할 때까지 또는 운영 체제가 임시 디렉토리를 정리할 때까지 유지됩니다.

명령은 전체 삭제 계획을 인쇄하고 아무것도 제거하기 전에 확인을 요청합니다.

v2.1.288 이전에는 명령이 claude project purge였습니다.

아래 예제는 ~/work/my-repo를 자리 표시자로 사용합니다. 프로젝트의 경로로 바꾸세요. 경로와 일치하는 상태가 없으면 명령은 오류를 인쇄하고 상태 1로 종료합니다.

아무것도 삭제하지 않고 계획 미리 보기:

claude purge ~/work/my-repo --dry-run

계획은 각 일치하는 항목과 포함된 이유를 나열합니다:

Purge plan for /home/user/work/my-repo:

  dir:    /home/user/.claude/projects/-home-user-work-my-repo
           project transcripts (.jsonl) and memory/
  config: projects["/home/user/work/my-repo"]
           project entry in ~/.claude.json (trust, history, MCP servers)
  filter: /home/user/.claude/history.jsonl
           12 prompt(s) typed in this project

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

단일 확인 프롬프트로 삭제:

claude purge ~/work/my-repo

명령은 동일한 계획을 인쇄한 다음 Delete 3 item(s) for /home/user/work/my-repo? This cannot be undone. [y/N]를 묻고 y로 답변한 경우에만 삭제합니다.

대화형 목록에서 프로젝트를 선택하려면 경로를 생략하세요.

스크립트에서 사용하기 위해 확인 프롬프트를 건너뛰세요:

claude purge ~/work/my-repo --yes

기타 옵션:

• 경로 대신 --all을 전달하면 한 번에 모든 프로젝트의 상태를 purge합니다. 이 경우 history.jsonl을 필터링하는 대신 완전히 삭제합니다.
• -i를 전달하면 삭제 계획을 한 번에 한 항목씩 단계별로 진행합니다.

명령은 shell-snapshots/ 및 backups/를 그대로 두는데, 이는 프로젝트 범위가 아니기 때문이며 계획 출력에서 이에 대해 경고합니다. 누군가 해당 머신에서 /heapdump를 실행했다면 그것이 작성한 .heapsnapshot 파일도 삭제하세요. 힙 스냅샷에는 전체 대화와 프로세스가 보유했던 모든 자격 증명이 포함되며, 보존 스윕과 purge 모두 이를 건드리지 않습니다.

유지해야 할 상태 파일을 제외하면 위의 애플리케이션 데이터 경로를 직접 삭제할 수도 있습니다.

~/.claude.json, ~/.claude/settings.json 또는 ~/.claude/plugins/를 삭제하지 마세요. 이들은 계정 정보, 기본 설정 및 설치된 플러그인을 보유합니다.

관련 리소스

• Claude의 메모리 관리: CLAUDE.md, rules, auto memory 작성 및 구성
• 설정 구성: 권한, hooks, 환경 변수, 모델 기본값 설정
• Skills 생성: 재사용 가능한 프롬프트 및 워크플로우 구축
• Subagents 구성: 자신의 컨텍스트가 있는 특화된 에이전트 정의