체크포인트 시스템
Claude Code는 작업 중 파일 변경을 자동으로 추적합니다. 코드가 의도와 다르게 바뀌었을 때 언제든 이전 상태로 되돌릴 수 있는 안전망입니다.
작동 원리
Claude Code가 파일을 수정할 때마다 자동으로 체크포인트가 생성됩니다.
프롬프트 1: "로그인 API 만들어줘"
→ 체크포인트 A 생성 → 코드 수정
프롬프트 2: "에러 핸들링 추가해줘"
→ 체크포인트 B 생성 → 코드 수정
프롬프트 3: "테스트 작성해줘"
→ 체크포인트 C 생성 → 코드 수정
← Esc+Esc 로 B 시점으로 되돌리기 가능
핵심 특성:
- 자동 생성: 사용자 프롬프트마다 체크포인트가 만들어짐
- 세션 간 유지: 세션을
/resume으로 재개해도 체크포인트 접근 가능 - 자동 정리: 30일 후 세션과 함께 삭제 (설정 변경 가능)
되돌리기 (Rewind)
접근 방법
Esc + Esc # 키보드 단축키 (가장 빠름)
/rewind # 슬래시 커맨드
스크롤 가능한 메뉴가 표시되며, 세션의 각 프롬프트 시점을 선택할 수 있습니다.
/clear로 대화를 비운 경우에도 /rewind로 /clear 이전 시점의 대화를 복원할 수 있습니다 (v2.1.191+).
복원 옵션
시점을 선택하면 5가지 옵션이 나타납니다:
| 옵션 | 코드 되돌림 | 대화 되돌림 | 용도 |
|---|---|---|---|
| 코드+대화 복원 | O | O | 완전히 그 시점으로 돌아가기 |
| 대화만 복원 | X | O | 코드는 유지하고 대화만 되돌리기 |
| 코드만 복원 | O | X | 대화는 유지하고 코드만 되돌리기 |
| 여기서 요약 | X | 요약 | 이 시점 이후 대화를 압축 |
| 취소 | X | X | 메뉴로 돌아가기 |
대화를 복원하면 해당 시점의 원래 프롬프트가 입력란에 자동으로 복원됩니다. 수정해서 다시 보내거나 그대로 실행할 수 있습니다.
"여기서 요약" vs 복원
복원은 상태를 되돌립니다 — 코드, 대화 기록, 또는 둘 다를 이전 시점으로 롤백합니다.
여기서 요약은 다르게 동작합니다:
- 선택한 시점 이전 메시지는 그대로 유지
- 선택한 시점 이후 메시지는 AI가 요약으로 대체
- 디스크의 파일은 변경하지 않음
- 원본 메시지는 세션 트랜스크립트에 보존
이것은 /compact의 타겟 버전입니다. 전체 대화를 압축하는 대신, 초반 컨텍스트는 온전히 유지하고 공간을 많이 차지하는 부분만 선택적으로 압축합니다.
/compact → 전체 대화를 압축
Esc+Esc → "여기서 요약" → 선택한 지점 이후만 압축
실전 활용 시나리오
다른 접근법 실험
> OAuth 로그인을 passport.js로 구현해줘
... 결과가 마음에 안 듦 ...
Esc + Esc → 이전 시점으로 되돌리기
> OAuth 로그인을 직접 구현해줘 (passport.js 없이)
실수 복구
> 이 모듈 전체 리팩토링해줘
... 리팩토링 결과가 기존 테스트를 깨뜨림 ...
Esc + Esc → "코드+대화 복원" → 리팩토링 전으로 돌아감
> 테스트를 깨뜨리지 않는 범위에서만 리팩토링해줘
디버깅 세션 정리
> 결제 실패 버그 수정해줘
... 30분간 디버깅, 많은 시행착오 ...
Esc + Esc → 디버깅 시작점에서 "여기서 요약"
→ 시행착오 내용이 요약으로 압축, 컨텍스트 여유 확보
기능 반복 개선
> 검색 기능 v1 만들어줘 → 체크포인트 A
> 필터링 추가해줘 → 체크포인트 B
> 자동완성 추가해줘 → 체크포인트 C (버그 발생)
Esc + Esc → B 시점으로 "코드만 복원"
→ 대화 기록은 유지하되 코드만 B 상태로
> 자동완성을 다른 방식으로 구현해줘
제한사항
Bash 명령으로 인한 변경은 추적 불가
체크포인트는 Claude의 파일 편집 도구를 통한 변경만 추적합니다. Bash 명령으로 수행된 파일 조작은 되돌릴 수 없습니다:
# 이런 변경은 체크포인트로 되돌릴 수 없음
rm file.txt
mv old.txt new.txt
cp source.txt dest.txt
외부 변경은 추적 불가
현재 세션 내에서 Claude가 편집한 파일만 추적됩니다. 다른 에디터에서 직접 수정한 내용이나 다른 Claude Code 세션의 변경은 포함되지 않습니다.
Git을 대체하지 않음
체크포인트는 세션 수준의 빠른 되돌리기용입니다. 영구적인 버전 관리에는 Git을 사용하세요.
| 체크포인트 | Git | |
|---|---|---|
| 용도 | 세션 내 빠른 되돌리기 | 영구적인 버전 히스토리 |
| 범위 | 현재 세션 | 전체 프로젝트 히스토리 |
| 유지 기간 | 30일 | 영구 |
| 비유 | "로컬 Undo" | "영구 히스토리" |
체크포인트와 별개로, 큰 작업을 시작하기 전에 git commit으로 스냅샷을 남기는 습관을 유지하세요. 체크포인트가 커버하지 못하는 Bash 명령 변경까지 안전하게 복구할 수 있습니다.
이 챕터를 완료하셨나요?
학습 진도를 체크하여 나의 로드맵 달성률을 높여보세요.