[Claude Code] 대화 컨텍스트 유실 복구하기
클로드 코드를 쓴 지 어느덧 6개월 쯤 되었다.
지금 다니는 곳에서는 Gemini Pro Enterprise 계정을 지급해줘서 CLI나 Web으로 사용해봤지만, 개인적으로 개발을 하는데에는 아직 Claude 모델이 앞서는 것 같다.
최근 시작한 프로젝트의 백오피스 프론트엔드 아키텍처 설계를 맡게 돼서 Claude Code를 써서 퇴근 후나 주말에 공부하며 진행하던 중이었다.
한참 터미널 환경에서 Claude Code로 설계 의사결정을 하다가 세션을 종료하고, 다음날 다시 실행헤 이전 세션을 재개(/resume 명령어) 했지만 /resume은 됐는데 기존 대화 내역이 화면에 출력되지 않았다.
터미널 강제 종료의 위험성과 안전한 종료 방법
작업을 마친 후 관성적으로 터미널 창의 우측 상단 X 버튼을 눌러 종료하는 경우가 많다. 공식 문서상으로는 자동 저장이 지원된다고 명시되어 있으나, 이렇게 종료할 경우 대화 내역이 유실될 위험이 높다.
개인적으로도 8할은 대화가 날라갔어서 이후 무조건 /exit을 써왔다.
GitHub 이슈 트래커에 보고된 알려진 버그와 시스템적 한계는 다음과 같다.
- 강제 종료 시 애플리케이션 메모리에 남아있는 마지막 대화 데이터가 디스크에 플러시(Flush)되지 않은 채 프로세스가 닫혀 최신 메시지가 유실된다.
- 동일한 세션을 여러 터미널에서 동시에 열어둔 상태로 종료할 경우 대화 데이터가 깨지거나 초기화되는 버그가 존재한다. (이슈 27751)
- VSCode 터미널 확장 등 특정 환경에서 트랜스크립트가 로컬 디스크에 정상적으로 저장되지 않는 현상이 발생한다. (이슈 22900)
따라서 대화 유실을 막으려면 애플리케이션에 명시적인 종료 시그널을 주어야 한다. 추천하는 안전한 종료 방법은 다음과 같다고 한다.
- /exit 커맨드: 프로세스가 정상적인 메모리 정리 및 파일 저장 절차를 거치도록 유도한다.
- Ctrl+D: 터미널의 표준 입력 종료(EOF) 시그널을 전송하여 안전하게 세션을 닫는다.
- 터미널 X 버튼 클릭: OS 레벨에서 프로세스를 강제 Kill하므로 사용을 피해야 한다.
Claude Code의 로컬 로깅 메커니즘
그런데 이번처럼 /exit 명령어나 Ctrl+D를 사용하여 세션을 안전하게 종료했음에도 재개 시 화면에서 대화 내역이 사라지는 경우가 있다. 이러한 상황을 해결하려고 내부 동작 방식을 좀 찾아보게 됐다.
Claude Code는 세션 상태와 대화 내역을 메모리에만 유지하지 않고 로컬 디스크에 .jsonl(JSON Lines) 형태로 실시간 기록한다. 로그 파일이 저장되는 기본 경로는 다음과 같다. 프로젝트의 절대 경로가 특수문자 치환 룰에 따라 인코딩되어 디렉토리명으로 사용된다.
C:\Users{사용자명}.claude\projects{인코딩된-프로젝트-경로}*.jsonl
화면에서 대화 내역이 사라진 이유는 파일이 삭제되어서가 아니라 (그런 경우도 있기야 하겠지만) 다음 두 가지 케이스 중 하나에 해당하기 때문이다.
- 세션 정상 종료: /exit 명령어로 프로세스가 종료되면서 UI 렌더링을 위한 컨텍스트 연결이 끊어짐.
- 컨텍스트 압축: 대화가 길어질 경우 LLM의 컨텍스트 윈도우 한계를 우회하기 위해 도구 자체적으로 오래된 메시지를 UI에서 숨기고 압축함.
말은즉슨 터미널에 렌더링만 되지 않을 뿐 물리적인 데이터는 파일 시스템에 그대로 남아있다.
.jsonl 로그 파일 복구하기
터미널에서 직접 해당 경로로 이동해 최근 수정된 로그 파일을 확인하고 컨텍스트를 복구한다.
1. 최근 작업 파일 조회
작업 중이던 디렉토리 경로를 기반으로 가장 최근에 기록된 로그 파일을 찾는다. (Windows bash 쉘 환경 기준)
ls -lt C:/Users/USER/.claude/projects/C--Users-USER-IdeaProjects/*.jsonl | head -5
2. 파일 내용 확인 및 컨텍스트 파악
.jsonl 포맷은 한 줄에 하나의 JSON 객체가 기록되는 구조라서 tail 명령어를 사용하면 마지막 대화 내역을 쉽게 역추적할 수 있다.
tail -n 100 C:/Users/USER/.claude/projects/.../{조회된파일명}.jsonl
파일을 열람하면 사용자의 프롬프트, 도구 실행 결과, 어시스턴트의 응답이 순차적으로 기록되어 있다. 이를 통해 마지막으로 작업하던 컨텍스트를 파악, 복구 가능하다.
세션 관리용 추천 설정들
안전한 종료와 로컬 파일 복구 외에도 프로젝트 단위의 대화 이력을 효율적으로 관리하기 위해 다음 기능들을 활용하는 걸 추천한다.
- /rename: 현재 진행 중인 세션에 고유한 이름을 부여하여 나중에 재개할 때 쉽게 식별할 수 있도록 한다.
- /export: 아키텍처 설계 등 중요한 의사결정이 포함된 대화는 별도의 마크다운 파일로 내보내어 안전하게 백업한다.
- cleanupPeriodDays: 기본 설정상 .jsonl 로그는 30일 후 자동 삭제된다. 장기적인 프로젝트 기록 보관이 필요하다면 내부 설정 파일에서 해당 기간을 연장해야 한다.
참고
- Claude Code 공식 가이드 및 개요: [https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview]
- 장애 조치(Troubleshooting) 및 한계점: [https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/troubleshooting]
GitHub 공식 이슈 트래커
- 다중 터미널 세션 동시 실행 시 대화 데이터 유실 버그 (Issue #27751): [https://github.com/anthropics/claude-code/issues/27751]
- VSCode 확장 환경에서 로컬 트랜스크립트 디스크 저장 누락 버그 (Issue #22900): [https://github.com/anthropics/claude-code/issues/22900]
로컬 설정 파일이나 자동 삭제 주기(cleanupPeriodDays) 같은 세부 옵션은 공식 문서의 Settings 파트를 찾아보면 더 자세히 나온다.
