Pumasi Image

/pumasi-image — Codex 이미지 생성

Codex의 네이티브 이미지 생성/편집 도구(image_gen, gpt-image-2)로 이미지를 만든다. 코드 병렬 외주(pumasi)와 완전히 분리된 독립 스킬. 이미지 요청은 사용자가 "코덱스로"라고 말해도 전부 이 스킬이 담당한다 — pumasi로 넘기지 않는다.

먼저 읽을 것

• references/clarification-matrix.md — 모드별 의도 파악 질문 매트릭스
• references/keyword-mapping.md — 비율·퀄리티 키워드 자동 매핑 + 자연어 힌트 변환표
• references/image-studio-prompt.md — 모드 분류 + Output Template 시스템 프롬프트 (영문 프롬프트 작성 직전에만 Read)

핵심 원칙

1. 백엔드는 2종 — Codex 네이티브 이미지 도구(기본)·Grok image_gen(선택) — nanobanana 등 다른 백엔드 사용 안 함. 백엔드는 Step 3에서 사용자가 고른다(입력에 지명이 있으면 스킵). Grok을 쓸 때는 반드시 scripts/imagen.sh(--backend grok)를 경유한다(비율 강제·확장자 정합·실패 사유 표면화가 그 안에 있다). grok을 직접 부르지 말 것.
2. API 키를 꺼내 직접 호출하지 않는다 — 볼트·환경변수·설정 파일에서 OpenAI(또는 xAI) API 키를 읽어 api.openai.com 등 이미지 API 엔드포인트를 직접 부르는 행동은 금지. 이미지는 오직 (a) Codex 네이티브 이미지 도구 또는 (b) scripts/의 codex/grok 백엔드로만 만든다. 구독 세션이 인증을 담당하며, 이 스킬은 어떤 키도 만들거나 복사하지 않는다.
3. image-studio 시스템 프롬프트 내면화 — 모드 분류 + Output Template 작성
4. 후처리 절대 금지 — sips/ImageMagick/재인코딩 금지, 생성 원본 그대로 저장(SHA1 유지)
5. 저장 경로 고정 — {BASE_DIR}/images/{YYYY-MM-DD}/{slug}-{seq}.png
6. 최대 5개 질문 — 기술 2개 + 의도 3개, 조건부 스킵
7. 텍스트는 이미지 도구가 직접 렌더링한다 — 썸네일·포스터·로고의 한글/영문 카피는 프롬프트의 Text Integration 섹션에 따옴표로 묶어 그대로 명시. HTML/CSS 분리·후합성·텍스트 레이어 분할 절대 금지. 구세대 diffusion(SD/Midjourney) 가정으로 "텍스트 못 그림"이라고 회피하지 말 것 — 다음 §의 capability snapshot 참조.

gpt-image-2 capability snapshot (as of 2026-05)

목적: 구세대 diffusion 직감으로 회피 행동(HTML/CSS 분리, 텍스트 빼고 합성, 재시도 회피)을 하지 못하게 capability를 명시적으로 박는다. 모델 업데이트 시 as of 날짜 기준으로 갱신.

CAN (자신 있게 시도)

• 한글/영문 헤드라인 텍스트 — 16pt 이상 굵은 sans-serif/serif, 정확한 자모/획
• 다국어 혼용 — 한+영 동시 노출(예: "광안대교 BEST 5 / Best Spots")
• 로고 타이포그래피 — 워드마크, 레터마크, 한자/한글 디자인 타이포
• 숫자/날짜 단순 표기 — "2026", "BEST 5", "Vol.3" 정도는 안정적
• 복잡한 레이아웃 — 헤드라인 + 서브카피 + 가격표 + CTA 버튼 한 컷에
• 표·UI 목업·차트 — 행/열 정렬, 라벨, 범례, 막대그래프 텍스트
• 손/얼굴/포즈 디테일 — 손가락 개수, 표정, 시선 방향 정확
• 사진 사실성 — DSLR 룩, 조명 일관성, 그림자/반사 물리

WEAK (조심해서 시도, 결과 보고 판단)

• 매우 작은 글씨 — 8pt 이하 본문은 깨질 확률 높음 → 헤드라인 위주로 설계
• 긴 본문 단락 — 한 블록 50자 이상은 중간에 자모 흔들림 가능
• 정확성이 중요한 숫자 — 가격/날짜/전화번호는 1-2글자 변형 위험 (생성 후 검수 필수)
• 손글씨/캘리그래피 한글 — 자모 결합 흔들림 잦음, 정자체 폰트가 안전

CAN'T 가정 금지 (구세대 diffusion 직감 차단)

• ❌ "한글은 어차피 깨지니까 영문으로만 만들자" — gpt-image-2는 한글 OK
• ❌ "텍스트는 빼고 만든 후 HTML/CSS로 합성하자" — 1차 직접 렌더 금지 사유 아님
• ❌ "썸네일이니까 텍스트 부분만 따로 디자인하자" — 한 컷에 통합 렌더가 정석
• ❌ "로고에 한자/한글 들어가면 안 됨" — 워드마크 직접 렌더 가능

Grok image_gen 차이 (선택 백엔드)

• 비율은 9:16 / 16:9 / 1:1만 지원 — 그 외를 주면 스크립트가 1:1로 강제하고 경고한다
• 퀄리티 파라미터 없음 (퀄리티 질문 스킵)
• 산출물이 보통 JPEG — 스크립트가 타깃 확장자를 소스에 맞춰 자동 조정하고 최종 경로를 path:로 보고한다
• 텍스트 렌더 품질은 gpt-image-2 대비 미검증. SuperGrok 구독이면 한계비용 0

운영 룰

1. 1차는 무조건 이미지 도구로 직접 렌더 — 텍스트 포함 여부 무관
2. 결과 검수 — 이미지 표시 후 텍스트 정확도 사용자 확인 (Step 7 모드 참조)
3. 재시도 우선 — 첫 결과가 깨졌으면 프롬프트 보강(폰트 명시, 크기 명시)해서 1-2회 재생성
4. 합성 옵션은 사용자 명시 거부 후 — "직접 렌더 결과 마음에 안 들어, 합성으로 가자"는 사용자 발화가 있을 때만 후합성 워크플로우 제안

워크플로우

Step 0: feature flag 확인 (scripts 경로를 쓸 때만)

네이티브 도구를 직접 쓰면 이 단계는 없다. scripts/imagen.sh 위임 경로를 쓸 때는 스크립트가 codex features list로 image_generation 플래그를 확인하고 꺼져 있으면 codex features enable image_generation으로 켠다 — 사용자에게는 조용히 수행한다고만 짧게 알린다.

Step 1: 모드 자동 감지

사용자 요청에서 7가지 모드 중 하나를 결정한다:

모드 판단 불확실 시 Step 3의 질문에 "모드 선택" 1개를 추가한다.

Step 2: 키워드 자동 매핑 → 파라미터 추출

references/keyword-mapping.md를 Read하여 비율·퀄리티 자연어 힌트를 추출한다.

• 비율 키워드가 입력에 있으면 → 비율 질문 스킵
• 퀄리티 키워드가 입력에 있으면 → 퀄리티 질문 스킵

Step 3: 사용자 질문 (§A 번호형 블록, 최대 5개)

Codex CLI에는 객관식 카드형 질문 UI가 없다. 결정이 꼭 필요하면 $PLUGIN_ROOT/shared/questioning-policy.md §A의 채팅 번호형 선택지 블록으로 묻는다.

references/clarification-matrix.md를 Read하여 모드별 의도 파악 카테고리 3개를 확정한다.

질문 순서 (한 턴 최대 4문항 — 초과분은 우선순위 낮은 의도 질문부터 잘라낸다): 0. 백엔드 (입력에 "그록으로"/"grok"/"코덱스로"/"codex" 지명이 있으면 스킵)

질문: 어떤 백엔드로 생성할까요?
1. Codex gpt-image-2 (권장) — 임의 비율, 한글/영문 텍스트 렌더 강함
2. Grok image_gen — SuperGrok 구독 시 한계비용 0. 단 비율 9:16/16:9/1:1만, 텍스트 렌더 미검증
3. 문장으로 직접 알려주기

1. 비율 (Step 2에서 확정됐으면 스킵. Grok 선택 시 선택지를 9:16/16:9/1:1로 제한)
2. 퀄리티 (Step 2에서 확정됐으면 스킵. Grok에는 퀄리티 파라미터가 없으므로 Grok 선택 시 스킵) 3~5. 의도 파악 3개 (모드 매트릭스 기반)

질문 원칙:

• §1 + §2c: 이미 입력에서 확정된 차원은 묻지 않는다. 요청이 구체적이면 질문 없이 바로 생성한다(과잉 질문 = 마찰 실패).
• 물을 때는 §A 번호형 블록으로 — 각 슬롯당 5개 이상 선택지, 그중 1~2개는 창의적 대안(★), 마지막은 "문장으로 직접 알려주기"(Other 대체).
• "자동 추천(AI 판단)" 안전망 선택지를 항상 포함하고, "모르면 1번(자동 추천)으로 진행하겠습니다"로 안내한다.
• 여러 슬롯을 한 번에 물을 때는 각 질문 블록을 이어서 출력하고 "여러 개면 1,3처럼 적어주세요"로 안내. 카드 UI를 흉내내지 말 것.

§A 블록 예시 (단일 슬롯):

질문: 어떤 분위기로 갈까요?
1. 자동 추천 — 내용에 맞게 판단. 결정 피로 없이 진행
2. 다크 시네마틱 — 영화적, 깊은 그림자
3. 따뜻함 — 친근, 햇살, 파스텔
4. 조용한 위로감 (★) — 잔잔함, 여운
5. 문장으로 직접 알려주기

Step 4: image-studio 내면화 + Output Template 작성

references/image-studio-prompt.md를 Read하여 시스템 프롬프트를 내면화한다.

내면화 후:

1. Normalization JSON 내부적으로 작성 (노출하지 않음)
2. 선택된 모드의 Output Template을 200~500 단어 영문 프롬프트로 작성
3. 사용자 선택 값(비율·퀄리티·의도 3개)을 Technical Specifications / Anti-Patterns 섹션에 반영
4. 비율·퀄리티 자연어 힌트를 Technical Specifications에 삽입 (keyword-mapping.md 참조)
5. Format / Medium Guard — 단일 심볼 컨셉(돋보기·로켓·방패 등)을 사용자가 로고/아이콘을 요청하지 않았는데 앱아이콘·글래스 배지로 만들지 않는다. hero/배너/커버/씬은 프레임을 가득 채우는 full-bleed 장면으로 번역한다 (image-studio-prompt.md의 가드 참조)

프롬프트를 다음 경로에 저장 (없으면 mkdir -p):

{BASE_DIR}/.imagen/prompt-{timestamp}.md

Step 4-bis (선택, feature flag 뒤): 영문 프롬프트 작성을 codex 워커에 위임

환경변수 PUMASI_IMAGE_DELEGATE_PROMPT=1 설정 시:

1. Step 4의 image-studio-prompt.md Read + 영문 프롬프트 작성 단계 스킵
2. Step 6에서 scripts/imagen-full.sh 호출 — 의도 한 줄 + mode + aspect + quality + 타깃 경로(+ 선택 ref 이미지)만 전달
3. 영문 프롬프트 작성은 codex 워커 측에서 수행하고 prompt.md + manifest.json + codex.log를 {타깃디렉토리}/.imagen-full/에 저장 (refine 복구용)
4. 자동 fallback: imagen-full.sh가 exit ≠ 0이면 즉시 Step 4(직접 작성) + 기본 경로로 폴백. 사용자에게는 "위임 경로 실패 → 직접 작성 경로로 전환" 한 줄 안내. codex 백엔드 전용(Grok에는 없음).

Step 5: 저장 경로 계산

기준 디렉토리 (하드코딩 금지, 동적 계산):

BASE_DIR=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
DATE=$(date +%Y-%m-%d)
TARGET_DIR="${BASE_DIR}/images/${DATE}"
mkdir -p "$TARGET_DIR"

SLUG="busan-gwangan-bridge-night"  # 요청에서 계산 (핵심 명사 1~2개 → 영문 kebab-case)
SEQ=1
TARGET_PATH="${TARGET_DIR}/${SLUG}-$(printf '%02d' $SEQ).png"
while [[ -e "$TARGET_PATH" ]]; do
  SEQ=$((SEQ + 1))
  TARGET_PATH="${TARGET_DIR}/${SLUG}-$(printf '%02d' $SEQ).png"
done
echo "$TARGET_PATH"

왜 git root 기준인가: 세션의 cwd가 항상 프로젝트 루트는 아니다. 단순 상대경로는 엉뚱한 곳에 저장될 위험이 있어, 프로젝트 루트의 images/ 하위를 기본값으로 둔다. git 저장소 밖이면 pwd 기준.

slug 예: "부산 광안대교 야경" → busan-gwangan-bridge-night, "AI 마켓플레이스 로고" → ai-marketplace-logo. 확장자는 .png. Grok 백엔드는 산출물이 보통 JPEG라 스크립트가 확장자를 맞춰 조정하므로 결과 보고는 스크립트 출력의 path:를 기준으로 한다.

Step 6: 이미지 생성 호출

기본 경로 — Codex 네이티브 이미지 도구를 직접 호출한다.

• 백그라운드 CLI 세션을 띄우지 않는다.
• Step 4의 영문 프롬프트 + Step 5의 타깃 경로를 도구에 전달한다.
• 프롬프트 끝에 후처리 금지 가드(원본 유지, 재인코딩 금지)를 명시한다.
• 텍스트가 깨졌으면 합성하지 말고 프롬프트를 보강해 1~2회 재생성한다(운영 룰 3).
• 도구가 돌려준 이미지를 이번 호출 산출물만 Step 5의 타깃 경로에 저장한다. 생성이 0장이면 거짓 성공을 보고하지 말고 실패로 처리한다.

스타일 앵커(레퍼런스): 여러 장을 같은 스타일로 뽑을 때는 1장을 먼저 생성·승인받고, 나머지를 전부 그 파일을 레퍼런스로 물려 편집 도구로 생성한다(앵커 우선 패턴). 레퍼런스가 있으면 프롬프트에서 스타일 서술을 걷어내고 "첨부 이미지의 스타일·조명·색감 유지" + 피사체·구도 델타만 쓴다 — 레퍼런스가 이미 묶은 것을 긴 산문으로 재서술하면 둘이 싸운다. 스타일 일관성 수단 서열(1차 출처 리서치 2026-08-22): 레퍼런스 이미지 ≫ 텍스트 재사용 ≫ seed(어느 벤더도 프롬프트가 달라진 뒤의 재현을 보장하지 않음).

위임 경로 (선택) — scripts 사용

별도 codex exec 워커에 생성을 위임하거나(호스트 컨텍스트 절약), Grok 백엔드를 쓰거나, 영문 프롬프트 작성까지 위임하려면 scripts/의 결정적 래퍼를 쓴다:

# 영문 프롬프트는 호스트가 작성, 생성만 위임 (3번째 인자 비율은 실측 비교 경고용, --ref 반복 가능)
bash $PLUGIN_ROOT/skills/pumasi-image/scripts/imagen.sh \
  "{prompt_file_path}" "{target_image_path}" "{aspect e.g. 16:9 — 생략 가능}" \
  --backend "{codex|grok — Step 3 선택 결과, 생략 시 codex}" \
  --ref "{anchor_image_path — 생략 가능}"

# 영문 프롬프트 작성까지 codex 워커에 위임 (PUMASI_IMAGE_DELEGATE_PROMPT 경로)
bash $PLUGIN_ROOT/skills/pumasi-image/scripts/imagen-full.sh \
  "{intent}" "{mode}" "{aspect}" "{quality}" "{target_image_path}" "{ref_image — 생략 가능}"

# 여러 장 일괄 (partial success + per-item retry manifest; 항목에 "ref" 키로 앵커 지정 가능)
bash $PLUGIN_ROOT/skills/pumasi-image/scripts/imagen-batch.sh "{batch_json_path}"

--backend grok: grok 헤드리스 image_gen으로 생성한다(--ref를 주면 image_edit). 사전 조건: grok CLI 설치($HOME/.grok/bin/grok) + grok login. 미설치/미로그인이면 스크립트가 exit 3으로 실패하니 사용자에게 알리고 codex 재생성 여부를 §A 블록으로 확인한다.

래퍼 내부 동작(codex 백엔드):

1. codex features list로 image_generation feature flag 재확인 (안전망)
2. codex exec --json … < /dev/null 호출 — codex가 이미지 도구로 1장 생성. < /dev/null은 exec가 stdin EOF를 무한 대기(헤드리스 행)하는 것을 막는다. 레퍼런스는 --image=<path>(파일당 1개)로 전달 — -i FILE...은 가변 인자라 뒤따르는 프롬프트를 이미지 경로로 삼켜 "No prompt provided" 실패를 만든다(실측 2026-08-22).
3. 회수 계약 (codex-cli 0.147+ 실측): codex exec는 이미지를 ~/.codex/generated_images/<thread_id>/exec-*.png로 저장하고 stdout JSONL에는 base64를 싣지 않는다. 래퍼는 stdout의 thread.started.thread_id(디렉토리명과 1:1)로 이 세션 산출물만 집어 타깃에 복사한다(동시 실행과 경합 없음, 스테일 오집음 없음). 구버전 codex 호환용으로 stdout(JSONL)·세션 rollout의 base64 디코딩 폴백(extract_image.py)을 유지한다. 생성 0장이면 거짓 성공 없이 exit 5.
4. 실측 해상도(sips) + 요청 비율과 15%↑ 괴리 시 경고. 후처리는 절대 하지 않음.
5. 프록시 우회 — 로컬 프록시(HTTP_PROXY/HTTPS_PROXY)가 환경에 상속돼 있으면 codex 호출에서만 벗긴다. 프록시를 경유하면 이미지 엔드포인트 요청이 ~153초 뒤 network error로 죽는다(2026-07-23 실측: 경유 89/89 실패, 우회 시 동일 프롬프트 44초 성공). 해제는 PUMASI_IMAGE_KEEP_PROXY=1.
6. 실패 사유 표면화 — codex가 남긴 image generation failed: … 원문을 REASON:으로 출력하고, network error면 프록시 힌트를 덧붙인다. 네트워크 실패와 정책 거부를 구분해 보고한다.

⚠️ 샌드박스/승인 우회 경계 (opt-in). 래퍼는 codex exec --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox로 비대화형 실행한다 — 동작은 대상 이미지 경로 1개 쓰기로 한정된다. 신뢰하는 본인 프로젝트에서만 사용한다.

Step 7: 결과 확인 + 표시 (모드별)

생성 모드를 판정한 후 그에 맞게 동작한다. (PNG 1장 표시 = 약 1,400~3,000 비전 토큰이 cached prefix에 박히므로 기본값은 표시 안 함.)

모드 판정 규칙

• fast/no-show (기본값): 검수/audit 키워드 없고, 모드가 텍스트 의존(E_THUMBNAIL/F_LOGO)도 아니고, 의도에 한글/영문 카피가 없을 때
• review/show-one: 모드가 MODE_E_THUMBNAIL / MODE_F_LOGO / 의도에 직접 인용된 카피(따옴표)가 있을 때 — 마지막 1장만 표시
• audit/show-all: 사용자가 "검수해줘", "전부 보여줘", "꼼꼼히 확인", "review all" 명시할 때 — 전체 표시

동작

1. 파일 존재 확인 + file {target_image_path}로 해상도/포맷/sha1 확인 (스크립트 경로면 출력의 path: 기준)
2. 모드별 분기:
   • fast: 경로만 안내 (✅ 생성 완료: {path} ({해상도} {포맷}, sha1: {prefix}) + "깨졌으면 '이미지 보여줘'라고 말씀해주세요"). 이미지 표시 안 함.
   • review: 위 안내 + 마지막 1장만 표시 (텍스트 렌더링 검수). 안내에 "[review 모드]" 추가.
   • audit: 위 안내 + 모든 이미지 표시. 안내에 "[audit 모드]" 추가.

Step 8: MODE_REFINE 루프 (state 유지 + Step 4 재로드 금지)

생성 직후 다음을 대화 컨텍스트(skill state)로 유지:

• last_prompt_path: 마지막 영문 프롬프트 파일 경로 (Step 4 산출물)
• last_image_path: 마지막 이미지 경로 (앵커 후보)
• last_manifest_path: 마지막 manifest.json 경로 (imagen-full.sh 사용 시)
• 선택 파라미터 (backend / mode / aspect / quality / 의도 답변 3개)

리파인 판정:

• 동일 이미지 리파인 ("색감 좀 바꿔줘", "더 밝게"):
  • Step 4 재로드 금지 — last_prompt_path Read + 사용자 델타만 patch
  • 시각 컨텍스트 필요 시 last_image_path 표시 (자동 review 모드)
  • 영문 프롬프트 재작성 필요 시 직전 호출 경로(네이티브 / imagen.sh / imagen-full.sh)와 백엔드 유지
  • image-studio-prompt.md는 절대 재로드 X (28KB)
• 완전 새 요청: Step 1부터 다시

운영 규칙 (토큰 효율)

1. Step 7 기본값 fast — 명시적 검수 요청이 없으면 PNG 표시 안 함 (비전 토큰이 cached prefix에 영구 누적되는 것 방지).
2. MODE_REFINE 시 Step 4 재로드 금지 — last_prompt_path + 델타 patch만. image-studio-prompt.md는 절대 재로드 X.
3. 여러 장 일괄 생성 — imagen-batch.sh 가용하면 사용, 아니면 호출 사이 결과 보고를 묶어 처리 (라운드트립 감소).
4. 검수 분리 권장 — 5장 이상 생성 후 검수가 필요하면 별도 짧은 세션에서 audit 모드 사용.
5. A+B 동시 기본값 금지 — PUMASI_IMAGE_DELEGATE_PROMPT=1은 feature flag로만 활성화. Step 7 fast 모드와 동시 적용 시 MODE_REFINE 컨텍스트 부서짐 위험.

기존 pumasi와의 분리

두 스킬은 같은 플러그인 안의 독립 모듈이며 서로 간섭하지 않는다.

References

• references/image-studio-prompt.md — 모드 분류 + Output Template 시스템 프롬프트 (Format/Medium Guard 포함)
• references/clarification-matrix.md — 모드별 의도 파악 질문 매트릭스
• references/keyword-mapping.md — 비율·퀄리티 키워드 자동 매핑 + 자연어 힌트 변환표

Scripts (선택 — 위임 경로 / Grok 백엔드)

• scripts/imagen.sh — feature flag 확인·활성화 + codex exec --json 호출(또는 --backend grok) + thread_id 기반 산출물 회수(+base64 폴백) + 프록시 우회 + 실패 사유 표면화 + --ref 스타일 앵커 + SHA1/해상도 검증
• scripts/imagen-full.sh — 영문 프롬프트 작성까지 codex 워커에 위임(manifest/prompt/log 보존). 프록시 우회·실패 사유 표면화 동일 적용
• scripts/imagen-batch.sh — 여러 장 일괄(partial success + per-item retry manifest, 항목별 ref)
• scripts/imagen-cleanup.sh — ~/.codex/generated_images/ 누적 정리(기본 DRY-RUN, --apply 시 trash)
• scripts/extract_image.py — 구버전 codex 호환: JSONL/세션 rollout의 image_generation_call base64를 구조 검증 후 PNG로 저장
• scripts/test-imagen-capture.sh — 회수 계약 회귀 테스트(mock codex/grok, 32 assertions)

사전 조건

• Codex CLI 설치 + 로그인 완료, 네이티브 이미지 생성 도구(gpt-image-2) 사용 가능
• (scripts 경로) codex features 서브커맨드 사용 가능
• (Grok 백엔드 선택 시) grok CLI 설치($HOME/.grok/bin/grok) + grok login (구독 세션, XAI_API_KEY 불필요)