Claude Code 세션 보관 스킬 — "세션보관해" (session-archive)

Claude Code 를 매일 쓰다 보면 세션이 끝없이 쌓입니다. 프로젝트마다, 작업마다, 중간에 끊겼다 다시 여는 것까지 전부 하나씩 남습니다. 문제는 이름입니다. 자동으로 붙는 제목은 비슷비슷하고, 며칠 지나면 어느 세션에서 무엇을 했는지 구분이 안 됩니다.

왜 만들었나

claude --resume 으로 이어받으려고 목록을 열면, 폴더별로 세션이 나뉘어 있긴 합니다. 그런데 그 폴더 안에서도 양이 너무 많아졌습니다. 작업량이 늘수록 목록은 길어지고, 결국 "그때 그 결정을 어디서 했더라"를 찾으려고 세션을 하나씩 열어 보게 됩니다.

처음엔 오래된 세션을 지우는 쪽으로 생각했습니다. 그런데 곧 반대라는 걸 알았습니다. 세션 기록은 버릴 쓰레기가 아니라 나중에 다시 꺼내 쓸 작업 이력입니다. 지울 게 아니라 찾을 수 있게 정리해야 했습니다. 그래서 세션을 md 파일로 바꿔 한곳에 모으고 색인을 붙였습니다. 일종의 세션 DB 입니다.

무엇을 하나

• 세션을 닫으면 자동으로 md 원문 — 세션 종료 훅이 대화를 사람이 읽는 md 로 바꿉니다. 사람의 요청, 작업 중에 끼어든 추가 메시지, Claude 의 답변, 도구 호출 한 줄 요약만 남기고 도구 출력 덩어리와 생각 과정은 뺍니다.
• 전체 색인 한 장 — INDEX.md 에 모든 프로젝트의 세션이 시작 시각, 프로젝트, 제목, 첫 요청과 함께 표로 정리됩니다.
• "세션보관해" 한마디로 정리본 — Claude 가 원문을 처음부터 끝까지 읽고, 목차와 작업별 정리(요청, 한 일, 결과 근거, 결정), 마지막에 작업 상태표를 씁니다.
• 프로젝트 폴더엔 안내판만 — 보관은 한곳에 모으고, 각 프로젝트엔 그 프로젝트 세션의 경로와 재개 명령만 적은 .claude/SESSIONS.md 를 둡니다.

실제로 돌려 본 결과

대화가 없던 세션(열었다 바로 닫은 것, /clear 만 친 것)은 건너뛰고, 백그라운드 작업 완료 알림은 사람 메시지와 섞이지 않게 한 줄로 따로 표시합니다.

정리본은 이렇게 생겼습니다

핵심 규칙은 하나입니다. 원문에 증거가 있을 때만 "완료"라고 씁니다. 커밋, 확인한 응답, 테스트 결과가 없으면 "확인 안 함"으로 남깁니다. 다음 세션에서 이 표만 보면 어디서부터 이어야 할지 바로 보입니다.

쓰는 법

1. 스킬을 ~/.claude/skills/ 에, 변환 스크립트를 ~/.claude/scripts/ 에 둡니다. python3 만 있으면 되고 외부 패키지는 없습니다.
2. 한 번 전체 변환: python3 ~/.claude/scripts/session2md.py --all
3. 세션 종료 훅을 켜 두면 이후로는 자동입니다.
4. 작업을 마칠 때 Claude 에게 "세션보관해"라고 하면 정리본까지 남습니다.

이런 분께

• Claude Code 세션이 수십, 수백 개 쌓여 --resume 목록에서 찾기 어려운 분
• 세션 기록을 나중에 검색하거나 DB 로 옮겨 분석하고 싶은 분
• 작업을 마칠 때마다 "무엇을 했고 무엇이 남았는지"를 문서로 남기고 싶은 분

구성

설치

unzip session-archive.zip
mkdir -p ~/.claude/skills ~/.claude/scripts
cp -r session-archive ~/.claude/skills/
cp session-archive/scripts/session2md.py ~/.claude/scripts/
python3 ~/.claude/scripts/session2md.py --all   # 지금까지의 세션 한 번에 변환

세션 종료 자동 변환은 README 의 훅 설정 한 블록을 ~/.claude/settings.json 에 붙이면 됩니다.

요구 사항

• Claude Code (세션 기록이 ~/.claude/projects 에 쌓이는 CLI)
• python3 (Linux, macOS). 외부 패키지 없음
• 원본 세션 기록은 읽기만 하고 지우거나 고치지 않습니다