튜토리얼 10: 체크포인트 — AI의 실행 취소 버튼

중요한 걸 방금 삭제했다는 사실을 깨달았을 때의 그 가라앉는 기분, 기억나시나요? 몇 시간을 쏟은 파일이었을 수도 있고, 모든 걸 망가뜨린 설정 변경이었을 수도 있습니다. 현실 세계에서 파일 시스템에는 Ctrl+Z가 없습니다. 하지만 Hermes Agent에는 있습니다. 바로 체크포인트라는 기능이죠.

체크포인트는 비디오 게임의 세이브 포인트라고 생각하면 됩니다. AI 에이전트가 위험한 작업을 하기 전에 — 파일을 덮어쓴다거나 파괴적인 명령을 실행하기 전에 — 프로젝트의 스냅샷을 빠르게 찍어둡니다. 문제가 생기면 단 하나의 명령으로 그 스냅샷으로 되돌아갈 수 있습니다. 프로젝트 전체에 실행 취소 버튼이 생기는 셈이죠.

안전망 켜기

솔직히 말씀드리면, 체크포인트는 Hermes v2에서 선택 사항입니다. 대부분의 사용자는 필요 없고, 저장 공간도 시간이 지나면서 늘어날 수 있습니다. 하지만 중요한 작업을 하고 있다면, 이 기능은 생명의 은인입니다.

활성화하는 방법은 두 가지입니다:

세션별 (채팅 한 번만):

hermes chat --checkpoints

전역 설정 (~/.hermes/config.yaml):

checkpoints:
  enabled: true

이게 전부입니다. 활성화하면 Hermes는 파괴적인 작업이 발생하기 전에 자동으로 프로젝트 스냅샷을 찍습니다.

무엇이 체크포인트를 트리거하나요?

Hermes는 스냅샷을 찍을 때를 똑똑하게 판단합니다. 다음을 감시합니다:

파일 작업 — write_file, patch 같은 것들
파괴적인 터미널 명령 — rm, mv, sed -i, truncate, 그리고 git reset이나 git clean까지

가장 좋은 점은? 턴마다 디렉토리당 최대 1개의 체크포인트만 생성하므로, 긴 세션에서 수백 개의 스냅샷이 쌓이는 일은 없습니다.

되돌리기: 슬래시 명령어

채팅 세션에서 /rollback은 가장 친한 친구입니다:

명령어	기능
`/rollback`	변경 통계와 함께 모든 체크포인트 표시
`/rollback <N>`	체크포인트 N으로 복원, 직접 수정한 내용은 유지
`/rollback <N> --all`	전체 복원 — 직접 수정한 내용도 덮어씀
`/rollback diff <N>`	체크포인트 N과 현재 사이의 변경 사항 미리보기
`/rollback <N> <file>`	체크포인트 N에서 파일 하나만 복원

기본 /rollback <N>은 영리합니다. 직접 손으로 수정한 내용은 유지하고, 에이전트가 한 작업만 되돌립니다. 완전히 초기화하려면 --all을 사용하세요.

터미널에서 저장소 관리하기

채팅 밖에서는 CLI 명령어로 체크포인트를 확인하고 관리할 수 있습니다:

hermes checkpoints              # 크기, 프로젝트, 세부 내역 표시
hermes checkpoints status       # 위와 동일
hermes checkpoints list         # status의 별칭
hermes checkpoints prune        # 고아 데이터와 오래된 데이터 정리
hermes checkpoints clear        # 모두 삭제 (확인 후 진행)
hermes checkpoints clear-legacy # 이전 v1 마이그레이션 아카이브 제거

내부적으로 어떻게 동작하나요?

“이게 내 실제 git 저장소를 건드리나요?“라고 궁금하실 수 있습니다. 아닙니다. Hermes는 ~/.hermes/checkpoints/store/에 별도의 “그림자 저장소”를 유지합니다. 실제 프로젝트의 .git은 절대 건드리지 않습니다.

모든 프로젝트가 이 하나의 저장소를 공유하며, git이 콘텐츠 주소 지정 방식을 사용하기 때문에 여러 프로젝트에 나타나는 파일은 한 번만 저장됩니다. 놀랍도록 효율적이죠.

설정 조정하기

체크포인트가 사용하는 저장 공간을 제어할 수 있습니다:

checkpoints:
  enabled: true
  max_snapshots: 20           # 프로젝트당 최대 체크포인트 수
  max_total_size_mb: 500      # 전체 저장소 크기 상한
  max_file_size_mb: 10        # 이보다 큰 파일은 건너뜀
  auto_prune: true            # 오래된 항목 자동 정리
  retention_days: 7           # 항목을 7일간 보관
  min_interval_hours: 24      # 정리는 하루 최대 1회

자동 정리 기능은 똑똑합니다. 시작 시 오래된 항목을 정리하지만 “고아” 항목(폴더를 찾을 수 없는 프로젝트)은 절대 삭제하지 않습니다. 폴더가 없다는 건 외장 드라이브가 아직 마운트되지 않았을 수도 있기 때문입니다. 고아 항목 정리는 hermes checkpoints prune을 직접 실행해야 합니다.

프로젝트의 실행 취소 버튼

체크포인트는 AI 에이전트가 자유롭게 작업하도록 믿고 맡길 수 있는 자신감을 줍니다. 언제든지 과거로 돌아갈 수 있다는 걸 알기 때문이죠. 코드 리팩토링, 설정 실험, 또는 그냥 마음의 평화가 필요할 때 — 활성화해 볼 가치가 있습니다.

다음 세션에서 hermes chat --checkpoints로 시도해 보세요. 롤백이 필요 없을 수도 있습니다. 하지만 필요할 때, 그게 있다는 사실에 감사하게 될 겁니다.