방금 전까지 되던 파일이 다음 요청 뒤 엉켜 버린 적 있으시죠?
Claude Code는 요청을 보내기 직전의 파일 상태를 매번 자동으로 남겨 둡니다. 처음부터 다시 고치기 전에, 어디까지 되돌릴지 고를 방법이 있습니다.
핵심 내용
- Claude Code는 프롬프트를 보낼 때마다 직전 파일 상태를 체크포인트로 저장합니다. 최근 100개의 체크포인트를 세션 안에 보관합니다.
- /rewind를 입력하거나 빈 입력칸에서 Esc를 두 번 누르면 되감기 메뉴가 열립니다. 코드만, 대화만, 둘 다 되돌리는 선택지가 따로 있습니다.
- 대화를 요약해도 파일은 바뀌지 않습니다. 긴 디버깅 대화의 맥락을 줄이면서 같은 세션을 계속 쓸 때 쓸모가 있습니다.
- Bash 명령으로만 바뀐 파일, 외부에서 직접 고친 파일, 일부 서브에이전트의 편집은 되감기 대상이 아닐 수 있습니다. 장기 기록과 협업에는 Git을 함께 써야 합니다.
왜 수정 전 상태가 남을까
Claude Code에 기능 하나를 더 만들어 달라고 요청했는데, 원래 잘 돌아가던 부분까지 함께 바뀌어 당황한 적 있으신가요? 어떤 파일을 건드렸는지 기억해도 바뀌기 전 내용을 손으로 되살리려면 꽤 번거롭습니다. 작은 요청을 연달아 보냈다면 어느 요청부터 문제가 생겼는지 찾기도 어렵죠.
Claude Code의 체크포인트는 이런 때 쓰는 세션 안의 되돌리기 장치입니다. 새 프롬프트를 보낼 때마다 그 요청을 처리하기 직전의 코드 상태를 자동으로 잡아 둡니다. Claude Code의 파일 편집 도구가 바꾼 내용을 중심으로 추적하므로, 따로 저장 버튼을 누르거나 파일 목록을 적어 둘 필요는 없습니다.
세션에는 최근 100개 체크포인트의 파일 복사본이 남습니다. 대화 기록과 함께 저장되기 때문에 나중에 같은 세션을 이어도 /rewind를 쓸 수 있습니다. 기본 설정에서는 마지막 저장 후 약 30일이 지나면 파일 복사본이 정리될 수 있습니다. 오래된 작업을 안전하게 보관하는 기능이라기보다, 진행 중인 작업에서 빠르게 방향을 바꾸는 용도에 가깝습니다.
새 구현을 시험하기 전에는 요청을 짧게 나누는 편이 좋습니다. 한 요청에 여러 변경을 몰아넣기보다 작게 고치고 확인한 뒤 다음 요청을 보내면, 되돌릴 지점도 훨씬 선명해지거든요. 작동하던 상태를 잃지 않은 채 실험할 수 있다는 점이 체크포인트의 가장 실용적인 쓰임입니다.
꿀팁 · 새 구현을 시도할 때는 한 요청에 변경 하나만 맡기면 /rewind 목록에서 되돌릴 지점을 고르기 쉽습니다.
클로드 코드 되돌리기 사용법
되돌릴 일이 생겼다면 먼저 Claude Code의 입력칸이 비어 있는지 확인하세요. 명령을 입력할 수 있다면 /rewind를 실행하면 됩니다. 입력칸이 비어 있을 때 Esc 키를 두 번 눌러도 같은 되감기 메뉴가 열립니다.
입력칸에 작성 중인 글이 있을 때 Esc를 두 번 누르면 메뉴가 열리는 대신 그 글은 지워집니다. 다만 지워진 문장은 입력 기록에 남습니다. 되감기 작업을 마친 뒤 위쪽 화살표 키를 누르면 다시 불러올 수 있으니 급하게 복사할 필요는 없습니다. 그래도 긴 요청문이라면 메뉴를 열기 전에 한 번 확인하는 습관이 낫습니다.
메뉴에서 Restore code and conversation을 고르면 파일과 대화를 함께 선택 지점으로 되돌립니다. Restore code는 대화는 그대로 두고 파일 수정만 되돌립니다. Restore conversation은 현재 파일을 유지한 채 대화 흐름만 과거 메시지로 옮깁니다. 실패한 요청을 표현만 바꿔 다시 보내려는 상황이라면 대화만 복원하는 선택이 잘 맞습니다.
선택한 지점 뒤에 추적된 파일 수정이 있어야 코드 복원 항목이 보입니다. 이후 파일 편집이 없었다면 Restore conversation과 요약 항목 등이 표시됩니다. 대화 복원을 선택하면 당시 보낸 원래 요청이 입력칸에 다시 들어옵니다. 문장을 다듬어 재전송해도 되고, 전혀 다른 요청으로 바꿔도 됩니다.
꿀팁 · 파일은 그대로 두고 요청문만 고치려면 Restore conversation을 선택한 뒤, 입력칸에 돌아온 문장을 편집하면 됩니다.
코드와 대화, 무엇을 돌릴까
되돌리기가 늘 ‘전부 취소’를 뜻하는 건 아닙니다. 예를 들어 Claude Code가 화면 구성 파일을 바꿨는데 파일 수정은 괜찮고, 길어진 설명 때문에 대화만 다시 정리하고 싶을 수 있습니다. 이때 파일까지 함께 복원하면 남기고 싶은 변경도 사라질 수 있으니, 먼저 필요한 것이 코드 복원인지 대화 복원인지 구분해야 합니다.
긴 대화 탓에 Claude가 앞선 지시를 충분히 담기 어려워 보일 때는 Summarize from here 또는 Summarize up to here를 쓸 수 있습니다. 앞의 항목은 고른 지점 이후 대화를 압축하고, 뒤의 항목은 그 지점 이전 대화를 압축합니다. 어느 쪽도 디스크의 파일을 바꾸지 않습니다. 대화 공간만 정리하는 선택입니다.
요약 항목을 화살표 키로 고르면 add context (optional) 줄에 요약의 초점을 적을 수 있습니다. 버그 원인과 이미 시도한 해결책만 남기고 싶다면 그 내용을 적고 Enter를 누르면 됩니다. 숫자 키로 항목을 고르면 추가 지침 없이 바로 실행됩니다. 요약 뒤에는 압축된 자리에 Summarized conversation 표시가 나타납니다.
대안 두 가지를 비교하고 싶다면 되감기보다 /branch 또는 claude --continue --fork-session이 더 어울릴 수 있습니다. 원래 세션을 보존한 채 다른 접근을 시도하는 방식이기 때문입니다. 이미 한 변경이 잘못됐다고 판단했다면 /rewind가 더 직접적입니다. 개인적으로는 코드 복원과 대화 요약을 따로 고를 수 있다는 점이 가장 반갑습니다.
꿀팁 · 긴 오류 해결 대화에서는 Summarize from here를 고른 뒤 “오류 원인과 이미 시도한 수정만 남겨 주세요”라고 초점을 지정해 보세요.
되돌리지 못하는 변경도 있나
체크포인트가 있다고 해서 모든 파일 변화가 자동으로 원상 복구되지는 않습니다. Claude Code의 파일 편집 도구로 한 번도 다루지 않은 파일을 Bash 명령으로만 바꿨다면 /rewind는 그 파일을 추적하지 않습니다. 그 파일은 그대로 남습니다. Bash로 대량 변경을 했다면 되감기 전후의 파일 상태를 확인해야 하는 이유입니다.
반대로 Claude가 파일 편집 도구로 이미 편집한 파일이라면, 그 뒤 Bash 명령이 해당 파일에 더한 변경도 되감기 과정에서 함께 취소될 수 있습니다. 메뉴는 각 프롬프트 아래에 편집된 파일의 변경을 모아 보여 줍니다. ‘누가 바꿨는지’보다 해당 파일이 현재 세션에서 추적 대상이 됐는지가 기준이라는 뜻입니다.
다른 창에서 직접 수정한 파일이나 다른 세션이 바꾼 파일도 대체로 현재 세션의 체크포인트에 잡히지 않습니다. 일부 서브에이전트가 다른 파일에 넣은 수정도 그대로 남을 수 있습니다. symlink나 hard link로 연결된 파일은 코드 복원 때 건너뛸 수 있고, 이 경우 Restored the code, but skipped N files라는 경고가 표시됩니다. 건너뛴 파일은 직접 고치거나 Claude에게 되돌리기를 요청해야 합니다.
또 /clear를 한 직후에는 같은 Claude Code 프로세스 안에서 메뉴 맨 위의 /resume <session-id> (previous session)으로 이전 대화를 다시 열 수 있습니다. 다만 Claude Code를 종료하거나 다른 세션을 열면 쓸 수 없습니다. 체크포인트는 빠르게 되돌리기 위한 수단이고, 오래 남길 작업 기록과 협업 기록은 Git의 커밋과 분기로 관리하는 편이 낫습니다.
꿀팁 · 되감기 뒤 파일이 예상과 다르다면 Bash로만 바뀐 파일, 다른 세션의 수정, 연결된 파일이 있었는지 먼저 확인하세요.
그래서 나에게 무엇이 달라질까
Claude Code에 맡긴 수정을 되돌릴 수 있으면 새 기능이나 수정안을 훨씬 가벼운 부담으로 시험해 볼 수 있습니다. 다만 체크포인트는 세션 안에서 빠르게 복구하는 수단입니다. 작업의 공식 기록과 협업 기준점은 Git에 남겨 두는 편이 안전합니다.
내일 바로 써먹기
- Claude Code에서 작은 파일 수정 요청 하나를 보낸 뒤 /rewind를 실행해 메뉴에 나타나는 기준점을 확인합니다.
- 실패한 요청문을 다시 쓰고 싶을 때 Restore conversation을 선택한 뒤 복원된 문장을 고쳐 재전송합니다.
- Bash 명령으로 파일을 바꾸기 전에는 Git 커밋이나 별도 변경 기록을 남깁니다.
용어사전
- checkpoint · 프롬프트를 보내기 직전의 파일 상태를 Claude Code가 세션 안에 남겨 둔 기준점입니다. 나중에 이 지점으로 파일이나 대화를 되돌릴 수 있습니다.
- Bash · 명령어를 입력해 파일을 바꾸거나 작업을 실행하는 방식입니다. Bash만으로 바뀐 파일은 체크포인트에 잡히지 않을 수 있습니다.
- Git · 파일 변경 이력을 오래 보관하고, 여러 사람이 작업을 합칠 때 쓰는 버전 관리 도구입니다. 체크포인트가 대신하지 못하는 장기 기록을 맡습니다.
- symlink · 다른 위치의 파일을 가리키도록 만든 연결 경로입니다. Claude Code의 되감기는 이런 연결된 파일을 건너뛸 수 있습니다.
출처
- 원문: Claude Code 공식 도움말 · https://code.claude.com/docs/ko/checkpointing