핵심 요약
- 체크포인트는 자동입니다: 새 턴을 시작하는 프롬프트마다 먼저 코드의 스냅샷을 찍습니다. 설정할 것이 없습니다 — 되돌리는 법만 알면 됩니다.
- /rewind를 실행하거나(빈 프롬프트에서 Esc 두 번) 복원 지점 메뉴가 뜨고, 각각 코드와 대화 복원, 대화만 복원, 코드만 복원을 고를 수 있습니다.
- rewind는 세션 단위 복구지 버전 관리가 아닙니다: Bash 쪽 부작용(rm, mv, cp), 대부분의 서브에이전트 편집, 직접 한 수동 편집은 잡히지 않습니다. git 커밋은 계속하세요.
- Claude Code는 세션별로 최근 100개의 체크포인트를 약 30일간 유지합니다(cleanupPeriodDays로 조정). 체크포인트는 /resume 후에도 살아 있어서, 어제 세션을 오늘 되돌릴 수 있습니다.
12 Claude Code Features Every Engineer Should Know: Subagents, CLAUDE.md, Checkpoints, MCP, and more
채널: ByteByteAI7:30
Claude Code Checkpoints Are Here (First Look)
채널: Build at Scale8:16
Checkpointing — official documentation
공식 문서: code.claude.com/docs
이 페이지의 모든 복원 옵션, 한계, 보관 수치는 공식 체크포인트 문서와 대조해 검증했습니다. 위의 영상들이 시각·사실 자료입니다.
스크린샷의 권리는 각 제작자에게 있으며, 해당 타임스탬프로 바로 연결됩니다. 얼굴이 나온 장면은 사용하지 않았습니다.
Claude Code 체크포인트로 되돌리기, 단계별로
파트 1 — 무엇이 담기는가
- 1
체크포인트가 뭔지 알기
체크포인트는 새 턴을 시작하는 각 프롬프트 직전에 자동으로 찍힌 코드 상태의 스냅샷입니다. 망한 리팩터링, 과한 편집, 잘못된 방향도 명령 한 번으로 되돌릴 수 있게 존재합니다 — stash도, 커밋도, 격식도 없이.
체크포인트의 매력: 모든 편집 전에 스냅샷, 실험이 옆으로 갔으면 코드와 대화를 언제든 되돌리기.2:15부터 시청 - 2
턴을 시작하는 프롬프트마다 하나씩
체크포인트는 수동으로 만들지 않습니다 — Claude를 움직이게 하는 각 프롬프트가 이제 건드릴 파일의 스냅샷을 찍습니다. 긴 세션은 프롬프트당 하나의 복원 지점 사슬을 쌓고, 저장소의 자동 세이브 상태처럼 됩니다.
편집 루프: Claude가 편집하고, 스냅샷이 체크포인트 사슬에 쌓이고, 다음 프롬프트가 새 주기를 시작한다.2:33부터 시청 - 3
/rewind로 rewind 메뉴 열기
프롬프트에 /rewind를 입력하면 현재 세션의 체크포인트 목록이 나옵니다. 키보드 경로가 더 빠릅니다: 입력 상자가 빈 상태로 Esc를 두 번. (입력에 텍스트가 있으면 double-Esc는 그냥 지울 뿐입니다 — 눌렀던 내용은 ↑로 불러오세요.)
Claude Code 프롬프트에 /rewind 입력 — 체크포인트 목록이 세션 안에서 바로 열립니다.2:40부터 시청 - 4
복원 지점 고르기
메뉴에는 각 체크포인트와 그것을 만든 프롬프트가 함께 나열됩니다 — "...직전 시점으로 코드와/또는 대화 복원". 문제가 생긴 순간으로 이동해 Enter를 누르고, 무엇을 복원할지 고릅니다.
복원 메뉴: 실수 직전의 프롬프트를 고르기 — 빨간색으로 강조된 항목은 이 세션의 이전 질문들입니다.2:45부터 시청
파트 2 — rewind 메뉴
- 5
코드와 대화를 함께 복원하기
풀 rewind입니다: 파일은 스냅샷 상태로 돌아가고 대화도 그 시점으로 분기해 돌아갑니다. 방향 자체가 틀렸을 때 쓰세요 — 코드도, 과제에 대한 Claude의 기억도 모두 리셋됩니다.
- 6
코드만 복원 — 대화는 유지
코드만 복원하면 파일은 되돌아가고 대화는 제자리에 남습니다. "접근은 맞고 결과가 틀린" 경우에 딱입니다: Claude는 논의한 모든 것을 기억한 채로, 망가진 편집만 사라집니다.
- 7
대화만 복원 — 채팅 분기하기
세 번째 옵션은 대화를 이전 시점으로 되돌리고 파일은 그대로 둡니다 — 체크포인트 이전부터 있던 double-Esc의 분기 동작과 같습니다. 코드는 괜찮은데 논의가 샛길로 빠졌을 때 쓰세요.
- 8
되돌리는 대신 여기서 요약하기
메뉴에는 "Summarize from here"와 "Summarize up to here"도 있습니다 — 대화의 한 구간을 초기 지시를 남긴 채 요약으로 압축하는 조준된 /compact입니다. 진짜 분기가 필요하면 /branch나 claude --continue --fork-session을 쓰세요.
파트 3 — 한계와 git 습관
- 9
rewind가 못 되돌리는 것 알기
체크포인트가 추적하는 것은 Claude가 만든 파일 편집이지 전부가 아닙니다: Bash를 통한 변경(rm, mv, cp), 대부분의 서브에이전트 편집, 직접 한 수동 편집, 다른 세션의 변경은 잡히지 않습니다. 심볼릭 링크는 건너뛰어집니다 — 복원이 "Restored the code, but skipped N files"라고 알려 줍니다.
- 10
체크포인트 vs git: 역할 나누기
체크포인트는 빠른 세션 단위 복구용입니다: 이 프롬프트 취소, 그 아이디어 재시도. git은 영구 기록용입니다: 돌아가는 상태를 커밋하고, 브랜치를 만들고, 푸시합니다. 추천 리듬은 탐색하는 동안엔 마음껏 rewind, 남길 가치가 있는 변경은 의도적으로 커밋.
- 11
보관 기간 신경 쓰기
Claude Code는 세션별로 최근 100개의 체크포인트를 유지하고 오래된 스냅샷은 약 30일 뒤 쓸어 냅니다 — 대화 기록을 관리하는 그 cleanupPeriodDays 설정입니다. /rewind와 /resume이 더 과거까지 닿게 하고 싶으면 settings.json에서 늘리세요.
체크포인트 vs git vs /branch vs double-Esc vs /compact
Claude Code에는 돌아가는 방법이 다섯 가지 있습니다 — 각자 푸는 문제가 다릅니다:
- 1체크포인트(/rewind) — 즉각적, 자동, 세션 단위: 코드·대화·둘 다를 임의의 프롬프트 경계까지 취소. 설정 불필요, 영구적이지 않음, 공유되지 않음.
- 2git — 진짜 역사: 남길 가치가 있는 작업에 내가 직접 하는 명시적 커밋. 체크포인트는 이걸 대체하지 않고, 안전 사슬의 그 앞에 앉아 있습니다.
- 3/branch와 --fork-session — 파일을 건드리지 않고 현재 대화에서 평행 타임라인 시작. 대안을 탐색하면서 두 줄을 모두 남기고 싶을 때.
- 4double-Esc — 프롬프트가 비었을 때 같은 rewind 메뉴로 가는 키보드 경로. 텍스트가 있으면 그냥 입력을 지웁니다(기록에는 남아 ↑로 불러올 수 있음).
- 5/compact과 "Summarize from here" — 대화를 이동하는 대신 줄이기: 세부와 맞바꿔 컨텍스트를 되찾되 결정은 남깁니다.
간단한 멘탈 모델: 실수는 rewind, 진전은 git, 대안은 fork, 공간은 summarize.
rewind가 기대와 다르게 작동했나요?
체크포인트에서 흔한 네 가지 깜짝 사고와 대처법:
- 1"No files were restored". 스냅샷이 쓸려 나갔습니다 — 100개 상한을 넘었거나 약 30일 보관 기간이 지났습니다. 더 긴 꼬리를 남기려면 settings.json의 cleanupPeriodDays를 늘리세요.
- 2"Restored the code, but skipped N files". 심볼릭 링크와 하드 링크는 설계상 건너뜁니다. /debug를 실행하고 ~/.claude/debug/<session-id>.txt에서 정확히 건너뛴 경로를 확인한 뒤 그것들만 손으로 되돌리세요.
- 3Bash로 바뀐 파일은 그대로. rm, mv, cp는 스냅샷 시스템 바깥의 셸에서 실행됩니다 — git checkout으로 되돌리거나 백업에서 복구하세요.
- 4원하는 프롬프트가 목록에 없음. 턴 도중에 뒤늦게 들어온 대기열 메시지는 체크포인트를 만들지 않습니다 — 대신 가장 가까운 턴 시작 프롬프트로 rewind하고, 서브에이전트 편집은 git revert가 필요할 수 있습니다.
- 5애초에 /rewind 명령이 없습니다. 체크포인트는 Claude Code 2.0에 들어왔습니다 — claude update(또는 claude doctor)로 버전을 확인하고, 이 기능 이전의 아주 오래된 세션에는 되돌릴 스냅샷이 없다는 점도 유의하세요.
황금률: 변경이 중요하면 커밋하라. 체크포인트는 에어백, git은 안전벨트 — 둘 다 착용하세요.