[Claude 활용 24회 — AI에게 일을 위임하는 법] 8/24화: Claude Code 체크포인트 활용 3단계 — 과감한 리팩터링의 조건
3줄 요약
- Claude Code는 파일을 수정하기 직전 체크포인트(자동 Git 스냅샷)를 찍는다. 되돌리기 한 번이면 수십 개 파일 변경이 원상 복구된다.
- Plan Mode → 실행 → /review 파이프라인을 걸면, 설계를 먼저 검토하고 결과를 다시 검증하는 이중 안전망이 생긴다.
- Git Worktree로 같은 문제에 3가지 접근을 동시에 돌리고, 최선만 채택하면 리팩터링 의사결정 비용이 사라진다.
금요일 오후 4시, 리팩터링이 삼킨 네 시간
그 서비스 클래스는 1,200줄짜리였다. 여행 예약 시스템의 BookingService — 예약 생성, 결제 검증, 재고 차감, 알림 발송, 환불 처리가 전부 한 파일에 있었다. 누가 봐도 쪼개야 하는 코드였다.
Claude Code에게 리팩터링을 맡겼다. “BookingService를 단일 책임 원칙에 맞게 분리해줘.” 그러자 Claude는 일을 시작했다. 파일 32개를 수정하고, 새 클래스 5개를 만들고, import 경로를 전부 바꿨다. 터미널에 초록색 글씨가 쏟아졌다. “잘 되고 있나 보다.” 그렇게 20분을 지켜봤다.
문제는 그 다음이었다. 테스트를 돌려 보니 42개가 실패했다. Claude에게 고쳐달라고 했더니, 고치면서 또 다른 것들이 깨졌다. 한 시간이 지나고, 두 시간이 지나고, 원래 코드가 어떤 상태였는지 기억도 희미해질 때쯤 깨달았다. 이건 수렁이다.
결국 git stash로 되돌리려 했지만, Claude가 중간에 만든 파일들은 untracked라 stash에 잡히지 않았다. 수작업으로 git checkout을 파일별로 치고, 새로 생긴 파일을 하나씩 지웠다. 금요일 오후 4시에 시작한 리팩터링이 끝난 건 저녁 8시였다. 결과물은? 원래 코드 그대로. 네 시간을 태우고 제자리.
그 날 이후로 한 가지를 확실히 알게 됐다. 되돌릴 수 있는 구조가 없으면, 과감할 수 없다. 그리고 과감하지 않으면, AI에게 위임하는 의미가 없다. Claude Code의 체크포인트, Plan Mode, /review는 그 구조를 만드는 도구다. 4화에서 잠깐 언급한 “체크포인트·Esc 두 번 되돌리기 습관”을 이번 회차에서 본격적으로 파고든다.
Claude Code 체크포인트 — 자동 스냅샷이 만드는 안전망
체크포인트란 무엇인가
Claude Code 체크포인트는 한마디로 자동 Git 스냅샷이다. Claude가 파일을 수정하기 직전, 현재 작업 디렉터리의 상태를 Git 커밋으로 저장한다. 이 커밋은 일반적인 git log에는 보이지 않는다. Claude Code가 내부적으로 관리하는 참조(ref)에 달려 있어서, 여러분의 커밋 히스토리를 더럽히지 않는다.
핵심은 이거다. 여러분이 아무것도 하지 않아도 찍힌다. “커밋 먼저 해야지” 같은 습관에 의존하지 않는다. 7화에서 다룬 컨텍스트 자동 압축처럼, 체크포인트도 백그라운드에서 자동으로 동작한다.
체크포인트가 기록하는 것:
- 수정 전 파일들의 정확한 상태 (바이너리 포함)
- 새로 생성될 파일이 아직 없다는 사실
- 삭제될 파일이 아직 존재한다는 사실
체크포인트가 기록하지 않는 것:
- 실행 중인 프로세스 상태 (DB 연결, 서버 상태 등)
- Git에 추적되지 않고
.gitignore에도 없는 파일 - 환경변수나 시스템 설정
체크포인트가 찍히는 순간
모든 도구 호출(tool use)이 체크포인트를 만드는 것은 아니다. 파일 시스템을 변경하는 도구 호출 직전에만 찍힌다.
# 체크포인트가 찍히는 경우
- Write 도구로 새 파일 생성 직전
- Edit 도구로 기존 파일 수정 직전
- Bash 도구로 파일을 변경하는 명령 실행 직전
(예: mv, cp, rm, 패키지 설치 등)
# 체크포인트가 찍히지 않는 경우
- Read 도구로 파일 읽기
- Grep/Glob으로 검색
- Bash로 읽기 전용 명령 실행 (ls, cat, git log 등)이 구분이 중요한 이유가 있다. 체크포인트는 공짜가 아니다. Git 커밋을 만드는 건 디스크 I/O와 시간이 든다. 읽기 전용 작업에까지 체크포인트를 찍으면 체감 속도가 떨어진다. Claude Code는 “변경이 일어날 때만” 이라는 원칙으로 이 비용을 최소화한다.
하나 더. Claude가 연속으로 여러 파일을 수정하는 경우, 각 파일 수정마다 체크포인트가 찍히는 게 아니라 도구 호출 단위로 찍힌다. 한 번의 Edit 도구 호출이 하나의 파일을 수정하므로, 결과적으로 파일당 하나의 체크포인트가 존재하게 된다. 하지만 Bash 도구로 여러 파일을 한꺼번에 바꾸는 명령을 실행하면, 그 전체가 하나의 체크포인트에 묶인다.
되돌리기: 되감기 한 번이면 된다
체크포인트로 되돌리는 방법은 단순하다.
# 방법 1: Claude가 작업 중일 때 — Esc 두 번
# 첫 번째 Esc: 현재 실행 중인 도구 호출을 중단
# 두 번째 Esc: 마지막 체크포인트로 파일 상태 복원
# 방법 2: Claude가 멈춰 있을 때 — 직접 지시
"방금 한 변경을 되돌려줘"
# Claude가 체크포인트 목록을 보여주고, 원하는 시점으로 복원
# 방법 3: 특정 시점으로 되돌리기
"BookingService 분리하기 전 상태로 돌아가줘"
# Claude가 관련 체크포인트를 찾아서 복원내가 금요일 저녁에 수작업으로 했던 일 — 32개 파일을 하나씩 원래 상태로 되돌리고, 새로 생긴 5개 파일을 지우고, import 경로를 전부 복원하는 일 — 이 2초면 끝난다. Esc 두 번. 그게 전부다.
그래서 나는 이제 리팩터링을 시작할 때 아무 사전 작업도 하지 않는다. 예전에는 git stash를 하고, 브랜치를 새로 파고, “혹시 모르니까” 수동 백업까지 했다. 체크포인트를 믿게 된 후로 그런 의식(ritual)이 전부 사라졌다. 되돌릴 수 있으니까, 그냥 시작한다.
Plan Mode → 실행 → /review: 되돌릴 수 있는 파이프라인 만들기
체크포인트는 사후 안전망이다. 이미 벌어진 일을 되돌린다. 하지만 진짜 효율적인 작업 방식은 사전에 방향을 잡고, 사후에 검증하는 파이프라인을 거는 것이다. Claude Code에는 이를 위한 도구가 이미 내장되어 있다.
Plan Mode — 설계를 먼저, 코드는 나중에
Plan Mode는 Claude에게 “아직 코드를 쓰지 마. 계획부터 보여줘”라고 말하는 것이다. Shift+Tab으로 토글하거나, 프롬프트 앞에 자연어로 “계획만 먼저 세워줘”라고 붙이면 된다.
# Plan Mode 진입 방법 1: 단축키
# Shift+Tab을 누르면 입력란 옆에 "Plan" 표시가 나타난다
# Plan Mode 진입 방법 2: 자연어
"BookingService를 리팩터링할 건데, 먼저 계획만 세워줘. 코드는 아직 건드리지 마."
# Plan Mode 진입 방법 3: 슬래시 명령
/planPlan Mode에서 Claude는 다음을 출력한다:
- 현재 상태 분석: 대상 코드가 어떤 구조이고, 어떤 문제가 있는지
- 변경 계획: 어떤 파일을 만들고, 어떤 파일을 수정하고, 어떤 순서로 할 것인지
- 위험 요소: 이 변경이 깨뜨릴 수 있는 것들
- 테스트 전략: 변경 후 어떻게 검증할 것인지
이걸 설계 리뷰로 쓴다. 4화에서 다룬 작업 지시서의 “완료 조건”과 “검증 방법”을 Claude가 역으로 제안하는 셈이다. 내가 놓친 것이 있으면 이 단계에서 잡힌다.
실제 예를 보자. 여행 예약 시스템의 BookingService를 리팩터링하려 한다.
# 입력 (Plan Mode)
"BookingService.py를 단일 책임 원칙에 맞게 분리해줘.
현재 이 클래스가 담당하는 것: 예약 생성, 결제 검증, 재고 차감, 알림 발송, 환불 처리.
제약: 기존 API 시그니처는 유지해야 하고, tests/test_booking.py가 깨지면 안 돼."
# Claude의 Plan Mode 출력 (요약)
───────────────────────────────────────
📋 리팩터링 계획: BookingService 분리
1. 현재 구조 분석
- BookingService: 1,247줄, 메서드 23개
- 외부 의존성: PaymentGateway, InventoryDB, NotificationQueue
- 테스트: test_booking.py (67개 테스트 케이스)
2. 분리 계획
┌─ BookingService (오케스트레이터, ~150줄)
├─ PaymentValidator (~200줄)
├─ InventoryManager (~180줄)
├─ NotificationDispatcher (~120줄)
└─ RefundProcessor (~250줄)
3. 수정 대상 파일 (7개)
- booking_service.py → 축소 + import 추가
- payment_validator.py → 신규
- inventory_manager.py → 신규
- notification.py → 신규
- refund_processor.py → 신규
- __init__.py → export 추가
- test_booking.py → import 경로 변경
4. 위험 요소
⚠ PaymentValidator와 RefundProcessor가 공유하는
_validate_payment_status() 내부 메서드 처리 필요
⚠ NotificationQueue 목(mock)이 BookingService에
직접 주입되는 테스트 3개 수정 필요
5. 실행 순서
Step 1: 새 클래스 파일 생성 (빈 껍데기)
Step 2: 메서드 이동 (의존성 적은 것부터)
Step 3: BookingService에서 새 클래스 호출로 교체
Step 4: 테스트 수정 및 실행
Step 5: import 정리
───────────────────────────────────────이 계획을 받고 나면 세 가지 판단을 할 수 있다.
- 승인: “좋아, 이대로 진행해.” → Claude가 Plan Mode를 끄고 실행에 들어간다.
- 수정 요청: “PaymentValidator와 RefundProcessor를 합쳐서 PaymentService로 하자.” → 계획이 갱신된다.
- 폐기: “이 방향은 아닌 것 같아. 다른 접근을 제안해줘.” → 계획을 버리고 새로 시작한다.
코드가 한 줄도 바뀌지 않은 상태에서 이 판단을 내린다는 게 핵심이다. 실행 전에 설계를 검토하니까 비용이 0이다.
실행 단계에서 지켜야 할 것
계획을 승인하고 Claude가 코드를 쓰기 시작하면, 그 과정을 지켜보는 것도 전략이다. 나는 두 가지 원칙을 따른다.
원칙 1: 중간에 방향을 틀지 않는다.
Claude가 Step 2를 진행 중인데 “아, 잠깐, Step 4에서 테스트 방식을 바꾸자”라고 끼어들면 문맥이 꼬인다. 7화에서 다룬 컨텍스트 오염이 여기서도 작동한다. 중간에 방향을 틀고 싶으면, 현재 작업을 멈추고(Esc), 체크포인트로 되돌린 다음, 새 계획으로 다시 시작하는 게 훨씬 깔끔하다.
원칙 2: 한 단위가 끝날 때마다 테스트를 돌린다.
# Claude에게 단계별 검증을 요청하는 방법
"위 계획대로 진행하되, 각 Step이 끝날 때마다 pytest를 돌려서
깨지는 테스트가 없는지 확인해줘. 실패하는 테스트가 나오면
다음 Step으로 넘어가지 말고 먼저 고쳐."이렇게 지시하면 Claude가 Step 1 완료 → pytest 실행 → 통과 확인 → Step 2 진행 순서로 움직인다. 문제가 Step 2에서 발견되면 Step 1의 체크포인트까지만 돌아가면 된다. 32개 파일이 아니라 해당 단계에서 바뀐 파일만 되돌리면 되니까, 복구 범위가 좁아진다.
/review와 /security-review로 자기 검증
Claude가 모든 변경을 마치면, 작업을 “끝냈습니다”라고 보고한다. 이때 바로 커밋하지 않는다. 리뷰를 건다.
# 일반 코드 리뷰
/review
# 보안 중점 리뷰
/security-review/review를 실행하면 Claude가 자기 자신이 방금 작성한 코드를 코드 리뷰어 관점에서 다시 읽는다. 이건 “다시 한번 봐줘”와는 다르다. 명시적으로 리뷰어 역할이 활성화되면서 Claude는 다음을 점검한다:
- 논리 오류: 엣지 케이스, off-by-one, 빈 컬렉션 처리
- 계획 준수: 처음 세운 계획과 실제 구현의 괴리
- 코드 스타일: 프로젝트 컨벤션, 네이밍, 타입 힌트
- 테스트 커버리지: 새 코드에 대한 테스트가 충분한지
- 성능: 불필요한 루프, N+1 쿼리, 메모리 누수 가능성
/security-review는 보안에 집중한다:
- 입력 검증: SQL 인젝션, XSS, 커맨드 인젝션 가능성
- 인증/인가: 권한 검사 누락, 토큰 노출
- 데이터 노출: 로그에 민감 정보가 찍히는지
- 의존성 취약점: 알려진 취약점이 있는 라이브러리 사용
실제 리뷰 결과 예시:
# /review 실행 결과 (실제 출력 요약)
───────────────────────────────────────
🔍 코드 리뷰 결과
✅ 전체적으로 계획대로 잘 분리되었습니다.
⚠️ 발견된 이슈 (2건):
1. [중요도: 중] inventory_manager.py:45
decrease_stock()에서 재고가 0 미만이 될 때
ValueError 대신 도메인 예외(InsufficientStockError)를
사용하는 게 기존 에러 핸들링과 일관됩니다.
수정 제안:
- class InsufficientStockError(BookingError): ...
- raise InsufficientStockError(item_id, requested, available)
2. [중요도: 하] refund_processor.py:112
_calculate_refund_amount()의 반환 타입이 float인데,
원래 BookingService에서는 Decimal이었습니다.
금액 계산에서 부동소수점은 위험합니다.
수정 제안:
- from decimal import Decimal
- def _calculate_refund_amount(...) -> Decimal:
📊 요약: 이슈 2건 (중 1건, 하 1건), 차단 이슈 없음
───────────────────────────────────────이 두 건을 발견하지 못하고 커밋했으면? 운이 좋으면 QA에서 잡히고, 운이 나쁘면 운영 환경에서 float 정밀도 문제로 결제 금액이 1원씩 어긋나는 버그가 된다. 20년 경력으로 단언하건대, 금액 관련 float 버그는 발견까지 평균 3개월이 걸린다. 조용히, 아주 작은 차이로, 천천히 쌓이기 때문이다.
“방금 작성한 걸 리뷰해줘”가 아니라 /review라는 전용 명령이 존재하는 이유가 있다. 모드가 전환된다. 작성자 모드에서는 “이게 돌아가게 만들어야 해”라는 관성이 있고, 리뷰어 모드에서는 “이게 왜 잘못될 수 있지?”라는 관성이 있다. 같은 Claude지만 역할이 다르면 발견하는 것도 다르다. 이건 사람도 마찬가지다.
6화에서 다룬 훅(hook)과 결합하면 더 강력해진다. /review에서 발견된 보안 이슈의 심각도가 “높음” 이상이면 커밋 자체를 차단하는 pre-commit 훅을 걸 수 있다. 프롬프트로 “보안 이슈 있으면 하지 마”라고 말하는 건 통제가 아니라는 걸 6화에서 이미 확인했다. 코드로 막아야 막힌다.
파이프라인 전체 흐름: 체크포인트 → Plan → 실행 → Review → 커밋
지금까지 다룬 세 가지 — 체크포인트, Plan Mode, /review — 를 하나의 파이프라인으로 정리하면 이렇다.
┌─────────────┐ ┌───────────┐ ┌──────────┐ ┌─────────┐ ┌────────┐
│ Plan Mode │────▶│ 계획 승인 │────▶│ 실행 │────▶│ /review │────▶│ 커밋 │
│ (설계 리뷰) │ │ (사람) │ │ (자동 │ │ (자기 │ │ (사람 │
│ │ │ │ │ 체크포인트)│ │ 검증) │ │ 확인) │
└─────────────┘ └───────────┘ └──────────┘ └─────────┘ └────────┘
│ │ │
▼ ▼ ▼
폐기 가능 되돌리기 가능 수정 후 재검증
(코드 0줄 변경) (Esc 두 번) 가능각 단계에서 “아니오”가 가능하다는 게 핵심이다.
- Plan Mode에서 방향이 마음에 안 들면? → 코드 한 줄 안 바뀐 상태로 폐기
- 실행 중에 이상하면? → 체크포인트로 되돌리기
- /review에서 문제 발견? → 수정 요청 후 재검증
- 커밋 전에 전체적으로 불안하면? → 전체 체크포인트로 원상 복구
이 구조가 있으면 실패 비용이 거의 0이다. 그리고 실패 비용이 0이면, AI에게 일을 위임하는 시대에서 가장 중요한 태도가 가능해진다 — 과감하게 시도하고, 빠르게 버리는 것.
실습: Git Worktree로 리팩터링 3방향 동시 시도
여기서 한 걸음 더 나간다. 체크포인트가 “하나의 시도를 안전하게 되돌리는” 도구라면, Git Worktree는 “여러 시도를 동시에 진행하는” 도구다.
시나리오
앞의 BookingService 리팩터링을 세 가지 접근법으로 동시에 시도한다.
- 접근 1 — Extract Method: 기존 클래스를 유지하되, 긴 메서드를 작은 private 메서드로 분리
- 접근 2 — Strategy Pattern: 예약 규칙을 전략 객체로 추출, BookingService는 오케스트레이터만
- 접근 3 — 완전 재작성: BookingService를 지우고, 도메인 이벤트 기반 아키텍처로 새로 설계
어떤 접근이 가장 나을지 미리 알 수 있을까? 없다. 20년 해 봐도 리팩터링 최적 경로는 해 보기 전에는 모른다. 그래서 세 개를 동시에 돌린다.
Worktree 세팅
# 현재 위치: 프로젝트 루트 (main 브랜치)
# 먼저 현재 작업 내용이 깨끗한지 확인
git status
# Worktree 3개 생성 — 각각 별도 브랜치
git worktree add ../booking-extract -b refactor/extract-method
git worktree add ../booking-strategy -b refactor/strategy-pattern
git worktree add ../booking-rewrite -b refactor/full-rewrite
# 결과 확인
git worktree list
# /c/projects/travel-booking abc1234 [main]
# /c/projects/booking-extract abc1234 [refactor/extract-method]
# /c/projects/booking-strategy abc1234 [refactor/strategy-pattern]
# /c/projects/booking-rewrite abc1234 [refactor/full-rewrite]각 Worktree는 독립된 작업 디렉터리다. 파일 시스템 수준에서 별도 폴더이므로, 서로의 변경이 간섭하지 않는다. 하지만 .git 저장소는 공유하므로, 나중에 결과를 비교하고 머지하는 게 쉽다.
3가지 접근을 동시에 실행
터미널 창을 세 개 열고, 각 Worktree에서 별도의 Claude Code 세션을 시작한다.
# 터미널 1 — Extract Method 접근
cd ../booking-extract
claude
# Claude 세션 시작 후:
"BookingService.py를 리팩터링해줘.
접근법: Extract Method — 클래스는 유지하되,
create_booking() 메서드(현재 180줄)를 10~20줄 단위 private 메서드로 분리.
제약: 퍼블릭 API 시그니처 변경 금지, 테스트 전부 통과해야 함."# 터미널 2 — Strategy Pattern 접근
cd ../booking-strategy
claude
# Claude 세션 시작 후:
"BookingService.py를 리팩터링해줘.
접근법: Strategy Pattern — 예약 유형별 규칙(국내/해외/패키지)을
BookingStrategy 인터페이스로 추출. BookingService는 전략 선택 + 실행만.
제약: 퍼블릭 API 시그니처 변경 금지, 테스트 전부 통과해야 함."# 터미널 3 — 완전 재작성 접근
cd ../booking-rewrite
claude
# Claude 세션 시작 후:
"BookingService.py를 완전히 새로 설계해줘.
접근법: 도메인 이벤트 기반 — BookingCreated, PaymentVerified,
InventoryReserved 이벤트를 발행하고, 각 핸들러가 독립적으로 처리.
제약: 퍼블릭 API 시그니처 변경 금지, 테스트 전부 통과해야 함."세 세션이 동시에 돌아간다. 각각의 세션 안에서 Claude Code 체크포인트가 독립적으로 찍힌다. 한 세션에서 문제가 생겨도 다른 세션에 영향을 주지 않는다.
여기서 중요한 건 제약 조건을 세 세션 모두에 동일하게 주는 것이다. “퍼블릭 API 시그니처 변경 금지, 테스트 전부 통과” — 이 두 가지가 동일해야 나중에 결과를 공정하게 비교할 수 있다. 접근법만 다르고, 품질 기준은 같아야 한다.
비교하고 채택하기
세 세션이 모두 끝나면 비교한다.
# 각 브랜치의 변경 통계 비교
git diff main..refactor/extract-method --stat
git diff main..refactor/strategy-pattern --stat
git diff main..refactor/full-rewrite --stat
# 줄 수 변화 비교
echo "=== Extract Method ==="
git diff main..refactor/extract-method --shortstat
# 8 files changed, 342 insertions(+), 289 deletions(-)
echo "=== Strategy Pattern ==="
git diff main..refactor/strategy-pattern --shortstat
# 12 files changed, 567 insertions(+), 312 deletions(-)
echo "=== Full Rewrite ==="
git diff main..refactor/full-rewrite --shortstat
# 15 files changed, 891 insertions(+), 456 deletions(-)숫자만으로는 판단하지 않는다. 다음 기준을 적용한다:
# 판단 기준 체크리스트
1. 테스트 통과 여부
cd ../booking-extract && python -m pytest tests/ -q
cd ../booking-strategy && python -m pytest tests/ -q
cd ../booking-rewrite && python -m pytest tests/ -q
2. 변경 범위 (작을수록 좋다 — 리뷰·충돌 비용 감소)
→ Extract Method: 8파일 — 가장 작음 ✅
→ Strategy: 12파일
→ Rewrite: 15파일
3. 복잡도 변화 (각 접근에서 /review 돌린 결과 비교)
→ Extract Method: "메서드가 잘게 나뉘었지만, 호출 깊이가 3단계"
→ Strategy: "구조가 명확하지만, 새 인터페이스 학습 비용"
→ Rewrite: "깔끔하지만, 이벤트 핸들러 순서 의존성 위험"
4. 팀 친화도 (혼자가 아니라면)
→ 동료들이 Strategy Pattern에 익숙한가?
→ 이벤트 기반 아키텍처 경험이 있는 팀인가?이번 예시에서 나의 판단은 접근 2(Strategy Pattern)였다. 변경 범위가 적당하고, 예약 유형이 추가될 때 확장이 자연스러우며, 팀이 패턴에 익숙했기 때문이다. 접근 3은 기술적으로 우아했지만, 이벤트 순서 의존성이라는 새로운 복잡도를 도입하는 게 마음에 걸렸다.
# 채택한 브랜치를 main에 머지 준비
git checkout main
git merge refactor/strategy-pattern
# 나머지 Worktree 정리
git worktree remove ../booking-extract
git worktree remove ../booking-rewrite
# 사용하지 않은 브랜치 삭제
git branch -D refactor/extract-method
git branch -D refactor/full-rewrite
이 전체 과정이 AI 없이 가능했을까? 이론적으로는 가능하다. 세 브랜치를 만들고, 각각에서 직접 리팩터링하면 된다. 하지만 현실적으로 1,200줄짜리 서비스 클래스를 세 가지 다른 방법으로 리팩터링하는 데 사람이 직접 한다면 각각 반나절, 총 이틀이 걸린다. Claude Code에게 위임하면 세 세션 합쳐서 30분에서 1시간이다.
AI가 코드를 짜주는 시대가 아니라, AI에게 일을 위임하는 시대라는 말이 여기서 구체적으로 실현된다. 세 가지 접근을 동시에 실험하고 최선만 채택하는 것 — 이건 위임할 수 있는 사람만 누리는 효율이다.
함정 — 체크포인트는 Git을 대체하지 않는다
체크포인트에 익숙해지면 빠지기 쉬운 함정이 있다. “체크포인트가 있으니 커밋은 나중에 해도 되겠지.” 이건 위험한 착각이다.
함정 1: 체크포인트는 휘발성이다
체크포인트는 Claude Code 세션에 종속된다. 세션이 끝나면 — 터미널을 닫거나, 새 세션을 시작하거나, /compact로 컨텍스트를 정리하면 — 이전 세션의 체크포인트를 되돌릴 수 있다는 보장이 없다. Git의 reflog처럼 일정 기간 남아 있을 수 있지만, 영구적이지 않다.
# ❌ 이렇게 하지 마세요
# Claude 세션 1에서: 대규모 리팩터링 수행
# "내일 마저 해야지" → 터미널 닫음
# 다음 날 Claude 세션 2에서: "어제 체크포인트로 돌아가줘"
# → 체크포인트를 찾을 수 없을 수 있음
# ✅ 이렇게 하세요
# Claude 세션에서 의미 있는 단위가 끝날 때마다:
git add -A
git commit -m "refactor(booking): extract PaymentValidator class"
# 이게 영구 기록이다. 체크포인트는 세션 내 안전망일 뿐.함정 2: 체크포인트에 맡기고 무한 루프에 빠지기
“되돌리면 되니까” 라는 안심이 과하면, 같은 실패를 반복하는 루프에 빠진다. 시도 → 실패 → 되돌리기 → 같은 방식으로 다시 시도 → 같은 이유로 실패 → 되돌리기… 7화에서 다룬 “컨텍스트 오염”의 변종이다.
세 번 되돌렸으면 멈춰야 한다. 같은 접근으로 세 번 실패하면, 그건 접근이 틀린 거다. 되돌리는 게 아니라 Plan Mode로 돌아가서 다른 계획을 세워야 한다. 또는 아예 세션을 리셋하고 새로 시작하는 게 나을 수 있다.
# 실패 반복 패턴 감지 — 자기 체크용 질문
# 1. 지금 몇 번째 되돌리기인가? → 3번 이상이면 STOP
# 2. 되돌린 이유가 매번 다른가? → 같은 이유면 접근 변경
# 3. Claude가 같은 코드를 반복 생성하는가? → 컨텍스트 오염, 세션 리셋함정 3: Plan Mode를 건너뛰는 습관
체크포인트가 있으니까 “일단 해 보고 아니면 되돌리자”로 가는 패턴. 간단한 변경에는 괜찮지만, 여러 파일에 걸친 구조적 변경에서 이러면 되돌리기 비용이 비싸진다.
파일 3개 이상이 바뀌는 작업이라면 Plan Mode를 거치는 게 거의 항상 이득이다. 계획을 세우는 데 30초, 잘못된 실행을 되돌리고 재시도하는 데 5분. 30초를 아끼려다 5분을 쓰는 건 좋은 거래가 아니다.
함정 4: /review 결과를 무비판적으로 수용
/review는 강력하지만 완벽하지 않다. Claude가 자기가 쓴 코드를 리뷰하는 것이므로, 원래 설계 전제 자체가 잘못된 경우에는 그 잘못을 발견하지 못할 수 있다. “이 메서드가 float를 반환하는데 Decimal이어야 합니다”는 잡을 수 있지만, “애초에 이 책임이 여기 있으면 안 됩니다”는 놓칠 수 있다.
/review는 전술적 리뷰(이 코드가 올바른가?)에 강하고, 전략적 리뷰(이 구조가 맞는 방향인가?)에는 약하다. 전략적 판단은 여전히 사람의 몫이다. 그래서 Plan Mode가 먼저 와야 한다 — Plan Mode에서 전략을 사람이 검증하고, /review에서 전술을 Claude가 검증하는 분업.
함정 5: Worktree를 정리하지 않는다
Git Worktree는 디스크 공간을 잡아먹는다. 각 Worktree가 프로젝트의 전체 파일 복사본을 가지고 있기 때문이다(Git 객체는 공유하지만, 워킹 카피는 별도). 실험이 끝나면 반드시 정리하자.
# 실험 끝난 Worktree 정리
git worktree remove ../booking-extract
git worktree remove ../booking-rewrite
# 정리 안 된 Worktree 확인
git worktree list
# 강제 제거 (파일이 수정된 상태에서도)
git worktree remove --force ../booking-extract
# 남겨진 브랜치도 정리
git branch -D refactor/extract-method
git branch -D refactor/full-rewrite특히 Windows에서는 Worktree 안의 파일이 다른 프로세스에 의해 잠겨 있으면 제거가 실패할 수 있다. Claude Code 세션이나 IDE가 해당 디렉터리를 열고 있지 않은지 확인하고 제거하자. 이건 1-A절의 Windows 환경 주의사항(파일 핸들 락)과 연결된다.
Claude Code 체크포인트를 일상 루틴으로 만드는 법
지금까지 다룬 도구들을 일상 개발 루틴에 어떻게 녹이는지 정리한다.
작업 규모별 적용 기준
┌──────────────────────────────────────────────────────────┐
│ 작업 규모 │ 적용 도구 │ 예상 시간 │
├──────────────────┼───────────────────────┼───────────────┤
│ 한 파일, 10줄 │ 체크포인트만 │ 1~2분 │
│ (오타 수정, │ (Plan Mode 생략 OK) │ │
│ 변수명 변경) │ │ │
├──────────────────┼───────────────────────┼───────────────┤
│ 3~5개 파일 │ Plan Mode │ 5~15분 │
│ (메서드 추출, │ + 체크포인트 │ │
│ 인터페이스 추가)│ + /review │ │
├──────────────────┼───────────────────────┼───────────────┤
│ 10개+ 파일 │ Plan Mode │ 15~45분 │
│ (모듈 분리, │ + 체크포인트 │ │
│ 아키텍처 변경) │ + /review │ │
│ │ + /security-review │ │
├──────────────────┼───────────────────────┼───────────────┤
│ 구조적 불확실성 │ Git Worktree │ 30분~1시간 │
│ (최적 접근을 │ + 위 전부 │ (병렬 실행) │
│ 모르는 경우) │ + 비교 채택 │ │
└──────────────────────────────────────────────────────────┘핵심은 작업 규모에 맞게 도구를 선택하는 것이다. 오타 하나 고치는 데 Plan Mode까지 돌리면 과잉이고, 아키텍처를 바꾸면서 Plan Mode를 건너뛰면 위험하다.
팀에 도입할 때의 순서
혼자 쓸 때는 위 표를 자기 기준에 맞게 조정하면 되지만, 팀에 도입할 때는 순서가 중요하다.
- 1주차: 체크포인트 + 되돌리기만 소개한다. “Claude가 뭔가 잘못하면 Esc 두 번 누르세요.” 이것만으로도 AI 코딩에 대한 불안감이 크게 줄어든다.
- 2주차: Plan Mode를 추가한다. “큰 작업 전에는 Shift+Tab 눌러서 계획부터 보세요.” 설계 리뷰 습관이 생긴다.
- 3주차: /review를 추가한다. “Claude가 끝냈다고 하면 /review 한번 돌려 보세요.” 자기 검증 루프가 완성된다.
- 4주차 이후: Git Worktree 병렬 실험은 필요한 사람만. 모든 사람이 쓸 필요는 없다.
한꺼번에 전부 소개하면 “이거 배우는 게 일이네”라는 반응이 나온다. 하나씩, 각각의 가치를 체감하게 하는 게 정착의 비결이다.
CLAUDE.md에 파이프라인 규칙 넣기
5화에서 다룬 CLAUDE.md를 떠올려 보자. 체크포인트·Plan Mode·/review 파이프라인을 프로젝트 표준으로 만들려면, CLAUDE.md에 다음을 추가하면 된다.
# CLAUDE.md에 추가할 수 있는 파이프라인 규칙 (예시)
## 변경 작업 절차
### 소규모 변경 (파일 3개 이하)
- 바로 실행 가능. 체크포인트가 자동으로 찍힌다.
- 완료 후 /review 실행 권장.
### 중규모 이상 변경 (파일 3개 초과)
1. 반드시 Plan Mode로 시작할 것.
2. 계획 승인 후 실행.
3. 각 논리 단계 완료 시 테스트 실행.
4. 전체 완료 후 /review 필수.
5. 금액·인증·권한 관련 변경이 포함되면 /security-review 추가.
### 되돌리기 기준
- 같은 접근으로 3회 이상 되돌렸으면,
Plan Mode로 돌아가서 다른 접근을 제안할 것.
- 되돌리기 사유를 한 줄로 기록할 것
(같은 실수 반복 방지).이 규칙이 CLAUDE.md에 들어가면, Claude Code가 알아서 이 절차를 따른다. “파일이 5개 바뀌는 작업인데, CLAUDE.md에 Plan Mode로 시작하라고 되어 있으니 계획부터 보여드리겠습니다.” — 5화에서 다룬 “헌법”의 효과가 여기서도 작동한다.
이번 회차의 수익화 지점
이번 회차에서 다룬 Claude Code 체크포인트·Plan Mode·/review 파이프라인과 Git Worktree 병렬 실험은, 그 자체로 하나의 “안전한 AI 코딩 워크플로 컨설팅” 상품이 된다.
AI 코딩 도구를 도입했지만 “무서워서 큰 작업은 못 맡기겠다”는 팀이 생각보다 많다. 이유를 물으면 대부분 같은 말을 한다. “뭔가 잘못되면 되돌리기가 어려워서.” 이 불안을 해소하는 구체적인 워크플로 — 체크포인트로 안전망을 깔고, Plan Mode로 설계를 먼저 검증하고, /review로 결과를 재검증하는 3단계 파이프라인 — 를 팀 맞춤형으로 세팅해 주는 것이 서비스가 된다. 변경 규모별 적용 기준표, CLAUDE.md에 넣을 파이프라인 규칙 템플릿, 도입 4주 로드맵을 문서화하면 그게 곧 컨설팅 자료다. 1~2시간 온라인 세션으로 팀의 실제 프로젝트에 적용해 보는 워크숍 형태가 가장 전환율이 높다.
다음 회 예고
체크포인트로 안전망을 깔았으니, 다음은 반복되는 작업을 자동으로 실행되는 Skill로 만드는 법이다. .claude/skills/ 폴더에 SKILL.md 하나를 잘 써 놓으면, Claude가 상황에 맞게 알아서 호출한다. 9화에서는 Skills의 구조, description 작성법, 그리고 “왜 내 Skill은 영원히 호출되지 않는가”라는 함정까지 다룬다.
이전 글: 7화: 컨텍스트 관리 — 100만 토큰 시대의 절약 기술
다음 글: 9화: Skills — 반복 작업을 자동 호출되는 명령으로 만들기
관련 글: 4화: 프롬프트가 아니라 작업 지시서를 쓴다 | 6화: 권한·샌드박스·훅 — 사고 치기 전에 막는 3중 방어
Photo by Deon Black on Pexels
◀ 이전 7화 (다음 차수는 아직 게시되지 않았습니다)
자주 묻는 질문
Claude Code 체크포인트는 언제 자동으로 찍히나요?
Claude Code 체크포인트는 파일 시스템을 변경하는 도구 호출 직전에만 찍힙니다. Write 도구로 새 파일을 생성하거나, Edit 도구로 기존 파일을 수정하거나, Bash 도구로 파일을 변경하는 명령을 실행할 때 자동으로 Git 스냅샷이 만들어집니다. 반면 파일 읽기, 검색, 읽기 전용 명령 실행 시에는 체크포인트가 찍히지 않습니다.
Claude Code로 대규모 리팩터링을 안전하게 하려면 어떤 순서로 해야 하나요?
Plan Mode로 먼저 설계를 검토하고, 실행한 뒤 /review 명령으로 결과를 검증하는 이중 안전망 파이프라인을 거치는 것이 권장됩니다. 체크포인트가 자동으로 찍히므로 문제가 생기면 되돌리기 한 번으로 수십 개 파일 변경을 원상 복구할 수 있습니다. 이 구조가 없으면 리팩터링 실패 시 수작업으로 파일을 하나씩 복원해야 하는 수렁에 빠질 수 있습니다.
Git Worktree를 리팩터링에 활용하면 어떤 장점이 있나요?
Git Worktree를 사용하면 같은 문제에 대해 3가지 접근 방식을 동시에 시도하고, 그중 최선의 결과만 채택할 수 있습니다. 이를 통해 리팩터링 의사결정 비용이 사라지며, 어떤 방식이 가장 좋은지 실제 결과를 비교한 뒤 선택할 수 있습니다.
[…] 시리즈: Claude 활용 24회 — AI에게 일을 위임하는 법 (총 24화 중 9화)◀ 이전 8화 (다음 차수는 아직 게시되지 […]