게임 개발 에이전트#

zuku agent는 내 컴퓨터에서 실행되는 HTML5 게임 개발 에이전트입니다. 한 줄 요청을 받아 설계 → 구조 → 구현 → 검증 → 실제 브라우저 플레이테스트 → 패키징까지 진행합니다. 이 문서는 CLI 0.3.0 기준이며, zuku와 zukujs는 같은 명령입니다(같은 런타임·설정·로그인 정보 ~/.config/zukujs/(Windows: %LOCALAPPDATA%\ZukuJS\)를 사용).

• 로컬 에이전트는 ZUKU 게임 생태계 전용입니다. 웹 서비스나 일반 앱을 만드는 도구가 아닙니다.
• 기본 실행은 게임을 만들고 로컬 브라우저에서 검증·패키징까지만 하고 아무것도 올리지 않습니다.
• --draft는 초안만 업로드하고, --yolo는 명시적인 1회 프로덕션 게시입니다.

명령 전체 목록은 명령 참조, 로그인은 인증, 모델 연결은 제공자와 모델을 참고하세요.

시작하기 전에#

생성에는 선택한 모델 제공자의 인증 또는 로컬 모델 환경이 필요합니다. 외부 제공자의 API 키나 로컬 모델로 생성할 때는 ZUKU 계정 로그인이 필요하지 않습니다. ZUKU AI를 선택하거나 초안을 업로드·게시할 때는 ZUKU 계정을 연결합니다.

zuku auth list                # 제공자별 인증 상태 확인 (값은 표시하지 않음)
zuku provider list            # 사용할 제공자와 현재 선택 확인

• ZUKU 공식 AI 제공자는 zuku/auto이며, 사용할 수 있는 모델 목록은 서버에서 동적으로 바뀝니다. 자세한 내용은 모델을 보세요.
• ZUKU 계정으로 네이티브 생성을 하려면 zuku login zuku --generate로 games:generate 권한을 명시적으로 승인해야 합니다. 기존 세 권한(games:upload games:create games:publish)만 있는 계정은 scope-required로 표시되고 생성 요청이 거부됩니다(ZUKU_GENERATE_SCOPE_REQUIRED).
• Codex를 쓰려면 처음 한 번 zuku login codex --experimental로 연결합니다. 이 연결은 ZukuJS의 비공식·실험적(exp!) 연동이라는 뜻이며, Codex 서비스 자체가 실험적이라는 뜻은 아닙니다. 기존 Codex CLI 로그인 파일을 읽지 않습니다.
• 로그인 정보는 생성된 게임 코드, 모델 입력, 플레이테스트 브라우저에 전달되지 않습니다.

사용법#

zuku agent "세 갈래 길에서 떨어지는 블록을 피하는 아케이드 게임"   # 로컬: 검증·플레이테스트·패키지까지
zuku agent "..." --name lane-dodger                               # 프로젝트 디렉터리 이름 지정
zuku agent "..." --draft                                          # 로컬 + 초안 업로드 (게시 안 함)
zuku agent "..." --yolo                                           # 검증을 통과하면 한 번 게시
zuku agent --resume run_20261003120000_0123abcd                   # 기록된 실행 재개

--no-skills, --skip-playtest 같은 알 수 없는 옵션, 중복·충돌 옵션, 잘못된 값은 파일이나 네트워크를 건드리기 전에 INVALID_INPUT(종료 코드 2)으로 거부됩니다.

요청을 생략하면 터미널에서 실행할 때만 한 줄을 묻습니다. 스크립트처럼 비대화형으로 실행하면 기다리지 않고 AGENT_REQUEST_REQUIRED로 끝납니다. 결과는 stdout으로, 진행 상황([zukujs agent] 설계(design) 시작 등)은 stderr로만 나갑니다.

세 가지 모드#

--yolo가 없으면 어떤 경우에도 게시하지 않습니다. 초안을 만든 뒤 직접 게시하는 방법은 게시를 보세요.

실행 흐름#

1. 로컬 검사: 인수, 요청(4000자 이하, 제어 문자·비밀 값 금지), 게임 스킬 팩 무결성, --name 충돌을 확인합니다.
2. --yolo일 때만 한도 확인: 모델을 호출하기 전에 ZUKU 계정과 남은 게시 한도를 확인합니다. 남은 횟수가 0이면 DEPLOY_QUOTA_EXCEEDED(대기 시간 포함)로 바로 끝나며 모델을 호출하지 않습니다.
3. 실행 잠금: 같은 디렉터리에서 동시에 실행하면 AGENT_BUSY로 거부합니다.
4. 모델 단계: design → architecture → implementation → playtest(입력 스크립트) → publish(스토어 메타데이터). 각 단계에는 CLI에 함께 배포되는 필수 게임 스킬이 적용되며 끌 수 없습니다.
5. 코드 게이트: 결과물을 코드가 직접 검사합니다. 한 번 더 고칠 기회를 준 뒤에도 실패하면 AGENT_GATE_FAILED, 경로 탈출·명령 실행·네트워크·비밀 값이 보이면 재시도 없이 AGENT_ARTIFACT_UNSAFE로 멈추고 아무것도 쓰지 않습니다.
6. 스테이징과 검증: 실제 zuku create 스캐폴드 위에 생성 파일을 src/ 아래에만 쓰고, zuku validate와 같은 규칙으로 검사합니다.
7. 실제 브라우저 플레이테스트(아래). 실패하면 한 번 수정하고, 그래도 실패하면 편집 가능한 프로젝트만 남기고 패키지·업로드·게시를 하지 않습니다(AGENT_PLAYTEST_FAILED).
8. 확정: 플레이테스트한 소스가 그대로인지 확인한 뒤 <현재 디렉터리>/<name>으로 옮깁니다. 기존 프로젝트는 덮어쓰지 않습니다.
9. 패키징: zuku package와 같은 결정적 ZWF 패키지를 만듭니다.
10. 모드별 마무리: 기본은 여기서 멈추고, --draft는 초안을 만들고, --yolo는 플레이테스트한 바이트와 패키지가 같을 때만 정확히 한 번 게시를 요청합니다.

만들어진 프로젝트는 일반 프로젝트와 같습니다. 디렉터리로 들어가 zuku run으로 다시 실행하거나 직접 고칠 수 있습니다.

실제 브라우저 플레이테스트#

플레이테스트는 모델의 리뷰가 아니라 로컬 브라우저에서 게임을 실제로 실행하는 검사입니다.

• 샌드박스를 켠 Chromium으로 실행합니다. 샌드박스를 끄고 물러서는 경로가 없으므로 root로 실행하면 AGENT_PLAYTEST_SANDBOX로 실패합니다. 일반 사용자로 실행하세요.
• 검증한 파일만 127.0.0.1의 임의 포트에서 제공하고, 루프백이 아닌 요청·WebSocket·서비스 워커는 차단합니다. 외부 요청이나 CSP 위반이 하나라도 있으면 실패입니다.
• 실제 키 입력으로 메뉴 → 시작 → 진행 → 게임 오버 → 리셋을 확인하고, 두 스크린샷의 픽셀 차이까지 봅니다. 플레이 중 스크린샷(960×540 PNG)은 게시 썸네일로 쓰입니다.
• 고정 버전 Chromium을 찾고, 없으면 한 번 내려받습니다(약 150MB, 네트워크 필요). --browser는 도움말과 파서에 남아 있지만 현재 Agent Core에는 전달할 수 없어 CORE_PROTOCOL_GAP로 실패합니다. 브라우저 다운로드·실행을 허용하는 일반 사용자 환경을 준비하세요. 브라우저를 쓸 수 없으면 프로젝트는 남기되 패키지·게시는 하지 않습니다(AGENT_PLAYTEST_UNAVAILABLE).

만들 수 있는 게임과 엔진#

에이전트는 허용된 HTML5 게임 유형만 만듭니다. 시뮬레이션 상태는 렌더러 밖에 두고, 키 입력은 명시적으로 매핑하며, HUD와 메뉴는 DOM으로 만듭니다. 게임은 CDN에 의존하지 않습니다.

• Canvas: zuku create의 Canvas 스캐폴드 계열입니다. 항상 사용할 수 있습니다.
• Phaser: CLI 0.3.0은 Phaser를 함께 설치하지 않습니다. 사용자가 CLI 설치본에 phaser 패키지를 직접 설치한 경우에만 에이전트가 Phaser를 선택할 수 있고, 이때 phaser.min.js와 라이선스를 프로젝트 src/vendor/에 복사합니다. 설치 없이 Phaser로 시작하려면 Phaser를 포함한 스타터를 내려받으세요.

엔진을 고른 이유는 실행 기록과 README에 남습니다.

취소와 유료 호출#

• Ctrl+C(SIGINT)나 SIGTERM을 보내면 진행 중인 모델·브라우저 작업을 중단합니다. 게시 요청 전이면 아무것도 게시되지 않으며, 종료 코드는 130입니다.
• 유료 제공자를 쓰는 경우, 중단된 모델 요청은 제공자 쪽에서 이미 처리되어 비용이 청구되었는지 알 수 없을 수 있습니다. CLI는 이런 요청을 자동으로 다시 보내지 않습니다. 다시 실행하기 전에 제공자의 사용량 화면과 로컬 실행 기록을 먼저 확인하세요.
• 한 번의 실행이 쓰는 양에는 상한이 있습니다(아래 표). 상한에 걸리면 추가 호출 없이 멈춥니다.

--yolo와 게시 한도#

• --yolo는 계획부터 게시까지 전체 흐름에 대한 명시적 승인입니다. 중간 확인이나 최종 승인 단계가 따로 없습니다.
• 게시 한도는 ZUKU 계정당 최근 6시간(롤링) 동안 성공한 프로덕션 게시 3회이며 서버가 강제합니다. 실패하거나 거부된 게시, 같은 패키지의 재확인은 한도를 쓰지 않습니다. 네 번째 요청은 429 DEPLOY_QUOTA_EXCEEDED와 Retry-After를 받습니다. 자세한 내용은 요청 한도를 보세요.
• 남은 횟수는 zuku account --quota로 확인합니다.

결과가 불확실할 때와 재개#

• 게시 요청 중 시간 초과, 네트워크 오류, 취소, 잘못된 응답이 생기면 결과 불명(AGENT_PUBLISH_OUTCOME_UNKNOWN)으로 기록하고 자동으로 다시 게시하지 않습니다.
• zuku agent --resume <run_id> --yolo는 먼저 서버에 상태를 조회합니다. 이미 게시되었으면 성공으로 기록하고 다시 보내지 않으며, 게시되지 않았음이 확인될 때만 재검증 후 한 번 게시합니다. 조회할 수 없으면 AGENT_RECOVERY_REQUIRED로 멈춥니다.
• --resume은 모델을 호출하지 않습니다. 소스가 기록과 달라졌으면 AGENT_SOURCE_CHANGED로 거부하고, 플레이테스트를 다시 통과해야 하며, 다시 만든 패키지 SHA-256이 기록과 같아야 합니다.
• 실행 기록은 <현재 디렉터리>/.zukujs/agent/runs/<run_id>/receipt.json에 있습니다. 요청 원문은 저장하지 않고 SHA-256만 남깁니다. .zukujs/는 저장소에 커밋하지 마세요.

자주 만나는 오류#

전체 목록은 오류의 CLI 오류 절를 보세요.