Godogen: 프롬프트 한줄로 게임 전부를 만들다

AI 코딩 에이전트 이야기를 할 때 늘 비슷한 한계가 나옵니다.
“코드는 써주는데, 결과물이 진짜로 돌아가느냐?”
특히 게임 개발에서는 이 문제가 훨씬 더 심각합니다. 텍스트로는 맞아 보여도, 화면에 띄워보면 카메라가 틀어지고, 오브젝트가 공중에 뜨고, 충돌이 깨지고, 아트 스타일이 제각각인 일이 너무 흔합니다.

htdt/godogen은 바로 그 지점을 정면으로 때리는 프로젝트입니다. 이 저장소는 단순한 “게임 코드 생성기”가 아니라, 자연어 설명을 받아 Godot 4 게임을 실제 프로젝트 단위로 만들어내는 AI 개발 파이프라인을 구현합니다. 더 중요한 건, 이 프로젝트가 코드를 생성하는 데서 멈추지 않고, 실행한 뒤 스크린샷을 찍고, 비전 모델로 결과를 검증하고, 다시 고치는 루프까지 포함한다는 점입니다. (GitHub)

https://github.com/htdt/godogen

GitHub - htdt/godogen: Claude Code skills that build complete Godot 4 projects from a game description

 

---

이 프로젝트는 정확히 무엇인가

Godogen은 Godot 4용 게임을 만들기 위한 Claude Code 스킬 기반 오케스트레이션 시스템입니다. 사용자는 “3D 스노보드 게임 만들어줘” 같은 설명을 던지고, 시스템은 그 요청을 받아 다음 일을 순차적으로 처리합니다.

• 최종 화면의 기준이 되는 비주얼 타깃 이미지 생성
• 게임 기능을 작업 단위로 분해
• Godot 프로젝트 구조와 씬/스크립트 아키텍처 설계
• 2D/3D 에셋 계획 및 생성
• 각 작업을 실제 GDScript와 .tscn 씬으로 구현
• Godot를 headless 모드로 실행해 검증
• 실행 결과를 캡처하고 비전 모델로 QA
• 문제가 보이면 수정 후 재검증

즉, 이 프로젝트의 핵심은 “LLM이 게임 코드를 잘 쓰게 하자”가 아닙니다.
정확히는 게임 개발 전체를 여러 단계로 나눈 뒤, 각 단계에 필요한 맥락만 로드해서, 실제 실행 결과를 기준으로 닫힌 피드백 루프를 만드는 것에 가깝습니다. 저장소 문서에서도 이를 게임 엔진이나 단순 코드 생성기가 아니라 자율적인 개발 파이프라인이라고 규정합니다. (GitHub)

이 저장소는 Alex Ermolov가 만든 공개 저장소이며, 실제 게임 프로젝트를 직접 담고 있는 레포라기보다 스킬 개발 소스입니다. publish.sh가 이 스킬들을 새 게임 디렉터리의 .claude/skills/ 아래로 복사하고, CLAUDE.md를 배치해 Claude Code가 해당 폴더에서 /godogen으로 작동하게 만듭니다. (GitHub)

---

왜 이런 프로젝트가 등장했을까

이 프로젝트의 배경은 아주 현실적입니다.

게임 프로토타이핑은 생각보다 많은 역할을 동시에 요구합니다.
아키텍처 설계, 입력 처리, 씬 구성, 에셋 준비, 물리 디버깅, 카메라 조정, UI 정리, 시각적 완성도 검토까지 전부 필요합니다. README와 프로젝트 설명 문서가 반복해서 강조하는 것도 이 부분입니다. **“게임 하나를 만들려면 코드만이 아니라 아트 디렉션과 디버깅까지 함께 필요하다”**는 점입니다. (GitHub)

기존 LLM 기반 게임 생성이 자주 실패하는 이유도 여기 있습니다.

첫째, 한 번의 거대한 프롬프트로는 전체 시스템을 안정적으로 유지하기 어렵습니다.
둘째, GDScript는 Python처럼 보이지만 실제로는 전혀 다른 함정이 많은 언어라서, 모델이 자신 있게 그럴듯한 틀린 코드를 뱉기 쉽습니다.
셋째, 텍스트 기반 검증만으로는 시각적 버그를 못 잡습니다. z-fighting, 텍스처 누락, 잘못된 스케일, 어색한 배치, 물리 폭주 같은 문제는 화면을 봐야 압니다. Godogen은 이 세 가지를 핵심 병목으로 보고 설계를 쪼갭니다. (GitHub)

정리하면, Godogen은 다음 질문에 대한 답입니다.

“AI가 게임을 만든다고 할 때, 실제로 사람이 며칠 동안 하던 일을 어떻게 안정적으로 자동화할 것인가?”

이 프로젝트의 해법은 멀티에이전트 과시도 아니고, 초대형 프롬프트도 아닙니다.
두 개의 큰 스킬과, 문서 기반 인터페이스, 단계별 맥락 로딩, 시각 QA 루프입니다. (GitHub)

---

핵심 구조: 두 개의 스킬로 전체를 굴린다

이 저장소에서 가장 흥미로운 부분은 에이전트 수를 무작정 늘리지 않았다는 점입니다.

Godogen은 크게 두 개의 스킬로 나뉩니다.

1) godogen

상위 오케스트레이터입니다.
게임을 전체 파이프라인으로 보고, 어떤 순서로 무엇을 해야 하는지 결정합니다. 비주얼 타깃 생성, 작업 분해, 구조 설계, 에셋 계획, 각 작업의 실행 순서 관리, 실패 시 재계획 판단 같은 메타 레벨의 결정을 맡습니다. (GitHub)

2) godot-task

개별 작업 실행기입니다.
PLAN.md에 정의된 한 개의 작업 블록을 받아, 실제로 씬 빌더를 만들고, 스크립트를 쓰고, Godot로 검증하고, 테스트 하네스를 만들고, 스크린샷을 찍고, 비전 QA를 수행합니다. 중요한 점은 이 스킬이 context: fork로 동작해 매 작업이 깨끗한 컨텍스트에서 시작된다는 것입니다. (GitHub)

이 구조는 의외로 매우 실용적입니다.
작업 단위별로 새로운 컨텍스트를 쓰면, 이전 작업의 잡음이 다음 작업을 오염시키지 않습니다. 대규모 생성에서 흔한 “앞에서 잘못 배운 패턴이 뒤에 계속 전염되는 문제”를 줄이는 데 효과적입니다. 이 저장소의 문서도 여러 단계가 대화가 아니라 구조화된 문서로 서로 통신한다고 설명합니다. (GitHub)

---

문서 프로토콜이 이 프로젝트의 진짜 핵심이다

Godogen을 단순한 프롬프트 모음으로 보면 안 되는 이유가 여기 있습니다.
이 시스템은 단계 사이를 모두 문서로 연결합니다.

주요 산출물은 다음과 같습니다.

• reference.png: 최종 게임이 어떤 느낌이어야 하는지 보여주는 시각 기준
• PLAN.md: 작업 DAG와 상태
• STRUCTURE.md: 씬, 스크립트, 시그널, 물리 레이어 등 구조 설계
• ASSETS.md: 에셋 목록, 용도, 크기, 경로
• MEMORY.md: 작업 중 발견한 함정과 우회책

이 방식의 장점은 명확합니다.

하나는 재개 가능성입니다. 실행이 끊겨도 PLAN.md와 STRUCTURE.md를 보고 이어갈 수 있습니다.
또 하나는 디버깅 가능성입니다. 대화 로그를 뒤지는 대신, 문서를 열어 현재 상태를 이해하고 수정할 수 있습니다.
마지막으로 컨텍스트 최적화입니다. 각 작업 에이전트는 필요한 문서만 보고 일하면 됩니다. (GitHub)

이건 실제 서비스 아키텍처 관점에서도 꽤 좋은 선택입니다.
메시지 기반 에이전트 체인보다, 명시적인 상태 문서 + 재진입 가능한 단계 실행기가 운영에 훨씬 유리하기 때문입니다.

---

파이프라인을 단계별로 뜯어보자

1. 비주얼 타깃 생성

코드부터 쓰지 않습니다. 먼저 reference image를 만듭니다.
이 이미지가 이후 아트 방향, 카메라 구도, 오브젝트 밀도, 화면 인상을 고정하는 “시각적 북극성” 역할을 합니다. 문서에서는 이 한 장의 이미지가 이후 에셋 생성과 QA의 기준점이 된다고 설명합니다. (GitHub)

이 선택은 매우 중요합니다.
보통 AI 게임 생성은 “에셋 몇 개를 따로 만들고 나중에 붙이는 방식”이라 스타일이 쉽게 깨집니다. 반면 Godogen은 먼저 결과 화면을 정의하고, 그에 맞춰 자산과 구현을 맞춥니다.
즉, 코드 중심이 아니라 결과 화면 중심으로 파이프라인을 설계했습니다.

---

2. 작업 분해

다음 단계는 decomposer입니다.
여기서 흥미로운 철학이 나옵니다. 모든 기능을 잘게 자르지 않습니다. 오히려 평범한 기능은 묶고, 정말 어려운 문제만 따로 뺀다는 전략을 택합니다. 예를 들어 이동, UI, 카메라 같은 보편적인 기능은 함께 다루고, 절차적 생성이나 커스텀 물리처럼 난도가 높은 것만 별도 작업으로 분리합니다. (GitHub)

이 접근은 개발 경험이 있는 사람이라면 바로 고개를 끄덕일 포인트입니다.
태스크를 너무 잘게 쪼개면 integration boundary가 늘어나고, 그 경계마다 버그가 생깁니다. Godogen은 이를 줄이기 위해 작업 수를 최소화하는 DAG를 만듭니다.
이건 “에이전트를 더 많이 붙이면 더 잘 된다”는 유행과 반대로 가는 설계입니다.

---

3. 아키텍처 스캐폴딩

scaffold 단계에서는 실제 Godot 프로젝트 구조를 설계합니다.

• 씬 계층
• 스크립트 책임 분리
• 시그널 흐름
• 물리 레이어
• 입력 매핑
• 프로젝트 설정 파일

문서에 따르면 이 단계는 단순 설계 문서가 아니라, Godot가 실제로 열 수 있는 컴파일 가능한 프로젝트 뼈대를 생성합니다. 그리고 STRUCTURE.md를 써서 이후 단계가 어떤 씬과 스크립트를 어디에 생성해야 하는지 알 수 있게 합니다. (GitHub)

이게 중요한 이유는 이후 작업이 모두 이 구조를 기준으로 움직이기 때문입니다.
아키텍처 없이 바로 기능을 붙이면 씬과 스크립트의 책임이 섞이고, 나중에 QA가 문제를 잡아도 어디를 고쳐야 할지 불분명해집니다.
Godogen은 이 문제를 중간 설계 산출물의 강제로 해결합니다.

---

4. 에셋 계획과 생성

이 프로젝트는 에셋 생성도 흥미롭습니다.
그냥 “필요한 이미지 다 만들어”가 아닙니다. asset-planner가 먼저 어떤 자산이 실제로 필요한지, 그리고 어떤 자산이 시각적 효과 대비 비용 효율이 높은지를 판단합니다. 문서에 따르면 2D 이미지는 Gemini를 쓰고, 3D 모델은 선택된 이미지를 Tripo3D로 변환합니다. 또한 각 에셋에 게임 내 실제 크기를 명시해, 지나치게 상세한 자산을 만들어 놓고 작은 크기로 축소해 망치는 문제를 피하려고 합니다. (GitHub)

이건 사소해 보이지만 실제 게임 프로토타이핑에서는 엄청 중요합니다.
에셋 품질 문제의 상당수는 생성 모델 성능보다 용도와 해상도 설계 실패에서 나옵니다. Godogen은 “어디에, 얼마나 크게, 어떤 역할로 쓰일지”를 먼저 정합니다.

---

5. 실제 작업 실행

이제 godot-task가 들어옵니다.
이 스킬은 단일 태스크를 받아 다음 루프를 수행합니다.

1. 타깃 파일 분석
2. 필요한 에셋 import
3. 씬 빌더 생성
4. 런타임 스크립트 작성
5. headless 검증
6. 에러 수정
7. 테스트 하네스 작성
8. 스크린샷 캡처
9. 시각 검증
10. 자동 VQA 수행
11. 결과 저장

문서에 적힌 이 워크플로를 보면, 사실상 AI용 CI 파이프라인에 가깝습니다. 코드 생성은 중간 한 단계일 뿐이고, 진짜 중요한 건 implement → screenshot → verify → VQA 루프입니다. (GitHub)

이 루프를 코드로 흉내 내면 대략 이런 느낌입니다.

# 새 에셋 import
timeout 60 godot --headless --import

# 씬 빌더 실행
timeout 60 godot --headless --script scenes/build_main.gd

# 전체 스크립트 파싱 검증
timeout 60 godot --headless --quit 2>&1

# 테스트 하네스 실행 및 캡처
godot --write-movie ...

실제 저장소 문서도 유사한 headless 검증 명령과 import 절차를 명시합니다. 중요한 건 Godot를 단순히 코드 출력용 백엔드가 아니라 검증 가능한 실행 환경으로 적극 활용한다는 점입니다. (GitHub)

---

GDScript 문제를 어떻게 푸는가

개발자 관점에서 가장 인상적인 부분은 이 저장소가 GDScript를 별도의 난제로 분리해서 다룬다는 점입니다.

많은 AI 코드 생성 프로젝트는 언어를 그냥 “또 하나의 프로그래밍 언어” 정도로 취급합니다.
하지만 Godogen은 GDScript가 가진 특수성 때문에 별도 레퍼런스 체계가 필요하다고 봅니다. 예를 들어:

• instantiate()는 Variant를 반환하므로 := 타입 추론이 깨질 수 있음
• abs(), clamp() 같은 함수는 다형적이라 명시 타입이 필요할 수 있음
• 람다 캡처 동작이 Python과 다름
• 씬 빌더와 런타임 스크립트의 생명주기가 완전히 다름

이런 내용은 모델이 학습 데이터만으로 안정적으로 맞히기 어렵습니다. 그래서 godot-task는 별도의 gdscript.md, quirks.md, 그리고 850개가 넘는 Godot 클래스 문서를 지연 로딩 방식으로 참조합니다. _common.md와 _other.md로 인덱스를 먼저 보고, 필요한 클래스 문서만 추가로 불러옵니다. (GitHub)

이 부분은 아키텍처적으로 아주 영리합니다.

전체 API 문서를 한 번에 집어넣으면 컨텍스트가 터집니다.
반대로 아무 문서도 안 넣으면 환각이 발생합니다.
Godogen은 그 중간에서 2단계 인덱스 + 클래스별 lazy lookup으로 균형을 맞춥니다.
LLM 시스템 설계 관점에서 보면, 이 프로젝트의 진짜 강점은 “생성 모델을 더 똑똑하게 만들었다”가 아니라 도메인 지식을 토큰 효율적으로 조회하게 만들었다는 데 있습니다. (GitHub)

---

씬 빌더와 런타임 스크립트를 분리한 이유

이 저장소를 자세히 보면 .tscn을 직접 손으로 쓰게 하지 않습니다.
대신 헤드리스 GDScript로 씬을 생성하는 scene builder를 먼저 쓰고, 그 결과로 .tscn 파일을 만듭니다. 이후 런타임 로직은 별도의 .gd 스크립트로 분리합니다. (GitHub)

이 설계가 중요한 이유는 두 가지입니다.

하나는 .tscn 직편집의 취약성입니다.
직렬화 포맷을 직접 맞추는 방식은 LLM이 실수하기 쉽습니다.

다른 하나는 빌드 타임과 런타임의 책임 분리입니다.
씬 빌더는 SceneTree를 상속해 한 번 실행되고 씬을 저장한 뒤 종료합니다. 이 단계에서는 @onready, 라이브 시그널 연결, 실시간 트리 의존 로직을 쓸 수 없습니다. 반대로 런타임 스크립트는 _ready(), _process(), _physics_process() 등 실제 실행 시점 로직을 담당합니다. 문서에서도 이 구분을 흐리면 버그가 발생한다고 명시합니다. (GitHub)

이건 단순한 구현 디테일이 아니라, 에이전트가 어떤 종류의 코드를 언제 생성해야 하는지에 대한 실행 모델입니다.

---

시각 QA가 왜 이 프로젝트를 특별하게 만드는가

Godogen의 가장 강한 차별점은 단연 Visual QA입니다.

작업이 끝나면 시스템은 실제 게임 화면을 캡처합니다. 그리고 그 이미지를 reference image 및 작업의 검증 조건과 비교합니다. 정적인 장면은 대표 프레임 하나로 보고, 움직임이 중요한 장면은 2 FPS 정도의 프레임 시퀀스로 평가합니다. 여기서 확인하는 것은 단순히 “화면이 떴는가”가 아닙니다.

• z-fighting
• 누락된 텍스처
• 부자연스러운 배치
• 잘못된 스케일
• 조명 누수
• 물리 이상 동작
• 애니메이션/움직임의 어색함

문서에 따르면 실패 시 최대 3회까지 수정-재캡처 루프를 돌고, 구조적 문제라고 판단되면 상위 오케스트레이터에게 재계획을 요청합니다. (GitHub)

이 지점이 정말 중요합니다.
지금까지 많은 AI 코딩 시스템이 “컴파일 성공 = 완료”에 가깝게 동작했습니다.
하지만 게임에서 컴파일 성공은 출발선일 뿐입니다. Godogen은 그걸 알고, 사람 QA가 화면을 보며 하는 판단을 모델 루프 안에 끌어들였습니다.

---

아키텍처를 그림으로 보면 이렇다

이 다이어그램에서 봐야 할 포인트는 두 가지입니다.

첫째, 모든 하위 단계가 오케스트레이터에 매달린 것이 아니라 문서 산출물로 연결된다는 점입니다.
둘째, 검증이 맨 마지막 이벤트가 아니라 작업 실행 루프 안으로 들어가 있다는 점입니다. (GitHub)

---

실제 사용 흐름은 어떻게 되나

프로젝트를 실제로 쓰는 흐름은 생각보다 단순합니다.

먼저 새 게임 디렉터리를 만들고 스킬을 퍼블리시합니다.

./publish.sh ~/my-game

혹은 커스텀 CLAUDE.md를 쓰고 싶다면 다음처럼 사용합니다.

./publish.sh ~/my-game local.md

그 뒤 생성된 폴더에서 Claude Code를 열고 /godogen으로 게임 설명을 넣으면 됩니다. 기본 teleforge.md는 Telegram 연동을 전제로 해서, 원격으로 진행 상황과 스크린샷, 최종 비디오를 받아보는 구조까지 염두에 두고 있습니다. 문서에는 GCE의 T4/L4 같은 GPU VM에서 몇 시간 단위 생성 작업을 돌리는 사용 방식도 설명되어 있습니다. (GitHub)

예를 들면 이런 식의 프롬프트가 가능하겠죠.

탑다운 시점의 2D 로그라이크 슈터를 만들어줘.
플레이어는 회피 대시가 가능하고,
웨이브마다 적이 많아지며,
네온 SF 스타일의 화면과 굵은 UI를 원해.

그러면 시스템은 바로 코드부터 쓰는 것이 아니라,

• 이 게임의 대표 화면을 상상한 reference image를 만들고
• 필요한 기능을 태스크로 쪼개고
• 플레이어/적/UI/웨이브 구조를 설계하고
• 필요한 에셋과 실제 씬/스크립트를 만든 뒤
• 캡처와 QA로 결과를 점검합니다. (GitHub)

---

개발자 입장에서 특히 좋게 보이는 점

이 프로젝트를 자세히 보면 “와, AI가 게임을 만든다”보다 더 흥미로운 포인트가 있습니다.

1. 생성보다 검증에 더 진심이다

실제로 안정적인 시스템은 보통 생성 능력보다 검증 루프가 강합니다. Godogen도 정확히 그 방향입니다. 컴파일, 실행, 캡처, VQA까지 이어지는 구조가 이 프로젝트의 핵심 경쟁력입니다. (GitHub)

2. 도메인 특화 지식을 프롬프트가 아니라 조회 시스템으로 넣었다

Godot와 GDScript는 범용 코드 모델이 강하지 않은 영역입니다. 이 저장소는 그 현실을 인정하고, 억지로 “모델이 알아서 알겠지”라고 하지 않습니다. 대신 문서 인덱스와 lazy loading으로 해결합니다. (GitHub)

3. 에이전트 간 통신을 대화가 아니라 파일로 설계했다

이건 실제 운영 가능한 시스템 설계에서 큰 장점입니다. 장애 복구, 재시도, 수동 개입, 상태 추적이 쉬워집니다. (GitHub)

4. Scene Builder 패턴이 현실적이다

Godot 씬 파일을 문자열로 바로 찍어내는 대신, 빌더 스크립트로 .tscn을 생산하는 전략은 매우 공학적입니다. LLM이 실수하기 쉬운 포맷 편집을 우회합니다. (GitHub)

---

그렇다면 어디에서 쓰면 좋은가

Godogen은 모든 게임 개발 문제를 해결하는 도구는 아닙니다. 하지만 다음 상황에서는 굉장히 매력적입니다.

프로토타입이 중요한 인디/실험 프로젝트

새 게임 아이디어를 며칠이 아니라 빠르게 시각화하고 싶을 때 적합합니다. 특히 “재미 여부를 빨리 확인해야 하는” 프로토타이핑 단계와 잘 맞습니다. 저장소 문서도 프로토타이핑 속도 문제를 핵심 배경으로 언급합니다. (GitHub)

Godot 기반 AI 게임 제작 연구

Godot를 중심으로 한 agentic workflow, visual QA, GDScript tooling 연구에는 아주 좋은 사례입니다. 이 저장소는 단순 사용 도구라기보다 설계 패턴 레퍼런스로도 가치가 있습니다. (GitHub)

“코드 생성”보다 “작동하는 결과물”이 중요한 경우

게임, UI-heavy 앱, 시뮬레이션처럼 텍스트 정합성보다 화면/동작 정합성이 중요한 도메인에 이 아키텍처는 매우 잘 맞습니다. 이는 Godogen의 시각 검증 루프가 그대로 확장 가능한 포인트이기도 합니다. (GitHub)

---

반대로 한계도 분명하다

이 프로젝트를 과장해서 보면 안 되는 이유도 있습니다.

첫째, 문서상 단일 생성 런이 몇 시간 걸릴 수 있습니다. 즉, instant toy generator가 아닙니다. (GitHub)

둘째, 3D까지 포함하면 Gemini, Tripo3D, Godot, Python 환경 등 외부 의존성이 있습니다. 완전히 self-contained한 프로젝트는 아닙니다. (GitHub)

셋째, teleforge.md에도 명시되어 있듯 현재 제한으로 오디오 지원이 없고, animated GLB도 다루지 않습니다. (GitHub)

넷째, macOS는 아직 미검증이며, 스크린샷 캡처가 X11/xvfb/Vulkan 경로에 기대고 있어서 Linux/VM 친화적입니다. (GitHub)

그리고 무엇보다, 저는 이 분석에서 저장소 구조와 문서를 기반으로 판단했지, 이 세션에서 직접 Godot 환경을 구성해 end-to-end 실행까지 확인한 것은 아닙니다. 그래서 평가는 “문서와 설계의 완성도”에 더 가깝습니다.

---

기술적으로 가장 배울 만한 한 줄

Godogen에서 진짜 배울 점을 한 줄로 요약하면 이겁니다.

LLM을 더 똑똑하게 만드는 대신, 문제를 잘게 쪼개고, 필요한 지식을 지연 로딩하고, 실행 결과를 시각적으로 검증하는 시스템을 만든다.

이건 게임 생성에만 해당하지 않습니다.
화면이 중요한 프런트엔드 생성, CAD/3D 파이프라인, 시뮬레이션 UI, 로보틱스 대시보드처럼 “코드가 맞는가”보다 “결과가 맞는가”가 중요한 분야 전체에 적용 가능한 패턴입니다. (GitHub)

---

최종 평가

htdt/godogen은 “AI가 게임을 만든다”는 자극적인 데모를 넘어서, 그걸 어떻게 공학적으로 성립시키는지를 꽤 진지하게 보여주는 프로젝트입니다.

이 저장소의 가치는 세 가지로 정리됩니다.

• 문서 기반 오케스트레이션
• GDScript/Godot 특화 지식 시스템
• 실행 화면을 기준으로 한 시각 QA 폐루프

즉, 이 프로젝트는 화려한 생성 모델 쇼케이스가 아니라,
에이전트 기반 소프트웨어 생산 시스템의 설계서에 더 가깝습니다.

게임 개발자라면 “언젠가 써볼 도구”로 볼 수 있고,
AI 에이전트 시스템을 만드는 개발자라면 “지금 당장 구조를 훔쳐와도 되는 레퍼런스”로 볼 수 있습니다. (GitHub)