체크포인팅

코드를 고치다 “아, 이 방향이 아니었는데” 싶을 때, Claude Code는 방금 전의 안전한 상태로 한 번에 되돌려 줍니다. 게임의 세이브 포인트처럼, 프롬프트 하나를 보낼 때마다 그 시점의 코드 상태를 슬쩍 찍어 두기 때문입니다. 이 문서는 그 안전망인 체크포인팅(checkpointing)과 되감기(rewind)를 다룹니다.

배경 참조

이 문서는 MoAI-ADK가 올라타 있는 플랫폼인 Claude Code 자체를 다루는 배경 자료입니다. MoAI-ADK 자체 기능은 사이드바 위쪽 섹션에서 다룹니다.

정보

한 줄 요약: 작업이 꼬여도 Esc를 두 번 누르면 코드와 대화를 함께 이전 상태로 되감을 수 있는, 세션 단위의 “되돌리기” 안전망입니다.

비유로 이해하기

보스 방 앞에서 세이브를 찍어 두면, 실수로 전멸해도 그 지점으로 돌아갈 수 있죠. Claude Code도 사용자가 프롬프트를 보낼 때마다 그 시점의 파일 상태를 세이브 포인트로 남겨 둡니다. 그래서 실험이 엉뚱한 곳으로 흘러가도 당황하지 말고 되감기 한 번이면 직전 세이브로 깔끔하게 돌아옵니다.

규모가 큰 코드베이스를 건드리는 작업은 늘 망설임이 따릅니다. “이렇게 바꿨다가 망하면 어쩌지.” 체크포인팅은 그 망설임을 거둬 주는 장치입니다. Claude가 파일을 편집하기 직전의 상태를 자동으로 찍어 두어서, 언제든 직전 지점으로 돌아갈 수 있다는 믿음 아래 과감하게 시도할 수 있습니다.

자동 추적(automatic tracking)은 이렇게 동작합니다.

체크포인트는 세션 단위의 빠른 복구를 위한 장치일 뿐, Git 같은 버전 관리 시스템을 대신하지 않습니다. 체크포인트는 “로컬 되돌리기”, Git은 “영구 기록"으로 생각하면 역할 구분이 명확해집니다.

되감기는 /rewind 명령으로 엽니다. v2.1.191 이상에서는 /checkpoint, /undo라는 별칭도 같은 동작을 합니다. 키보드로는 프롬프트 입력창이 비어 있을 때 Esc를 두 번 누르면 됩니다.

/rewind
# v2.1.191 이상에서 별칭
/checkpoint
/undo
# 또는 입력창이 비어 있을 때
Esc  Esc

입력창에 텍스트가 남아 있으면 Esc 두 번은 메뉴를 여는 대신 입력 내용을 지웁니다. 다만 지워진 텍스트는 입력 기록에 남으므로, 되감기를 마친 뒤 Up 키로 다시 불러올 수 있습니다.

되감기 메뉴는 세션 동안 보낸 프롬프트 목록을 보여 줍니다. 되돌릴 지점을 고른 뒤, 아래 동작 중 하나를 선택합니다.

대화를 복원하거나 Summarize from here를 선택하면, 선택한 메시지의 원래 프롬프트가 입력창에 복원되어 그대로 다시 보내거나 고쳐 보낼 수 있습니다.

복원(restore) 계열은 상태를 되돌립니다. 코드 변경이든 대화 기록이든, 아니면 둘 다를 취소합니다. 반면 요약(summarize) 계열은 디스크의 파일은 그대로 둔 채 대화의 일부만 AI가 만든 요약으로 압축합니다.

• Summarize from here: 선택 메시지 이전은 온전히 남고, 선택 메시지와 그 이후가 요약으로 대체됩니다. 곁다리 논의를 버리되 초반 맥락은 상세히 남기고 싶을 때 씁니다.
• Summarize up to here: 선택 메시지 이전이 요약으로 대체되고, 선택 메시지와 이후는 그대로 유지됩니다. 초반 셋업 논의는 압축하되 최근 작업은 상세히 남기고 싶을 때 씁니다.

두 경우 모두 원본 메시지는 세션 트랜스크립트에 보존되므로, 필요하면 Claude가 세부 내용을 다시 참조할 수 있습니다. /compact와 비슷하지만, 전체가 아니라 선택 메시지 기준으로 어느 쪽을 압축할지 고를 수 있다는 점이 다릅니다.

되감기가 추적하는 것은 세션 안에서 Claude의 파일 편집 도구가 만든 변경뿐입니다. 그 경계 바깥의 변경은 복원되지 않습니다.

flowchart TD
    A[Claude 작업] --> B{변경 유형}
    B -->|편집 도구로
파일 수정| C[체크포인트에
기록됨]
    B -->|bash 명령
rm·mv·cp| D[추적 안 됨]
    B -->|git 커밋
네트워크 호출| E[외부 부작용
되돌릴 수 없음]
    C --> F[되감기로
복원 가능]
    D --> G[수동 복구 필요]
    E --> G

되감기의 핵심은 로컬 파일 상태의 되돌리기입니다. 외부 시스템에 이미 반영된 부작용(side effect)은 체크포인트의 책임 밖이므로 따로 챙겨야 합니다.

체크포인트는 다음 상황에서 특히 빛을 발합니다.

• 대안 탐색: 시작 지점을 잃지 않고 서로 다른 구현 방식을 자유롭게 시도합니다.
• 실수 복구: 버그를 만들거나 기능을 깨뜨린 변경을 빠르게 되돌립니다.
• 기능 반복: 동작하던 상태로 되돌릴 수 있다는 전제 아래 변형을 실험합니다.
• 컨텍스트 공간 확보: 장황한 디버깅 세션을 중간 지점부터 요약해, 초기 지시는 온전히 둔 채 컨텍스트 윈도우(context window)를 비웁니다.

결과가 불확실한 실험적 리팩터링을 앞두었다면, 먼저 프롬프트를 하나 보내 체크포인트를 만들어 두고 마음 편히 진행한 뒤, 마음에 들지 않으면 Esc Esc로 코드와 대화를 함께 되돌리는 흐름이 효율적입니다.

MoAI-ADK 관점에서 체크포인팅은 에이전틱 루프를 과감하게 돌릴 수 있게 하는 조건입니다. 루프가 “행동 → 검증 → 교정"을 자율 반복하려면 실패한 시도를 값싸게 되돌릴 수 있어야 하고, 체크포인트가 그 되돌리기 비용을 거의 0으로 만듭니다. SPEC 단위 작업 중 코드가 크게 흔들렸을 때 빠르게 직전 상태로 복귀하는 세션 내 안전망으로 활용하되, 영구 이력은 항상 Git 커밋으로 남기는 것이 원칙입니다.

• bash 명령 변경 미추적: 편집 도구가 아닌 셸 명령으로 바뀐 파일은 되돌릴 수 없습니다. 파괴적 셸 명령은 신중하게 다뤄야 합니다.
• 외부·동시 변경 미추적: 다른 세션이나 외부 에디터의 변경은, 마침 같은 파일을 건드린 경우가 아니면 포착되지 않습니다.
• 버전 관리 대체 불가: 체크포인트는 세션 단위 복구용입니다. 영구 기록과 협업은 반드시 Git 같은 버전 관리 시스템으로 이어 가야 합니다.
• 보존 기간: 체크포인트는 세션과 함께 30일 후 자동 정리됩니다 (설정으로 조정 가능).
• 요약과 포크(fork)의 차이: 요약은 같은 세션 안에서 컨텍스트를 압축합니다. 원본 세션을 그대로 두고 다른 접근을 시도하려면 claude --continue --fork-session으로 세션을 분기하는 편이 적합합니다.

• 컨텍스트 윈도우
• 세션 관리
• 대화형 모드

• Checkpointing — Claude Code Docs

팁

파괴적인 리팩터링을 시작하기 전에 짧은 프롬프트 한 번으로 체크포인트를 의도적으로 만들어 두면, 실험이 실패해도 Esc Esc 한 번으로 깔끔히 직전 상태로 돌아올 수 있습니다.