클로드 코드가 안정적으로 느껴지는 이유: 로컬 스토리지 설계에 대한 개발자의 심층 분석
Claude Code는 최근 모든 곳에서 사용되고 있습니다. 개발자들은 기능을 더 빠르게 출시하고, 워크플로를 자동화하고, 실제 프로젝트에서 작동하는 에이전트를 프로토타이핑하는 데 사용하고 있습니다. 더욱 놀라운 점은 코딩을 하지 않는 사람들도 도구를 구축하고, 작업을 연결하고, 거의 설정 없이도 유용한 결과를 얻는 등 많은 사람들이 이 도구에 뛰어들었다는 것입니다. AI 코딩 도구가 이렇게 다양한 기술 수준에 걸쳐 빠르게 확산되는 경우는 드뭅니다.
하지만 정말 눈에 띄는 것은 안정성이라는 점입니다. Claude Code는 여러 세션에서 일어난 일을 기억하고, 진행 상황을 잃지 않고 충돌을 극복하며, 채팅 인터페이스가 아닌 로컬 개발 도구처럼 작동합니다. 이러한 안정성은 로컬 저장소를 처리하는 방식에서 비롯됩니다.
Claude Code는 코딩 세션을 임시 채팅으로 취급하는 대신 실제 파일을 읽고 쓰고, 프로젝트 상태를 디스크에 저장하고, 상담원의 모든 작업 단계를 기록합니다. 세션을 추측 없이 재개, 검사 또는 롤백할 수 있으며, 각 프로젝트가 깨끗하게 격리되어 있어 많은 상담원 도구에서 발생하는 교차 오염 문제를 피할 수 있습니다.
이 글에서는 이러한 안정성을 뒷받침하는 스토리지 아키텍처를 자세히 살펴보고, 이 아키텍처가 일상적인 개발에서 Claude Code를 실용적으로 만드는 데 큰 역할을 하는 이유에 대해 설명합니다.
모든 로컬 AI 코딩 어시스턴트가 직면한 과제
Claude Code가 스토리지에 접근하는 방식을 설명하기 전에 로컬 AI 코딩 도구가 직면하는 일반적인 문제를 살펴봅시다. 이러한 문제는 어시스턴트가 파일 시스템에서 직접 작업하고 시간이 지나도 상태를 유지할 때 자연스럽게 발생합니다.
1. 프로젝트 데이터가 여러 작업 공간에 섞여 있습니다.
대부분의 개발자는 하루 종일 여러 리포지토리를 전환합니다. 어시스턴트가 한 프로젝트에서 다른 프로젝트로 상태를 이월하면 그 동작을 이해하기 어렵고 잘못된 가정을 하기 쉬워집니다. 각 프로젝트에는 상태와 히스토리를 위한 깨끗하고 격리된 자체 공간이 필요합니다.
2. 크래시로 인해 데이터가 손실될 수 있습니다.
코딩 세션 중에 어시스턴트는 파일 편집, 도구 호출, 중간 단계 등 유용한 데이터를 꾸준히 생성합니다. 이 데이터를 즉시 저장하지 않으면 충돌이나 강제 재시작으로 인해 데이터가 지워질 수 있습니다. 안정적인 시스템은 중요한 상태가 생성되는 즉시 디스크에 기록하므로 예기치 않게 작업이 손실되지 않습니다.
3. 상담원이 실제로 무엇을 했는지 항상 명확하지 않습니다.
일반적인 세션에는 많은 작은 작업이 포함됩니다. 이러한 작업에 대한 명확하고 정돈된 기록이 없으면 어시스턴트가 특정 결과물에 어떻게 도달했는지 역추적하거나 문제가 발생한 단계를 찾기가 어렵습니다. 전체 기록이 있으면 디버깅과 검토가 훨씬 더 관리하기 쉬워집니다.
4. 실수를 되돌리려면 너무 많은 노력이 필요합니다.
가끔 어시스턴트가 제대로 작동하지 않는 변경을 할 때가 있습니다. 이러한 변경 사항을 롤백할 수 있는 기본 제공 방법이 없다면 결국 리포지토리 전체에서 수동으로 편집 내용을 찾아야 합니다. 시스템이 자동으로 변경된 내용을 추적하여 추가 작업 없이 깔끔하게 되돌릴 수 있어야 합니다.
5. 프로젝트마다 다른 설정이 필요합니다.
로컬 환경은 다양합니다. 어떤 프로젝트는 특정 권한, 도구 또는 디렉터리 규칙이 필요하고, 어떤 프로젝트는 사용자 지정 스크립트나 워크플로우가 필요합니다. 어시스턴트는 이러한 차이를 존중하고 프로젝트별 설정을 허용하면서도 핵심 동작은 일관되게 유지해야 합니다.
클로드 코드의 스토리지 설계 원칙
Claude Code의 스토리지 디자인은 네 가지 간단한 아이디어를 중심으로 구축되었습니다. 단순해 보일 수 있지만, AI 어시스턴트가 머신과 여러 프로젝트에서 직접 작업할 때 발생하는 실질적인 문제를 함께 해결합니다.
1. 각 프로젝트마다 고유한 저장 공간을 확보합니다.
클로드 코드는 모든 세션 데이터를 해당 세션이 속한 프로젝트 디렉토리에 연결합니다. 즉, 대화, 편집 및 로그는 해당 프로젝트에 보관되며 다른 프로젝트로 유출되지 않습니다. 저장소를 분리하면 어시스턴트의 동작을 더 쉽게 이해할 수 있고 특정 리포지토리의 데이터를 검사하거나 삭제하기 쉬워집니다.
2. 데이터가 바로 디스크에 저장됩니다.
Claude Code는 인터랙션 데이터를 메모리에 보관하는 대신 생성되는 즉시 디스크에 기록합니다. 각 이벤트(메시지, 도구 호출 또는 상태 업데이트)는 새 항목으로 추가됩니다. 프로그램이 충돌하거나 예기치 않게 종료되더라도 거의 모든 데이터가 그대로 유지됩니다. 이 접근 방식은 복잡성을 크게 추가하지 않고도 세션의 내구성을 유지합니다.
3. 모든 작업은 기록에서 명확한 위치를 차지합니다.
Claude Code는 각 메시지와 도구 작업을 그 이전의 작업과 연결하여 완전한 시퀀스를 형성합니다. 이렇게 정돈된 이력을 통해 세션이 어떻게 전개되었는지 검토하고 특정 결과를 이끌어낸 단계를 추적할 수 있습니다. 개발자는 이러한 종류의 추적을 통해 에이전트 동작을 훨씬 쉽게 디버깅하고 이해할 수 있습니다.
4. 코드 편집 내용을 쉽게 롤백할 수 있습니다.
어시스턴트가 파일을 업데이트하기 전에 Claude Code는 이전 상태의 스냅샷을 저장합니다. 변경 사항이 잘못된 것으로 판명되면 리포지토리를 뒤지거나 무엇이 변경되었는지 추측할 필요 없이 이전 버전으로 복원할 수 있습니다. 이 간단한 안전망 덕분에 AI 기반 편집은 훨씬 덜 위험합니다.
클로드 코드 로컬 스토리지 레이아웃
Claude Code는 모든 로컬 데이터를 한 곳, 즉 홈 디렉토리에 저장합니다. 따라서 시스템을 예측 가능하게 유지하고 필요할 때 검사, 디버그 또는 정리를 더 쉽게 할 수 있습니다. 스토리지 레이아웃은 작은 전역 설정 파일과 모든 프로젝트 수준 상태가 저장되는 더 큰 데이터 디렉터리라는 두 가지 주요 구성 요소를 중심으로 구축됩니다.
두 가지 핵심 구성 요소:
~/.claude.json프로젝트 매핑, MCP 서버 설정, 최근에 사용한 프롬프트 등 글로벌 구성과 바로가기를 저장합니다.~/.claude/기본 데이터 디렉토리: 대화, 프로젝트 세션, 권한, 플러그인, 스킬, 기록 및 관련 런타임 데이터를 저장하는 곳입니다.
이제 이 두 가지 핵심 구성 요소를 자세히 살펴보겠습니다.
(1) 전역 구성: ~/.claude.json
이 파일은 데이터 저장소가 아닌 인덱스 역할을 합니다. 어떤 프로젝트에서 작업했는지, 각 프로젝트에 어떤 도구가 첨부되어 있는지, 최근에 사용한 프롬프트가 무엇인지 기록합니다. 대화 데이터 자체는 여기에 저장되지 않습니다.
{
"projects": {
"/Users/xxx/my-project": {
"mcpServers": {
"jarvis-tasks": {
"type": "stdio",
"command": "python",
"args": ["/path/to/run_mcp.py"]
}
}
}
},
"recentPrompts": [
"Fix the bug in auth module",
"Add unit tests"
]
}
(2) 기본 데이터 디렉토리: ~/.claude/
~/.claude/ 디렉토리는 클로드 코드의 로컬 상태 대부분이 있는 곳입니다. 이 구조는 프로젝트 격리, 즉각적인 지속성, 실수로부터의 안전한 복구라는 몇 가지 핵심 설계 아이디어를 반영합니다.
~/.claude/
├── settings.json # Global settings (permissions, plugins, cleanup intervals)
├── settings.local.json # Local settings (machine-specific, not committed to Git)
├── history.jsonl # Command history
│
├── projects/ # 📁 Session data (organized by project, core directory)
│ └── -Users-xxx-project/ # Path-encoded project directory
│ ├── {session-id}.jsonl # Primary session data (JSONL format)
│ └── agent-{agentId}.jsonl # Sub-agent session data
│
├── session-env/ # Session environment variables
│ └── {session-id}/ # Isolated by session ID
│
├── skills/ # 📁 User-level skills (globally available)
│ └── mac-mail/
│ └── SKILL.md
│
├── plugins/ # 📁 Plugin management
│ ├── config.json # Global plugin configuration
│ ├── installed_plugins.json # List of installed plugins
│ ├── known_marketplaces.json # Marketplace source configuration
│ ├── cache/ # Plugin cache
│ └── marketplaces/
│ └── anthropic-agent-skills/
│ ├── .claude-plugin/
│ │ └── marketplace.json
│ └── skills/
│ ├── pdf/
│ ├── docx/
│ └── frontend-design/
│
├── todos/ # Task list storage
│ └── {session-id}-*.json # Session-linked task files
│
├── file-history/ # File edit history (stored by content hash)
│ └── {content-hash}/ # Hash-named backup directory
│
├── shell-snapshots/ # Shell state snapshots
├── plans/ # Plan Mode storage
├── local/ # Local tools / node_modules
│ └── claude # Claude CLI executable
│ └── node_modules/ # Local dependencies
│
├── statsig/ # Feature flag cache
├── telemetry/ # Telemetry data
└── debug/ # Debug logs
이 레이아웃은 의도적으로 단순합니다. Claude Code에서 생성하는 모든 것이 프로젝트와 세션별로 정리된 하나의 디렉터리 아래에 있습니다. 시스템 곳곳에 숨겨진 상태가 흩어져 있지 않으므로 필요할 때 쉽게 검사하거나 정리할 수 있습니다.
클로드 코드의 구성 관리 방식
Claude Code의 구성 시스템은 여러 머신에서 기본 동작을 일관되게 유지하되 개별 환경과 프로젝트에서 필요한 사항을 사용자 지정할 수 있도록 하는 간단한 아이디어를 중심으로 설계되었습니다. 이를 위해 Claude Code는 3계층 구성 모델을 사용합니다. 동일한 설정이 두 곳 이상에서 나타나는 경우 항상 더 구체적인 계층이 우선합니다.
세 가지 구성 수준
Claude Code는 우선순위가 가장 낮은 것부터 가장 높은 것 순으로 구성을 로드합니다:
┌─────────────────────────────────────────┐
│ Project-level configuration │ Highest priority
│ project/.claude/settings.json │ Project-specific, overrides other configs
├─────────────────────────────────────────┤
│ Local configuration │ Machine-specific, not version-controlled
│ ~/.claude/settings.local.json │ Overrides global configuration
├─────────────────────────────────────────┤
│ Global configuration │ Lowest priority
│ ~/.claude/settings.json │ Base default configuration
└─────────────────────────────────────────┘
글로벌 기본값으로 시작한 다음 머신별 조정을 적용하고 마지막으로 프로젝트별 규칙을 적용한다고 생각하면 됩니다.
이제 각 구성 수준을 자세히 살펴보겠습니다.
(1) 전역 구성: ~/.claude/settings.json
전역 구성은 모든 프로젝트에서 클로드 코드의 기본 동작을 정의합니다. 여기서 기본 권한을 설정하고, 플러그인을 활성화하고, 정리 동작을 구성할 수 있습니다.
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": ["Read(**)", "Bash(npm:*)"],
"deny": ["Bash(rm -rf:*)"],
"ask": ["Edit", "Write"]
},
"enabledPlugins": {
"document-skills@anthropic-agent-skills": true
},
"cleanupPeriodDays": 30
}
(2) 로컬 구성: ~/.claude/settings.local.json
로컬 구성은 단일 머신에만 적용됩니다. 공유하거나 버전 관리로 확인하지 않습니다. 따라서 API 키, 로컬 도구 또는 환경별 권한을 저장하기에 좋은 곳입니다.
{
"permissions": {
"allow": ["Bash(git:*)", "Bash(docker:*)"]
},
"env": {
"ANTHROPIC_API_KEY": "sk-ant-xxx"
}
}
(3) 프로젝트 수준 구성: project/.claude/settings.json
프로젝트 수준 구성은 단일 프로젝트에만 적용되며 우선순위가 가장 높습니다. 여기에서 해당 리포지토리에서 작업할 때 항상 적용되어야 하는 규칙을 정의할 수 있습니다.
{
"permissions": {
"allow": ["Bash(pytest:*)"]
}
}
구성 계층이 정의되었으므로 다음 질문은 Claude Code가 런타임에 실제로 구성 및 권한을 해결하는 방법입니다.
Claude Code는 글로벌 기본값으로 시작한 다음, 머신별 재정의, 마지막으로 프로젝트별 규칙을 적용하는 세 가지 계층으로 구성을 적용합니다. 동일한 설정이 여러 곳에 표시되는 경우 가장 구체적인 설정이 우선 적용됩니다.
권한은 고정된 평가 순서를 따릅니다:
거부 - 항상 차단
ask - 확인 필요
허용 - 자동으로 실행
기본값 - 일치하는 규칙이 없을 때만 적용
이렇게 하면 기본적으로 시스템을 안전하게 유지하면서 프로젝트와 개별 시스템에 필요한 유연성을 제공합니다.
세션 스토리지: 클로드 코드가 핵심 인터랙션 데이터를 유지하는 방법
클로드 코드에서 세션은 데이터의 핵심 단위입니다. 세션은 대화 자체, 도구 호출, 파일 변경 및 관련 컨텍스트를 포함하여 사용자와 AI 간의 전체 상호 작용을 캡처합니다. 세션이 저장되는 방식은 시스템의 안정성, 디버깅 가능성 및 전반적인 안전성에 직접적인 영향을 미칩니다.
각 프로젝트마다 세션 데이터를 별도로 보관
세션이 정의되면 다음 질문은 데이터를 체계적이고 격리된 상태로 유지하는 방식으로 세션을 저장하는 방법입니다.
클로드 코드는 프로젝트별로 세션 데이터를 분리합니다. 각 프로젝트의 세션은 프로젝트의 파일 경로에서 파생된 디렉토리에 저장됩니다.
저장 경로는 이 패턴을 따릅니다:
~/.claude/projects/ + path-encoded project directory
유효한 디렉토리 이름을 만들기 위해 /, 공백 및 ~ 과 같은 특수 문자는 - 로 대체됩니다.
예를 들어
/Users/bill/My Project → -Users-bill-My-Project
이 접근 방식을 사용하면 서로 다른 프로젝트의 세션 데이터가 섞이지 않고 프로젝트별로 관리하거나 제거할 수 있습니다.
세션이 JSONL 형식으로 저장되는 이유
클로드 코드는 표준 JSON 대신 JSONL(JSON 줄)을 사용하여 세션 데이터를 저장합니다.
기존 JSON 파일에서는 모든 메시지가 하나의 큰 구조 안에 함께 묶여 있으므로 메시지가 변경될 때마다 전체 파일을 읽고 다시 작성해야 합니다. 이와는 대조적으로 JSONL은 각 메시지를 파일에 개별 줄로 저장합니다. 한 줄은 외부 래퍼 없이 하나의 메시지와 동일합니다.
| Aspect | 표준 JSON | JSONL(JSON 줄) |
|---|---|---|
| 데이터 저장 방식 | 하나의 큰 구조 | 한 줄당 하나의 메시지 |
| 데이터가 저장되는 시기 | 보통 마지막에 | 즉시, 메시지당 |
| 충돌 영향 | 전체 파일이 깨질 수 있음 | 마지막 줄만 영향을 받음 |
| 새 데이터 쓰기 | 전체 파일 다시 쓰기 | 한 줄 추가 |
| 메모리 사용량 | 모든 항목 로드 | 한 줄씩 읽기 |
JSONL은 몇 가지 주요 방식으로 더 잘 작동합니다:
즉각적인 저장: 각 메시지는 세션이 완료될 때까지 기다리지 않고 생성되는 즉시 디스크에 기록됩니다.
충돌 방지: 프로그램이 충돌하는 경우 마지막 미완성 메시지만 손실될 수 있습니다. 그 전에 작성된 모든 내용은 그대로 유지됩니다.
빠른 추가: 기존 데이터를 읽거나 다시 쓰지 않고 파일 끝에 새 메시지가 추가됩니다.
메모리 사용량이 적습니다: 세션 파일은 한 번에 한 줄씩 읽을 수 있으므로 전체 파일을 메모리에 로드할 필요가 없습니다.
단순화된 JSONL 세션 파일은 다음과 같습니다:
{"type":"user","message":{"role":"user","content":"Hello"},"timestamp":"2026-01-05T10:00:00Z"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}]}}
{"type":"user","message":{"role":"user","content":"Help me fix this bug"}}
세션 메시지 유형
세션 파일은 클로드 코드와 상호작용하는 동안 일어나는 모든 일을 기록합니다. 이를 명확히 하기 위해 다양한 종류의 이벤트에 대해 서로 다른 메시지 유형을 사용합니다.
사용자 메시지는 시스템에 들어오는 새로운 입력을 나타냅니다. 여기에는 사용자가 입력한 내용뿐만 아니라 셸 명령의 출력과 같이 도구에서 반환한 결과도 포함됩니다. AI의 관점에서 보면 두 가지 모두 응답해야 하는 입력입니다.
어시스턴트 메시지는 클라우드가 이에 응답하여 수행하는 작업을 캡처합니다. 이러한 메시지에는 AI의 추론, 생성하는 텍스트, 사용하기로 결정한 모든 도구가 포함됩니다. 또한 토큰 수와 같은 사용 세부 정보도 기록하여 상호 작용에 대한 완전한 그림을 제공합니다.
파일 히스토리 스냅샷은 Claude가 파일을 수정하기 전에 생성되는 안전 체크포인트입니다. 원본 파일 상태를 먼저 저장함으로써 Claude Code는 문제가 발생했을 때 변경 사항을 되돌릴 수 있습니다.
요약은 세션에 대한 간결한 개요를 제공하며 최종 결과와 연결됩니다. 요약은 모든 단계를 다시 재생하지 않고도 세션의 내용을 쉽게 이해할 수 있게 해줍니다.
이러한 메시지 유형은 대화뿐만 아니라 세션 중에 발생하는 모든 작업 및 효과의 전체 순서를 함께 기록합니다.
이를 보다 구체적으로 이해하기 위해 사용자 메시지와 어시스턴트 메시지의 구체적인 예를 살펴보겠습니다.
(1) 사용자 메시지 예시:
{
"type": "user",
"uuid": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
"parentUuid": null,
"sessionId": "e5d52290-e2c1-41d6-8e97-371401502fdf",
"timestamp": "2026-01-05T10:00:00.000Z",
"message": {
"role": "user",
"content": "Analyze the architecture of this project"
},
"cwd": "/Users/xxx/project",
"gitBranch": "main",
"version": "2.0.76"
}
(2) 어시스턴트 메시지 예시:
{
"type": "assistant",
"uuid": "e684816e-f476-424d-92e3-1fe404f13212",
"parentUuid": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
"message": {
"role": "assistant",
"model": "claude-opus-4-5-20251101",
"content": [
{
"type": "thinking",
"thinking": "The user wants to understand the project architecture, so I need to check the directory structure first..."
},
{
"type": "text",
"text": "Let me take a look at the project structure first."
},
{
"type": "tool_use",
"id": "toolu_01ABC",
"name": "Bash",
"input": {"command": "ls -la"}
}
],
"usage": {
"input_tokens": 1500,
"output_tokens": 200,
"cache_read_input_tokens": 50000
}
}
}
세션 메시지가 연결되는 방식
클로드 코드는 세션 메시지를 독립된 항목으로 저장하지 않습니다. 대신 메시지를 서로 연결하여 명확한 이벤트 체인을 형성합니다. 각 메시지에는 고유 식별자(uuid)와 그 앞에 온 메시지에 대한 참조(parentUuid)가 포함됩니다. 이를 통해 어떤 일이 일어났는지뿐만 아니라 왜 그런 일이 일어났는지도 확인할 수 있습니다.
세션은 사용자 메시지로 시작하여 체인을 시작합니다. 클로드의 각 응답은 그 원인이 된 메시지를 가리킵니다. 도구 호출과 그 출력도 같은 방식으로 추가되며, 모든 단계는 그 전 단계에 연결됩니다. 세션이 종료되면 최종 메시지에 요약이 첨부됩니다.
모든 단계가 연결되어 있기 때문에 Claude Code는 전체 작업 순서를 재생하고 결과가 어떻게 생성되었는지 이해할 수 있어 디버깅과 분석이 훨씬 쉬워집니다.
파일 스냅샷으로 코드 변경 사항을 쉽게 되돌리기
AI가 생성한 편집 내용이 항상 정확한 것은 아니며, 때로는 완전히 잘못된 방향으로 변경되는 경우도 있습니다. 이러한 변경 사항을 안전하게 실험할 수 있도록 Claude Code에서는 변경 사항을 실행 취소할 수 있는 간단한 스냅샷 시스템을 사용하여 Diff를 파헤치거나 파일을 수동으로 정리할 필요 없이 편집 내용을 되돌릴 수 있습니다.
Claude Code는 파일을 수정하기 전에 원본 콘텐츠의 사본을 저장합니다. 편집이 실수로 판명되면 시스템은 즉시 이전 버전으로 복원할 수 있습니다.
파일 히스토리 스냅샷이란 무엇인가요?
파일 히스토리 스냅샷은 파일을 수정하기 전에 생성되는 체크포인트입니다. Claude가 수정하려는 모든 파일의 원본 콘텐츠를 기록합니다. 이러한 스냅샷은 실행 취소 및 롤백 작업의 데이터 소스 역할을 합니다.
사용자가 파일을 변경할 수 있는 메시지를 보내면 Claude Code는 해당 메시지에 대한 빈 스냅샷을 만듭니다. 편집하기 전에 시스템은 각 대상 파일의 원본 콘텐츠를 스냅샷에 백업한 다음 편집 내용을 디스크에 직접 적용합니다. 사용자가 실행 취소를 트리거하면 클로드 코드는 저장된 콘텐츠를 복원하고 수정된 파일을 덮어씁니다.
실제로 실행 취소가 가능한 편집의 수명 주기는 다음과 같습니다:
사용자가 메시지를 보냄클라우드코드가 빈
file-history-snapshot레코드를 새로 생성합니다.Claude가 파일 수정을 준비합니다시스템이편집할 파일을 식별하고 원본 콘텐츠를
trackedFileBackups에 백업합니다.Claude가 편집을 실행합니다편집및 쓰기 작업이 수행되고 수정된 콘텐츠가 디스크에 기록됩니다.
사용자가und를 트리거합니다사용자가 Esc + Esc를 눌러 변경 사항을 되돌리라는 신호를 보냅니다.
원본 콘텐츠가 복원됩니다클라우드코드가
trackedFileBackups에서 저장된 콘텐츠를 읽고 현재 파일을 덮어쓰면서 실행 취소가 완료됩니다.
실행 취소가 작동하는 이유 스냅샷은 이전 버전을 저장합니다
Claude Code에서 실행 취소가 작동하는 이유는 시스템이 편집하기 전에 원본 파일 콘텐츠를 저장하기 때문입니다.
사후에 변경 사항을 되돌리려고 하는 대신, Claude Code는 수정하기 전에 존재했던 파일을 복사하여 trackedFileBackups 에 저장하는 더 간단한 접근 방식을 취합니다. 사용자가 실행 취소를 트리거하면 시스템은 이 저장된 버전을 복원하고 편집한 파일을 덮어씁니다.
아래 다이어그램은 이 흐름을 단계별로 보여줍니다:
┌─────────────────────────┐
│ before edit, app.py │
│ print("old") │───────→ Backed up into snapshot trackedFileBackups
└─────────────────────────┘
↓
┌──────────────────────────┐
│ After Claude edits │
│ print(“new”) │───────→ Written to disk (overwrites the original file)
└──────────────────────────┘
↓
┌──────────────────────────┐
│ User triggers undo │
│ Press Esc + Esc │───────→ Restore “old” content to disk from snapshot
└──────────────────────────┘
파일-히스토리 스냅샷의 내부 모습
스냅샷 자체는 구조화된 레코드로 저장됩니다. 사용자 메시지, 스냅샷의 시간, 그리고 가장 중요한 것은 파일의 원본 콘텐츠에 대한 맵에 대한 메타데이터를 캡처합니다.
아래 예는 Claude가 파일을 편집하기 전에 만든 단일 file-history-snapshot 레코드를 보여줍니다. trackedFileBackups 의 각 항목은 파일의 편집 전 콘텐츠를 저장하며, 나중에 실행 취소 시 파일을 복원하는 데 사용됩니다.
{
"type": "file-history-snapshot",
"messageId": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
"snapshot": {
"messageId": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
"trackedFileBackups": {
"/path/to/file1.py": "Original file content\ndef hello():\n print('old')",
"/path/to/file2.js": "// Original content..."
},
"timestamp": "2026-01-05T10:00:00.000Z"
},
"isSnapshotUpdate": false
}
스냅샷이 저장되는 위치 및 보관 기간
스냅샷 메타데이터가 저장되는 위치: 스냅샷 레코드는 특정 세션에 바인딩되어
~/.claude/projects/-path-to-project/{session-id}.jsonl아래에 JSONL 파일로 저장됩니다.원본 파일 콘텐츠가 백업되는 위치: 각 파일의 사전 편집 콘텐츠는 콘텐츠 해시별로
~/.claude/file-history/{content-hash}/에 별도로 저장됩니다.기본적으로 스냅샷이 보관되는 기간: 스냅샷 데이터는 글로벌
cleanupPeriodDays설정에 따라 30일 동안 보존됩니다.보존 기간을 변경하는 방법 보존 일수는
~/.claude/settings.json의cleanupPeriodDays필드에서 조정할 수 있습니다.
관련 명령
| 명령/작업 | 설명 |
|---|---|
| Esc + Esc | 가장 최근의 파일 편집을 실행 취소합니다(가장 일반적으로 사용됨). |
| /되감기 | 이전에 지정한 체크포인트(스냅샷)로 되돌립니다. |
| /diff | 현재 파일과 스냅샷 백업 간의 차이점 보기 |
기타 중요 디렉토리
(1) plugins/ - 플러그인 관리
plugins/ 디렉터리에는 Claude Code에 추가 기능을 제공하는 애드온이 저장됩니다.
이 디렉터리에는 설치된 플러그인, 플러그인의 출처, 해당 플러그인이 제공하는 추가 기능이 저장됩니다. 또한 다운로드한 플러그인의 로컬 복사본을 유지하므로 다시 가져올 필요가 없습니다.
~/.claude/plugins/
├── config.json
│ Global plugin configuration (e.g., enable/disable rules)
├── installed_plugins.json
│ List of installed plugins (including version and status)
├── known_marketplaces.json
│ Plugin marketplace source configuration (e.g., Anthropic official marketplace)
├── cache/
│ Plugin download cache (avoids repeated downloads)
└── marketplaces/
Marketplace source storage
└── anthropic-agent-skills/
Official plugin marketplace
├── .claude-plugin/
│ └── marketplace.json
│ Marketplace metadata
└── skills/
Skills provided by the marketplace
├── pdf/
│ PDF-related skills
├── docx/
│ Word document processing skills
└── frontend-design/
Frontend design skills
(2) 스킬/ - 스킬이 저장되고 적용되는 위치
Claude Code에서 스킬은 PDF 작업, 문서 편집, 코딩 워크플로 따라하기 등 특정 작업을 수행하는 데 도움이 되는 재사용 가능한 작은 기능입니다.
모든 스킬을 모든 곳에서 사용할 수 있는 것은 아닙니다. 일부는 전 세계에 적용되는 반면, 일부는 단일 프로젝트로 제한되거나 플러그인으로 제공됩니다. Claude Code는 각 스킬을 사용할 수 있는 위치를 제어하기 위해 스킬을 여러 위치에 저장합니다.
아래 계층 구조는 전 세계적으로 사용 가능한 스킬부터 프로젝트별 및 플러그인 제공 스킬까지 범위별로 스킬이 어떻게 계층화되어 있는지 보여줍니다.
| 레벨 | 저장 위치 | 설명 |
|---|---|---|
| 사용자 | ~/.claude/skills/ | 전 세계에서 사용 가능하며 모든 프로젝트에서 액세스 가능 |
| 프로젝트 | project/.claude/skills/ | 현재 프로젝트에서만 사용 가능, 프로젝트별 사용자 지정 |
| 플러그인 | ~/.claude/플러그인/마켓플레이스/*/skills/ | 플러그인과 함께 설치, 플러그인 활성화 상태에 따라 다름 |
(3) todos/ - 작업 목록 저장소
todos/ 디렉터리에는 완료할 단계, 진행 중인 항목, 완료된 작업 등 대화 중 작업을 추적하기 위해 Claude가 생성하는 작업 목록이 저장됩니다.
작업 목록은~/.claude/todos/{session-id}-*.json 아래에 JSON 파일로 저장되며, 각 파일 이름에는 작업 목록을 특정 대화에 연결하는 세션 ID가 포함되어 있습니다.
이러한 파일의 내용은 TodoWrite 도구에서 가져오며 작업 설명, 현재 상태, 우선순위 및 관련 메타데이터와 같은 기본적인 작업 정보를 포함합니다.
(4) local/ - 로컬 런타임 및 도구
local/ 디렉터리에는 클로드 코드가 컴퓨터에서 실행하는 데 필요한 핵심 파일이 있습니다.
여기에는 claude 명령줄 실행 파일과 런타임 종속성이 포함된 node_modules/ 디렉터리가 포함됩니다. 이러한 구성 요소를 로컬에 유지함으로써 Claude Code는 외부 서비스나 시스템 전체 설치에 의존하지 않고 독립적으로 실행할 수 있습니다.
(5) 추가 지원 디렉터리
shell-snapshots/: 셸 세션 상태 스냅샷(현재 디렉토리 및 환경 변수 등)을 저장하여 셸 작업 롤백을 가능하게 합니다.
plans/: 계획 모드에서 생성된 실행 계획(예: 다단계 프로그래밍 작업의 단계별 분석)을 저장합니다.
statsig/: 반복되는 요청을 줄이기 위해 기능 플래그 구성(예: 새 기능 활성화 여부)을 캐시합니다.
telemetry/: 제품 최적화를 위해 익명의 텔레메트리 데이터(예: 기능 사용 빈도)를 저장합니다.
debug/: 문제 해결을 돕기 위해 디버그 로그(오류 스택 및 실행 추적 포함)를 저장합니다.
결론
Claude Code가 모든 것을 로컬에 저장하고 관리하는 방법을 자세히 살펴본 결과, 이 도구는 기초가 탄탄하여 안정적으로 느껴집니다. 화려하지 않고 사려 깊은 엔지니어링이 돋보입니다. 각 프로젝트에는 고유한 공간이 있고, 모든 작업은 기록되며, 파일 편집 내용은 변경되기 전에 백업됩니다. 조용히 제 몫을 다하고 작업에만 집중할 수 있는 디자인이죠.
제가 가장 좋아하는 점은 신비로운 요소가 없다는 점입니다. Claude Code는 기본이 제대로 되어 있기 때문에 잘 작동합니다. 실제 파일을 다루는 에이전트를 구축해 본 적이 있다면 상태가 뒤섞이고, 충돌로 인해 진행 상황이 지워지고, 실행 취소가 추측으로 바뀌는 등 일이 얼마나 쉽게 무너지는지 잘 알 것입니다. Claude Code는 간단하고 일관되며 깨지기 어려운 스토리지 모델을 통해 이러한 모든 문제를 방지합니다.
특히 보안 환경에서 로컬 또는 온프레미스 AI 에이전트를 구축하는 팀의 경우, 이 접근 방식은 강력한 스토리지와 지속성이 일상적인 개발에서 AI 도구를 얼마나 안정적이고 실용적으로 만드는지 보여줍니다.
로컬 또는 온프레미스 AI 에이전트를 설계 중이고 스토리지 아키텍처, 세션 설계 또는 안전한 롤백에 대해 더 자세히 논의하고 싶다면 언제든지 Slack 채널에 참여하세요. 또한 Milvus 오피스 아워를 통해 20분간 일대일 상담을 예약하여 개인화된 안내를 받을 수도 있습니다.
Try Managed Milvus for Free
Zilliz Cloud is hassle-free, powered by Milvus and 10x faster.
Get StartedLike the article? Spread the word
