2026년 10월 30일 자로 게시된 Claude Code 공식 문서의 세션 관리(Manage sessions) 페이지는 AI 코딩 도구 Claude Code가 작업 내용을 다루는 방식을 설명합니다. 어디에 어떤 형식으로 저장하는지, 얼마나 오래 보관하는지, 지난 작업을 어떻게 다시 이어 가는지가 이 페이지에 담겨 있습니다. 코딩 에이전트를 팀 단위로 도입하는 조직이라면 이 내용에서 데이터 관리 정책을 시작하게 됩니다.
작업하는 동안 기록이 계속 저장됩니다
Claude Code는 사용자가 작업하는 동안 세션을 로컬 기록 파일(transcript)에 계속 저장합니다. 작업을 마칠 때 한꺼번에 저장하는 방식이 아닙니다. 대화가 진행되는 동안 파일에 내용이 쌓입니다.
기본 저장 위치는 사용자 홈 폴더의 ~/.claude/projects 아래입니다. 프로젝트마다 폴더가 생기고, 그 안에 세션 ID별로 파일이 하나씩 만들어집니다. 파일 형식은 한 줄에 JSON 객체 하나를 담는 JSONL입니다.
각 줄에는 여러 종류의 정보가 담깁니다. 사용자와 Claude가 주고받은 메시지가 담기고, 도구 호출과 그 결과도 담깁니다. Claude Code가 모델에 보낸 요청 기록과 메타데이터도 함께 남습니다. 도구 실행 결과까지 기록된다는 점은 눈여겨볼 만합니다. 작업 중에 Claude가 읽은 파일 내용이나 명령 실행 결과가 기록 파일에 함께 남을 수 있기 때문입니다.
프로젝트 폴더 이름은 작업 디렉터리 경로를 변환해 만듭니다. 변환한 이름이 200자를 넘으면 Claude Code는 이름을 200자로 자릅니다. 그리고 전체 경로의 해시를 뒤에 덧붙입니다.
기본 보관 기간은 30일입니다
기록 파일은 기본적으로 30일 동안 보관됩니다. 이 기간은 설정 파일 settings.json의 cleanupPeriodDays 값으로 바꿀 수 있습니다. 감사나 회고를 위해 더 오래 남겨야 하는 팀은 기간을 늘릴 수 있습니다. 민감한 코드를 다루는 팀은 기간을 줄일 수 있습니다.
저장 위치도 옮길 수 있습니다. CLAUDE_CONFIG_DIR 환경 변수를 지정하면 기록이 ~/.claude가 아닌 다른 경로에 저장됩니다. 회사가 관리하는 경로에 기록을 모으려는 조직이라면 이 설정을 검토할 수 있습니다.
기록 파일로 세션을 다시 이어 갑니다
기록 파일은 보관용에서 끝나지 않습니다. claude –resume 명령에 .jsonl 파일의 절대 경로를 넘기면 그 파일에 저장된 세션을 이어서 작업할 수 있습니다.
압축(compaction)을 거친 세션은 조금 다르게 동작합니다. 압축된 세션을 재개하면 마지막 압축에서 요약된 메시지는 대화에 다시 불러오지 않습니다. 요약되기 전의 세부 대화는 재개한 세션에 들어오지 않는다는 뜻입니다. 긴 작업을 나중에 이어 갈 계획이라면 중요한 결정 사항을 별도 문서로 남겨 두는 편이 안전합니다.
이전 세션을 재개하지 않고 새 대화를 시작할 때도 있습니다. 이때 Claude가 이전 대화를 찾아볼 수 있다는 안내가 나오면, 새 대화에서도 앞선 작업을 언급할 수 있습니다.
기록 파일을 직접 분석하려는 팀이 알아 둘 점
기록 파일이 JSONL 형식이다 보니 사용량이나 작업 패턴을 집계하는 스크립트를 만들고 싶어지는 팀도 있을 것입니다. 문서는 이 부분을 분명히 경고합니다. 기록 항목의 형식은 Claude Code 내부용이고 버전마다 바뀝니다. 그래서 파일을 직접 파싱하는 스크립트는 업데이트 후에 동작하지 않을 수 있습니다.
기록 파일을 근거로 사내 지표나 보고서를 만들 계획이라면 형식이 바뀌는 상황을 전제로 설계해야 합니다. 파싱에 실패하면 이를 감지해 알리는 장치를 넣어 두는 것이 좋습니다. Claude Code를 업데이트할 때마다 스크립트를 함께 점검하는 절차도 정해 두면 좋습니다.
도입 전에 확인할 것
먼저 보관 기간을 정해야 합니다. 기본값 30일이 사내 데이터 보관 규정과 맞는지 확인합니다. 규정과 다르다면 cleanupPeriodDays 값을 조직 기준에 맞게 정해 배포합니다. 개인마다 설정이 달라지지 않도록 공통 설정으로 관리하는 방법도 검토할 만합니다.
다음은 저장 위치입니다. 기록은 개발자의 로컬 컴퓨터에 남습니다. 기기 분실이나 백업 범위를 고려해, 기본 위치를 그대로 둘지 CLAUDE_CONFIG_DIR로 관리 경로를 지정할지 결정해야 합니다.
기록에 담기는 내용도 점검해야 합니다. 메시지뿐 아니라 도구 실행 결과까지 저장되므로, 고객 정보나 비밀 값이 들어 있는 파일을 다룬 작업도 기록에 남을 수 있습니다. 어떤 저장소에서 Claude Code를 사용해도 되는지 기준을 세워 두어야 합니다. 기록 파일을 누가 열람할 수 있는지도 함께 정해야 합니다.
교육도 필요합니다. 세션 재개와 압축이 어떻게 동작하는지 모르면, 이어서 작업할 때 맥락이 빠진 것을 알아차리지 못할 수 있습니다. 개발자 교육에는 세션을 재개하는 방법과 압축 뒤에 다시 불러오지 않는 범위를 넣어 두면 좋습니다. 기록 파일의 위치와 보관 기간도 함께 다루면 팀이 도구를 안정적으로 사용하는 데 도움이 됩니다.

이정민






























