Claude Code를 설치하고 나면 홈 디렉토리에 .claude 폴더가 하나 생긴다. 처음엔 별 생각 없이 지나치지만, 이 폴더 하나에 Claude Code의 설정, 세션 기록, 확장 기능, 메모리까지 전부 들어 있다. 프로젝트 폴더에도 .claude가 생길 수 있고, 별도의 설정 파일들이 디렉토리 밖에 존재하기도 한다.
이 글에서는 Claude Code가 사용하는 모든 파일과 디렉토리를 빠짐없이 정리한다.
구조의 핵심: 세 가지 레벨
Claude Code의 설정 체계는 본질적으로 단순하다.
**첫째, 스코프(어디에 있느냐)**에 따라 글로벌과 프로젝트로 나뉜다. ~/.claude/에 넣으면 모든 프로젝트에 적용되고, 프로젝트 루트의 .claude/에 넣으면 해당 프로젝트에만 적용된다. 엔터프라이즈 환경에서는 시스템 경로에 관리형 설정을 배포할 수도 있다.
**둘째, 내용(뭘 넣느냐)**은 동일하다. CLAUDE.md는 지침, settings.json은 설정, commands/는 커맨드, agents/는 에이전트. 글로벌이든 프로젝트든 같은 하위 구조가 반복된다.
셋째, OS별 차이는 인증 저장 위치와 엔터프라이즈 관리 경로 정도다. macOS는 Keychain을 쓰고, Linux/Windows는 .credentials.json 파일을 쓰는 식이다.
이 세 가지를 이해하면 아래의 전체 구조가 자연스럽게 읽힌다.
1. 글로벌 디렉토리: ~/.claude/
Claude Code의 핵심 데이터 저장소다. 사용자 설정, 전체 세션 이력, 파일 체크포인트, 스킬, 플러그인 등 모든 것이 이 안에 있다.
~/.claude/
│
├── CLAUDE.md # 글로벌 지침 (모든 프로젝트에 적용)
├── settings.json # 글로벌 사용자 설정 (권한, 모델, 훅 등)
├── settings.local.json # 로컬 사용자 설정 (동기화 대상 아님)
├── .credentials.json # API 인증 정보 (Linux/Windows 전용)
├── history.jsonl # 모든 세션의 프롬프트 이력 (글로벌 인덱스)
├── stats-cache.json # 사용량 통계 집계 (일별 활동, 토큰 사용량)
│
├── projects/ # 프로젝트별 세션 데이터
│ └── {인코딩된-프로젝트-경로}/
│ ├── {sessionId}.jsonl # 전체 대화 기록
│ ├── agent-{shortId}.jsonl # 서브에이전트 대화 기록
│ ├── sessions-index.json # 세션 메타데이터 인덱스
│ ├── CLAUDE.md # 프로젝트별 자동 메모리
│ └── memory/ # 자동 메모리 디렉토리
│ ├── MEMORY.md # 주요 메모리 (첫 200줄 자동 로드)
│ ├── debugging.md # 토픽별 메모리 (온디맨드 로드)
│ └── patterns.md # 토픽별 메모리 (온디맨드 로드)
│
├── file-history/ # 파일 체크포인트 (되돌리기/롤백용)
│ └── {sessionId}/
│ └── {fileHash}@v{version} # 파일 스냅샷
│
├── todos/ # 세션별 태스크 목록
│ └── {sessionId}-agent-{agentId}.json
│
├── plans/ # Plan 모드에서 생성된 마크다운 문서
├── session-env/ # 세션별 환경 변수 저장
├── shell-snapshots/ # 셸 환경 스냅샷
├── debug/ # 세션별 디버그 로그
├── statsig/ # 분석 캐시
│
├── commands/ # 글로벌 커스텀 슬래시 커맨드
│ └── {command-name}.md
├── skills/ # 글로벌 스킬
│ └── {skill-name}/
│ ├── SKILL.md
│ └── scripts/
├── agents/ # 글로벌 서브에이전트
│ └── {agent-name}.md
└── plugins/ # 플러그인 마켓플레이스 및 설치 데이터
2. 디렉토리 밖의 독립 파일들
.claude/ 디렉토리 안이 아닌 밖에 존재하는 파일들이 있다. 놓치기 쉬우니 주의가 필요하다.
~/.claude.json # 홈 디렉토리 루트에 위치
~/.mcp.json # 홈 디렉토리 루트에 위치 (글로벌 MCP)
~/.claude.json — 테마, 알림 설정, 에디터 모드 등 사용자 환경설정과 OAuth 세션 정보, MCP 서버 설정(user/local 스코프), 프로젝트별 상태(허용 도구, 신뢰 설정), 각종 캐시를 담고 있다. settings.json이 사용자가 직접 관리하는 정책/권한 파일이라면, .claude.json은 시스템이 관리하는 인프라/상태 파일이다.
~/.mcp.json — 글로벌 MCP(Model Context Protocol) 서버 설정 파일이다. 여기에 등록한 MCP 서버는 모든 프로젝트의 모든 세션에서 사용할 수 있다.
3. 프로젝트 디렉토리: 프로젝트/.claude/
팀과 공유하거나 해당 프로젝트에만 적용할 설정을 담는다. 글로벌 디렉토리와 동일한 하위 구조를 가진다.
프로젝트/
│
├── CLAUDE.md # 프로젝트 루트 지침 (팀 공유)
├── CLAUDE.local.md # 개인 프로젝트 지침 (gitignore 대상)
├── .mcp.json # 프로젝트 스코프 MCP 서버 설정
│
├── src/ # 소스 코드 디렉토리 (예시)
│ └── auth/
│ └── CLAUDE.md # 모듈 레벨 지침 (가장 높은 우선순위)
│
└── .claude/
├── CLAUDE.md # 프로젝트 지침 (./CLAUDE.md의 대안 위치)
├── settings.json # 프로젝트 공유 설정 (Git 커밋 대상)
├── settings.local.json # 개인 로컬 설정 (Git 무시, 자동 gitignore)
│
├── agents/ # 프로젝트 전용 서브에이전트
│ ├── code-reviewer.md
│ ├── security-auditor.md
│ └── debugger.md
│
├── commands/ # 프로젝트 전용 슬래시 커맨드
│ ├── optimize.md
│ ├── deploy.md
│ └── frontend/
│ └── build.md # 하위 폴더로 스코핑 가능
│
├── skills/ # 프로젝트 전용 스킬
│ ├── testing-patterns/
│ │ ├── SKILL.md # 스킬 정의 (필수)
│ │ └── scripts/ # 실행 스크립트 (선택)
│ ├── pdf-parser/
│ │ └── SKILL.md
│ └── skill-rules.json # 스킬 자동 활성화 규칙
│
├── hooks/ # 훅 스크립트
│ ├── bash/
│ │ ├── PreToolUse/ # 도구 실행 전 (차단 가능)
│ │ ├── PostToolUse/ # 도구 실행 후
│ │ ├── SessionStart/ # 세션 시작 시
│ │ └── SessionEnd/ # 세션 종료 시
│ └── powershell/
│ ├── PreToolUse/
│ └── PostToolUse/
│
└── rules/ # 모듈화된 규칙 파일
├── security.md # 보안 규칙
├── style.md # 스타일 가이드
└── frontend/
└── react.md # 파일 경로 스코핑 가능
4. 엔터프라이즈 관리형 설정
조직 차원에서 정책을 강제 적용할 때 사용하는 시스템 레벨 설정이다. 사용자/프로젝트 설정보다 항상 우선한다.
# macOS
/Library/Application Support/ClaudeCode/managed-settings.json
/Library/Application Support/ClaudeCode/managed-mcp.json
# Linux / WSL
/etc/claude-code/managed-settings.json
/etc/claude-code/managed-mcp.json
# Windows
C:\Program Files\ClaudeCode\managed-settings.json
C:\Program Files\ClaudeCode\managed-mcp.json
5. OS별 인증 저장 위치
| OS | 저장 방식 |
|---|---|
| macOS | 시스템 Keychain (“Claude Code” 또는 “Anthropic” 항목) |
| Linux | ~/.claude/.credentials.json |
| Windows | ~/.claude/.credentials.json |
6. 주요 파일 상세 설명
설정 파일
CLAUDE.md — Claude Code가 세션 시작 시 자동으로 읽는 지침 파일이다. 프로젝트 구조, 코딩 컨벤션, 빌드/테스트 명령어, 워크플로우 등을 자연어로 작성한다. /init 명령으로 자동 생성할 수 있고, 수동으로 작성해도 된다. 길이와 무관하게 전체가 로드된다.
CLAUDE.local.md — 프로젝트 루트에 위치하는 개인용 지침 파일이다. .gitignore 대상이라 팀에 공유되지 않는다. 개인 환경에 맞는 설정(로컬 DB 포트, 디버그 설정 등)을 넣기 좋다.
settings.json — 권한(allow/deny/ask), 환경 변수, 훅, 모델 선택, 샌드박스 설정 등 Claude Code의 동작을 제어하는 핵심 설정 파일이다. 글로벌/프로젝트/엔터프라이즈 세 레벨에서 동일한 포맷으로 사용된다.
settings.local.json — settings.json과 딥 머지되며, 충돌 시 로컬 값이 우선한다. Git에 커밋하지 않는 개인 설정용이다. 생성 시 자동으로 .gitignore에 추가된다.
~/.claude.json — .claude/ 디렉토리 밖에 위치하는 시스템 관리 파일이다. 테마, 알림, OAuth 세션, MCP 서버 설정, 프로젝트별 허용 도구, 캐시 등을 저장한다. Claude Code가 자동으로 백업을 관리하며 최근 5개 백업을 유지한다.
.mcp.json — MCP 서버 설정 파일이다. 프로젝트 루트에 두면 프로젝트 스코프, 홈 디렉토리에 두면 글로벌 스코프로 동작한다. 팀 공유를 위해 Git에 커밋할 수 있다.
런타임 데이터
history.jsonl — 모든 프로젝트, 모든 세션의 프롬프트를 시간순으로 기록하는 글로벌 인덱스다. 각 줄은 프롬프트 텍스트, 타임스탬프, 프로젝트 경로, 세션 ID를 포함하는 JSON 객체다. 세션을 찾을 때 유용하다.
stats-cache.json — 일별 메시지 수, 세션 수, 도구 호출 수, 모델별 토큰 사용량, 총 세션 수, 최장 세션 정보, 시간대별 활동 등 집계된 사용 지표를 저장한다.
projects/ — 프로젝트별 세션 데이터가 저장되는 곳이다. 프로젝트 경로의 /가 -로 치환되어 디렉토리명이 된다. 예를 들어 /Users/sean/myproject는 -Users-sean-myproject가 된다. 각 세션은 JSONL 형식으로 저장되어 한 줄이 하나의 메시지에 대응하며, 크래시 시에도 데이터가 보존된다.
projects/.../memory/ — Claude Code의 자동 메모리 시스템이다. MEMORY.md의 첫 200줄이 매 세션 시작 시 자동 로드되고, 토픽별 파일(debugging.md, patterns.md 등)은 필요할 때 온디맨드로 읽힌다. 일반 마크다운이라 직접 편집하거나 삭제할 수 있다.
file-history/ — Claude Code가 파일을 수정할 때마다 변경 전 상태를 스냅샷으로 저장한다. /rewind 명령으로 이전 상태로 되돌릴 때 이 데이터를 사용한다.
todos/ — 세션 중 생성된 태스크 목록을 세션별, 에이전트별로 JSON 파일로 관리한다.
plans/ — Plan 모드에서 작성된 마크다운 문서가 저장된다.
session-env/ — 각 세션의 환경 변수를 격리하여 저장한다.
shell-snapshots/ — 셸 환경의 스냅샷을 보관한다.
debug/ — 세션별 디버그 로그가 기록된다.
확장 디렉토리
commands/ — 커스텀 슬래시 커맨드를 마크다운 파일로 정의한다. 하위 폴더로 스코핑할 수 있어 같은 이름의 커맨드를 프론트엔드/백엔드 등으로 나눠 사용할 수 있다. /help로 등록된 커맨드 목록을 확인할 수 있다.
agents/ — YAML 프론트매터가 포함된 마크다운 파일로 서브에이전트를 정의한다. 에이전트 파일의 내용은 사용자 프롬프트가 아닌 시스템 프롬프트로 동작한다. 코드 리뷰어, 보안 감사, 디버거 등 전문화된 에이전트를 만들어 Claude Code가 자동으로 위임하게 할 수 있다.
skills/ — 각 스킬 폴더에는 SKILL.md(필수)와 실행 스크립트(선택)가 포함된다. 스킬은 특정 키워드나 파일 경로에 따라 자동 활성화되거나 명시적으로 호출할 수 있다. skill-rules.json으로 활성화 조건을 세밀하게 설정할 수 있다.
hooks/ — PreToolUse(도구 실행 전, 차단 가능), PostToolUse(도구 실행 후), SessionStart(세션 시작), SessionEnd(세션 종료) 등의 시점에 자동 실행되는 스크립트를 정의한다. 훅 스크립트는 반드시 실행 가능(chmod +x) 상태여야 한다. settings.json의 hooks 키에서도 설정할 수 있다.
rules/ — CLAUDE.md를 모듈화하여 주제별로 분리 관리하는 디렉토리다. 하위 폴더를 포함한 모든 .md 파일이 재귀적으로 탐색된다. 파일 경로 글로브 패턴으로 스코핑할 수 있어, 특정 파일 작업 시에만 해당 규칙이 컨텍스트에 로드된다.
plugins/ — 플러그인 마켓플레이스에서 설치한 플러그인 데이터(스킬, 에이전트, 훅, MCP 서버의 번들)를 저장한다.
7. 설정 우선순위
Claude Code는 여러 레벨의 설정을 머지하되, 더 구체적인 것이 항상 이긴다.
엔터프라이즈 managed-settings.json ← 최우선 (관리자 강제)
↓
settings.local.json ← 개인 로컬 설정
↓
settings.json ← 공유 설정
↓
글로벌 ~/.claude/settings.json ← 최하위
CLAUDE.md 파일의 우선순위도 마찬가지다:
./src/auth/CLAUDE.md ← 모듈 레벨 (최우선)
↓
./CLAUDE.md 또는 ./.claude/CLAUDE.md ← 프로젝트 레벨
↓
~/.claude/CLAUDE.md ← 글로벌 (최하위)
8. 실제 확인 명령어
자신의 환경에서 전체 구조를 직접 확인하고 싶다면:
# 글로벌 디렉토리 구조 확인
find ~/.claude -maxdepth 2 -type d | sort
# 글로벌 설정 파일 확인
ls -la ~/.claude.json ~/.mcp.json ~/.claude/settings.json 2>/dev/null
# 프로젝트 디렉토리 구조 확인
find .claude -type f | sort
# 프로젝트 설정 파일 확인
ls -la CLAUDE.md CLAUDE.local.md .mcp.json .claude/settings.json 2>/dev/null
# 세션 이력 확인
ls ~/.claude/projects/
마무리
.claude 디렉토리는 결국 **”어디에(스코프) 무엇을(내용) 넣느냐”**의 조합이다. 글로벌이든 프로젝트든 같은 하위 구조가 반복되고, 더 구체적인 설정이 항상 우선한다. OS별 차이는 인증 저장 방식과 엔터프라이즈 관리 경로 정도다.
이 구조를 이해하면 Claude Code를 팀 단위로 표준화하거나, 프로젝트별로 최적화하거나, 개인 워크플로우를 자동화하는 것이 훨씬 수월해진다.