Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

6.1 KB
Raw Blame

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 / CLI sprite-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