공식 레퍼런스: Trusted folders · Sandboxing · Checkpointing · Plan Mode
학습 경로
- Gemini CLI 시작하기 — 설치, 인증, 메모리 기초
- 100만 토큰의 장점 — 전체 코드베이스로 작업하기 — 저장소 단위 분석을 낭비 없이
- Gemini Extensions & MCP — 커스텀 워크플로 만들기 — 명령, MCP, 스킬 패키징
- Gemini CLI MCP 연동 — 외부 도구와 데이터 연결하기
- Trusted Folders, Sandboxing, 그리고 Restore — 신뢰, 격리, 복구 ← 현재 문서
- Gemini Task Decomposition — 복잡한 작업을 성공적으로 완수하기
- Gemini CLI Headless Automation — 스크립트, CI, 구조화 출력
- Gemini Git Worktrees — 병렬 작업 최적화
- 서브 에이전트와 스킬 오케스트레이션 — 위임과 전문가 워크플로
- GEMINI.md Mastery — 계층적 컨텍스트 설계
- Gemini 첫날 안전 루프
- Multi-Agent Orchestration — 서브 에이전트와 스킬 조합
- Gemini 주간 단위 딜리버리 플레이북
- Gemini GitHub Actions — CI 자동화와 리뷰
- Gemini 고위험 변경 통제 모델
- Gemini Effective Prompting — 100만 토큰을 지배하는 프롬프팅
- Gemini 운영 매뉴얼 — 팀 단위 CLI 딜리버리 리듬
- Gemini Hooks Automation — 로컬 자동화의 방패
- Gemini 사고 복구 플레이북
- Mid-size Refactor Playbook — 중규모 리팩터링
- Gemini 사고 후 하드닝 루프
- Gemini 카오스 복원력 드릴
- Human-Agent Handoffs — 인간과 AI의 릴레이
- Ralph Persistence Loops — 끝까지 물고 늘어지는 자가 치유
- Gemini 복원력 지표와 SLO
- Release Readiness Automation — 배포 자동화
- ADR Automation — 아키텍처 결정 기록 자동화
이 문서에서 참고한 공식 문서
- trusted / untrusted workspace에서 달라지는 동작 — Trusted folders
- sandbox 실행 방식과 목적 — Sandboxing
- shadow Git checkpoint와 restore 흐름 — Checkpointing
Gemini CLI 안전성은 한 스위치가 아니라 레이어다
“Gemini CLI가 안전한가요?”라고 물으면 하나의 답을 기대하기 쉽습니다. 하지만 실제로는 실패 유형마다 대응하는 여러 레이어가 있습니다.
- Trusted folders — 저장소가 세션을 얼마나 바꿀 수 있는지 통제
- Plan Mode — 너무 일찍 수정하지 못하게 제어
- Sandboxing — 위험한 실행을 호스트 밖으로 격리
- Checkpointing + Restore — 잘못된 수정에서 빠르게 복구
이 네 가지를 같이 이해해야 Gemini CLI를 “빠르지만 불안한 도구”가 아니라 통제 가능한 엔지니어링 도구로 쓸 수 있습니다.
trusted folders는 저장소가 세션에 개입할 권한을 정한다
trusted folders는 첫 번째 관문입니다. 이 저장소를 Gemini CLI가 믿을 만한 작업 공간으로 볼지, 아니면 조심스럽게 격리된 상태로 다룰지를 결정합니다.
특히 아래 상황에서는 untrusted로 시작하는 편이 맞습니다.
- 내가 소유하지 않은 고객사 저장소
- 막 클론한 오픈소스 프로젝트
- 스크립트가 많은 샘플 저장소
- 보안 이슈 분석처럼 조심스럽게 열어야 하는 코드
이 trust prompt는 단순한 확인창이 아닙니다. “이 repo가 로컬 설정과 동작으로 내 세션을 바꿔도 되는가?”를 묻는 단계입니다.
좋은 기본값은 "먼저 읽고, 나중에 trust"다
제가 추천하는 루틴은 이렇습니다.
- 처음에는 untrusted로 연다.
- 디렉터리 구조, lockfile, scripts, 설정 파일을 본다.
- 로컬 규칙과 명령이 무엇인지 이해한 뒤에 trust한다.
이 습관 하나로, repo-local 명령이나 설정 때문에 깜짝 놀랄 가능성이 크게 줄어듭니다.
Plan Mode는 "실행 시점"을 늦춰 준다
trusted folders가 “이 저장소를 믿어도 되는가?”를 다룬다면, Plan Mode는 “지금 수정해도 되는가?”를 다룹니다.
복잡한 작업일수록 가장 안전한 순서는 아래와 같습니다.
- 먼저 Plan Mode에 들어간다
- 아키텍처와 리스크를 조사한다
- 수정 범위를 결정한다
- 전략이 확정됐을 때만 기본 모드로 돌아온다
AI Native Notes 같은 다국어 콘텐츠 저장소에서는 이 단계가 특히 중요합니다. slug, frontmatter, locale parity는 한번 꼬이면 UI 전체가 어긋나기 쉽기 때문입니다.
sandboxing은 판단이 아니라 실행 리스크를 다룬다
sandboxing은 다음 레이어입니다. 에이전트가 셸 명령을 돌리거나 의존성을 설치하거나 낯선 코드를 실행해야 할 때, 그 실행을 호스트 밖의 격리 환경으로 밀어 넣는 역할을 합니다.
이럴 때 특히 유용합니다.
- postinstall 스크립트가 불분명한 패키지 설치
- 낯선 저장소에서 테스트 / 빌드 실행
- 제3자 샘플 앱 검증
- 새 자동화 체인이 로컬 머신에 어떤 영향을 줄지 아직 모를 때
정리하면:
- Plan Mode는 해도 되는가를 통제하고
- Sandboxing은 어디서 실행할 것인가를 통제합니다.
둘은 같은 기능이 아니라 서로 보완하는 기능입니다.
checkpointing은 필요해진 뒤에야 고마운 안전망이다
checkpointing은 파일 쓰기 전에 복구 지점을 만들어 줍니다. 덕분에 에이전트가 조금 더 빠르게 움직여도 매번 재난 복구처럼 대응할 필요가 없습니다.
특히 아래 상황에서 체감이 큽니다.
- 많은 파일을 한 번에 수정할 때
- 프롬프트 버전을 바꿔 가며 실험할 때
- 포맷 규칙이 엄격한 저장소에서 작업할 때
- cleanup / refactor 성격의 수정일 때
restore는 Git을 대체하지는 않지만, “작업은 했는데 diff가 마음에 들지 않는다”는 순간을 빠르게 되돌리기에 아주 좋습니다.
저장소 유형마다 guardrail을 다르게 쓰자
| 상황 | Trust | Plan Mode | Sandbox | Checkpoint |
|---|---|---|---|---|
| 낯선 외부 저장소 | untrusted로 시작 | 거의 항상 사용 | 대체로 사용 | 선택 |
| 내가 운영하는 프로덕션 저장소 | 제한적으로 trust | 넓은 작업이면 사용 | 위험한 명령일 때만 | 대형 수정 시 사용 |
| 빠른 문구 수정 | trusted | 선택 | 보통 불필요 | 선택 |
| 자동화 / CI 실험 | 신뢰된 runner | 사전 설계 권장 | 사용 권장 | Git / artifact와 병행 |
핵심은 마찰을 최대화하는 것이 아니라, 위험이 있는 곳에만 안전 예산을 쓰는 것입니다.
안전 장치는 사고력도 좋아지게 만든다
재미있는 점은, 이런 제약이 단지 사고 방지 장치만은 아니라는 것입니다. 프롬프트 자체를 더 명확하게 만듭니다.
- "수정하지 말고 조사만 해줘"
- "이 명령은 sandbox 안에서만 실행해줘"
- "파일 바꾸기 전에 checkpoint를 남겨줘"
이런 식의 제약은 가드레일이면서 동시에 좋은 task design이기도 합니다.
이 저장소에서 추천하는 실제 사용 루틴
AI Native Notes 기준으로는 아래 패턴이 좋습니다.
- 외부 기여가 섞인 영역은 untrusted로 먼저 열기
- 네비게이션, 로케일 구조, slug를 건드릴 때는 Plan Mode 먼저
- 여러 MDX를 고칠 때는 checkpointing 켜기
- 실제 셸 실행이나 설치가 필요할 때만 sandboxing 사용
이렇게 하면 콘텐츠 작업의 속도는 유지하면서도, “문서 repo라서 안전하겠지” 같은 위험한 낙관을 피할 수 있습니다.
다음에 읽으면 좋은 글
- 안전한 탐색을 자동화로 연결하려면 Gemini CLI Headless Automation
- 위임과 전문가 모드 위에 guardrail을 얹는 법은 서브 에이전트와 스킬 오케스트레이션