agy

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 <작업 워크스페이스>   # ★ cwd = agy 워크스페이스. 여기의 .agents/skills/* 를 agy가 상속한다
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장 덱의 겹침·깨진 글자를 잡았다. 반드시 지킬 두 가지(실측 실패 사례):

1. 파일은 항상 절대경로로 나열하라. "이 디렉토리의 slide-01.png"처럼 모호하게 주면 agy가 존재하지 않는 슬라이드 내용을 그럴듯하게 지어 보고한다 (실측: 내 덱이 아닌 "증거 원장 허브, 80점 차트" 보고).
2. "각 이미지의 제목 텍스트를 그대로 인용하라"를 요구하라. 인용이 순서와 안 맞으면 '파일확인실패'라고 쓰게 한다 — 실제로 열었는지의 증명이 된다.
3. 검수 로그를 tail로 자르지 마라 — 판정 일부가 잘려 누락된 채 넘어갈 수 있다.

프롬프트 작성 규칙 (검증 강제)

agy에 시킨 일은 전부 이 형식으로 지시한다. 실전에서 환각·조작을 막은 패턴이다:

1. 단계를 번호로 하드 지정 + 각 단계의 정확한 셸 커맨드 제시. "각 단계 통과 못하면 다음으로 가지 마라."
2. 증거 강제: "마지막에 각 단계의 실제 출력을 그대로 붙여라. 통과했다고 말만 하지 마라."
3. 손수 확인 금지 지시: 문서 치환 등은 "키를 손으로 타이핑하지 마라"처럼 함정(U+2027/U+00B7 혼용 등)을 미리 막는다. "grep으로 잔재 확인하지 마라, 지정된 검증 커맨드로 확인하라" — grep만으로 '잔재 0건' 보고 후 실제 215/330문단이 원문 그대로였던 사고 있음.
4. 정직 강제: "못 했으면서 했다고 하지 마라. 도구가 없으면 없다고 적어라."
5. 산출물은 프롬프트에 명시한 경로로, 확인 커맨드 출력과 함께 보고하게 한다.

함정 목록 (전부 실측)

증상	원인	대처
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)