Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
Troubleshooting
Owns: Symptoms of a pipeline that is "quietly wrong", with causes and fixes · Index: docs/README.md
파이프라인이 "조용히 이상한" 대표 증상들과 원인·대처. 전부 회귀에서 도출. (엔진은 특정 오케스트레이터를 모른다 — 여기의 규칙은 어떤 에이전트 환경에서든 성립.)
사이드카(curation.json)를 에이전트가 직접 쓸 때 — 스테일 가드에 드랍됨
- 증상: 에이전트가
curation.json에 쓴 상태 항목이 compose/뷰에 반영되지 않고,curation.stale-*.json백업이 생기며 항목이 사라진다. - 원인: 사이드카는 세대 도장(
run_revision+ 행별revision)으로 보호된다. 재추출로 런 세대가 바뀐 뒤 도장 없이 raw JSON 을 직접 쓰면, 로더가 "재생성 이전의 낡은 항목"으로 판정해 드랍한다 (per-state salvage — 의도된 방어). - 대처: 에이전트 쓰기는 반드시 정식 경로로 —
sprite_gen.curate.curation.load_curation(run_dir)로 읽고 수정한 뒤stamp_curation(run_dir, payload)를 거쳐 저장한다. 웹뷰 API(/api/curation)를 쓰면 서버가 도장을 찍는다.
열린 큐레이션 탭 + 에이전트 동시 쓰기 (두-작성자 충돌)
- 증상: 에이전트가 사이드카에 쓴 값이 곧 사라진다.
- 원인: 열린 브라우저 탭은 자기 메모리 상태를 디바운스 저장한다 — 에이전트의 디스크 쓰기를 모른 채 덮어쓴다.
- 대처: 에이전트가 사이드카를 만진 뒤엔 탭을 새로고침시키라고 안내한다. (서버는 run_revision/HTTP-409 로 세대 충돌만 막는다 — 같은 세대 안의 두-작성자는 마지막 저장이 이긴다.)
생성 provider CLI 무출력 행 (auth 정상인데 몇 분째 침묵)
- 증상:
sprite-gen gen자식(provider CLI)이 출력 없이 멈춘다. 인증도 정상. - 원인(회귀): 에이전트 세션 안에서 스폰된 자식 CLI 가 부모 오케스트레이터의
세션 신분 env 를 상속하면, 오케스트레이터의 훅이 자식을 멤버로 착각해 턴 종료를
차단할 수 있다. 엔진은
provider_subprocess_env()로 알려진 오케스트레이터 env 접두어 가족을 전부 벗겨 자식을 깨끗한 독립 프로세스로 스폰한다 (근본 수리는 해당 오케스트레이터 훅 소유). - 대처: provider 를 엔진 스크립트를 거치지 않고 직접 spawn 하는 커스텀
코드를 짰다면 같은 원칙을 적용하라. 진단은 짧은 텍스트 프로브(
codex exec에 "PONG" 한 줄, 60s 타임아웃)로 — env 상속/스크럽 두 케이스를 비교하면 즉시 갈린다.
행 스트립이 세로로 생성됨 → 추출이 빈/희소 프레임으로 전멸
- 증상: 추출 리포트에 특정 행들이
empty or too sparse,could not extract N components로 몰리고 (fail-loud 라 프레임은 미발행), raw 를 보면 가로 스트립이 아니라 세로/단일 대형 이미지다. - 원인: provider 가 레이아웃 가이드의 가로 슬롯 배치를 무시함 (grok 로코모션 행에서 관측).
- 대처: 해당 행만 재생성 — 가이드 준수가 강한 provider(codex)로 바꾸거나 프롬프트의 슬롯/가로폭 계약을 강조. 로컬에서 자르거나 회전시켜 살리지 않는다 (필수 게이트: raw 수리 금지).
비교 캔버스 WebM/MP4 저장이 500
- 원인: WebM/MP4 조립은 서버 머신의
ffmpeg를 쓴다 — 없으면 관측 가능한 500(ffmpeg not found)을 준다. GIF 는 ffmpeg 없이 동작. - 대처: 서버 머신에 ffmpeg 설치 (
brew install ffmpeg등).
테스트 스위트가 순서에 따라 깨짐 (pytest tests/packaging tests/gen 만 빨강) — 제거됨
- 상태: 2026-09-13 원인 제거(플랜
gen-generate-image-shim-removal, v2.3.0). 아래는 기록. - 증상(과거):
pytest tests/gen과pytest tests/packaging은 각각 초록인데 한 세션에서 packaging → gen 순으로 돌리면tests/gen이TypeError: 'module' object is not callable로 수십 건 실패. 테스트만의 문제가 아니라 런타임에서도import sprite_gen.gen.generate_image한 줄이 같은 죽음을 일으켰다. - 원인(과거): 은퇴한 shim 모듈
sprite_gen/gen/generate_image.py가 같은 패키지가 export 하는 함수generate_image()와 이름이 같았다. 파이썬은 서브모듈을 import 하면 부모 패키지에 같은 이름의 속성으로 바인딩하므로 함수가 모듈로 덮여 세션 끝까지 남고,gen.run()은 그 이름을 호출하니 이후 모든 생성이 죽는다. - 수리: shim 모듈을 삭제했다(개명이 아니라 삭제 — 그 경로를 부르는 CLI 동사·MCP 표면·
코드 참조가 0건이라 남길 이름이 없었다).
sprite_gen._modules.MODULE_DOMAIN과 패키징 import-surface 목록에서도 행을 뺐다. 이제sprite_gen.gen.generate_image는 어떤 import 순서에서도 함수로만 해석되고, 옛 모듈 경로 import 는ModuleNotFoundError로 loud 하게 실패한다. 이미지 생성 진입점은sprite_gen.gen/ CLIsprite-gen gen하나다. - 잔존 장치:
tests/packaging/test_package_surface.py의import_probe픽스처는 일반 격리 장치로 유지한다(서브모듈 import 가 부모 속성을 덮는 규칙 자체는 남아 있다). - 확인:
pytest tests/packaging tests/gen,pytest tests/gen tests/packaging,pytest tests/가 모두 같은 결과여야 한다. - 같은 계열(2026-09-13 수리):
tests/curate가tests/frames의 헬퍼를 bare 이름 (from test_takes_heal import …)으로 가져와pytest tests/curate단독이ModuleNotFoundError였다. 다른 폴더의 테스트 헬퍼는tests/루트 기준 (from frames.test_takes_heal import …)으로만 import 한다 — pyproject 의pythonpath = ["tests"]가 그 루트를 보장하고, 폴더 수집 순서는 보장하지 않는다.
Related
- docs/README.md — documentation index