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(어느 벤더도 프롬프트가 달라진 뒤의 재현을 보장하지 않음).