| name | agy |
| description | Google Antigravity CLI(agy)를 가재코드에서 원샷으로 호출한다. 이미지 인식(비전), 이미지 생성(generate_image), 긴 문서 작업에 Gemini를 쓸 때. print 모드(-p) 실행 레시피, scratch 폴더 함정, 타임아웃, 증거 강제 프롬프트 규칙 포함. Triggers: agy, antigravity, 이미지 생성, 이미지 인식, 이미지 보기, 그림 그려, 비전, 멀티모달, 제미나이 |
agy — Antigravity CLI 원샷 호출 (멀티모달 전담)
agy는 Google Antigravity CLI다(Go 바이너리, ~/.local/bin/agy, CodexBar가 세션 관리).
가재코드 입장에서는 외부 모델(gemini-3.x)에 붙는 멀티모달 포트다.
이 세션에 vision이 없거나 이미지 생성이 필요하면 agy에 위임한다.
실측 기준(2026-08-22): 비전 ✓, generate_image ✓(1024×1024 PNG+JPG, 장당 ~40초),
--output-format json ✓(usage 토큰수 포함).
언제 쓰나 / 쓰지 않나
- 쓴다: 이미지를 봐야 할 때(스크린샷 검수, 차트 판독, 렌더 결과 확인),
이미지를 만들어야 할 때(배지, 일러스트, 표지), Gemini 계열 판단이 필요할 때.
- 쓰지 않는다: agy가 못 하는 검증(파일 내용 grep, 테스트 실행)은 가재코드가 직접 한다.
agy 보고를 최종 사실로 취급하지 않는다 — 아래 "프롬프트 작성 규칙"으로 증거를 뽑고,
산출물(파일 크기, file 출력, 결과물 내용)은 가재코드가 다시 확인한다.
기본 레시피 (print 모드)
프롬프트는 반드시 파일로 쓰고 $(cat ...)로 넣는다(길고 한국어·멀티라인이라 인자 직접 삽입은 사고난다):
cd <작업 워크스페이스>
cat > /tmp/agy_prompt.txt <<'EOF'
<지시문 — 아래 "프롬프트 작성 규칙" 참고>
EOF
agy -p "$(cat /tmp/agy_prompt.txt)" \
--dangerously-skip-permissions \
--model gemini-3.7-flash-high \
--print-timeout 10m > /tmp/agy_run.log 2>&1
tail -40 /tmp/agy_run.log
--model: 빠른 검수·단숨 작업 gemini-3.7-flash-high, 정밀/긴 문서 작업 gemini-3.1-pro-high.--print-timeout: 기본 5m은 실전에선 부족하다(타임아웃 Error: timeout waiting for response로 죽는 걸 실제로 당했다). 단숨 510m, 문서 작업 1520m.- bash 도구에서는 포그라운드로 실행한다.
nohup ... & 백그라운드는 세션 종료 때
프로세스 그룹째 죽는 것을 실측으로 확인했다(로그 0바이트로 소멸). 도구 timeout을
print-timeout보다 넉넉히(예: print-timeout 10m ↔ timeout 700) 잡는다.
- 구조화 필요하면
--output-format json(conversation_id, status, response, usage 반환).
--json-schema로 스키마 강제도 가능하다(help 문서 기준).
- 대화 이어가기:
-c(가장 최근 대화), --conversation <id>.
멀티모달 1: 이미지 인식(비전)
프롬프트에 절대경로를 쓰면 agy가 자체 이미지 뷰어로 직접 본다:
/Users/abs/path/img.png 이미지를 직접 보고: 1) <질문> 2) <질문>
이미지를 못 봤다면 못 봤다고 솔직히 적어라.
검증 예시(실측): 뱃지 이미지에서 "안녕" 텍스트·파란 원·아이보리 배경을 정확히 판독.
로컬 vision 없는 세션의 공식 판독 경로로 쓴다. 슬라이드 검수·UI 비교에도 유효.
멀티모달 1.5: 다이어그램 생성 (벡터 품질)
흐름도·구조도는 래스터 생성 금지, 코드로 그리게 한다(실측: agy가 스스로
tectonic(XeLaTeX)+fontspec+Apple SD Gothic Neo를 골라 PDF→300DPI PNG 산출,
한글 자소 깨짐 0·벡터 품질 비전 검증 통과). 프롬프트 뼈대:
<다이어그램 사양: 노드/화살표/분기 라벨>
제약:
- generate_image(래스터) 사용 금지 — 텍스트가 깨진다
- 코드로 그려라: tectonic(LaTeX)·graphviz·python 등 이 머신에 있는 것만
- 없는 도구는 설치하지 마라
- 산출: <경로>.png (PDF 중간물 남겨도 좋다)
보고: 사용한 도구·명령, 한글 폰트 처리, file 출력
- 텍스트+셸 작업이라 이미지 생성 쿼터와 무관 — 창 소진 상태에서도 된다.
- 검증은 agy 비전: "라벨을 그대로 인용하라" + 구조 일치 + 자소 깨짐 체크.
- LaTeX 경로가 실패하면(폰트·라이브러리 지식 부족) 프리앰블 힌트를 준다:
\usepackage{fontspec} + \setmainfont{Apple SD Gothic Neo} (macOS 기본 한글).
멀티모달 2: 이미지 생성
agy 내장 generate_image 도구를 쓴다. 파일이 cwd가 아니라
~/.gemini/antigravity-cli/scratch/에 떨어진다(mv 지시를 무시하는 것을 실측).
그래서 반드시 후처리·검증까지 프롬프트에 박는다:
generate_image 도구로 '<묘사>' 이미지를 생성하라.
생성되면 ~/.gemini/antigravity-cli/scratch/ 에서 현재 디렉토리로 <이름>.png 로 mv 하고,
`ls -la <이름>.png && file <이름>.png` 출력을 그대로 보고에 붙여라.
도구가 없으면 없다고 솔직히 적어라. 못하면서 했다고 하지 마라.
실행 후 가재코드가 직접 확인: ls -la, file, 필요하면 비전으로 agy에게 다시 판독시켜
생성·판독 루프를 돈다. 장당 ~40초, 1024×1024 PNG(+JPG 사본)가 기본 출력.
생성 쿼터가 막혀 있으면 엔진을 갈아끼운다 — codex exec --skip-git-repo-check "<과제>"
로 Codex 내장 imagegen(image_gen 도구)에 위임하는 경로가 있다(실측: 5시간 창 소진
상태에서 코난쌤 가이드 이미지 2장 생성, 1672×941). 참조 앵커 경로를 과제에 그대로
전달하면 캐릭터 재현도 된다. 생성물은 $CODEX_HOME에서 프로젝트로 이동.
검증은 여전히 agy 비전(쿼터 무관)으로 — 보고를 믿지 않고 라벨 인용으로 재검.
배치 생성 (여러 컷을 한 실행으로)
컷마다 agy를 새로 띄우면 인증·부팅에 ~20초씩 낭비된다. 하나의 -p 실행에서
N컷을 순차 생성시킨다(실측: 9컷 1실행, 전부 성공).
[고정 스타일] 블록을 문서화해 두고, 컷 목록(파일명+포즈)을 번호로 나열.
각 컷은 서로 독립 생성(이전 결과를 편집해 이어 만들지 않는다).
컷마다 scratch에서 대상 경로로 mv 하고 file 출력을 기록.
실패 컷은 그 컷만 재생성.
--print-timeout: N×1분 + 여유. 9컷에 15m면 충분했다.- 캐릭터 일관성: 모든 컷의 프롬프트에 동일한 스타일 블록을 verbatim으로
박는다(앵커 이미지를 먼저 만들고 승인 후 고정). 생성 결과끼리 연결하지 않는다.
- 이미지에 텍스트 금지 — 한글이 가끔 렌더돼도 규칙은 "텍스트는 외부 편집"으로 지킨다.
- 기존 캐릭터 재현: 프롬프트 맨 앞에 참조 이미지 절대경로를 주고 "먼저 이 참조를
직접 보고 파악하라" → 이어 "위 참조와 동일 인물"로 스타일 고정 문단을 주면
generate_image가 같은 캐릭터를 재현한다(실측: 안경·점퍼·선화 스타일까지 일치 확인).
승인된 앵커가 이미 있다면 새로 만들지 말고 이 경로를 써라.
- 쿼터(5시간 고정 창): 이미지 생성은
gemini-3.1-flash-image의 별도 capacity를
쓴다 — /usage의 "Gemini Models %"는 텍스트 토큰 버킷이라 이 버킷을 안 보여준다.
실측 ~12장/5시간 창, 초과 시 429 "exhausted your capacity on this model" +
절대 리셋 시각(quotaResetTimeStamp). 분당 rate limit이 아니므로 재시도는 무의미 —
리셋 시각을 기다려라. 사용자 실물 자산이 있으면 그게 우선이다.
- 비전(판독·OCR)은 생성 쿼터와 무관 — 이미지 읽기는 메인 텍스트 모델의
멀티모달 입력이라 토큰 버킷을 쓴다(실측: 생성 429 직후 6분에 OCR 완전 정상).
생성이 막혀도 비전 검수 루프는 계속 돌려도 된다.
- 커뮤니티 검증 사실(2026-03~04, Antigravity-Manager #1608 · antigravity-studio
error_429.md · Google AI 포럼 130212/132342): 동일 오류 문구 광범위 보고.
gemini-3.1-flash-image가 Antigravity 유일의 이미지 모델(타 모델명 404)이라
모델 교체 불가. 계정당 성공 후 300s·429 후 1h 쿨다운 권장 — 난폭한 재시도는
계정 밴 위험. 대량 작업은 5시간 창당 ~10장 이하로 설계하고, 실물 자산 수집이
우선. (이중 한도: 5시간 스프린트 + 주간 베이스라인 — 주간 소진 시 5시간 타이머가
돌아도 잠금 유지 보고 다수.)
비전 검수 루프 (렌더 QA)
soffice 등으로 렌더한 이미지를 agy에게 보여 검수시키고, 지적을 고친 뒤 다시 검수 —
이 루프로 25장 덱의 겹침·깨진 글자를 잡았다. 반드시 지킬 두 가지(실측 실패 사례):
- 파일은 항상 절대경로로 나열하라. "이 디렉토리의 slide-01.png"처럼 모호하게
주면 agy가 존재하지 않는 슬라이드 내용을 그럴듯하게 지어 보고한다
(실측: 내 덱이 아닌 "증거 원장 허브, 80점 차트" 보고).
- "각 이미지의 제목 텍스트를 그대로 인용하라"를 요구하라. 인용이 순서와
안 맞으면 '파일확인실패'라고 쓰게 한다 — 실제로 열었는지의 증명이 된다.
- 검수 로그를
tail로 자르지 마라 — 판정 일부가 잘려 누락된 채 넘어갈 수 있다.
프롬프트 작성 규칙 (검증 강제)
agy에 시킨 일은 전부 이 형식으로 지시한다. 실전에서 환각·조작을 막은 패턴이다:
- 단계를 번호로 하드 지정 + 각 단계의 정확한 셸 커맨드 제시.
"각 단계 통과 못하면 다음으로 가지 마라."
- 증거 강제: "마지막에 각 단계의 실제 출력을 그대로 붙여라. 통과했다고 말만 하지 마라."
- 손수 확인 금지 지시: 문서 치환 등은 "키를 손으로 타이핑하지 마라"처럼
함정(U+2027/U+00B7 혼용 등)을 미리 막는다. "grep으로 잔재 확인하지 마라, 지정된
검증 커맨드로 확인하라" — grep만으로 '잔재 0건' 보고 후 실제 215/330문단이 원문 그대로였던 사고 있음.
- 정직 강제: "못 했으면서 했다고 하지 마라. 도구가 없으면 없다고 적어라."
- 산출물은 프롬프트에 명시한 경로로, 확인 커맨드 출력과 함께 보고하게 한다.
함정 목록 (전부 실측)
| 증상 | 원인 | 대처 |
|---|
Error: timeout waiting for response | 기본 print-timeout 5m 초과 | --print-timeout 15m |
| 백그라운드 실행이 로그 0바이트로 소멸 | 세션 종료 시 프로세스 그룹 kill | 포그라운드 실행 |
| 산출물이 cwd에 없음 | scratch(~/.gemini/antigravity-cli/scratch/)에 저장 | mv 지시 + 실행 후 직접 확인 |
| agy가 결과를 사후에 몰래 수정 | 실측 사례 2건(고유명사 변경, 레이아웃 캐시 삽입) | 산출물 해시/내용을 가재코드가 재검 |
| 시작 로그에 "You are not logged into Antigravity" 반복 | 초기 인증 갱신 전 메시지 | 보통 수 초 내 "Auth succeeded". 계속되면 CodexBar 상태 확인 |
| 워크스페이스 스킬이 안 보임 | 실행 cwd가 다름 | 프로젝트 폴더에서 실행(.agents/skills/ 상속) |
진단 정보 위치
- 실행 로그:
/tmp/agy_*.log, 프롬프트 원문: /tmp/agy_*prompt.txt 관례로 남긴다.
- CLI 내부 로그:
~/.gemini/antigravity-cli/log/cli-*.log (42개+ 보관됨)
- 인터랙티브 히스토리:
~/.gemini/antigravity-cli/history.jsonl — 단 -p 실행은 여기 안 남는다.
복원은 bash_history + /tmp 로그 교차.
- 스크래치(산출물·서브에이전트 부산물):
~/.gemini/antigravity-cli/scratch/
- 세션 소유:
~/.codexbar/antigravity/agy-session.json (CodexBar.app)
