체크포인팅(Checkpointing)

체크포인팅(Checkpointing)

작업하다 보면 "이 전 상태로 되돌리고 싶다"는 순간이 꼭 생겨요. 체크포인팅은 Claude의 파일 편집과 대화를 추적해서, 무언가 잘못됐을 때 빠르게 변경을 되돌리고 이전 상태로 되감을 수 있게 해 주는 기능입니다. Claude Code는 작업하는 동안 Claude의 파일 편집을 자동으로 추적합니다.

출처: 공식문서

본문

체크포인트가 동작하는 방식

Claude와 작업할 때, 체크포인팅은 턴을 시작하는 프롬프트를 보낼 때마다 코드의 상태를 자동으로 캡처합니다.

자동 추적

Claude Code는 파일 편집 도구가 만든 모든 변경을 추적합니다.

  • 턴을 시작하는 프롬프트마다 새 체크포인트를 만듭니다.
  • Claude Code는 세션에서 가장 최근 100개 체크포인트의 파일 스냅샷을 유지합니다. 더 오래된 체크포인트를 버리면 더 이상 어떤 체크포인트도 참조하지 않는 스냅샷 파일을 삭제합니다. 단, 각 파일의 첫 스냅샷은 VS Code 확장이 세션 diff의 기준선으로 사용하므로 제외합니다.
  • Claude Code는 체크포인트를 대화와 함께 저장하므로, 세션을 재개한 뒤에도 /rewind를 실행할 수 있습니다.
  • Claude Code는 보존 정리에서 세션의 파일 스냅샷을 삭제하는데, 기본적으로 세션이 마지막으로 스냅샷을 저장한 뒤 약 30일 후입니다. 스냅샷이 사라진 체크포인트로 되감으면 No files were restored로 실패할 수 있어요. 스냅샷을 더 오래 유지하려면 cleanupPeriodDays를 설정하세요.

되감기와 요약

프롬프트 입력이 비어 있을 때 /rewind를 실행하거나 Esc를 두 번 누르면 되감기 메뉴가 열립니다.

Note: 프롬프트 입력에 텍스트가 있으면 이중 Esc는 메뉴를 여는 대신 입력을 지웁니다. 지워진 텍스트는 입력 기록에 저장되므로, 되감기 메뉴에서 끝낸 뒤 Up을 눌러 다시 불러올 수 있어요.

되감기 메뉴는 세션 중 보낸 각 프롬프트를 나열합니다(실행 중 턴에 합류한 메시지 제외). 처리하려는 지점을 고른 뒤 동작을 선택하세요.

  • Restore code and conversation: 코드와 대화를 모두 그 지점으로 되돌림
  • Restore conversation: 현재 코드는 유지하며 대화만 그 메시지로 되감기
  • Restore code: 대화는 유지하며 파일 변경만 되돌림
  • Summarize from here: 이 지점 이후의 대화를 요약으로 압축해 컨텍스트 창 공간 확보
  • Summarize up to here: 이 지점 이전의 대화를 요약으로 압축해 이후 메시지는 유지
  • Never mind: 변경 없이 메시지 목록으로 복귀

두 코드 복원 옵션은 선택한 체크포인트가 되돌릴 추적된 파일 변경을 갖고 있을 때만 나타납니다. 그 지점 이후 캡처된 파일 편집이 없으면 메뉴에는 Restore conversation, 요약 옵션, Never mind만 제공돼요.

대화를 복원하거나 Summarize from here을 선택하면, 선택한 메시지의 원래 프롬프트가 입력 필드에 복원되어 다시 보내거나 편집할 수 있습니다.

Summarize up to here을 선택하면 입력이 비어 있는 대화의 끝에 남게 됩니다. 두 요약 옵션 모두 압축된 메시지가 있던 자리에 Summarized conversation 마커가 대화에 나타납니다.

지워진 대화 너머로 되감기

같은 Claude Code 프로세스에서 이전에 /clear를 실행했다면, 되감기 메뉴는 목록 맨 위에 /resume <session-id> (previous session)이라는 레이블의 추가 항목을 보여줍니다. 선택하면 /clear가 실행되기 전에 활성화돼 있던 대화를 재개합니다. 이 항목은 Claude Code를 종료하거나 다른 세션을 재개할 때까지 사용 가능하며 Claude Code v2.1.191 이상이 필요해요. 이전 버전에서는 /resume을 실행하고 목록에서 이전 세션을 고르세요.

요약 안내하기

요약은 디스크의 파일을 바꾸지 않고, 원래 메시지는 세션 트랜스크립트에 남아 Claude가 세부 사항을 계속 참조할 수 있어요. 요약이 집중할 내용을 안내하려면 화살표 키로 Summarize 옵션을 강조하고, add context (optional)이라고 나오는 줄에 지시를 입력한 뒤 Enter를 누르세요. 번호 키로 옵션을 선택하면 지시 없이 즉시 요약합니다.

Note: Summarize는 같은 세션에 머물며 컨텍스트를 압축해, 목표 지점의 /compact와 같아요. 원래 세션을 온전히 보존하며 다른 접근을 시도하려면 /branch 또는 claude --continue --fork-session을 쓰세요.

일반적인 사용 사례

체크포인트는 특히 다음 상황에서 유용해요.

  • 대안 탐색: 시작점을 잃지 않고 서로 다른 구현 접근을 시도
  • 실수 복구: 버그를 도입하거나 기능을 망가뜨린 변경을 빠르게 되돌리기
  • 기능 반복: 동작 상태로 되돌릴 수 있다는 걸 알며 변형을 실험
  • 컨텍스트 공간 확보: 장황한 디버깅 세션을 중간부터 요약해 초기 지시는 유지

제한 사항

bash 명령 변경은 추적되지 않음

체크포인팅은 bash 명령이 수정한 파일을 추적하지 않아요. 예를 들어 Claude Code가 다음을 실행하면,

rm file.txt
mv old.txt new.txt
cp source.txt dest.txt

이런 파일 변경은 되감기로 되돌릴 수 없습니다. Claude의 파일 편집 도구로 직접 한 편집만 추적됩니다.

서브에이전트 편집은 복원되지 않음

서브에이전트는 Claude의 파일 편집 도구로 편집하지만, Claude Code는 보통 그 편집을 세션의 체크포인트에 캡처하지 않아요. 되감기가 복원하는지 여부는 서브에이전트가 어떻게 실행되는지에 달려 있습니다.

  • 포그라운드 fork 스킬: 포그라운드에서 실행되는 context: fork 스킬은 자신의 턴 동안 작업 트리를 편집하므로, 되감기가 그 편집을 평소대로 복원합니다. fork를 포그라운드로 실행하려면 background: false를 설정하세요. skills 페이지에 나열된 몇 가지 상황은 설정과 무관하게 포그라운드로 실행됩니다.
  • 그 외 모든 서브에이전트: 되감기가 그 편집을 복원하지 않습니다. 되돌리려면 git을 쓰세요. 여기에는 백그라운드(기본값)로 실행되는 fork 스킬과 백그라운드 /code-review --fix 실행이 포함됩니다.

외부 변경은 추적되지 않음

체크포인팅은 현재 세션 안에서 편집된 파일만 추적합니다. Claude Code 밖에서 파일에 한 수동 변경이나 다른 동시 세션의 편집은, 우연히 현재 세션과 같은 파일을 수정하지 않는 한 보통 캡처되지 않습니다.

실행 중 턴에 보낸 메시지는 체크포인트되지 않음

Claude가 작업하는 동안 대기열에 넣은 메시지가 실행 중 턴 안에서 Claude에게 도달하면, 새 턴을 시작하는 대신 그 턴에 합류합니다. 메시지는 대화에 나타나지만 Claude Code는 그것을 위한 체크포인트를 만들지 않고, 되감기 메뉴에도 나열하지 않습니다. Claude Code가 자신의 턴으로 보내는 대기열 메시지는 평소대로 체크포인트를 받아요.

그런 메시지를 제거하거나 그 뒤 Claude가 만든 편집을 되돌리려면, 턴을 시작한 프롬프트로 되감으세요. 그러면 메시지가 도착하기 전 Claude가 한 작업을 포함해 전체 턴을 되감습니다.

심링크·하드링크 경로는 복원되지 않음

체크포인팅은 심링크·하드링크 파일을 되감지 않습니다. /rewind 메뉴에서 Restore code 또는 Restore code and conversation을 고르면, 심링크나 하드링크인 추적된 경로를 건너뛰고 Restored the code, but skipped N files 경고를 보여줍니다. 건너뛴 파일은 현재 내용을 유지해요. 그 중 하나에 대한 세션 변경을 되돌리려면 Claude에게 편집을 되돌리라고 하거나 직접 편집하세요. dotfile 매니저가 프로젝트에 심링크하는 설정 파일과 pnpm이 제자리에 하드링크하는 파일이 모두 이 범주에 들어갑니다.

복원이 건너뛰는 경로를 보려면 복원 전에 /debug로 디버그 로깅을 켜세요. ~/.claude/debug/<session-id>.txt의 디버그 로그가 각 건너뛴 경로의 이름을 밝혀줍니다. 건너뛰기 이유와 복구 단계는 에러 레퍼런스의 skipped-files 항목을 보세요.

버전 관리의 대체는 아님

체크포인트는 빠른 세션 수준 복구를 위해 설계됐어요. 영구 버전 기록과 협업이 필요하면 커밋·브랜치·장기 기록을 위해 Git 같은 버전 관리를 계속 사용하세요.

더 알아보기