이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.
저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다.
Claude Code로 코드를 수정하다가 "아, 원래대로 되돌리고 싶다"는 생각이 들 때가 있다. 체크포인팅은 이런 순간을 위한 자동 안전망이다. 매번 메시지를 보낼 때마다 코드 상태를 스냅샷으로 저장해서, 언제든 이전 상태로 돌아갈 수 있다.
체크포인트(Checkpoint)란? 사용자가 메시지를 보낼 때마다 자동으로 생성되는 코드 상태 스냅샷이다. Git 커밋과 비슷하지만, 세션 수준에서 작동하며 빠른 복구를 위해 설계되었다.
체크포인팅이 유용한 경우
Claude가 코드를 수정했는데 결과가 마음에 들지 않을 때
여러 가지 접근 방법을 실험해보고 싶을 때
실수로 중요한 코드가 변경되었을 때
Git 커밋 전에 다양한 시도를 해보고 싶을 때
시작하기
체크포인팅은 자동이다
별도 설정이나 명령어 없이, Claude Code를 사용하는 것만으로 체크포인트가 자동 생성된다. 알아야 할 건 "되감기" 방법 하나뿐이다.
처음 써보기 - 3단계
Step 1: 평소처럼 Claude Code 사용
> 이 함수에 에러 처리를 추가해줘
Claude가 코드를 수정한다. 이때 자동으로 체크포인트가 생성된다.
Step 2: 결과가 마음에 안 들면?
Esc 키를 두 번 누른다 (Esc + Esc)
되감기 메뉴가 나타난다. ex)
Step 3: 원하는 시점 선택
체크포인트 목록에서 돌아가고 싶은 시점을 선택하고, "코드만 되감기"를 선택한다. 끝! 코드가 이전 상태로 돌아간다.
한 문장 요약
체크포인팅 = "Ctrl+Z의 강화판". 메시지 단위로 자동 저장되고, Esc Esc로 되돌린다.
체크포인팅 vs Git - 언제 무엇을 쓸까?
혼동하지 말자
체크포인팅은 Git을 대체하는 것이 아니라 보완하는 기능이다. 둘의 용도가 다르니, 상황에 맞게 사용하자.
체크포인팅
Git
비유
"Ctrl+Z" (실행 취소)
"저장" + "히스토리"
범위
세션 수준 (현재 대화)
프로젝트 수준 (전체 히스토리)
보존 기간
30일 (설정 가능)
영구
생성 방식
자동 (메시지마다)
수동 (커밋)
용도
빠른 실험, 즉시 복구
협업, 배포, 장기 관리
실제 작업 흐름 예시
Claude에게 코드 수정 요청
결과가 마음에 안 들면 → 체크포인트로 되감기
다른 방법으로 다시 시도
결과가 만족스러우면 → Git 커밋
자동 체크포인트 - 따로 할 게 없다
팁
체크포인트는 자동으로 생성된다. 별도로 저장하거나 명령어를 실행할 필요가 없다. 그냥 평소처럼 Claude Code를 사용하면 된다!
체크포인트가 생성되는 시점
메시지 전송 시
사용자가 Enter를 눌러 메시지를 보낼 때마다 자동으로 체크포인트가 생성된다.
세션 간 유지
대화를 종료했다가 다시 시작해도 이전 체크포인트에 접근할 수 있다. claude --resume으로 세션을 재개하면 된다.
자동 정리
오래된 체크포인트는 30일 후 자동으로 삭제된다. (세션 보존 기간과 동일하게 설정 가능)
되감기 (Rewind) - 이전 상태로 돌아가기
언제 되감기를 사용할까?
Claude가 코드를 수정했는데 예상과 다를 때
실험해본 변경사항을 취소하고 싶을 때
대화가 잘못된 방향으로 갔을 때
되감기 시작하는 방법
방법 1: 키보드 단축키 (가장 빠른 방법)
Esc 를 두 번 누른다 (Esc + Esc)
방법 2: 슬래시 명령어 (명시적인 방법)
입력창에 /rewind 입력
되감기 옵션 선택하기
되감기를 시작하면 체크포인트 목록이 나타나고, 원하는 시점을 선택한 후 복원 옵션을 고를 수 있다.
세 가지 복원 옵션 ex)
옵션 1: 대화만 되감기
코드 변경은 유지하면서 대화 내용만 이전 시점으로 돌아간다.
이럴 때 사용: 코드 수정 결과는 좋은데, 대화 맥락을 다시 잡고 싶을 때
옵션 2: 코드만 되감기
대화 내용은 유지하면서 파일 변경사항만 이전으로 되돌린다.
이럴 때 사용: Claude의 설명은 유지하면서 다른 구현 방법을 시도하고 싶을 때
옵션 3: 코드와 대화 모두 되감기
선택한 시점으로 완전히 되돌린다. 코드와 대화 모두 이전 상태로.
이럴 때 사용: 완전히 처음부터 다시 시작하고 싶을 때
실전 팁: "코드만 되감기"가 가장 유용하다
Claude가 좋은 설명을 했는데 구현이 마음에 들지 않을 때, "코드만 되감기"를 선택하면 대화 컨텍스트(Claude가 이해한 내용)를 유지하면서 다른 접근법을 시도할 수 있다.
예: "좋은 설명이야, 하지만 다른 방법으로 구현해줘"라고 바로 이어서 요청 가능.
실전 시나리오 - 이럴 때 체크포인팅을 쓰자
구체적인 예시로 이해하기
실제로 체크포인팅이 어떻게 작동하는지 코드와 함께 살펴보자.
1. 원래 코드
def calculate_total(items):
total = 0
for item in items:
total += item['price']
return total
2. Claude에게 요청
"이 함수에 할인 적용 기능을 추가해줘"
이 시점에 체크포인트가 자동 생성된다
3. Claude의 수정 결과 (마음에 안 듦)
def calculate_total(items, discount_rate=0):
# 너무 복잡하게 바뀌었다...
subtotal = sum([i['price'] for i in items])
discount = subtotal * discount_rate
return subtotal - discount
"원래 for 루프 방식을 유지하고 싶은데..."
4. 되감기
Esc Esc 누르고, "코드만 되감기" 선택
코드가 원래대로 돌아간다
5. 다시 요청
"for 루프 방식을 유지하면서 할인 기능만 추가해줘"
def calculate_total(items, discount_rate=0):
total = 0
for item in items:
total += item['price']
return total * (1 - discount_rate) # 깔끔!
시나리오 1: 여러 가지 접근법 비교하기
상황:
"이 함수를 최적화해줘"라고 요청했는데, 여러 방법 중 어떤 게 나은지 비교해보고 싶다.
해결:
첫 번째 최적화 방법 적용
결과 확인 후 → Esc Esc로 되감기
"다른 방법으로 최적화해줘"
두 번째 방법 확인
마음에 드는 버전으로 최종 선택
시나리오 2: 실수 복구하기
상황:
Claude가 코드를 수정했는데 기존에 잘 되던 기능이 깨졌다.
해결:
Esc Esc로 되감기 메뉴 열기
문제가 발생하기 전 체크포인트 선택
"코드만 되감기" 선택
다른 방법으로 수정 요청
시나리오 3: 안전한 실험하기
상황:
대규모 리팩토링을 해보고 싶은데, 잘 안 되면 원래대로 돌아가고 싶다.
해결:
현재 상태가 자동으로 체크포인트됨 (걱정 없이 시작)
"이 모듈을 완전히 리팩토링해줘"
결과가 마음에 들면 → Git 커밋
결과가 마음에 안 들면 → 되감기 후 다시 시도
제한사항 - 알아두어야 할 것들
중요: 이런 변경은 추적되지 않는다
체크포인팅은 Claude의 파일 편집 도구로 수행된 변경만 추적한다. 아래 경우는 되감기로 복구할 수 없다.
추적되지 않는 변경 1: Bash 명령어로 수정된 파일
Claude가 bash 명령어를 사용해서 파일을 변경한 경우, 체크포인팅에 포함되지 않는다.
# 이런 명령어로 인한 변경은 추적되지 않음
rm file.txt # 파일 삭제
mv old.txt new.txt # 파일 이동/이름 변경
cp source.txt dest.txt # 파일 복사
sed -i 's/old/new/g' file.txt # 파일 내용 수정
왜 그럴까?
체크포인팅은 Claude의 내장 편집 도구(Edit, Write 등)와 연동된다. Bash 명령어는 시스템 레벨에서 실행되므로 추적 범위 밖이다.
추적되지 않는 변경 2: Claude Code 외부에서의 수정
추적 안 됨
설명
수동 편집
VS Code, Vim 등 다른 에디터에서 직접 수정한 내용
다른 세션
다른 터미널에서 실행 중인 Claude Code 세션의 편집
예외
현재 세션에서 Claude가 편집한 파일과 같은 파일을 외부에서 수정한 경우에만 부분적으로 캡처됨
결론: 안전한 작업 습관
체크포인팅을 최대한 활용하려면:
파일 수정은 가능하면 Claude의 편집 기능을 통해 하자
중요한 변경 전에는 Git 커밋을 해두자
체크포인팅은 "빠른 실험"용, Git은 "영구 저장"용으로 사용하자
자주 묻는 질문 (FAQ)
Q: 체크포인트를 직접 만들 수 있나요?
A: 아니요, 체크포인트는 자동으로만 생성된다. 메시지를 보낼 때마다 자동 생성되므로, "지금 상태를 저장하고 싶다"면 간단한 메시지(예: "현재 상태 확인")를 보내면 된다.
Q: 체크포인트가 디스크 공간을 많이 차지하나요?
A: 체크포인트는 변경된 부분만 저장하므로 일반적으로 크지 않다. 30일 후 자동으로 정리되며, 이 기간은 세션 보존 설정과 연동된다.
Q: 세션을 종료해도 체크포인트가 유지되나요?
A: 네! claude --resume으로 이전 세션을 재개하면 해당 세션의 체크포인트에 접근할 수 있다.
Q: 되감기 후에 다시 앞으로 갈 수 있나요?
A: 아니요, 되감기는 "되돌리기"만 가능하다. 되감기 후 새로운 작업을 하면 새로운 체크포인트가 생성된다. 필요하다면 되감기 전에 현재 상태를 Git으로 커밋해두자.
