상태 관리

상태 관리 개요

Claude Code는 모든 대화를 로컬 디스크에 영구 저장 합니다. 세션을 닫아도 대화 내용이 사라지지 않으며, 나중에 정확히 이어서 작업할 수 있습니다.

~/.claude/
├── sessions/
│   ├── <session-id-1>.json    # 대화 트랜스크립트
│   ├── <session-id-2>.json
│   └── ...
├── settings.json              # 전역 설정
└── agent-memory/              # 에이전트 메모리

대화 저장 구조

각 세션은 ~/.claude/sessions/ 아래 고유한 JSON 파일로 저장됩니다.

// 세션 파일 구조 예시
{
  "id": "sess_01abc123def456",
  "createdAt": "2026-03-31T10:00:00Z",
  "updatedAt": "2026-03-31T11:30:00Z",
  "cwd": "/Users/reserve/Workspace/my-project",
  "messages": [
    {
      "role": "user",
      "content": "테스트 파일을 작성해줘",
      "timestamp": "2026-03-31T10:00:01Z"
    },
    {
      "role": "assistant",
      "content": [
        { "type": "tool_use", "name": "Write", "input": { ... } },
        { "type": "text", "text": "테스트 파일을 작성했습니다." }
      ],
      "timestamp": "2026-03-31T10:00:15Z"
    }
  ],
  "compactedAt": null,
  "tags": []
}

세션 ID

세션 ID는 sess_ 접두어로 시작하는 고유 식별자입니다. 다음 방법으로 확인할 수 있습니다.

# 현재 세션 ID 확인
/session-id

# 모든 세션 목록 보기
claude --list-sessions

세션 재개

이전 대화를 이어서 진행하려면 --resume 플래그를 사용합니다.

# 세션 ID로 직접 재개
claude --resume sess_01abc123def456

# 대화형 선택으로 재개 (최근 세션 목록 표시)
claude --resume

재개 시 동작 방식

세션을 재개할 때 단순히 이전 메시지를 불러오는 것 이상의 작업이 일어납니다.

항목	동작	주의사항
메시지 히스토리	전체 로드	컴팩션된 경우 요약문 포함
메모리 파일	재탐색	최초 세션과 달라질 수 있음
작업 디렉토리	저장된 경로 사용	디렉토리가 삭제되면 오류
권한 모드	기본값으로 리셋	--dangerously-skip-permissions 재지정 필요
MCP 연결	재연결 시도	서버 상태 변경 반영됨

권한 모드 리셋 은 중요한 보안 동작입니다. 이전 세션에서 자동 승인 모드를 사용했더라도 재개 시 반드시 명시적으로 다시 지정해야 합니다.

컴팩션과 원본 보존

컨텍스트 윈도우가 포화 상태에 가까워지면 컴팩션이 실행됩니다.

원본 메시지 50개
    ↓ 컴팩션
요약문 1개 + 최근 메시지 10개
    ↓ 메모리에서는 압축된 상태로 유지
    ↓ 디스크에는 원본 50개 전부 보존

컴팩션 전후 비교

// 컴팩션 전 메시지 구조
{
  "messages": [
    { "role": "user", "content": "..." },  // 메시지 1
    { "role": "assistant", "content": "..." },  // 메시지 2
    // ... 48개 더
  ]
}

// 컴팩션 후 메시지 구조 (메모리)
{
  "messages": [
    {
      "role": "user",
      "content": "[Summary] 이전 대화 요약: 사용자가 auth.ts를 리팩토링하고..."
    },
    { "role": "user", "content": "..." },  // 최근 메시지 10개 유지
    // ...
  ],
  "compactedAt": "2026-03-31T11:00:00Z"
}

원본 트랜스크립트는 ~/.claude/sessions/<id>.json 에 항상 보존됩니다. 컴팩션은 메모리 내 표현만 압축합니다.

세션 관리 함수

Claude Code는 세션을 프로그래밍 방식으로 관리하는 함수들을 제공합니다.

// 모든 세션 목록 조회
const sessions = await listSessions()
// Returns: Array<{ id, createdAt, cwd, messageCount, tags }>

// 특정 세션의 메시지 조회
const messages = await getSessionMessages('sess_01abc...')

// 현재 세션을 새 세션으로 포크
const newSessionId = await forkSession('sess_01abc...')
// 원본 세션은 유지, 새 분기점에서 독립적으로 진행 가능

// 세션 이름 지정 (기본값: 첫 메시지 미리보기)
await renameSession('sess_01abc...', '인증 모듈 리팩토링')

// 태그 추가
await tagSession('sess_01abc...', ['refactoring', 'auth'])

세션 포크 활용 예시

# 현재 세션에서 두 가지 접근법을 병렬로 시험
$ claude --resume sess_01abc...

# 접근법 A: 현재 세션에서 계속
> 방법 A로 구현해줘

# 접근법 B: 포크 후 별도 시도
$ claude --resume sess_01abc...  # 동일 시점에서 재개
> 방법 B로 구현해줘

저장 공간 관리

세션 파일이 쌓이면 디스크 공간을 차지합니다.

# 세션 파일 크기 확인
du -sh ~/.claude/sessions/

# 30일 이상 된 세션 삭제 (직접 관리)
find ~/.claude/sessions -name "*.json" -mtime +30 -delete

세션 유형	평균 크기	보존 권장 기간
짧은 대화 (10턴 미만)	50KB	7일
중간 작업 세션	200KB~1MB	30일
대형 리팩토링 세션	1MB~5MB	영구 보존 권장