AI 에이전트를 위한 CLI: Unity, Unreal, Godot에서 토큰 최대 83% 절감

이제 세 가지 엔진 커맨드라인 도구인 unity-mcp-cli, unreal-mcp-cli, godot-cli를 AI 에이전트가 훨씬 적은 비용으로 사용할 수 있습니다. 동일한 에디터 작업에서 콜드 스타트 에이전트는 이전 버전보다 토큰을 60%에서 83%까지 덜 쓰고, 도구 호출 횟수도 눈에 띄게 줄였습니다. 방법은 단순하고 약간 겸연쩍은 것이었습니다. 작은 AI 에이전트에게 CLI만 주고, 어디서 막히는지 지켜본 뒤, 그 부분을 고치고, 다시 측정했습니다.

이 글에서는 그 작업의 세 라운드를 살펴보고, 수치(잘못된 방향으로 간 것 하나 포함)와 AI 에이전트를 위한 CLI를 만드는 누구에게나 적용되는 교훈을 정리합니다. Claude Code, Codex 또는 다른 에이전트를 Unity, Unreal Engine, Godot과 함께 사용한다면, 이번 변경은 더 짧은 세션, 더 적은 재시도, 더 작은 청구서를 의미합니다.

AI 에이전트용 CLI를 테스트한 방법

모든 라운드의 모든 실행은 동일한 엄격한 환경에서 진행했으므로, 결과는 실제 머신에서 실제 에이전트가 마주하는 상황을 반영합니다.

• 에이전트는 작고 빠른 LLM(DeepSeek Flash)입니다. 작은 모델은 큰 모델이 조용히 우회하는 거친 부분을 드러냅니다.
• 에이전트에게는 CLI와 기본 파일 도구만 주어집니다. MCP 연결도, 문서도, 프롬프트 안의 힌트도 없습니다.
• 콜드 스타트로 시작합니다. 새 프로젝트, 엔진은 닫혀 있고, 캐시된 것은 없습니다.
• 실제 최종 상태가 올바를 때만 통과입니다. 디스크의 씬 또는 레벨 파일, 혹은 컴파일 결과가 기준입니다. 에이전트가 스스로 했다고 말하는 것은 인정되지 않습니다.

에이전트가 읽고 쓴 토큰, 턴 또는 도구 호출 횟수, 도구 오류, 통과한 작업을 집계했습니다. 그다음 트랜스크립트를 읽었습니다. 수치는 무언가 느리다는 것을 알려주고, 트랜스크립트는 그 이유를 알려주기 때문입니다.

라운드 1: 에이전트가 길을 찾을 수 있을까?

첫 트랜스크립트는 거칠었습니다. 에이전트는 에디터의 AI 도구를 아예 찾지 못했습니다. CLI가 "로그인되지 않음"이라고 하자, 이를 피하려고 설정 파일을 직접 편집했습니다. 존재하지 않는 명령 이름을 추측하기도 했습니다. 이는 에이전트의 잘못이 아닙니다. CLI가 알아야 할 것을 알려주지 않았을 뿐입니다.

그래서 첫 번째 수정 라운드는 탐색에 관한 것이었습니다.

• 새로운 tools 명령은 엔진이 닫혀 있어도 에디터의 AI 도구를 나열합니다. 헤드리스 에디터를 한 번 실행해 목록을 캐시하고, 이후에는 캐시에서 응답합니다.
• --help 출력 끝에는 이제 일상 워크플로를 요약한 짧은 푸터가 붙습니다. 에이전트가 실제로 필요한 몇 가지 명령을 필요한 순서대로 보여줍니다.
• ai-game.dev에 한 번도 로그인하지 않은 머신은 이제 막다른 길 대신 로컬 서버를 사용합니다. 로그인된 머신은 항상 클라우드에 머뭅니다.
• 헤드리스 에디터는 컴파일 오류에서 살아남고, 아무 말 없이 실패하는 대신 로그 위치를 에이전트에게 알려줍니다.
• 새로운 test 및 compile 명령(godot-cli에서는 check라고 부릅니다)과, 에디터를 막고 있는 모달 다이얼로그를 나열하고 그중 하나의 버튼을 누를 수 있는 Unity 및 Unreal용 dialog 명령이 추가되었습니다.
• 세 CLI 모두 종료 코드가 동일하며, 에이전트용 명령은 스크립트가 파싱할 수 있는 출력을 위해 --format json을 받아들입니다.

이 단계의 첫 라운드와 마지막 라운드를 비교하면(작업당 한 번 실행) 다음과 같습니다.

• Unity: 입력 토큰 275k → 104k(−62%), 턴 46 → 30.
• Godot: 입력 토큰 598k → 203k(−66%), 턴 71 → 40, 통과한 작업 3/4 → 4/4, 도구 오류 27 → 6.
• Unreal: 입력 토큰 383k → 414k(+8%), 턴 66 → 60, 도구 오류 13 → 8.

세 엔진 전체에서 에이전트는 해결한 작업당 입력 토큰을 1.9배 덜 사용했고(114k → 60k), 12개 중 11개가 아니라 12개 작업 모두를 통과했습니다.

그렇습니다, Unreal은 늘어났습니다. 에이전트는 오류를 덜 내고 더 적은 턴으로 끝냈지만, 그 과정에서 더 많이 읽었습니다. 라운드 1은 에이전트가 무엇을 찾을 수 있는지를 고쳤습니다. 얼마나 많이 읽어야 하는지는 아직 고치지 못했고, 그것이 다음 라운드의 주제였습니다.

라운드 2: 초반의 모든 바이트는 매 턴마다 다시 지불된다

이 라운드의 핵심 통찰은 한 번 보면 간단합니다. 에이전트의 대화는 단계마다 길어지고, 초반에 읽은 모든 내용은 이후 매 턴마다 모델로 다시 전송됩니다. 첫 턴에 읽은 커다란 도움말 페이지는 두 번째, 열 번째, 서른 번째 턴에도 다시 지불됩니다.

베이스라인에서 루트 --help(4.8 KB이며 항상 에이전트가 가장 먼저 읽는 것)는 전체 도구 출력의 토큰 가중치 중 43%를 차지했습니다. RQL 스키마가 또 24%를 차지했습니다. 초반의 두 번의 읽기가 비용의 3분의 2였습니다.

수정 사항은 다음과 같습니다.

• 바로 사용할 수 있는 RQL 레시피가 담긴 짧은 --help. 에이전트가 레퍼런스를 공부하는 대신 동작하는 쿼리를 복사할 수 있습니다.
• 전체 스키마 대신 간결한 스키마 개요.
• 올바른 소스나 멤버 이름에 대한 힌트를 포함하는 RQL 오류.
• 쿼리를 일반 인자로 받는 일급 rql 명령. JSON 인용을 잘못할 일이 없습니다.
• 디스크에 기록한 파일을 출력하는 저장 작업. 예전에는 에이전트가 저장이 실제로 되었는지 확인하느라 4~9번의 호출을 추가로 썼습니다.

RQL은 에디터 도구가 씬, 오브젝트, 컴포넌트, 에셋을 읽고 변경하는 데 사용하는 쿼리 언어입니다. ai-game.dev/docs/rql 에서 더 읽어볼 수 있습니다.

다음 아이디어를 얹기 전에 각 아이디어를 개별적으로 측정했습니다. Unreal에서 작업당 세 번 실행했을 때 단계별 결과는 다음과 같습니다.

1. 베이스라인: 403k 토큰, 도구 호출 60회.
2. 레시피가 담긴 짧은 도움말, 간결한 스키마, RQL 힌트: 123k 토큰(−69%).
3. 여기에 일급 rql 명령 추가: 106k 토큰(−74%).
4. 여기에 기록된 파일을 출력하는 저장 추가: 68k 토큰(−83%), 도구 호출 31회(−48%).

같은 변경을 세 CLI 모두에 적용하고, 매 실행마다 콜드 스타트에서 측정했습니다(Unreal은 작업당 세 번, Unity와 Godot은 두 번).

• Unreal: 토큰 403k → 68k(−83%), 도구 호출 60 → 31.
• Unity: 토큰 248k → 82k(−67%), 도구 호출 33.5 → 26, 통과한 작업 4/4.
• Godot: 토큰 131k → 53k(−60%), 도구 호출 34 → 28.5, 통과한 작업 4/4.

라운드 3: CLI가 스스로 작성하는 작은 스킬

많은 에이전트가 스킬을 지원합니다. 작업이 해당될 때 에이전트가 불러오는 짧은 지침 파일입니다. 각 CLI의 setup-skills 명령은 이제 에디터를 실행하지 않고 오프라인으로 약 2.2 KB 크기의 스킬을 작성합니다. 이 스킬은 --help와 같은 소스에서 생성되므로 둘이 어긋날 수 없습니다.

스킬이 없는 에이전트와 스킬이 있는 에이전트를, 둘 다 최적화된 CLI에서, 세 가지 에디터 작업과 207번의 격리된 실행으로 비교했습니다.

• Unity: 토큰 160k → 60k(−63%), 도구 호출 42 → 23, 18/18 통과.
• Unreal: 토큰 87k → 53k(−39%), 도구 호출 37 → 24, 9/9 통과.
• Godot: 토큰 117k → 81k(−31%), 도구 호출 49 → 39, 18/18 통과.

스킬을 조정하면서 세 가지가 놀라웠습니다.

• 짧은 스킬이 긴 스킬을 이겼습니다. 스킬의 모든 줄은 도움말처럼 매 턴마다 다시 읽힙니다.
• 경고 형태로 쓰인 규칙은 에이전트가 추가 확인을 하게 만들었습니다. 사실을 담백하게 서술하는 편이 경고하는 것보다 나았습니다.
• 코드에만 관한 작업에서는 스킬이 큰 도움이 되지 않습니다. 스킬의 가치는 씬, 레벨, 오브젝트, 에셋 같은 에디터 작업에 있습니다.

AI 에이전트용 CLI를 만드는 모든 이에게 주는 교훈

이 중 게임 엔진에만 해당하는 것은 없습니다. AI 에이전트가 사용할 커맨드라인 도구를 만든다면, 다음이 우리가 전하고 싶은 교훈입니다.

• 워크플로와 레시피를 --help에 넣으세요. 에이전트는 도움말을 가장 먼저 읽습니다. 전체 레퍼런스가 아니라 중요한 다섯 개 명령과 각각의 동작하는 예제를 주세요.
• 초반 출력을 아주 작게 유지하세요. 에이전트가 처음 몇 턴에 읽는 것은 이후 매 턴마다 다시 지불됩니다. 첫 화면을 과감히 줄이세요.
• 결과가 스스로 검증되게 하세요. 저장이 파일 경로와 함께 "디스크에 저장됨"을 출력하면, 에이전트는 확인하느라 호출을 낭비하지 않습니다.
• 모든 오류에 다음 단계를 주세요. 유효한 옵션을 알려주는 오류는 막다른 길을 한 번의 호출로 바꿉니다.
• 콜드 스타트 평가로 측정하세요. 작은 모델, 새 프로젝트, 실제 최종 상태 확인을 사용하세요. 트랜스크립트를 읽고, 한 번에 하나만 바꾸고, 다시 측정하세요.

직접 사용해 보기

새 명령은 각 엔진 플러그인의 최신 릴리스에 포함되어 있습니다. unity-mcp-cli 1.11.1, unreal-mcp-cli 0.31.1, godot-cli 0.39.1입니다. unity-mcp-cli --help(또는 Unreal이나 Godot의 해당 명령)에 rql과 tools가 나오지 않는다면 이전 버전이므로, update 명령으로 최신 버전으로 올릴 수 있습니다.

npx unity-mcp-cli tools
npx unity-mcp-cli rql 'objects | where name starts-with "Tree" | count'
npx unity-mcp-cli compile
npx unity-mcp-cli setup-skills claude-code

npx unreal-mcp-cli tools --filter rql
npx unreal-mcp-cli rql 'actors | where Label starts-with "Rock" | set Scale = Scale * 1.5'
npx unreal-mcp-cli rql 'editor | call SaveLevel()'

npx godot-cli rql 'nodes | where name contains "Enemy" | count'
npx godot-cli check
npx godot-cli setup-skills claude-code

첫 에디터 명령이 헤드리스 에디터를 실행하고 계속 유지하므로, 엔진을 먼저 열 필요가 없습니다. rql로 수행한 변경은 무엇이 바뀌었고 어떤 파일이 기록되었는지 출력하므로, 에이전트는 곧바로 다음 단계로 넘어갈 수 있습니다.

시작하기

• Unity: ai-game.dev/engines/unity
• Unreal Engine: ai-game.dev/engines/unreal
• Godot: ai-game.dev/engines/godot
• RQL 쿼리 언어: ai-game.dev/docs/rql
• 퀵스타트 가이드: ai-game.dev/docs/quickstart
• Discord 커뮤니티: https://discord.gg/cfbdMZX99G

CLI가 성장하는 동안 우리는 이 콜드 스타트 평가를 계속 실행할 것입니다. 에이전트가 어딘가에서 막힌다면 Discord에서 알려주세요. 어디서 잘못됐는지 담긴 트랜스크립트가 바로 우리에게 필요한 것입니다.