SpyBara
Go Premium

checkpointing.md 2026-10-19 23:58 UTC to 2026-10-20 23:00 UTC

This page contains 20 additions and 48 deletions.

2026
Tue 6 23:59 Sat 10 23:01 Thu 15 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Sun 25 23:58 Wed 28 23:57

Checkpointing

Claude의 편집 및 대화를 추적, 되돌리기 및 요약하여 세션 상태를 관리합니다.

Claude Code는 작업하면서 Claude의 파일 편집을 자동으로 추적하므로 변경 사항을 빠르게 실행 취소하고 문제가 발생한 경우 이전 상태로 되돌릴 수 있습니다.

Checkpoint의 작동 방식

Claude와 함께 작업할 때 checkpointing은 각 사용자 프롬프트가 시작하는 턴 전에 코드의 상태를 자동으로 캡처합니다.

자동 추적

Claude Code는 파일 편집 도구로 수행된 모든 변경 사항을 추적합니다:

  • 시작하는 턴마다 보내는 모든 프롬프트는 새로운 checkpoint를 생성합니다
  • Claude Code는 세션의 가장 최근 100개 checkpoint에 대한 파일 스냅샷을 유지합니다. 이전 checkpoint를 삭제하면 남은 checkpoint가 참조하지 않는 스냅샷 파일이 삭제되며, 각 파일의 첫 번째 스냅샷은 예외입니다. 이 스냅샷은 VS Code 확장이 세션 diff의 기준선으로 사용합니다.
  • Checkpoint는 세션과 함께 저장되므로 재개된 세션에서도 /rewind를 사용할 수 있습니다
  • Claude Code는 retention sweep에서 세션의 파일 스냅샷을 삭제합니다. 기본적으로 세션이 마지막으로 저장된 후 약 30일 후입니다. 스냅샷이 없는 checkpoint로 되돌리면 No files were restored 오류가 발생할 수 있습니다. 스냅샷을 더 오래 유지하려면 cleanupPeriodDays를 설정하세요.

되돌리기 및 요약

/rewind를 실행하거나 프롬프트 입력이 비어 있을 때 Esc를 두 번 눌러 rewind 메뉴를 엽니다.

[!NOTE]

프롬프트 입력에 텍스트가 포함되어 있으면 Esc를 두 번 누르면 메뉴를 열지 않고 대신 텍스트를 지웁니다. 지워진 텍스트는 입력 기록에 저장되므로 rewind 메뉴에서 작업을 마친 후 Up을 눌러 복구할 수 있습니다.

Rewind 메뉴는 세션 중에 보낸 프롬프트를 나열합니다. 작업할 지점을 선택한 다음 작업을 선택합니다:

  • 코드 및 대화 복원: 코드와 대화를 해당 지점으로 되돌립니다
  • 대화 복원: 현재 코드를 유지하면서 해당 메시지로 되돌립니다
  • 코드 복원: 대화를 유지하면서 파일 변경 사항을 되돌립니다
  • 여기서부터 요약: 이 지점부터 이후의 대화를 요약으로 압축하여 context window 공간을 확보합니다
  • 여기까지 요약: 이 지점 이전의 대화를 요약으로 압축하여 이후 메시지를 그대로 유지합니다
  • 취소: 변경 사항을 적용하지 않고 메시지 목록으로 돌아갑니다

두 코드 복원 옵션은 선택한 checkpoint에 되돌릴 추적된 파일 변경 사항이 있을 때만 나타납니다. 해당 지점 이후에 파일 편집이 캡처되지 않은 경우 메뉴는 대화 복원, 요약 옵션 및 취소만 제공합니다.

대화를 복원하거나 여기서부터 요약을 선택한 후 선택한 메시지의 원본 프롬프트가 입력 필드에 복원되므로 다시 보내거나 편집할 수 있습니다.

여기까지 요약을 선택하면 대화의 끝에 남겨지며 입력 필드는 비어 있습니다. 두 요약 옵션 중 하나를 사용하면 압축된 메시지가 있던 대화에 Summarized conversation 마커가 나타납니다.

이전 세션의 지워진 대화로 되돌리기

동일한 Claude Code 프로세스에서 이전에 /clear를 실행한 경우 rewind 메뉴는 목록 맨 위에 /resume <session-id> (이전 세션)이라는 레이블이 지정된 추가 항목을 표시합니다. 이를 선택하여 /clear가 실행되기 전에 활성화되었던 대화를 재개합니다. 이 항목은 Claude Code를 종료하거나 다른 세션을 재개할 때까지 사용 가능합니다.

요약 안내

요약은 디스크의 파일을 변경하지 않으며 원본 메시지는 세션 기록에 남아 있으므로 Claude가 여전히 세부 정보를 참조할 수 있습니다. 요약이 초점을 맞출 내용을 안내하려면 화살표 키로 Summarize 옵션을 강조 표시하고 행에 **add context (optional)**이라고 표시된 위치에 지침을 입력한 다음 Enter를 누르세요. 숫자 키로 옵션을 선택하면 지침 없이 즉시 요약합니다.

[!NOTE]

Summarize는 동일한 세션에 유지되고 범위를 좁힌 /compact처럼 context를 압축합니다. 원본 세션을 그대로 유지하면서 갈라져 나와 다른 접근 방식을 시도하고 싶다면 대신 /branch 또는 claude --continue --fork-session을 사용하세요.

일반적인 사용 사례

Checkpoint는 다음과 같은 경우에 특히 유용합니다:

  • 대안 탐색: 시작점을 잃지 않으면서 다양한 구현 접근 방식을 시도합니다
  • 실수 복구: 버그를 도입하거나 기능을 손상시킨 변경 사항을 빠르게 실행 취소합니다
  • 기능 반복: 작동하는 상태로 되돌릴 수 있다는 확신을 가지고 변형을 실험합니다
  • Context 공간 확보: 초기 지침을 그대로 유지하면서 중간 지점부터 시작하여 자세한 디버깅 세션을 요약합니다

제한 사항

Bash 명령 변경 사항이 추적되지 않음

Checkpointing은 Bash 명령으로 수정된 파일을 추적하지 않습니다. 예를 들어 Claude Code가 다음을 실행하는 경우:

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

이러한 파일 수정 사항은 rewind를 통해 실행 취소할 수 없습니다. Claude의 파일 편집 도구를 통해 직접 수행된 파일 편집만 추적됩니다.

Subagent 편집이 복원되지 않음

Subagent는 Claude의 파일 편집 도구로 편집을 수행하지만, Claude Code는 일반적으로 세션의 checkpoint에서 이러한 편집을 캡처하지 않습니다. Rewind가 이를 복원하는지 여부는 subagent가 실행되는 방식에 따라 달라집니다:

  • Foreground forked skill: foreground에서 실행되는 context: fork가 있는 skill은 사용자의 차례 동안 작업 트리를 편집하므로, rewind는 일반적으로 편집을 복원합니다. background: false를 설정하여 fork를 foreground에서 실행합니다. 몇 가지 상황(skills 페이지에 나열됨)은 설정과 관계없이 foreground에서 실행됩니다.
  • 다른 모든 서브에이전트: rewind는 대화에서 Claude가 이미 편집한 파일만 복원합니다. 다른 파일에 대한 서브에이전트의 편집은 그대로 남으므로 git을 사용하여 되돌립니다. 여기에는 background에서 실행되는 포크된 스킬(기본값)과 background /code-review --fix 실행이 포함됩니다.

외부 변경 사항이 추적되지 않음

Checkpointing은 현재 세션 내에서 편집된 파일만 추적합니다. Claude Code 외부에서 수동으로 수행한 파일 변경 사항과 다른 동시 세션의 편집은 현재 세션과 동일한 파일을 수정하는 경우를 제외하고는 일반적으로 캡처되지 않습니다.

차례 중간에 전송된 메시지가 checkpoint되지 않음

rewind 메뉴에서 Claude가 아직 작업하는 동안 입력한 메시지에 No code restore 표시가 붙을 수 있습니다. Claude는 턴이 끝나기 전에 해당 메시지를 읽었습니다. 체크포인트는 턴을 시작하는 프롬프트에 대해 생성되므로, 이 메시지에는 자체 체크포인트가 없습니다. Claude가 이 메시지를 읽은 후 수행한 편집은 해당 턴을 시작한 프롬프트에 포함됩니다.

메시지 자체에 대해서는 별도로 조치할 필요가 없습니다. 세션의 해당 부분에서 발생한 파일 변경 사항을 실행 취소하려면, 턴을 시작한 프롬프트를 선택하고 Restore code 또는 Restore code and conversation을 선택합니다. 이렇게 하면 메시지가 도착하기 전의 편집을 포함하여 전체 턴에서 Claude가 수행한 파일 편집이 되돌려집니다. 표시가 붙은 메시지를 선택해도 Restore conversation은 여전히 제공되며, 이 옵션은 대화를 해당 메시지 시점으로 rewind하고 파일은 그대로 유지합니다.

Checkpointing은 symlink 또는 hard link된 파일을 rewind하지 않습니다. /rewind 메뉴에서 Restore code 또는 Restore code and conversation을 선택하면, Claude Code는 symlink 또는 hard link인 추적된 경로를 건너뛰고 Restored the code, but skipped N files 경고를 표시합니다. 건너뛴 파일은 현재 내용을 유지합니다. 세션의 변경 사항 중 하나를 실행 취소하려면 Claude에 편집을 되돌리도록 요청하거나 파일을 직접 편집합니다. dotfile manager가 프로젝트에 symlink하는 구성 파일과 pnpm이 제자리에 hard link하는 파일 모두 이 범주에 해당합니다.

restore가 건너뛰는 경로를 확인하려면 restore 전에 /debug로 debug logging을 켭니다: ~/.claude/debug/<session-id>.txt의 debug log는 건너뛴 각 경로를 나열합니다. 모든 건너뛰기 이유와 복구 단계는 error reference의 skipped-files 항목을 참조합니다.

버전 관리의 대체가 아님

Checkpoint는 빠른 세션 수준의 복구를 위해 설계되었습니다. 영구적인 버전 기록 및 협업을 위해 Git과 같은 버전 관리를 계속 사용하여 커밋, 분기 및 장기 기록을 유지합니다.

참고 항목