덕삼
블로그

agy 실전 가이드 2편 — 실행 모드·권한·컨텍스트

agy 실전 가이드 2편입니다. 1편에서는 설치와 지침 파일을 다뤘습니다. 이번 편은 agy 에게 일을 얼마나 맡길지 정하는 장치, 그리고 그 일을 담는 컨텍스트를 다룹니다.

이번 편의 질문은 agy 에게 어디까지 묻지 않고 맡길 것인가입니다. 답은 실행 모드 네 가지와 action(target) 꼴의 권한 규칙이 그 경계를 정한다는 것입니다. 단 plan 모드는 도구를 막는 장치가 아니라 앞에 붙는 지시문이었습니다. 읽기만 시키려면 프롬프트에도 그렇게 적어야 합니다.

실행 모드는 네 가지입니다

공식 문서 기준으로 모드는 default, accept-edits, auto, plan 넷입니다. 파일 편집과 터미널 명령을 각각 어떻게 다루는지가 다릅니다.

모드파일 편집터미널 명령
default편집마다 diff 를 보여 주고 묻습니다묻습니다
accept-edits워크스페이스 안 편집은 묻지 않습니다묻습니다
auto워크스페이스 안 편집은 묻지 않습니다샌드박스 안에서 돌리고, 밖으로 나가는 명령은 자동 검토 뒤 위험한 것만 묻습니다
plan코드를 쓰기 전에 실행 계획을 내고 승인을 받습니다계획 단계에서는 조사만 합니다

세션 안에서는 Shift+Tab 으로 모드를 돌립니다. /config 의 Agent Mode 나 settings.json 의 agentMode 로 기본값을 저장할 수 있습니다. 한 번만 바꾸려면 agy --mode plan 처럼 플래그를 줍니다.

기본 모드는 1.5.7 에서 auto 로 바뀌었습니다

changelog 1.5.7 에 중요한 변경이 있습니다. 저장된 모드가 없는 세션은 auto 를 쓸 수 있는 환경이면 auto 로 시작합니다. 비대화형 -p 실행도 마찬가지입니다. 예전처럼 쓰려면 /config 에서 Default 를 고르라고 적혀 있고, 그러면 "agentMode": "" 가 저장됩니다.

제 antigravity-cli/settings.json 에는 agentMode 키가 없습니다. changelog 대로라면 1.5.7 이후 제 세션은 auto 로 시작했을 것입니다. 다만 직접 확인하지는 못했습니다. 비대화형 실행의 첫 이벤트에는 permission_mode: request-review 만 찍히고 모드 이름은 나오지 않았습니다. 그래서 스크립트에서 부를 때는 항상 --mode 를 명시합니다. 기본값이 또 바뀌어도 동작이 그대로이기 때문입니다.

auto 모드는 조건이 붙습니다. 공식 문서 기준으로 터미널 샌드박스(sandbox, 격리 실행 환경)와 개인 계정이 필요합니다. macOS·Linux 는 1.3.5 부터 씁니다. 샌드박스 밖으로 나가는 명령은 별도 모델이 검토합니다. 1.5.4 부터 이 검토에 추론을 덜 하는 Gemini Flash 모델을 씁니다. 1.5.10 에서는 샌드박스 안 명령이 ~/.config 를 기본으로 읽지 못하게 바뀌었습니다. 다른 프로그램이 거기에 토큰을 두기 때문이라고 적혀 있습니다.

plan 모드는 지시문입니다

plan 모드가 어떻게 구현됐는지 비대화형 실행으로 들여다봤습니다(2026-11-18, 1.5.10). --output-format stream-json 을 주면 첫 줄에 init 이벤트가 나옵니다.

{"event":"init","init":{"permission_mode":"request-review",
  "expanded_commands":[{"name":"plan","type":"system"}],
  "tools":["ask_permission","run_command","write_to_file","replace_file_content", "..."]}}

expanded_commands 에 plan 이 시스템 명령으로 찍힙니다. 공식 문서도 plan 모드가 /plan 지시문을 앞에 붙인다고 설명합니다. 도구 목록은 60개였고 run_command·write_to_file 이 그대로 있었습니다. 모드 없이 실행했을 때도 도구는 60개였습니다.

해석은 이렇습니다. plan 모드는 쓰기 도구를 빼는 장치가 아니라, 계획부터 세우라는 지시입니다. 그래서 저는 읽기만 시킬 때 프롬프트에 “도구를 쓰지 말라"를 함께 적습니다. plan 모드에서 쓰기 도구 호출을 런타임이 막는지는 시험하지 않았습니다. 파일을 고치게 하는 프롬프트가 필요해서입니다. 막는다면 이 해석은 반만 맞습니다.

하나 더 있습니다. 1.3.2 부터 --dangerously-skip-permissions 는 plan 모드의 계획을 자동 승인하지 않습니다. 이 플래그는 도구 권한 확인만 건너뛰고, 계획은 다시 사람의 검토를 기다립니다.

권한 규칙은 action(target) 꼴입니다

권한 규칙은 ~/.gemini/antigravity-cli/settings.json 의 permissions 아래 allow·deny·ask 목록에 적습니다. 제 파일의 allow 에는 352개가 쌓여 있었고 모두 command(...) 꼴이었습니다.

"permissions": { "allow": ["command(git show)", "command(git diff)", "command(git status)"] }

공식 문서 기준으로 액션은 command, read_file, write_file, read_url, execute_url, mcp, unsandboxed 등이 있습니다. command 는 낱말 앞부분이 같으면 맞고, regex: 를 붙이면 정규식으로 맞춥니다. 우선순위는 deny, ask, allow 순입니다.

모드와 별개로 toolPermission 설정이 셸 명령의 기본 처리를 정합니다. 기본값은 request-review 이고, strict 와 always-proceed 는 auto 모드보다 우선합니다. always-proceed 가 --dangerously-skip-permissions 와 같은 동작입니다.

352개는 많은 숫자입니다. 규칙이 쌓이면 무엇이 언제 열렸는지 알기 어려워집니다. 저는 Claude Code 가이드 1편에서 쓴 기준을 그대로 씁니다. 되돌릴 수 있는 명령만 열고, 이력을 지우는 명령은 계속 묻게 둡니다.

대화를 비우고 줄이는 명령

컨텍스트를 다루는 명령은 Claude Code 와 이름이 거의 같습니다.

명령하는 일
/clear (/new)대화를 비우고 새로 시작합니다
/compact대화를 요약해 압축합니다. 1.3.5 에 생겼습니다
/rewind앞선 체크포인트로 되돌립니다
/resume, agy -c, agy --conversation <ID>저장된 대화를 다시 엽니다
/context컨텍스트 사용량을 항목별로 보여 줍니다

/compact <메시지> 처럼 쓰면 요약한 뒤 그 메시지에 답합니다. 공식 문서는 대화가 길어지면 오래된 턴을 체크포인트 요약으로 자동 압축한다고 적습니다.

비대화형 실행에는 함정이 하나 있었습니다. 1.1.11 이전에는 -p "/clear" 가 대화를 비웠다고 답하면서 실제로는 아무것도 하지 않았습니다. 대화형 전용 명령이 프롬프트 글자로 넘어가 모델이 그럴듯하게 답한 것입니다. 지금은 이런 명령을 명시적으로 거절합니다.

/learn 은 교정을 규칙으로 옮깁니다

이 절은 공식 문서와 changelog 기준입니다. /learn 은 최근 대화에서 사용자가 바로잡은 내용을 찾아 규칙이나 스킬로 저장하자고 제안합니다. 먼저 learning_proposal.md 라는 제안서를 만들고, 사용자가 승인한 뒤에만 파일을 고칩니다. 저장 위치는 AGENTS.md·.agents/rules/·~/.gemini/config/ 등이고, 워크스페이스와 전역 가운데 하나를 에이전트가 고릅니다.

Claude Code 가이드 1편에서 “같은 지시를 세 번 하면 규칙"이라고 썼습니다. /learn 은 그 옮겨 적기를 도와주는 명령입니다. 주의할 점도 changelog 에 있습니다. 1.5.8 전에는 /learn 이 AGENTS.md 에 계속 덧붙여 크기 한도를 넘겼고, 넘친 뒷부분이 매 턴 조용히 잘렸습니다. 1편에서 본 24,000바이트 한도입니다. 승인하기 전에 제안서가 어느 파일에 얼마나 더하는지 봅니다.

Claude Code 와 다른 점

두 도구의 모드 체계는 닮았지만 이름과 플래그가 다릅니다. 표는 각 도구의 --help 출력 기준입니다(Claude Code 2.1.326, agy 1.5.10).

항목Claude Codeagy
모드 플래그--permission-mode--mode
모드 값acceptEdits, auto, bypassPermissions, manual, dontAsk, planaccept-edits, auto, plan (생략하면 기본)
확인 전부 건너뛰기--dangerously-skip-permissions--dangerously-skip-permissions
권한 규칙 예Bash(npm -v) 꼴command(git show) 꼴

agy 쪽의 특징은 auto 모드가 터미널 샌드박스를 전제로 한다는 점입니다. 샌드박스를 쓸 수 없는 환경에서는 Shift+Tab 을 눌러도 auto 를 건너뛴다고 문서에 적혀 있습니다.

실사례 — 숫자 하나를 묻는 데 입력 토큰 18,852개

2026-11-18 에 빈 폴더에서 agy 1.5.10 을 --mode plan 으로 불렀습니다. 프롬프트는 “도구를 쓰지 말고 숫자 하나로만 답하라: 17 더하기 25 는?” 이었습니다. 답은 42 였고 JSON 출력의 usage 는 다음과 같았습니다.

항목값
input_tokens18,852
output_tokens128
thinking_tokens122
duration_seconds3.9
명령 시작부터 종료까지9.9초

질문을 바꿔 두 번 더 물었습니다(한 번은 모드 없이). 입력 토큰은 18,849개와 18,824개였습니다. 질문 내용과 상관없이 약 1만 9천 토큰이 매번 깔린다는 뜻입니다. 그 안에는 시스템 프롬프트와 도구 정의가 있을 것입니다. 1편의 전역 지침(10,956바이트)과 스킬 목록도 들어 있을 것입니다. 항목별 비중은 대화형 /context 에서만 보여 이번에는 나누지 못했습니다.

해석은 이렇습니다. agy 를 짧은 질문에 자주 부르면 고정비가 답보다 훨씬 큽니다. 전역 지침과 스킬을 줄이는 일이 곧 매 턴 비용을 줄이는 일입니다. 시간에도 고정비가 있습니다. 명령 전체는 9.9초였고, agy 가 보고한 duration_seconds 는 3.9초였습니다. 나머지 약 6초는 시작에 걸렸습니다. 측정은 한 번이라 이 6초는 참고치입니다.

정리

2편의 답은 이렇습니다. agy 에게 맡기는 범위는 모드와 action(target) 규칙이 정합니다. 기본 모드는 1.5.7 에서 auto 로 바뀌었고, plan 모드는 도구를 막지 않는 지시문이었습니다. 스크립트에서는 모드를 늘 명시하고, 읽기만 시킬 때는 프롬프트에도 적습니다.

다음에 확인할 것은 /context 화면입니다. 1만 9천 토큰 가운데 무엇이 가장 큰지 보면 줄일 곳이 나옵니다. 3편에서는 그 비용의 한 축인 스킬과 서브에이전트, 그리고 이를 묶어 배포하는 플러그인을 다룹니다.