Claude Code Checkpoints로 잘못된 작업 되돌리기

Claude Code로 단계가 많거나 시간이 오래 걸리는 작업을 진행하다 보면 중간에 Claude가 잘못된 방향으로 일하는 상황을 마주하게 됩니다. 여러 파일에 걸친 리팩토링 도중 의도와 다른 방향으로 변경하거나, 수정한 코드가 다른 부분을 깨뜨리는 상황이 그 예죠. 작업이 복잡해질수록 Claude가 잘못 판단할 수 있고, 세션이 길어질수록 초반에 전달한 지시 사항이 희미해지기 때문입니다.

문제를 실시간으로 확인했다면 즉시 중단하면 되긴 합니다. 그러나 여러 파일이 동시에 수정됐거나, 테스트를 돌리거나 관련 파일을 열어봤을 때 비로소 문제를 발견할 때는 상황이 다르죠. Claude가 여러 단계를 거치며 연쇄적으로 파일을 수정한 상태에서는 특정 프롬프트 시점의 파일 상태로 한 번에 복원하기 어렵습니다. 에디터의 Undo만으로는 Claude가 한 번에 바꾼 여러 파일을 한꺼번에 되돌릴 수 없고요. git reset은 미리 커밋해둔 지점으로만 돌아갈 수 있기 때문이죠.

Claude Code에서는 Checkpoints 기능으로 이 문제를 해결할 수 있습니다. Checkpoints는 사용자가 새 프롬프트를 입력할 때마다 해당 작업이 시작되기 전의 파일 상태와 그때까지 대화 내용을 함께 기록으로 남깁니다. 이 기록을 바탕으로 /rewind 명령을 실행하거나 Esc 키를 두 번 입력하면, rewind 메뉴가 열리는데요. 메뉴에서 파일과 대화를 함께 되돌리거나, 둘 중 하나만 되돌리는 등 복원 범위를 선택해 원하는 시점의 작업 상태로 돌아갈 수 있습니다.

이 글에서는 Checkpoints의 동작 방식을 정리하고, 두 가지 축에 따라 사용법을 실습하겠습니다. 또 Checkpoints를 효과적으로 활용하는 방법도 소개하겠습니다.

Checkpoints 개요

Checkpoints가 무엇이고, 어떤 방식으로 동작하는지 살펴보겠습니다.

개념

Checkpoints는 Claude Code가 파일을 편집하기 전 코드 상태와 대화 내용을 함께 저장하는 자동 스냅샷 시스템입니다. 사용자가 프롬프트를 입력할 때마다 새 체크포인트가 생성되고, 이후 /rewind 명령을 실행하거나 Esc 키를 두 번 누르면, 저장된 기록에 따라 파일과 대화를 이전 시점으로 되돌릴 수 있습니다.

체크포인트는 세션이 종료돼도 일정 기간 보존됩니다. claude --continue로 세션을 이어받거나, claude --resume으로 과거 세션을 재개해도 이전 체크포인트에 접근할 수 있죠. 보관 기간은 기본 30일이며, settings.json의 cleanupPeriodDays로 조정할 수 있습니다. 장기 보관이 필요하면, 365와 같이 큰 숫자를 명시하는 게 좋습니다.

참고로 Checkpoints는 Claude의 공식 편집 도구(Write, Edit, NotebookEdit)로 수행한 변경만 추적합니다. Bash 명령으로 수정한 파일(rm, mv, cp, sed -i 등), 사용자가 에디터로 직접 수정한 변경은 추적하지 않습니다. 이런 변경이 섞인 상태에서 /rewind를 실행하면 추적된 파일만 되돌아가고 나머지는 그대로 남기에 주의해야 합니다.

파일 변경 방식에 따른 Checkpoints 추적 여부

동작 방식

Claude Code에서 작업 진행 도중 /rewind를 실행하거나 Esc 키를 두 번 누르면, rewind 메뉴가 열리고 이전에 입력한 프롬프트 목록이 표시됩니다. 이중 되돌릴 시점에 해당하는 프롬프트를 선택하고, 다음 5가지 동작 중 1가지 동작을 고를 수 있습니다.

앞의 세 가지 동작은 코드와 대화를 함께 되돌리거나, 둘 중 하나만 되돌립니다. 그러나 Summarize from here는 코드를 건드리지 않고, 선택한 프롬프트 이후의 대화를 요약해 컨텍스트 윈도우를 확보하죠. /compact가 전체 대화를 압축한다면, Summarize from here는 초기 맥락은 보존하고 중간 이후 맥락만 압축하는 게 특징입니다. 마지막 Never mind는 아무 동작 없이 메뉴를 닫는 취소 선택지입니다.

Checkpoints 활용 실습

지금까지 Checkpoints의 개념과 동작 방식을 살펴봤습니다. 이제 두 가지 실습으로 실제 사용 흐름을 확인하겠습니다.

• 실습 1: 같은 실패 상황에 네 가지 복원 모드를 차례로 적용해 차이를 확인합니다.
• 실습 2: Tasks로 분할한 작업 중간에 /rewind를 적용해 Tasks 상태와의 관계를 확인합니다.

실습 환경은 Claude Code v2.0 이상, Python 3.10 이상, Git 설치 완료 기준입니다.

실습 1. 코드·대화 복원: 같은 상황, 4가지 선택지

상황

/rewind는 단순한 '되돌리기'가 아니며, 5가지 옵션을 제공합니다. 이 중 취소 옵션(Never mind)을 제외한 네 가지 복원 모드를 같은 실패 상황에서 차례대로 적용해 차이를 살펴봅니다.

사전 준비

1. 실습용 디렉터리를 만들고 초기 파일을 작성합니다.

   bash

   mkdir ~/claude-checkpoint-a && cd ~/claude-checkpoint-a
   

2. calc.py 파일을 생성합니다.

   bash

   cat > calc.py << 'EOF'
   def add(a, b):
       return a + b
   
   def divide(a, b):
       return a / b
   
   def multiply(a, b):
       return a * b
   EOF
   

3. 파일 내용을 확인합니다.

   bash

   cat calc.py
   

   세 함수가 화면에 보이면 준비 완료입니다.

단계

준비: async 실패 상황 만들기

1. 같은 디렉터리에서 Claude Code 세션을 시작합니다.

2. Claude에게 타입 힌트 추가를 지시합니다.

   markdown

   calc.py의 세 함수에 Python 타입 힌트를 추가해줘.
   

   Claude가 Edit 도구로 calc.py를 수정합니다.

   Claude가 타입 힌트를 추가한 화면

3. 이어서 의도적으로 잘못된 방향을 유도합니다.

   markdown

   이 함수들을 async로 리팩토링해줘.
   

   Claude가 async def로 함수를 바꿉니다.

   Claude가 async로 리팩토링한 화면

4. Esc 키를 두 번 눌러 rewind 메뉴를 엽니다.

   이전에 입력한 프롬프트 목록과 각 프롬프트가 만든 변경 요약(+추가 줄 -삭제 줄)이 함께 표시됩니다.

   Esc 두 번으로 열린 rewind 메뉴와 프롬프트별 변경 요약

5. "이 함수들을 async로 리팩토링해줘" 프롬프트를 선택합니다.

   async 프롬프트를 선택하면 async 작업 직전 상태(타입 힌트까지만 추가된 상태)로 돌아갈 수 있는 5가지 옵션이 나타납니다.

   5가지 옵션이 표시된 화면

   이제 네 가지 모드를 차례로 적용해 차이를 살펴보겠습니다. 각 모드를 적용한 후에는 cat calc.py로 파일 상태를 확인하고, Claude Code 세션에서 대화 내용과 입력창 상태도 함께 관찰합니다.

모드 1: Restore code and conversation

코드와 대화를 모두 async 작업 직전 시점으로 되돌립니다.

• calc.py: 타입 힌트 상태로 복원 (async 제거)
• 대화: 선택 시점 이전 대화만 남음
• 입력창: "이 함수들을 async로 리팩토링해줘" 프롬프트가 자동으로 채워짐

입력창에 프롬프트가 자동으로 채워지는 건 재시도를 지원하는 UX입니다. Enter로 재전송하거나, 프롬프트를 수정해 다른 방향으로 진행할 수 있습니다.

Restore code and conversation 적용 후 화면

cat calc.py 결과

모드 2: Restore code

다음 모드로 넘어가기 위해, 입력창의 async 프롬프트를 그대로 Enter로 전송해 async 상태를 재현합니다. 이후 Esc 두 번 → 최근 async 프롬프트 선택 → Restore code를 선택합니다.

• calc.py: 타입 힌트 상태로 복원 (async 제거)
• 대화: 현재 상태 유지
• 입력창: 비어 있음

코드는 되돌렸지만 대화 맥락은 유지됩니다. Claude에게 "방금 한 async 방향 말고 다른 방법으로 해줘"와 같은 후속 지시를 이어갈 수 있습니다.

Restore code 적용 후 화면

모드 3: Restore conversation

입력창이 비어 있으니 async 프롬프트를 직접 입력해 async 상태를 재현합니다. 이후 Esc 두 번 → 최근 async 프롬프트 선택 → Restore conversation을 선택합니다.

• calc.py: async 상태 유지
• 대화: 선택 시점 이전 대화만 남음
• 입력창: async 프롬프트 자동 채움

파일은 async 상태 그대로인데 대화 맥락에는 async 작업 흔적이 없는 상태가 됩니다. 파일과 대화의 불일치를 의도적으로 만드는 모드입니다.

Restore conversation 적용 후 화면

모드 4: Summarize from here

입력창의 async 프롬프트를 그대로 Enter로 전송해 대화 맥락을 다시 쌓습니다. Esc 두 번 → 최근 async 프롬프트 선택 → Summarize from here를 선택합니다.

• calc.py: async 상태 유지
• 대화: 선택 시점 이후 대화가 Summarized conversation 요약 블록으로 대체됨
• 입력창: async 프롬프트 자동 채움

앞의 세 모드와 달리 이 모드는 ‘되돌리기’가 아니라 대화 압축입니다. 선택 시점 이전 대화는 그대로 남고, 이후 대화만 요약으로 대체돼 컨텍스트 윈도우를 확보합니다.

Summarize from here 적용 후 화면

동작 확인

네 가지 모드 적용 결과를 정리하면 다음과 같습니다.

실습 2. Tasks로 나눈 작업 rewind

상황

Claude Code의 Tasks는 작업을 태스크 단위로 분할해 디스크 기반으로 상태를 관리합니다. 그렇다면 Tasks로 분할한 작업 중간에 /rewind를 적용하면 어떻게 될까요? Checkpoints의 공식 문서는 파일과 대화의 복원 동작만 설명하며, Tasks 상태와의 관계는 다루지 않습니다. 실습으로 직접 확인하겠습니다.

사전 준비

실습용 디렉터리를 만들고 Tasks ID를 지정해 Claude Code를 시작합니다.

mkdir ~/claude-checkpoint-d && cd ~/claude-checkpoint-d
CLAUDE_CODE_TASK_LIST_ID=checkpoint-demo claude

단계

1. Claude에게 Tasks 분할을 요청합니다.

   markdown

   숫자 리스트의 통계를 계산하는 CLI 스크립트를 Python으로 만들어줘. 태스크를 다음 4개로 분할하고 의존성도 설정해 줘. 1) 입력 파싱 함수, 2) 통계 계산 함수(평균·중앙값·표준편차), 3) CLI 인터페이스, 4) 단위 테스트. 의존성은 2→3, 1→3, 1→2, 1→4, 2→4로 설정해 줘.
   

   Claude가 TaskCreate 도구로 4개 태스크를 생성하고 의존성 트리를 보여줍니다.

   Tasks로 분할된 4개 태스크와 의존성 트리

2. 태스크 1 실행을 지시합니다.

   markdown

   1번 태스크부터 시작해 줘.
   

   Claude가 stats_cli/parser.py를 생성합니다. 완료되면 태스크 1 상태가 completed로 바뀝니다.

3. 태스크 2로 넘어가면서 과도한 방향을 유도합니다.

   markdown

   계속 진행해 줘. 통계 함수는 numpy, scipy, pandas까지 모두 의존성으로 넣어서 구현해 줘.
   

   평균·중앙값·표준편차는 Python 표준 라이브러리 statistics 모듈로 충분한 작업입니다. 이번 실습처럼 단순한 통계 계산에서 세 라이브러리를 모두 얹는 건 과도한 의존성입니다. Claude가 이 방향을 탐지하고 되물을 수 있습니다. 이 실습에서는 그대로 진행을 지시합니다.

   markdown

   세 개 모두 써서 그대로 진행해 줘.
   

   Claude가 stats_cli/stats.py를 생성합니다. numpy로 평균, pandas로 중앙값, scipy로 표준편차를 계산하는 구조입니다. 완료되면 태스크 2 상태가 completed로 바뀝니다.

4. 과도한 의존성 구현을 되돌리기 위해 Esc를 두 번 누릅니다.

   rewind 메뉴에서 "세 개 모두 써서 그대로 진행해 줘" 프롬프트를 선택하고 Restore code and conversation을 선택합니다.

동작 확인

rewind 적용 후 세 가지를 확인합니다.

1. 파일 상태

   새 터미널에서 다음과 같이 확인합니다.

   bash

   cd ~/claude-checkpoint-d
   ls stats_cli/
   

   parser.py는 남아 있고, stats.py는 삭제됐습니다. Claude의 공식 편집 도구로 만든 파일은 선택한 프롬프트가 실행되기 직전 시점에 맞춰 복원됩니다.

2. 대화창 상태

   Claude Code 세션 화면에서 "세 개 모두 써서 그대로 진행해 줘" 프롬프트와 그 이후 태스크 2 구현 응답이 제거됩니다. 입력창에는 해당 프롬프트가 자동으로 채워집니다.

   rewind 적용 후 Claude Code 화면

3. 태스크 상태

   Claude Code 세션에서 Ctrl + T를 누릅니다.

   markdown

   4 tasks (2 done, 2 open)
   ✔ 입력 파싱 함수 구현
   ✔ 통계 계산 함수 구현
   ◻ CLI 인터페이스 구현
   ◻ 단위 테스트 작성
   

   태스크 2가 completed 상태로 그대로 남아 있습니다. 파일(stats.py)은 삭제됐지만 태스크 2는 완료로 인식됩니다.

   디스크의 태스크 파일을 직접 확인합니다.

   bash

   cat ~/.claude/tasks/checkpoint-demo/2.json
   

   태스크 2 JSON 파일의 status가 completed로 남아 있는 모습

   태스크 2의 상태가 JSON 파일로 ~/.claude/tasks/ 경로에 저장돼 있고, "status": "completed"가 유지돼 있습니다. Tasks의 상태 관리는 파일과 대화의 복원 범위 밖에 별도 저장소로 존재합니다.

Checkpoints는 파일과 대화만 추적합니다. Tasks 상태는 ~/.claude/tasks/ 경로에 별도로 저장돼 rewind 영향을 받지 않습니다. 그 결과, 파일은 태스크 2를 수행하기 이전 상태로 돌아갔는데 태스크 2의 상태는 completed로 남아 있는 불일치가 발생합니다.

Checkpoints 잘 쓰는 법

Checkpoints를 효과적으로 활용하기 위한 두 가지 원칙을 살펴보겠습니다.

1. 상황별로 적합한 옵션 선택

다음 상황에 따라 Checkpoints의 복원 옵션을 선택할 수 있습니다.

• 코드와 대화가 모두 잘못된 방향일 때 → Restore code and conversation

  방향 자체를 초기화합니다. 입력창에 채워지는 프롬프트를 수정해 다른 접근으로 다시 시도할 수 있습니다.

• 코드만 잘못됐고 대화 맥락은 유지하고 싶을 때 → Restore code

  Claude의 이해나 설명이 유용했다면 대화는 남겨둡니다. "방금 한 방향 말고 다른 방법으로 해 줘"와 같은 후속 지시를 바로 이어갈 수 있습니다.

• 대화만 잘못됐고 코드는 원하는 상태일 때 → Restore conversation

  파일은 그대로 두고 대화 맥락만 이전으로 돌립니다. 대화에 불필요한 시도가 쌓였을 때 유용합니다.

• 문제가 아니라 컨텍스트를 확보하고 싶을 때 → Summarize from here

  코드는 건드리지 않고 선택 시점 이후 대화만 요약으로 압축합니다. 긴 디버깅 세션에서 초기 지시는 유지하고 중간 맥락만 정리할 때 씁니다.

2. 돌이킬 수 없는 작업 전에는 Git 커밋

데이터베이스(DB) 마이그레이션, 대량 파일 이동, rm -rf 같은 위험한 Bash 작업 전에는 Git 커밋을 먼저 남기세요. Checkpoints는 공식 편집 도구(Write, Edit, NotebookEdit) 변경만 추적하는데요. Bash로 일어난 변경이나 DB 상태 변경은 rewind로 되돌릴 수 없습니다. 같은 이유로 Tasks 상태(~/.claude/tasks/ 저장소)도 추적 범위 밖입니다. Git 커밋은 이런 모든 추적 범위 밖 상태까지 포함해 복구 경로를 만들 수 있습니다.

맺음말

지금까지 Checkpoints의 개념과 동작 방식, 활용법을 살펴봤습니다. 이 글의 요점은 다음과 같은데요.

1. Checkpoints는 사용자가 프롬프트를 입력할 때마다 파일 상태와 대화 내용을 함께 저장하는 자동 스냅샷 시스템입니다. /rewind 명령을 실행하거나 Esc 키를 두 번 눌러 이전 시점으로 되돌아가도록 작업할 수 있습니다.
2. rewind 메뉴는 5가지 옵션을 제공합니다. 코드와 대화를 함께 되돌리거나, 둘 중 하나만 되돌리거나, 선택 시점 이후 대화를 요약으로 압축하는 게 그 예입니다.
3. Tasks로 분할한 작업 중간에 rewind를 적용하면, 파일과 대화는 되돌아가지만 태스크 상태는 completed로 유지됩니다. Tasks 상태가 Checkpoints의 추적 범위 밖이기 때문입니다.
4. Checkpoints는 공식 편집 도구(Write, Edit, NotebookEdit) 변경만 추적합니다. Bash 명령이나 DB 상태 변경은 rewind로 되돌릴 수 없으니, 위험한 작업 전에는 Git 커밋을 먼저 남기세요.

참고 자료

1. "Checkpointing", Anthropic, https://docs.claude.com/en/docs/claude-code/checkpointing
2. "Rewind file changes with checkpointing", Anthropic, https://code.claude.com/docs/en/agent-sdk/file-checkpointing
3. "Claude Code settings", Anthropic, https://code.claude.com/docs/en/settings
4. "Enabling Claude Code to work more autonomously", Anthropic, 2025-09-29, https://www.anthropic.com/news/enabling-claude-code-to-work-more-autonomously
5. Fabbro(박용석), "Claude Code Tasks로 복잡한 프로젝트 효율적으로 진행하기", 인포그랩, 2026-02-25, https://insight.infograb.net/blog/2026/02/25/claude-tasks/

우리 회사에 딱 맞는 DevSecOps 관행과 프레임워크를 찾고 계시나요? DevOps 전문가, 인포그랩과 상담하세요!