Claude Code 체크포인트와 /rewind: 무엇이 되돌아가고 무엇이 안 되나

Claude에게 빌드 폴더 정리를 시켰다가 마음이 바뀌어 /rewind로 되돌렸는데 지워진 파일이 돌아오지 않는다면, 고장이 아닙니다. 그 정리가 rm 같은 Bash 명령이었다면 처음부터 체크포인트 밖이었던 거예요.

/rewind(또는 입력창이 비어 있을 때 Esc 두 번)는 프롬프트 단위로 코드와 대화를 되돌려 줍니다.

다만 되돌아가는 건 Claude가 파일 편집 도구로 고친 것뿐이에요. Bash로 지우거나 옮긴 파일, 백그라운드 서브에이전트가 고친 파일, 세션 밖에서 고친 파일은 git으로 되돌려야 합니다.

그래서 저는 파일 삭제·이동이나 서브에이전트 위임 같은 작업 앞에서는 체크포인트와 별개로 커밋을 하나 만들어 두길 권합니다.

2026년 9월 19일 공식 문서 기준입니다. 건너뛴 링크 파일을 찾는 명령은 Ubuntu 24.04 테스트 환경에서 직접 실행했습니다.

10월 12일에는 Windows 11 · PowerShell 5.1 · Claude Code 2.1.296에서 claude -p 편집이 스냅샷을 남기는지와 Windows에서 링크 파일을 찾는 명령을 확인했습니다.

되감기 메뉴에서 고르는 것

/rewind를 입력하거나, 입력창이 비어 있을 때 Esc를 두 번 누릅니다. 입력창에 글자가 있으면 Esc 두 번은 입력을 지우는데, 지운 글자는 입력 기록에 남아 Up으로 불러올 수 있어요. 메뉴에서 프롬프트 하나를 고르면 아래 중에서 고릅니다.

항목	파일	대화
Restore code and conversation	되돌림	되돌림
Restore conversation	그대로	되돌림
Restore code	되돌림	그대로
Summarize from here	그대로	이 지점 뒤를 요약
Summarize up to here	그대로	이 지점 앞을 요약
Never mind	그대로	그대로

파일만 되돌리려면 Restore code, 대화만이면 Restore conversation, 둘 다면 Restore code and conversation, 컨텍스트만 줄이려면 Summarize입니다.

한 가지 헷갈리기 쉬운 점이 있습니다. 코드 복원 두 항목은 되돌릴 편집이 기록돼 있을 때만 보여요. 그 지점 뒤로 기록된 편집이 없으면 대화 복원과 요약, Never mind만 남는데, 고장이 아니라 그 구간에 기록된 편집이 없다는 뜻일 수 있습니다.

대화를 되돌리거나 Summarize from here를 고르면 그 메시지의 원래 프롬프트가 입력창에 돌아와, 고쳐서 다시 보낼 수 있습니다. Summarize up to here는 입력창을 비워 두고, 압축된 자리에는 Summarized conversation 표시가 남습니다.

요약·/compact·/branch는 하는 일이 다르다

셋 다 “대화를 정리한다”처럼 들려서 헷갈립니다.

• /rewind의 Summarize: 같은 세션에서 고른 구간만 압축합니다. 파일은 그대로이고, 원래 메시지도 세션 기록에 남아 Claude가 세부를 참조할 수 있습니다.
• /compact: 같은 세션에서 대화 전체를 요약으로 바꿉니다.
• /branch, claude --continue --fork-session: 원래 세션은 그대로 두고 갈라져 다른 방법을 시도합니다.

요약의 초점을 정하려면 화살표로 Summarize를 고르고 add context (optional) 줄에 지시를 적은 뒤 Enter를 누릅니다. 숫자 키로 바로 고르면 지시 없이 요약해요. 컨텍스트가 차는 문제 자체는 컨텍스트가 찰 때 무엇이 사라지는지 정리한 글에 있습니다.

/clear를 했어도 같은 프로세스라면 돌아갈 수 있다

같은 Claude Code 프로세스 안에서 /clear를 했다면 되감기 목록 맨 위에 /resume <session-id> (previous session) 항목이 생깁니다. 고르면 /clear 직전 대화로 돌아가요. Claude Code를 끄거나 다른 세션을 재개하면 사라지고, v2.1.191 이상이 필요합니다.

VS Code 되감기 버튼도 같은 체크포인트를 쓴다

VS Code 확장에서 메시지에 마우스를 올리면 되감기 버튼에 세 선택지가 나옵니다.

• Fork conversation from here: 코드는 그대로 두고 이 메시지에서 새 대화 갈래를 시작합니다.
• Rewind code to here: 대화는 모두 남기고 파일만 이 지점으로 되돌립니다. 터미널의 Restore code와 같습니다.
• Fork conversation and rewind code: 새 갈래를 시작하면서 파일도 되돌립니다.

체크포인트는 언제 생기고 얼마나 남나

턴을 시작하는 프롬프트를 보내기 직전의 코드 상태가 자동으로 저장됩니다. 기본으로 켜져 있어 따로 켤 필요는 없어요. 되감기 단위가 사용자의 프롬프트라서, 프롬프트 하나로 파일 열 개를 고치게 했다면 열 개가 한 덩어리로 돌아갑니다.

끄는 스위치는 있습니다. /config의 Rewind code (checkpoints) 항목을 끄면 사용자 설정에 "fileCheckpointingEnabled": false가 저장되고, 한 세션만 끄려면 환경 변수 CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING=1을 씁니다. 둘 중 하나라도 끄면 다른 쪽으로는 다시 켤 수 없어요.

claude -p로 고친 것도 되감기 대상일 거라고 기대하면 안 됩니다. Windows에서 -p로 파일 한 줄을 고치게 해 보니, 체크포인트를 끄는 설정이 없는데도 그 세션의 file-history 폴더가 생기지 않았고, 세션 기록의 스냅샷 항목도 비어 있었어요. 비대화형 실행에는 되감기 메뉴도 없으니, 스크립트로 돌리는 작업은 처음부터 git으로 되돌릴 준비를 해 두세요.

항목	값
보관량	세션당 최근 체크포인트 100개분
저장 위치	~/.claude/file-history/<세션 ID>/
세션 재개 후	그대로 /rewind 가능
정리 시점	마지막 저장 뒤 기본 약 30일

오래된 체크포인트를 버릴 때도 각 파일의 첫 스냅샷은 남깁니다. VS Code 확장이 세션 diff의 기준선으로 쓰기 때문이에요. 스냅샷이 지워진 체크포인트는 목록에 보여도 되감으면 No files were restored로 실패할 수 있습니다.

더 오래 두려면 cleanupPeriodDays를 올립니다. 최소 1인 정수이고 0은 검증에 걸리므로, 길게 두려면 큰 값을 쓰세요. 이 정리는 보존 기간을 안전하게 판단할 수 있을 때만 돕니다.

{ "cleanupPeriodDays": 3650 }

되감기가 닿지 않는 곳

1. Bash 명령

rm file.txt·mv old.txt new.txt·cp source.txt dest.txt처럼 Bash가 바꾼 파일은 추적되지 않아 되돌릴 수 없습니다. 추적되는 것은 Claude의 파일 편집 도구를 거친 편집뿐이에요.

2. 서브에이전트

서브에이전트가 고친 것은 대개 세션 체크포인트에 담기지 않고, 어떻게 도느냐에 따라 갈립니다.

• 포그라운드로 도는 포크 스킬(context: fork)은 사용자 턴 안에서 고치므로 평소대로 되돌아갑니다. 포그라운드로 돌리려면 background: false를 주는데, 설정과 상관없이 포그라운드로 도는 경우도 몇 가지 있습니다.
• 그 밖의 서브에이전트가 고친 것은 git으로 되돌립니다. 기본값인 백그라운드 포크 스킬과 백그라운드로 도는 /code-review --fix도 여기에 들어갑니다.

3. 세션 밖의 변경

에디터로 직접 고친 것과 동시에 돌던 다른 세션의 편집은 보통 잡히지 않습니다. 다만 현재 세션이 건드린 것과 같은 파일을 고쳤다면 예외입니다.

4. 턴 도중에 합류한 메시지

Claude가 일하는 동안 보낸 메시지가 돌고 있는 턴에 합류하면, 대화에는 보이지만 체크포인트도 생기지 않고 목록에도 뜨지 않습니다. 지우려면 그 턴을 연 프롬프트로 되감아야 해서, 메시지가 닿기 전에 Claude가 한 일까지 함께 되돌아가요. 자기 턴으로 보내진 메시지는 평소대로 체크포인트가 생깁니다.

체크포인트가 있으니 커밋은 안 해도 되느냐 하면, 편집 도구로만 고치는 작업이라면 되감기로 충분합니다. 하지만 위 네 갈래 중 하나라도 섞이면 되감기는 일부만 돌려놓으니, 오래 남길 이력과 협업에는 계속 git을 쓰세요.

아예 버려도 되는 자리에서 시도하고 싶다면 claude –worktree로 병렬 세션 돌리기가 맞고, 맡기는 정도를 올릴수록 이 사각이 왜 넓어지는지는 네 단계로 세운 글에서 다룹니다.

되돌리고 싶은 것	수단
편집 도구로 고친 파일	/rewind → Restore code
Bash가 지우거나 옮긴 파일	git
백그라운드 서브에이전트가 고친 파일	git

건너뛴 링크 파일 찾기

코드 복원을 고르면 체크포인트에 기록된 경로라도 심볼릭 링크나 하드 링크는 건너뛰고 Restored the code, but skipped N files가 뜹니다. dotfile 관리 도구가 프로젝트로 링크해 둔 설정 파일, pnpm이 하드 링크로 놓은 파일이 대표적이에요. 건너뛴 파일은 지금 내용 그대로입니다.

문제는 경고가 개수만 알려 준다는 점입니다. 어떤 파일인지는 따로 찾아야 해요.

복원 전에 /debug로 디버그 로그를 켜 두면 ~/.claude/debug/<세션 ID>.txt에 건너뛴 경로가 남습니다.

macOS·Linux라면 링크 후보를 미리 찾을 수도 있고요. 심볼릭 링크 하나와 하드 링크 한 쌍을 둔 폴더에서 직접 실행한 결과입니다.

$ find . -type l
./config/eslintrc.json
$ find . -type f -links +1
./src/util.ts
./config/util.link.ts

직접 해 보니 하드 링크는 원본과 링크가 둘 다 나오더라고요. 하드 링크에는 원본·사본 구분이 없어서 링크 수가 1보다 큰 파일이 모두 걸리기 때문입니다. 이 목록을 경고의 개수와 맞춰 보면 손으로 되돌릴 파일을 좁힐 수 있습니다.

Windows PowerShell에서는 이렇게 찾습니다. 같은 구성(하드 링크 한 쌍)의 폴더에서 돌린 결과예요.

Get-ChildItem -Recurse -File | Where-Object { $_.LinkType -eq 'HardLink' }

.\config\util.link.ts
.\src\util.ts

여기서도 원본과 링크가 둘 다 나왔습니다. 파일 하나에 연결된 이름을 모두 보려면 fsutil hardlink list <파일>을 쓰면 돼요.

심볼릭 링크와 폴더 정션은 Get-ChildItem -Recurse -Force -Attributes ReparsePoint로 찾습니다. 폴더 정션을 하나 만들어 돌려 보니 LinkType이 Junction인 항목으로 잡혔어요.

참고로 Windows는 개발자 모드가 꺼져 있으면 심볼릭 링크를 만들 때 관리자 권한을 요구합니다. 테스트 환경에서도 Administrator privilege required for this operation.으로 막혔으니, Windows 프로젝트에서는 심볼릭 링크보다 하드 링크나 정션 쪽을 먼저 의심하는 게 빠릅니다.

오류 메시지별로 보면

Restored the code, but skipped N files

건너뛰는 조건은 경로가 링크이거나 링크가 됐거나 일반 파일이 아닌 경우, 체크포인트 뒤로 그 폴더가 바뀐 경우, 백업을 안전하게 읽을 수 없는 경우입니다.

위 절의 방법으로 파일을 찾아 Claude에게 그 편집을 되돌려 달라고 하거나 손으로 고치세요. 만든 적 없는 링크라면 체크포인트 뒤에 무언가 그 파일을 바꿨다는 뜻이니 내용부터 살펴봅니다.

v2.1.216 이전에는 /rewind가 링크를 따라가 쓰거나 지웠고 부분 복원도 알리지 않았습니다.

No files were restored: 1 file failed (backup missing, or the file could not be updated)

편집 전 백업이 없거나, Claude Code가 그 파일을 쓰거나 지우지 못한 경우입니다. 오래된 세션이라면 정리 작업이 백업을 이미 지웠을 수 있고, 그러면 다시 해도 같으니 Claude에게 편집을 되돌려 달라고 하거나 git에서 되살립니다.

쓰기가 막힌 경우라면 파일 권한을 먼저 푸세요.

v2.1.260 이전에는 백업 없는 파일을 조용히 건너뛰어 성공한 것처럼 보였습니다.

메뉴에 Restore code가 보이지 않는다

고른 지점 뒤로 기록된 편집이 없는 겁니다. Bash나 백그라운드 서브에이전트가 고친 파일은 애초에 기록되지 않으니, 화면에서 바뀐 것을 봤다고 체크포인트에 있는 것은 아니에요. Bash가 옮기거나 지웠다면 git으로 되돌립니다.

다른 사람들이 겪은 문제

공개 GitHub 이슈의 내용입니다. 보고된 버전은 모두 2.1.278보다 낮습니다.

• SachaMarino(2025-12-15, 이슈 #14002, Claude Code 2.0.69 · macOS): Restore code가 가끔 메뉴에서 빠지고 일부 파일만 복원된다고 보고했습니다. 디버그 로그에 FileHistory: Added snapshot ... tracking 0 files가 남았고, Claude는 편집 도구를 썼다고 적었습니다. 원인은 확정되지 않았습니다.
• hasen6(2025-12-26, 이슈 #15403, Claude Code 2.0.76 · macOS): 대화 되감기만 뜨는데 충분히 과거의 체크포인트는 정상이라고 보고했습니다. closed as not planned로 닫혔고 원인은 확정되지 않았습니다.
• dashesy(2026-04-24, 이슈 #53011, Claude Code 2.1.119 · macOS): 체크포인트를 고른 직후 CLI가 멈추고 Ctrl+C도 듣지 않아 kill -9가 필요했다고 보고했습니다. 자신이 찾은 우회법은 새 세션을 여는 것뿐이었다고 적었습니다.
• EloB(2026-01-09, 이슈 #16976): claude -p 비대화형 실행으로 도는 스크립트에서 체크포인트를 복원할 지원 방법이 없다며 기능을 요청했고, 지금 쓸 수 있는 우회는 git 래퍼, 파일시스템 스냅샷, 세션 재시작뿐이라고 적었습니다. closed as not planned로 닫혔습니다.

앞의 두 건은 “편집이 기록돼 있을 때만 코드 복원이 보인다”는 규칙과 증상이 같습니다. 메뉴가 줄어 보이면 그 구간에 편집 도구로 고친 기록이 있는지부터 보세요.

마치며

되감기는 편리하지만, 어디까지나 Claude의 편집 도구가 남긴 기록만 돌려놓습니다. Bash·서브에이전트·세션 밖 편집은 되감기 밖이고, 링크 파일은 건너뛰고, 스냅샷은 약 30일 뒤 정리돼요. 그러니 오래된 세션이나 파일을 지우고 옮기는 작업이라면 git이 더 믿을 만합니다.

다음에 Claude에게 파일 삭제나 대규모 이동을 시킬 일이 있다면, 그 전에 커밋부터 하나 만들어 두세요. 서브에이전트에 넘긴 일이 왜 되감기 밖인지는 도구를 좁힌 서브에이전트를 정의하는 절차를 이어서 보면 분명해집니다.