# Agy

> Google Antigravity CLI(agy)를 가재코드에서 원샷으로 호출한다. 이미지 인식(비전), 이미지 생성(generate_image), 긴 문서 작업에 Gemini를 쓸 때. print 모드(-p) 실행 레시피, scratch 폴더 함정, 타임아웃, 증거 강제 프롬프트 규칙 포함. Triggers: agy, antigravity, 이미지 생성, 이미지 인식, 이미지 보기, 그림 그려, 비전, 멀티모달, 제미나이

- Skill: `jkf87/agy` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jkf87/agy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jkf87/agy/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jkf87 (https://skillmd.com/u/jkf87)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jkf87/agy

---


# 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 ...)`로 넣는다(길고 한국어·멀티라인이라 인자 직접 삽입은 사고난다):

```bash
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`로 죽는 걸 실제로 당했다). 단숨 5~10m, 문서 작업 15~20m.
- 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)