Claude .claude 디렉터리 탐색
기준일: 2026-07-26 · CLI 기준 2.1.220
개요
Claude Code는 프로젝트 루트와 홈 디렉터리의 파일시스템 레이아웃에서 지침·설정·확장·세션 데이터를 읽습니다. 이 페이지는 어디에 무엇을 두는지 고르는 기준과 파일 레퍼런스, 로컬 데이터 정리 방법을 제공합니다.
핵심 개념
프로젝트 쪽 (공유·커밋 가능 항목 중심)
| 경로 | 범위 | 역할 |
|---|---|---|
CLAUDE.md 또는 .claude/CLAUDE.md |
project | 매 세션 프로젝트 지침 |
.claude/rules/*.md |
project (+ 상위) | 경로·주제별 규칙 |
.claude/settings.json |
project | 팀 공유 설정 |
.claude/settings.local.json |
local | 개인 오버라이드 (gitignore) |
.mcp.json |
project root | 팀 공유 MCP |
.worktreeinclude |
project | worktree에 복사할 gitignore 파일 |
.claude/skills/<name>/SKILL.md |
project/global | 재사용 프롬프트·워크플로 |
.claude/commands/*.md |
project/global | 레거시 단일 파일 명령 (skills 권장) |
.claude/output-styles/*.md |
project/global | 시스템 프롬프트 섹션 |
.claude/agents/*.md |
project/global | 서브에이전트 정의 |
.claude/workflows/*.js |
project/global | 동적 워크플로 스크립트 |
.claude/agent-memory/<name>/ |
project/global | 서브에이전트 영속 메모리 |
글로벌 (~/.claude 및 ~/.claude.json)
| 경로 | 역할 |
|---|---|
~/.claude/CLAUDE.md, rules/, skills/, settings |
사용자 전역 |
~/.claude.json |
앱 상태, OAuth, UI, 개인 MCP |
projects/<project>/memory/ |
auto memory |
keybindings.json, themes/*.json |
키바인딩·테마 |
Commands와 skills는 동일 메커니즘으로 수렴 중이며, 신규는 skills/를 사용합니다.
상세
파일 고르기
| 목적 | 선택 |
|---|---|
| 매 세션 팀 컨벤션 | CLAUDE.md |
| 특정 경로/작업만 | rules/ 또는 skill |
| 팀 MCP | .mcp.json + ${ENV} 시크릿 |
| 개인 MCP | claude mcp add --scope user → ~/.claude.json |
| 재사용 워크플로 | skills/ |
| 권한·훅·모델 기본 | settings.json 계층 |
CLAUDE.md는 200줄 전후를 목표로 하고, 작업 한정 지식은 skill/rule로 분리하세요. /memory로 세션 중 편집할 수 있습니다.
애플리케이션 데이터 (~/.claude/)
자동 정리 대상 예:
projects/<project>/<session>.jsonl대화 transcript- subagents/, tool-results/, file-history/, plans/, debug/, caches, tasks/, shell-snapshots/ 등
삭제 전까지 유지:
history.jsonl(프롬프트 히스토리)stats-cache.json(/usage)remote-settings.json,cache/changelog.md,policy-limits.json
일부 데이터는 평문 저장됩니다. 공유 머신이면 디스크 암호화·홈 권한·로그아웃 정책을 검토하세요. 로컬 데이터 삭제는 공식 Clear local data 절차를 따릅니다(세션·히스토리·캐시 선택 삭제).
문제 해결
설정이 안 먹으면 우선순위(managed > project > user > local), 파일 경로 오타, JSON 구문, WSL 경로, CLAUDE_CONFIG_DIR 재배치를 확인합니다. /status의 Setting sources를 봅니다.
체크리스트
- 팀 공유 vs 개인 파일 경계를 정했다
- 시크릿을 git에 커밋하지 않았다
- skills 신규, commands 레거시 정책을 공유했다
- auto memory·transcript 보존 정책을 안다
- 필요 시 로컬 데이터 정리 방법을 문서화했다