이 글은 https://ziva.sh/blogs/ai-assistant-large-godot-project의 일본어 버전입니다 (영어 원문은 Ziva.sh가 2026년 11월 7일에 공개했습니다).
AI 어시스턴트는 대규모 Godot 프로젝트에서도 전체를 놓치지 않고 작업할 수 있을까요? 저희는 Ziva와 Claude Code에 Pixelorama에 동일한 기능을 추가하도록 요청했습니다. Pixelorama는 Godot 4로 작성된 오픈 소스 픽셀 아트 에디터이며, GDScript 파일이 249개(약 60,000줄)이고 장면(scene)이 120개 있습니다. 두 도구 모두 Claude Opus 5.5를 사용했습니다. 추가할 기능은 8개의 파일에 걸쳐 있습니다. 여기에는 셰이더, 새로운 대화형 장면과 스크립트, 메뉴 코드, 단축키 목록, 레이어 효과 목록, 프로젝트 설정 및 번역 템플릿이 포함됩니다.
도구별로 총 4회(각 도구당 2회) 실행을 진행했으며, 모두 실행 중인 앱에서 동일한 독립적인 검사를 통과했습니다. Ziva는 각각 6분과 13분이 걸렸고, Claude Code는 두 번 모두 약 16분이 소요되었습니다. 개인 작업 테스트에서는 Claude Code가 더 신중했습니다. Ziva의 게임 러너는 대기 상태여서 아무런 조작이 없는 Pixelorama의 스크린샷을 찍지 못했으며, Ziva는 프로젝트 루트에 예상치 못한 파일을 남겼습니다. 자세한 내용은 다음과 같습니다.
Ziva는 Ziva.sh에서 개발했으며, 이 테스트 역시 Ziva.sh가 진행했습니다.
테스트는 2026년 11월 7일에 Linux 환경의 Godot 4.7.2를 대상으로 Pixelorama 커밋 5b2ebf5 (MIT 라이선스)을 사용하여 실행되었습니다. Ziva는 같은 날짜의 개발 빌드를, Claude Code는 2.1.318 버전을 사용했습니다. 두 도구 모두 추론 설정은 기본값으로 유지했습니다. 첫 번째 실행은 두 도구 간 시간이 겹쳤고, 두 번째 실행은 동일한 머신에서 동시에 시작했기 때문에 머신의 CPU를 공유하게 되었습니다. Ziva로 Claude Opus 5.5를 사용하려면 Pro 플랜(월 $50)이 필요합니다.
두 도구 모두 프로젝트의 새 복사본에 다음 프롬프트를 한 글자도 빠짐없이 전달했습니다 (실제로 사용한 영어 프롬프트와 그 번역입니다).
Add a Sepia color effect to this project (Pixelorama). It should work like the existing color effects:
1. Effects > Color > Sepia opens a dialog with an Intensity slider (0 to 100%, default 100%) and a live preview. Applying it works on the same targets as Desaturation (selected cels, current frame, all frames, all projects, and only the selection when that option is checked), with undo.
2. Sepia gets its own shortcut entry in Preferences > Shortcuts like the other effects (no default key).
...
번역: 이 프로젝트(Pixelorama)에 Sepia(세피아) 컬러 효과를 추가해 주세요. 기존의 컬러 효과와 동일하게 작동해야 합니다.
- Effects > Color > Sepia에서 Intensity(강도) 슬라이더(0~100%, 기본값 100%)와 라이브 프리뷰가 있는 대화 상자가 열려야 합니다. 적용은 Desaturation(채도 감소)과 동일한 대상(선택된 셀, 현재 프레임, 모든 프레임, 모든 프로젝트, 해당 옵션에 체크되어 있을 때만 선택 범위)에서 작동하며, 되돌리기(undo)가 가능해야 합니다.
- Preferences > Shortcuts에 다른 효과들과 마찬가지로 Sepia 전용 단축키 항목이 있어야 합니다 (기본 키 없음).
- Layer Effects 대화 상자에서 Sepia를 비파괴적 레이어 효과로 사용할 수 있으며, 동일한 Intensity 매개변수가 있어야 합니다.
이펙트에 대해서는 프로젝트의 기존 패턴을 따르세요. 완료 후에는 프로젝트가 이전과 동일하게 열리고 새로운 오류 없이 실행되는지 확인하세요.
대규모 프로젝트에서 어시스턴트가 '전체 맥락을 놓치는' 것은 바로 이러한 종류의 변경 사항입니다. 이펙트가 어디에 등록되어 있는지에 대한 정보는 프롬프트 어느 곳에도 적혀 있지 않습니다. Pixelorama에서는 각 이펙트를 5곳에서 연결하고 있어, 단 한 곳이라도 누락되면 아무 반응이 없는 메뉴 항목, 표시되지 않는 바로 가기(shortcut), 존재하지 않는 레이어 이펙트 중 하나가 됩니다.
Ziva는 Godot 에디터 내에서 자동 승인(auto-approval)을 켜고 실행했습니다. Claude Code는 터미널에서 실행했습니다. 플러그인, MCP 서버, 프로젝트 지침 없이 권한을 자동 승인으로 설정하고, 커맨드 라인(command line)에서 Godot과 가상 디스플레이를 사용할 수 있도록 했습니다.
| Ziva 1차 시도 | Ziva 2차 시도 | Claude Code 1차 시도 | Claude Code 2차 시도 |
|---|
| 실행 중인 앱에서의 점검 | 합격 | 합격 | 합격 |
| ... | | | |
| 점검에는 모든 실행에서 동일한 스크립트를 사용했습니다. 실행 중인 앱에서 Effects > Color > Sepia를 열고, 파란색 캔버스에 적용하고, 되돌린 후, 선택 영역에만 50%로 적용하고, 바로 가기 항목을 확인하며, Sepia를 레이어 이펙트로 추가합니다. 네 번 모두 동일한 픽셀 값이 나왔으며, 어떤 실행에서도 시작 로그(startup log)에 새로운 오류가 증가하지 않았습니다. | | | |
Claude를 구독하여 사용할 경우, Claude Code의 견적 방식이 아닌 정액 요금을 지불합니다. Ziva의 비용은 플랜에 포함된 사용량에 따라 달라집니다. 어떤 실행도 모델의 컨텍스트 상한(context limit)에는 훨씬 미치지 못했기 때문에, 요약이 필요할 정도로 긴 채팅을 각 도구가 어떻게 처리하는지는 이 테스트만으로는 알 수 없습니다.
Ziva는 코드의 인덱싱(indexing)도, 임베딩(embedding)도 수행하지 않았으며, 프로젝트를 모델에 로드시키지도 않았습니다. 두 실행 모두에서 첫 단계는 스크립트, 씬(scene), 셰이더(shader), 프로젝트 설정, 번역 파일을 대상으로 'desaturat'을 검색하는 것이었습니다. 이 검색을 통해 기존의 Desaturation 이펙트가 연결된 모든 위치를 찾았습니다. 그 후, 첫 번째 실행에서는 17개, 두 번째 실행에서는 22개의 파일을 읽고 동일한 패턴을 모방했습니다.
도중에 유용했던 몇 가지 사항이 있었는데, 모두 Ziva가 Godot 에디터 내에서 작동했기 때문에 가능했습니다.
- 스크립트를 편집할 때마다 GDScript를 점검. Ziva는
.gd 파일을 생성하거나 편집할 때마다 Godot의 언어 서버(language server)가 해당 파일과 이 파일에 의존하는 파일을 점검했습니다. 결과는 모두 'No problems in this file or its callers.' (이 파일과 그 호출원에 문제가 없습니다)였습니다.
- 프로젝트 설정은 Godot를 통해. Ziva는 바로 가기 입력 액션(input action)을
project.godot 파일을 수동으로 편집하는 것이 아니라, Godot의 프로젝트 설정 API로 추가했습니다. 첫 번째 시도에서는 먼저 현재 입력 맵(input map)을 읽어왔습니다.
- 스텁이 아닌 실제 앱. Ziva는 에디터에서 Pixelorama의 메인 씬을 실행하고, 그 출력과 오류를 읽었습니다.
- 다음 차트를 위한 메모리. 두 번째 시도에서는 Pixelorama 코드의 테스트 방법을 기록한 프로젝트 메모리를 Ziva가 저장했습니다. 다음 채팅은 이 정보에 대한 단서가 있는 상태로 시작됩니다. 자세한 내용은 메모리를 참고하세요.
Claude Code는 셸(shell) 도구로 같은 결과에 도달했습니다. grep, sed 그리고 가상 디스플레이에서 커맨드 라인으로 실행되는 Godot을 사용했습니다. 변경 대상 파일 역시 Ziva와 동일했습니다.
- 대기 중인 Pixelorama에서, Ziva의 게임 러너가 타임아웃. Pixelorama는 Godot의 저프로세서 모드(low-processor mode)를 활성화하고 있기 때문에, 무언가 변경되었을 때에만 다시 그리기(redraw)합니다. Ziva의
run_scene
렌더링된 프레임을 기다려 스크린샷을 찍기 때문에 메인 씬 실행이 약 35초 만에 타임아웃되었습니다. 각 실행에서 두 번씩 발생했습니다. 원인은 확인되었습니다. 저성능 모드(low processor mode)를 비활성화하자 동일한 호출로 스크린샷이 반환되었습니다. Ziva는 앱을 조작하여 결과를 출력하는 임시 테스트 씬(temporary test scene)을 만들어 이를 회피했습니다. 두 번째 실행에서는 이 테스트 씬이 앱의 렌더링을 계속 진행하게 했기 때문에 run_scene도 스크린샷을 반환했습니다.
Ziva의 스크립트 러너가 Pixelorama의 오토로드(autoload)를 불러오지 못했습니다. 단발성 GDScript 실행 러너가 “Identifier not found: Global”이라고 보고했기 때문에, Ziva는 위의 테스트 씬으로 전환했습니다.
예상치 않게 남겨진 파일들. 첫 번째 실행에서는 테스트 씬과 스크립트를 프로젝트 루트(project root)에 남기고 삭제할지 물었습니다. 두 번째 실행에서는 테스트 파일을 삭제했지만, 테스트 중에 루트에 untitled.png가 나타났고, Ziva는 이 점을 지적했습니다.
테스트 범위의 차이. Ziva는 선택된 셀(Selected cels) 대상만 테스트했으며, Ziva 자신도 그렇게 전달했습니다. Claude Code는 네 가지 모든 대상을 포함하여 저장 및 불러오기까지 테스트했습니다. Claude Code는 첫 번째 실행에서 Pixelorama의 공통 효과 코드에 있을 법한 버그를 보고했습니다. 이 효과를 모든 프로젝트에 적용할 경우, 다른 프로젝트가 현재 프로젝트 크기로 잘려나간다는 내용이었습니다. 해당 줄을 읽고 보고와 일치하는지 확인했지만, 재현은 하지 못했습니다.
Full Game Playtest Agent는 실행되지 않았습니다. Ziva는 두 번의 실행에서 사용하려고 했지만, 로컬 테스트 환경의 인증 정보(credentials) 문제로 시작 전에 멈췄습니다. 이 테스트만으로는 Full Game Playtest Agent에 대해 좋다고도 나쁘다고도 말할 수 없습니다.
대상은 하나의 프로젝트, 하나의 기능, 도구별로 두 번의 실행, 그리고 하나의 모델이었습니다. 이 작업은 여러 파일에 걸친 기능 추가였습니다. 다수의 씬(scene)에 걸친 이름 변경이나 파일 이동 같은 것은 아직 테스트하지 않았습니다. 두 도구 모두 채팅을 요약할 필요는 없었습니다. 다른 모델, 더 큰 프로젝트, 또는 더 모호한 프롬프트에서는 결과가 다를 수 있습니다.
이번 테스트에서 유용했던 습관으로, 어떤 어시스턴트에게나 적용 가능합니다.
- 기존 예시 제시. “Desaturation과 동일하게 작동하도록”이라는 지시로, 두 도구 모두 어디를 봐야 할지 알았습니다. 프로젝트 내의 유사한 씬(scene), 스크립트, 메커니즘을 이름으로 지정해 주어야 합니다.
- 프로젝트 규칙 작성. Ziva는 프로젝트 내
AGENTS.md 파일을 읽고, Claude Code는 CLAUDE.md를 읽습니다. 폴더 구성, 오토로드, 규약을 거기에 적어두면 어시스턴트가 채팅할 때마다 다시 조사할 필요가 없습니다.
- 프로젝트 실행. 두 도구 모두 보고하기 전에 Pixelorama를 실행하여 오류를 읽었습니다. 텍스트 편집만 하는 어시스턴트는 로딩에 실패하는 씬을 볼 수 없습니다.
- 새로운 작업에는 새로운 채팅을 사용합니다. 오래된 파일 내용으로 가득 찬 긴 채팅에서는 현재 변경 사항을 적용할 여지가 줄어듭니다.
두 도구를 더 광범위하게 비교한 글은 Ziva vs Claude Code for Godot(영어)입니다. Claude Code를 사용하고 있는 상태에서 그 안에서 Ziva의 Godot 도구를 사용하고 싶다면, Ziva를 로컬 MCP 서버로 실행할 수 있습니다.
이번 테스트에서는 다룰 수 있었습니다. 둘 다 Claude Opus 5.5를 사용하여 Ziva와 Claude Code에게 Pixelorama(GDScript 파일 249개, 약 60,000줄, 씬 120개)에 Sepia 효과를 추가하도록 요청했습니다. 변경 사항은 8개의 파일에 걸쳐 있었으며, 셰이더, 다이얼로그 씬 및 스크립트, 메뉴 코드, 단축키 목록, 레이어 효과 목록, 프로젝트 설정, 번역 템플릿 등에 이르렀습니다. 네 번의 실행(도구별로 두 번) 모두 실행 중인 앱에서 동일한 독립적인 검사에 합격했습니다. 하나의 프로젝트와 하나의 작업에서의 결과이므로, 벤치마크가 아닌 한 가지 예시로 봐주십시오.
모델이 볼 수 있는 것은 컨텍스트 윈도우(context window)의 내용물뿐이며, 큰 프로젝트는 그 안에 담기지 않습니다. 에이전트는 올바른 파일을 검색하고, 해당 파일만 읽으며, 채팅이 길어져도 자신의 메모를 유지해야 합니다. Pixelorama 테스트에서 Ziva는 프로젝트의 1,383개 파일 중 17개와 22개를 읽었으며, 컨텍스트 최대값은 각각 137,000 토큰과 157,000 토큰으로 Claude Opus 5.5의 한도를 크게 밑돌았습니다.
Ziva는 GDScript 편집을 모두 Godot의 언어 서버(language server)에서 검사합니다. 새로운 채팅에도 계승되는 프로젝트 메모리(project memory)를 저장할 수 있으며, 프로젝트 규칙이 작성된 AGENTS.md 파일을 읽고, 긴 채팅이 모델의 한계에 가까워지면 자동으로 요약합니다.
이번에 테스트한 것은 리네임(rename)이 아니라, 여러 파일에 걸친 기능 추가입니다. Ziva는 셰이더와 다이얼로그 시퀀스 및 해당 스크립트를 생성하고, 기존의 5개 파일을 수정했습니다. 여기에는 Godot 자체 프로젝트 설정 API를 거친 project.godot 편집도 포함됩니다.
Ziva의 두 번의 실행 모두 검사에 합격했습니다. 다만, 다수의 시퀀스에 걸친 대규모 리네임이나 이동은 아직 테스트하지 않았습니다.
이 작업에서는 둘 다 작동하는 코드를 만들었습니다. Ziva는 6분과 13분이 걸렸고, 플랜 사용량으로 $1.94와 $2.93을 소비했습니다. Claude Code는 둘 다 약 16분이 걸렸으며, API 가격 추정치는 각각 $2.70와 $3.58이었습니다. 테스트는 Claude Code가 더 꼼꼼했습니다. 적용 대상 4개 전체와 저장/읽기를 확인했으며, 한 번의 실행에서는 Pixelorama의 공통 효과 코드에 있을 법한 버그도 보고했습니다. Ziva가 테스트한 것은 기본 대상만이었고, 두 실행 모두 프로젝트 루트에 파일을 남겼으며, Ziva는 이 점을 지적했습니다.
아닙니다. Ziva에는 코드 임베딩(code embedding)도, 시맨틱 인덱스(semantic index)도 없습니다. 필요할 때 ripgrep 기반의 파일 검색과 텍스트 검색으로 프로젝트를 검색하고, 파일을 범위별로 읽습니다. 대규모 프로젝트의 첫 채팅에서 표시될 수 있는 "Indexing project" 메시지는 Ziva가 Undo(실행 취소)에 사용하는 기록을 생성하는 것이지, 코드 인덱스가 아닙니다.
이 기사의 원문(영어): https://ziva.sh/blogs/ai-assistant-large-godot-project
