Claude Code에서 에이전트에게 여러 파일의 변경을 맡겼는데, "아, 이 변경은 역시 아니었어"라고 느낀 경험이 있는 분들을 위한 기사입니다.

• 예상 독자: Claude Code를 일상적으로 사용하며, 규모가 큰 리팩터링(Refactoring)이나 여러 파일에 걸친 변경을 에이전트에게 맡겨본 적이 있는 사람

• 전제 환경: 2026년 7월 시점의 Claude Code CLI(checkpoint/rewind 기능 탑재 버전), macOS/Linux 모두에서 확인 완료

• checkpoint 기능은 비교적 최신 기능이므로, 구버전에서는 /rewind나 Esc Esc 조작이 작동하지 않을 수 있습니다. claude --version으로 확인해 두면 안심할 수 있습니다.

• Claude Code에는 "Esc Esc" 또는 /rewind를 통해 세션 내의 과거 체크포인트(checkpoint)까지 코드를 되돌릴 수 있는 기능이 있습니다.

• 단, 되돌아가는 것은 파일 내용뿐입니다. Bash에서 실행한 명령의 부작용(패키지 설치, 컨테이너 실행, git commit 등)은 전혀 되돌아가지 않습니다.

• 되돌리기는 턴(turn) 단위의 통째로 찍은 스냅샷(snapshot)이므로, 좋은 변경과 나쁜 변경이 같은 턴에 섞여 있으면 둘 다 사라집니다.

적당한 git 리포지토리(repository)에서 재현할 수 있습니다.

mkdir rewind-demo && cd rewind-demo
git init -q
echo "# rewind demo" > README.md
...

세션 내에서 여러 턴에 걸쳐 지시를 내립니다.

• 1턴째: "utils.py에 add(a, b) 함수를 추가해줘" → 파일 생성
• 2턴째: "requests 라이브러리를 사용하도록 하고, pip install requests도 실행해줘" → Bash에서 설치가 실행됨
• 3턴째: "add 함수에 버그를 심어버렸다(의도치 않게 a - b가 되었다)」는 가정하에 확인

여기서 Esc를 두 번 누르면 체크포인트 목록이 나옵(/rewind로도 동일한 메뉴가 열립니다).

❯ Esc Esc
Rewind to a checkpoint
> 3. utils.py に add() を追加(直前)
...

두 번째 체크포인트를 선택해 되돌리면, utils.py의 내용은 "requests 도입 직후" 상태로 돌아갑니다. 여기서 git status와 pip list를 비교해 봅니다.

git status # utils.py의 변경은 되돌아와 있음
pip show requests # → 사라지지 않고, 설치된 상태 그대로 남아 있음

파일 내용은 되돌아갔지만, pip install로 설치한 패키지 실체는 그대로 남아 있습니다. 이것이 이 기능의 가장 큰 특징(특이점)입니다.

pip install / npm install / docker run / git commit 등 Bash를 통해 실행한 조작의 결과는 rewind 대상이 아닙니다. checkpoint는 에이전트의 Edit/Write 조작에 의한 파일 스냅샷을 관리할 뿐, 셸(shell)의 상태나 외부 프로세스의 상태까지는 추적하지 않습니다.

• git commit을 한 경우, 커밋 자체는 사라지지 않습니다(HEAD는 rewind의 영향을 받지 않습니다). rewind 후에 다른 변경을 쌓으면, 지웠어야 할 변경이 커밋 히스토리(history) 상에는 남아 있는 뒤틀림이 발생합니다.
• DB 마이그레이션(Migration)을 실행한 경우도 마찬가지로, rewind해도 스키마(schema)는 돌아오지 않습니다.

회피책: 패키지 설치, 마이그레이션, 외부 API 호출과 같이 "취소할 수 없는" Bash 조작을 에이전트에게 맡기기 전에는, 한 템포 쉬고 정말 필요한지 확인합니다. 꼭 필요하다면 먼저 git commit을 해두고, rewind가 아니라 git revert를 기반으로 되돌릴 수 있도록 하는 편이 안전합니다.

1턴에서 파일 A의 좋은 변경과 파일 B의 버그 유입이 동시에 일어난 경우, rewind를 하면 A의 좋은 변경도 함께 사라집니다. checkpoint는 파일 단위가 아니라, 그 턴 시점의 전체 스냅샷을 저장·복원하는 구조이기 때문입니다.

회피책: 리스크가 높은 변경(기존 로직의 재작성 등)과 안전한 변경(문서 추가 등)은 의식적으로 턴을 나누어 의뢰합니다. 1턴 1태스크(task)를 유념하면 rewind의 입도(granularity)가 실용적이 됩니다.

Claude Code의 외부(사용자의 에디터)에서 사람이 수동으로 편집한 파일은 checkpoint의 스냅샷 (snapshot) 관리 대상에서 제외됩니다. 그대로 rewind를 실행하면, 의도치 않게 수동 편집분이 오래된 상태로 되돌아가 사라질 수 있습니다.

회피책: rewind를 사용하기 전에 git status를 통해 추적되지 않거나 (untracked) 커밋되지 않은 (uncommitted) 수동 변경 사항이 있는지 반드시 확인하십시오. 변경 사항이 있다면 먼저 커밋(commit)하거나 스태시(stash)한 뒤에 rewind를 수행합니다.

왜 Bash의 부작용 (side effect)까지는 관리해주지 않는 것일까요? checkpoint는 아마도 에이전트 스스로가 수행한 Edit/Write 계열의 도구 호출에 대해 파일의 차분 스냅샷 (diff snapshot)을 저장 및 복원하는 레이어일 뿐, git과 같은 전체 버전 관리나 컨테이너·프로세스의 상태 관리까지는 수행하지 않는다고 생각하면 납득이 갑니다. "코드 되돌리기"에 특화된 경량 기능이며, 시스템 전체의 스냅샷 (VM 이미지와 같은 것)이 아니라는 점을 이해하고 사용하면 사고를 줄일 수 있습니다.

• checkpoint/rewind는 편리하지만 "파일 되돌리기" 전용 기능이며, Bash의 부작용은 되돌릴 수 없습니다.
• 패키지 설치나 DB 조작 등 취소할 수 없는 계열의 Bash 조작 전에는 잠시 주의를 기울이십시오.
• 변경 사항이 클수록 1턴 1태스크 (1 turn 1 task)를 의식하면 rewind의 입도 (granularity)를 다루기 쉬워집니다.
• 보험으로서 git commit을 병행해 두면, rewind로 다 커버하지 못하는 부분도 git 측에서 보완할 수 있습니다.