Codex 이미지 파이프라인 키트 (투명 PNG·프레임 세트)

---
name: codex-image-pipeline
description: Use Codex's built-in image_gen headlessly (codex exec) to deliver finished image files into a project - transparent-background PNGs via magenta keying, a consistent character across several images via reference images, and animation frame sets generated one frame per call with geometry normalization and a generation ledger. Use when the image must land in the project folder in usable form, not just be previewed. 투명 배경 이미지, 같은 캐릭터 여러 장, 스프라이트 애니메이션 프레임, 이미지 생성 기록(원장)이 필요할 때. Codex 전용 - needs the Codex CLI logged in.
---

# Codex 이미지 파이프라인

Codex 에 내장된 `image_gen` 도구를 **터미널에서 대신 불러**, 그림을 "쓸 수 있는 파일"로 프로젝트 폴더에 가져온다.
Codex 의 기본 `imagegen` 스킬을 **대체하지 않고 그 위에 얹는다** — 미리보기용 한 장이면 `imagegen` 만으로 충분하다.

## 언제 쓰나 / 언제 안 쓰나

쓴다
- 투명 배경 PNG 가 필요하다 (아이콘·스티커·스프라이트·합성용 컷아웃)
- 같은 캐릭터·스타일로 **여러 장**을 이어서 만들어야 한다 (기준 이미지 물리기)
- 애니메이션 프레임 세트(걷기·대기·공격)를 칸 크기에 맞춰 뽑아야 한다
- "이 그림 어떤 프롬프트로 만들었지?"에 답할 생성 기록이 필요하다

안 쓴다
- 코드·SVG·HTML/CSS 로 직접 그리는 편이 나은 아이콘·도형·도표
- 한 번 보고 버릴 미리보기 → Codex 기본 `imagegen` 으로 충분
- Codex 가 없는 환경(Claude 앱·ChatGPT 웹만 쓰는 경우) → 이 스킬은 `codex` 명령을 부른다

## 준비물 (하나라도 없으면 먼저 알려 주고 멈춘다)

1. `codex --version` 이 동작하고 로그인돼 있다 (내장 `image_gen` 은 API 키 없이 로그인 세션으로 돈다)
2. `python3` 와 Pillow 패키지 (`python3 -c "import PIL"` 이 에러 없이 끝나야 한다)
3. Node.js 18 이상

## 절차

1. 슬롯이 이미 만들어져 있는지 먼저 본다. 승인된 그림은 덮어쓰지 않는다 (스크립트도 기본 거부).
2. 무엇을 만드는지 고른다.
   - 그림 한 장: `node scripts/gen-image.mjs <출력.png> "<설명>" [옵션]`
   - 애니메이션 세트: `node scripts/gen-frames.mjs <폴더> "<캐릭터 설명>" <동작> [프레임수] [옵션]`
3. 먼저 `--plan` 으로 계획만 출력해 본다 (Codex 를 부르지 않는다). 프롬프트·기준 이미지·호출 횟수를 확인한다.
4. 실행한다. 한 장에 보통 1~3분. 끝나면 `art-raw/` 에 원본이, 출력 경로에 마무리본이, `image-ledger.jsonl` 에 기록이 남는다.
5. **눈으로 확인한다.** 스크립트의 검사는 "깨진 것"을 거르지 "좋은 그림"을 보증하지 않는다. 투명 그림은 어두운 배경과 밝은 배경 양쪽에 올려 가장자리 번짐을 본다. 프레임 세트는 한 장으로 이어 붙여(contact sheet) 본다.
6. 실패한 한 장만 다시 뽑는다. 프레임 세트는 `art-raw/<세트 이름>/frame_NN.png`(원본) 중 **다시 뽑을 장만 지우고** 같은 명령에 `--resume` 을 붙인다 — 없는 원본만 새로 만들고, 마무리(배경 지우기→fit→normalize→audit)는 항상 원본 전체에서 다시 한다. 단일 그림은 `--force`. 세트 전체를 다시 뽑지 않는다.

## 옵션 요약

| 옵션 | 뜻 |
|---|---|
| `--transparent` | 배경을 마젠타 단색으로 받아 알파로 바꾼다 (체커보드 방지) |
| `--ref <이미지>` | 기준 이미지. 여러 번 줄 수 있다. 같은 캐릭터·스타일로 그린다 |
| `--style "…"` | 스타일 한 줄 ("도트 픽셀아트, 제한된 팔레트" 등) |
| `--size WxH` | 마무리 캔버스. 비율 유지, 남는 자리는 투명. 도트면 `--pixel` 같이 |
| `--model`, `--effort` | Codex 에이전트 모델·추론 강도. 안 주면 내 Codex 기본값 |
| `--plan` | 호출 없이 계획만 출력 |
| `--force` / `--resume` | 덮어쓰기(프레임 수를 줄이면 남는 꼬리 프레임도 치움) / 원본이 있는 프레임은 건너뛰고 없는 것만 생성 |

`--model` 은 **그림을 그리는 모델이 아니라 Codex 에이전트 모델**이다. 내장 도구 모드는 그림 모델을 고르는 손잡이를 주지 않는다.

## 지켜야 할 것

- 내장 `image_gen` 만 쓴다. API/CLI 대체 경로(별도 API 키 필요)로 슬쩍 넘어가지 않는다. 필요하면 사용자에게 먼저 묻는다.
- 프롬프트에 사용자가 적은 문구·글자는 **그대로** 옮긴다. 그림 속 글자는 틀리기 쉬우니 맞는지 확인한다.
- 실존 인물·기존 캐릭터·상표를 그리게 하는 요청은 사용자가 권리를 가진 경우에만 진행한다.
- 결과를 보고할 때 저장 경로, 쓴 프롬프트, 호출 횟수, 실패해서 다시 뽑은 장수를 함께 말한다.

## 더 읽을 것

- `references/how-it-works.md` — 왜 이렇게 만들었나(마젠타·표준입력·옛 파일 함정·앵커 방식)
- `references/pitfalls.md` — 실제로 겪은 실패와 증상별 해결
- `references/prompt-recipes.md` — 용도별 프롬프트 틀