Claude Code의 세션 지속성

개요

Claude Code는 단순한 대화 기록을 넘어서는 정교한 세션 지속성을 제공합니다. 이 기능은 백그라운드 프로세스, 파일 컨텍스트, 권한, 작업 디렉터리를 포함한 개발 환경의 전체 상태를 유지합니다.

세션 명령어

핵심 명령어

명령어	설명	예시
`claude --continue`	가장 최근 대화를 계속합니다	`claude --continue`
`claude --resume`	특정 세션을 다시 시작합니다 (대화형 선택)	`claude --resume`
`claude --resume <id>`	ID로 특정 세션을 다시 시작합니다	`claude --resume abc123-def456`
`claude --session-id <uuid>`	지정한 세션 ID로 시작합니다	`claude --session-id my-custom-id`

지속되는 항목

1. 대화 기록

사용자와 Claude 사이의 전체 메시지 기록
매개변수와 응답을 포함한 툴 호출 기록
이전 상호작용에서의 컨텍스트
파일 참조와 수정 내역

2. 백그라운드 프로세스

run_in_background: true로 시작한 백그라운드 작업은 세션이 달라져도 유지됩니다:

# 예시: 한 세션에서 서버를 시작합니다
python3 -m http.server 8080  # bash_3

# --continue 또는 --resume 이후:
# - 프로세스가 계속 실행 중입니다
# - 셸 ID가 유지됩니다 (bash_3)
# - BashOutput 도구로 출력을 확인할 수 있습니다
# - KillBash 도구로 종료할 수 있습니다

검증된 테스트 결과:

세션이 종료된 후에도 백그라운드 프로세스가 계속 실행됩니다
셸 ID(bash_1, bash_2 등)가 유지됩니다
출력 버퍼가 유지되어 증분 읽기가 가능합니다
프로세스 상태(실행 중/완료/종료됨)가 추적됩니다

3. 파일 컨텍스트

Claude는 어떤 파일에 접근했는지 기억합니다:

# Read 도구로 읽은 파일
# Edit 도구로 수정한 파일
# Write 도구로 생성한 파일
# 모든 내용이 세션 간에 유지됩니다

테스트 예시:

# 세션 1: 표시용 파일을 생성합니다
claude> Write test-session-marker.txt

# 세션 2: Claude는 다시 읽지 않아도 파일을 알고 있습니다
claude --continue
claude> "What's in test-session-marker.txt?"
# Claude는 메모리에서 해당 파일을 참조할 수 있습니다

4. 작업 디렉터리 컨텍스트

# 현재 작업 디렉터리가 유지됩니다
# 환경 상태가 유지됩니다
# 경로 컨텍스트가 기억됩니다

5. 도구 권한

한 세션에서 승인한 권한은 그대로 이어집니다:

# 첫 번째 세션: git 명령을 위해 Bash 도구를 승인합니다
# 이후 세션: 동일한 패턴에 대해 다시 승인할 필요가 없습니다

증분 출력 추적

BashOutput 도구가 읽기 위치를 유지합니다:

# 첫 번째 확인: bash_6
BashOutput(bash_6) → 1-10줄을 표시합니다

# 두 번째 확인 (세션을 다시 시작한 이후에도)
BashOutput(bash_6) → 새로 추가된 11-20줄만 표시합니다

# 중복 출력 표시를 방지합니다

세션 저장소

저장 위치

세션은 로컬 머신에 저장되며(운영체제에 따라 경로가 다릅니다):

대부분 ~/.config/claude/ 또는 유사한 경로에 있습니다
각 세션에는 고유 식별자가 있습니다
오래된 세션은 자동으로 정리됩니다

세션 구조

{
  "sessionId": "abc123-def456",
  "startTime": "2025-08-11T22:00:00Z",
  "lastActive": "2025-08-11T22:27:00Z",
  "messages": [...],
  "backgroundTasks": {
    "bash_3": {
      "command": "python3 -m http.server 8080",
      "status": "running",
      "pid": 295416,
      "outputPosition": 1234
    }
  },
  "fileContext": {
    "read": ["file1.txt", "file2.js"],
    "modified": ["config.json"],
    "created": ["test-marker.txt"]
  },
  "permissions": {
    "approvedTools": ["Bash(git:*)", "Edit"],
    "directories": ["/workspaces/project"]
  }
}

실전 예시

예시 1: 개발 서버 관리

# 월요일: 개발을 시작합니다
claude
> npm run dev를 백그라운드에서 시작하세요
> docker-compose up을 백그라운드에서 시작하세요
> 기능 개발을 진행합니다...
> 종료합니다 (서버는 계속 실행됩니다)

# 화요일: 작업을 이어갑니다
claude --continue
> npm run dev 상태를 확인합니다  # 여전히 실행 중입니다!
> docker 로그를 보여주세요  # 모든 출력을 확인할 수 있습니다
> 개발을 계속합니다...

예시 2: 장시간 빌드

# 긴 빌드를 시작합니다
claude
> 빌드 스크립트를 백그라운드에서 실행하세요
> 점심 식사를 위해 종료합니다

# 돌아와서 진행 상황을 확인합니다
claude --continue
> 빌드 출력을 확인합니다  # 자리를 비운 동안 무슨 일이 있었는지 확인합니다
> 빌드가 끝났나요? 종료 코드를 확인합니다

예시 3: 디버그 세션

# 복잡한 디버깅 세션
claude
> 모니터링을 백그라운드에서 설정합니다
> 테스트 파일을 만듭니다
> 진단을 실행합니다
> [시스템 충돌/자리 이탈 필요]

# 떠난 지점 그대로에서 다시 시작합니다
claude --resume
> 모든 백그라운드 모니터가 여전히 실행 중입니다
> 테스트 파일이 여전히 컨텍스트에 포함되어 있습니다
> 정확히 그 지점에서 디버깅을 이어갑니다

모범 사례

1. 세션 관리

이렇게 하세요:

당일 작업을 이어가려면 --continue를 사용하세요
특정 과거 세션이 필요할 때는 --resume을 사용하세요
--session-id로 세션에 의미 있는 이름을 부여하세요
장기간 자리를 비우기 전에 백그라운드 작업을 정리하세요

이렇게 하지 마세요:

불필요한 백그라운드 작업을 며칠씩 실행된 채로 두지 마세요
일주일 이상 지난 세션에 의존하지 마세요(정리될 수 있습니다)
백그라운드 프로세스가 시스템 재부팅 후에도 살아 있을 것이라고 가정하지 마세요

2. 백그라운드 작업 관리

# 세션을 종료하기 전에 백그라운드 작업을 확인하세요
/bashes  # 모든 백그라운드 작업을 나열합니다

# 필요하면 정리하세요
"dev server를 제외한 모든 백그라운드 작업을 종료하세요"

# 또는 선택적으로 정리하세요
"bash_1과 bash_2는 종료하고 bash_3은 유지하세요"

3. 컨텍스트 유지

# 복잡한 작업을 위해 세션 마커를 만드세요
"현재 컨텍스트로 SESSION_NOTES.md를 생성하세요"

# 당신과 Claude 모두 컨텍스트를 기억하는 데 도움이 됩니다
"진행 상황으로 SESSION_NOTES.md를 업데이트하세요"

제한 사항

1. 시스템 경계

세션은 머신 로컬로 유지됩니다
시스템 재부팅 시 유지되지 않습니다
머신 간에 이전할 수 없습니다

2. 프로세스 제한

백그라운드 프로세스가 자원 문제로 OS에 의해 종료될 수 있습니다
오랫동안 유휴 상태인 프로세스는 시간 초과될 수 있습니다
출력 버퍼에는 크기 제한이 있습니다

3. 보안 경계

세션 재개 시 파일 권한을 다시 확인합니다
새로운 민감한 작업은 다시 승인이 필요합니다
각 세션마다 디렉터리 접근을 검증합니다

고급 기능

세션 분기

동일한 세션을 여러 번 다시 시작할 수 있습니다:

# 원래 작업
claude --session-id project-main

# 분기 1: 접근 방식 A를 시도합니다
claude --resume project-main
# 접근 방식 A를 진행합니다

# 분기 2: 접근 방식 B를 시도합니다  
claude --resume project-main
# 접근 방식 B를 진행합니다
# 두 분기 모두 동일한 시작 컨텍스트를 가집니다

부분 복구

세션이 부분적으로 손상되더라도:

대화 기록은 대부분 복구할 수 있습니다
파일 컨텍스트가 유지되는 경우가 많습니다
백그라운드 작업은 다시 시작해야 할 수 있습니다

자동 정리

Claude Code는 세션을 자동으로 관리합니다:

일정 기간이 지나면 오래된 세션을 정리합니다
보존 기간을 설정할 수 있습니다
큰 세션은 자동으로 압축합니다

문제 해결

문제: 세션 재개 후 백그라운드 작업을 찾을 수 없음

# 프로세스가 아직 존재하는지 확인합니다
ps aux | grep <command>

# 프로세스가 종료되었다면 다시 시작하세요
"bash_3에서 실행되던 dev server를 다시 시작하세요"

문제: 세션이 다시 시작되지 않음

# 대신 continue를 시도하세요
claude --continue

# 최근 세션을 나열합니다
claude --resume  # 대화형 선택

# 필요하면 새로 시작하세요
claude  # 새 세션

문제: 권한이 기억되지 않음

# 보안을 위해 권한이 만료될 수 있습니다
# 요청이 표시되면 다시 승인하면 됩니다
# 개발 중이라면 --dangerously-skip-permissions를 사용할 수도 있습니다

검증된 테스트

다음 기능을 테스트하여 검증했습니다:

✅ 백그라운드 작업 지속성

python3 -m http.server 8080을 bash_3으로 실행했습니다
세션을 계속한 후에도 서버가 실행 중이었습니다
ps aux로 프로세스를 확인했습니다

✅ 셸 ID 유지

백그라운드 작업 ID(bash_1, bash_2 등)가 유지되었습니다
세션 재개 후에도 동일한 ID를 참조할 수 있었습니다

✅ 증분 출력

BashOutput은 마지막 확인 이후의 새 출력만 반환했습니다
세션 간에도 위치 마커가 유지되었습니다

✅ 파일 컨텍스트 기억

세션에서 생성하거나 수정한 파일을 기억했습니다
세션 재개 후 파일을 다시 읽을 필요가 없었습니다

✅ 다중 백그라운드 작업

여러 백그라운드 프로세스를 실행할 수 있었습니다
각각 독립적으로 추적되었습니다
각 작업이 고유 상태를 유지했습니다

Session Persistence