코딩 에이전트가 실수했을 때 되돌릴 수 없다면, 아무리 성능이 좋아도 실제 프로젝트에 붙이기 어렵다. SafeSandbox는 그 간극을 메우는 도구다. 에이전트가 파일을 건드리기 전 상태를 자동으로 스냅샷 찍어두고, 오작동이 생기면 특정 시점으로 되돌린다.
1. 왜 지금 이걸 봐야 하나
Cursor, Claude Code, Codex 같은 코딩 에이전트는 이제 로컬 파일을 직접 수정한다. 단순한 자동완성이 아니라, 함수를 통째로 교체하거나 여러 파일을 동시에 편집하는 수준이다.
문제는 에이전트 품질이 충분해도 실행 환경에 안전망이 없으면 한 번의 오작동이 프로젝트 전체를 건드린다는 점이다. git commit 전 상태라면 git checkout으로 복구할 수 있지만, 에이전트가 여러 단계에 걸쳐 파일을 바꾸면 어느 시점으로 돌아가야 하는지 파악하는 것 자체가 어렵다.
실제로 이런 상황이 생긴다.
- 에이전트가 리팩터링 도중 의존성이 있는 유틸 함수를 삭제함
- 테스트는 통과했지만 3파일 뒤에서 빌드가 깨짐
- 어느 수정이 문제였는지 역추적하는 데 30분 이상 소요
SafeSandbox가 주목받는 이유가 여기 있다. 에이전트 경쟁이 "얼마나 잘 쓰냐"에서 "얼마나 안전하게 실행하냐"로 넘어가는 시점이 됐기 때문이다.
2. 핵심 아이디어
실행 전 스냅샷 → 에이전트 실행 → 문제 발생 시 롤백이 전부다.
개념 자체는 단순하지만, 실무에서 이걸 직접 구현하면 복잡해진다. 스냅샷 시점을 언제로 잡을지, 롤백 범위를 파일 단위로 할지 디렉터리 단위로 할지, 에이전트가 여러 단계로 실행될 때 중간 체크포인트를 어떻게 만들지가 다 다르다.
SafeSandbox는 이 설정을 레이어로 분리한다.
| 구성 항목 | 설명 | 기본값 |
|---|---|---|
snapshot_on |
스냅샷 트리거 (before_run / interval) | before_run |
rollback_scope |
롤백 단위 (file / directory / project) | directory |
checkpoint_interval |
중간 스냅샷 간격 (초) | 60 |
max_snapshots |
보관할 스냅샷 최대 수 | 10 |
가장 중요한 판단 기준은 두 가지다.
첫째, 에이전트가 몇 단계로 실행되느냐. 단일 작업이면 before_run 스냅샷 하나로 충분하다. 긴 체인이면 checkpoint_interval을 설정해 중간 복원 지점을 만들어야 한다.
둘째, 롤백 범위를 어디까지 잡느냐. 파일 단위 롤백은 정밀하지만 연관 파일까지 같이 되돌리지 않으면 의존성이 깨질 수 있다. 프로젝트 전체 롤백은 안전하지만 의도하지 않은 변경까지 날아간다.
3. 바로 따라하는 방법
SafeSandbox를 로컬 프로젝트에 붙이는 기본 흐름이다.
# 설치
pip install safesandbox
# 프로젝트 루트에 설정 파일 생성
safesandbox init
safesandbox init을 실행하면 프로젝트 루트에 .safesandbox.yaml이 생성된다.
# .safesandbox.yaml
snapshot_on: before_run
rollback_scope: directory
checkpoint_interval: 60
max_snapshots: 10
watch_paths:
- src/
- tests/
ignore_paths:
- node_modules/
- .git/
- __pycache__/
에이전트 실행 전에 SafeSandbox를 래퍼로 감싸는 방식이 가장 깔끔하다.
from safesandbox import Sandbox
with Sandbox(config=".safesandbox.yaml") as sb:
sb.snapshot("before_refactor")
# 에이전트 실행
result = run_agent(task="리팩터링: utils.py 함수 분리")
if not result.success:
sb.rollback("before_refactor")
print("롤백 완료. 에이전트 실행 전 상태로 복원됨.")
else:
sb.commit() # 스냅샷 확정, 보관 목록에 추가
Claude Code나 Cursor처럼 CLI로 에이전트를 실행하는 환경이라면 훅 방식으로도 붙일 수 있다.
# 에이전트 실행 전 스냅샷
safesandbox snapshot --label "pre-agent-$(date +%s)"
# 에이전트 실행
claude "tests/ 디렉터리 아래 커버리지 80% 이하 파일 리팩터링해줘"
# 빌드 검증
npm test
# 실패 시 롤백
if [ $? -ne 0 ]; then
safesandbox rollback --latest
fi
롤백 후 상태를 확인하는 명령어는 아래와 같다.
# 스냅샷 목록 확인
safesandbox list
# 특정 스냅샷과 현재 상태 비교
safesandbox diff --label "pre-agent-1716864000"
# 실제 롤백 (dry-run으로 먼저 확인)
safesandbox rollback --label "pre-agent-1716864000" --dry-run
safesandbox rollback --label "pre-agent-1716864000"
기대 출력:
[dry-run] 롤백 대상 파일:
src/utils.py (현재 → 스냅샷 시점)
src/handlers/order.py (현재 → 스냅샷 시점)
tests/test_utils.py (변경 없음, 스킵)
[dry-run] 총 2개 파일 복원 예정. --dry-run 제거 후 실제 롤백.
4. 운영할 때 조심할 점
스냅샷 저장 용량이 생각보다 빠르게 찬다. 대형 모노레포에서 rollback_scope: project로 설정하면 스냅샷 하나가 수백 MB가 될 수 있다. max_snapshots를 5 이하로 줄이거나, watch_paths를 에이전트가 실제로 건드리는 디렉터리로만 좁혀야 한다.
중간 체크포인트와 git commit 시점이 어긋나면 혼란이 생긴다. SafeSandbox 스냅샷은 git과 별개로 움직인다. 에이전트 세션이 끝난 뒤 SafeSandbox로 확정된 상태를 git에 커밋하는 순서를 팀 내에서 합의해두는 게 좋다.
Mac/Linux 환경 차이가 있다. 파일 시스템 이벤트 감지(fsevents vs inotify)가 달라서 checkpoint_interval 정확도가 다를 수 있다. Docker 컨테이너 안에서 실행할 때는 볼륨 마운트 경로가 watch_paths에 제대로 반영되어 있는지 확인해야 한다.
에이전트가 외부 API를 호출하거나 DB를 수정한 경우는 SafeSandbox로 롤백이 안 된다. 파일 시스템 범위에서만 동작하기 때문이다. 에이전트 작업 범위를 파일 수정에 한정하거나, 외부 사이드이펙트가 있는 작업은 별도 롤백 전략을 갖춰야 한다.
다음에 개선할 부분으로는 스냅샷 메타데이터에 에이전트 실행 로그를 함께 저장하는 구성을 추가하면 롤백 판단이 훨씬 빨라진다. sb.snapshot("label", metadata=result.log) 형태로 붙이면 어떤 작업이 어느 시점의 스냅샷을 만들었는지 추적할 수 있다.
자주 묻는 질문
SafeSandbox 같은 롤백 레이어가 필요한 시점은 언제일까?
에이전트가 단일 파일 하나만 수정하는 수준이라면 git undo로 충분하다. 여러 파일을 연달아 수정하거나, 에이전트가 자율적으로 여러 단계의 작업을 이어서 실행하는 환경이라면 SafeSandbox처럼 중간 스냅샷을 찍어두는 구조가 필요해진다. 실제 코드베이스에 에이전트를 붙이기 시작하는 시점이 도입 타이밍이다.
적용 전에 먼저 확인해야 할 것이 있다면?
watch_paths 범위를 먼저 정해야 한다. 너무 넓게 잡으면 스냅샷 용량이 폭증하고, 너무 좁게 잡으면 에이전트가 건드린 파일이 스냅샷에 빠질 수 있다. 처음엔 에이전트가 주로 작업하는 디렉터리 1~2개만 지정하고 운영 경험을 쌓은 뒤 범위를 조정하는 방식이 안전하다.
롤백 후 제대로 복원됐는지 어떻게 검증할까?
safesandbox diff 명령어로 스냅샷 시점과 현재 파일 상태를 비교할 수 있다. 복원 뒤에는 기존 테스트 스위트를 그대로 돌려서 빌드와 테스트가 스냅샷 시점과 동일하게 통과하는지 확인하는 게 가장 확실하다.
마무리
에이전트 성능 경쟁은 이미 어느 정도 수렴 중이다. 다음 변수는 실행 환경의 안전성이다. SafeSandbox는 그 시작점으로, 스냅샷과 롤백이라는 단순한 원리를 에이전트 워크플로에 끼워 넣는 방식으로 실무 리스크를 줄인다.
다음 글에서는 SafeSandbox를 CI/CD 파이프라인과 연결해 PR 단위로 에이전트 실행 이력을 관리하는 구성을 다룰 예정이다.
🐦 X에서 더 빠르게: @baegseungh7061
📚 이 시리즈 더 보기: 전체 글 목록
💌 새 글 알림: X 팔로우 또는 블로그 RSS 구독