AI 코딩 에이전트를 위한 경량 Unity Editor 브릿지 구축하기

AI 코딩 에이전트(AI coding agents)는 코드를 작성하는 능력이 점점 향상되고 있습니다.

하지만 제가 Unity와 함께 이들을 본격적으로 사용하기 시작했을 때, 계속해서 동일한 문제에 부딪혔습니다.

그들은 C# 파일을 편집할 수는 있었지만, Unity Editor 내부에서 어떤 일이 일어나고 있는지 신뢰할 수 있는 방식으로 알지는 못했습니다.

Unity 개발에서 파일 시스템은 진실의 일부일 뿐입니다.

실제 질문들은 종종 다음과 같습니다:

Unity가 프로젝트를 컴파일했는가?
Console 에러가 있는가?
어떤 씬(Scene)이 활성화되어 있는가?
이 GameObject가 실제로 존재하는가?
Inspector에서 컴포넌트(Component) 값이 변경되었는가?
Play Mode를 시작할 수 있는가?
EditMode 또는 PlayMode 테스트를 통과하는가?
에이전트가 UI를 변경했다면, 실제로 제대로 보이는가?

실행 중인 Editor에 접근할 수 없다면, AI 에이전트는 추측을 해야만 합니다.

그것이 제가 hera-agent-unity를 만들기 시작한 이유입니다.

GitHub:
https://github.com/NotNull92/hera-agent-unity

hera-agent-unity란 무엇인가?

hera-agent-unity는 오픈 소스 Go CLI 및 Unity Editor 패키지입니다.

이 도구는 AI 코딩 에이전트가 localhost HTTP를 통해 실행 중인 Unity Editor와 통신할 수 있게 해줍니다.

에이전트는 다음과 같은 명령을 호출할 수 있습니다:

hera-agent-unity status
hera-agent-unity console --type error --lines 20
hera-agent-unity scene info
...

또한 Editor 내부에서 C#을 실행할 수도 있습니다:
hera-agent-unity exec 'return UnityEditor.EditorSceneManager.GetActiveScene().name;'

목표는 AI가 "마법처럼 Unity를 이해하게" 만드는 것이 아닙니다.
목표는 더 실용적입니다:
에이전트가 프로젝트를 편집하고, 실제 Unity Editor에 무슨 일이 일어났는지 묻고, 문제를 해결한 뒤, 완료되었다고 말하기 전에 다시 검증하도록 하는 것입니다.

왜 그냥 MCP를 사용하지 않나요?

MCP는 유용합니다. 저는 그것에 반대하지 않습니다.
하지만 이 프로젝트를 위해 저는 의도적으로 CLI 우선(CLI-first) 설계를 선택했습니다.
그 이유는 Unity Editor 자동화에는 매우 특정한 워크플로우(Workflow)가 있기 때문입니다.
대부분의 경우, 저는 일반적인 도구 프로토콜(tool protocol), 서버 협상(server negotiation), 또는 거대한 구조화된 응답(structured responses)이 필요하지 않습니다.
저는 코딩 에이전트가 작고 반복 가능한 질문을 던지기를 원합니다:

Editor가 준비되었는가?
프로젝트가 컴파일되었는가?
최근 Console 에러가 있는가?
씬(Scene)에 어떤 오브젝트들이 존재하는가?
Play Mode를 시작할 수 있는가?
내 변경 사항이 실제로 적용되었는가?

그러한 루프(loop)에서는 응답 크기가 중요합니다.
AI 에이전트는 컨텍스트(context), 지연 시간(latency), 그리고 비용(cost)의 제한을 받습니다. 만약 모든 Editor 작업이 거대한 오브젝트 그래프(object graph)나 장황한 스키마(schema)를 반환한다면, 해당 도구는 반복적으로 사용하기에 실용성이 떨어지게 됩니다.
따라서 Hera는 컴팩트한 명령(compact commands)을 중심으로 설계되었습니다.

예를 들어:

list --compact는 약 93 토큰(tokens)입니다.
find_gameobjects --ids는 약 49-55 토큰입니다.
부수 효과(side-effecting)가 있는 명령들은 보통 단순히 OK만을 반환합니다.

이것이 작게 들릴 수도 있지만, 워크플로(workflow)를 변화시킵니다.
명령의 비용이 충분히 저렴하다면, 에이전트는 이를 자주 호출할 수 있습니다.
이는 에이전트가 추측하는 대신 검증(verify)할 수 있음을 의미합니다.

내가 원했던 워크플로

내가 원했던 워크플로는 다음과 같습니다:

AI 에이전트가 Unity 코드를 수정함
        ↓
실제 Editor에게 무슨 일이 일어났는지 물어봄
...

이는 Unity에서 특히 중요한데, 많은 에러가 텍스트 에디터 내부의 일반적인 컴파일러 피드백(compiler feedback)으로 나타나지 않기 때문입니다.
스크립트는 컴파일될 수 있지만, 씬(scene)은 여전히 잘못되어 있을 수 있습니다.
프리팹(prefab)은 존재할 수 있지만, 인스펙터(Inspector) 값이 에이전트가 의도한 것과 다를 수 있습니다.
UI가 기술적으로는 생성되었을지라도, 시각적으로는 깨져 있을 수 있습니다.
Play Mode 문제는 Editor가 실제로 실행될 때에만 나타날 수도 있습니다.

에이전트 전용 규칙 (Agent-specific rules)

프로젝트의 또 다른 부분은 에이전트 규칙 생성(agent rule generation)입니다.

Hera는 다음과 같은 도구들을 위한 프로젝트 규칙을 생성할 수 있습니다:

Codex
Claude
Cursor
GitHub Copilot
Google AntiGravity

아이디어는 간단합니다.
AI 코딩 에이전트가 프로젝트에 진입했을 때, 즉시 다음 사항들을 알아야 합니다:

어떤 Hera 명령을 사용해야 하는지
Unity 상태를 어떻게 검사(inspect)하는지
거대한 Unity 오브젝트를 반환하는 것을 어떻게 피하는지
Console 에러를 어떻게 읽는지
완료를 주장하기 전에 어떻게 검증하는지

예를 들어, 전체 GameObject나 Transform을 반환하는 대신, 규칙은 에이전트가 컴팩트한 식별자(identifiers)를 반환하도록 유도합니다:

var go = GameObject.Find("Player");
return new { name = go.name, instanceID = go.GetInstanceID() };

도구의 출력값이 에이전트의 컨텍스트 (context) 일부가 될 때, 이와 같은 작은 디테일들이 매우 중요합니다.

Ultra Hera

제가 최근에 추가한 최신 기능은 Ultra Hera라고 불립니다.
이는 AI 지원 Unity 작업을 위한 검증 워크플로우 (verification workflow)입니다.
이 기능이 스스로 AI 작업을 수행하는 것은 아닙니다. 대신, 에이전트가 Hera를 사용한 후 자신의 Unity 작업 내용을 얼마나 주의 깊게 확인해야 하는지 알려줍니다.
두 가지 주요 모드가 있습니다.

Light Mode

Light Mode는 기본 모드입니다.

이 모드는 에이전트가 다음과 같이 행동하도록 유도합니다:

목표 확인
필요한 Unity 상태 (state)만 읽기
변경 사항 적용
컴파일 또는 상태 검증
최근 Console 에러 확인
변경된 대상만 다시 읽기
필요 시 한두 번 재시도
짧은 증거 보고

이는 일반적인 Unity 코딩, Editor 및 Inspector 작업에 적합하도록 설계되었습니다.

Ultra Mode

Ultra Mode는 더 엄격한 요청을 위한 모드입니다.

예를 들어:
"실행해서 확인해줘"
"Inspector도 확인해줘"
"이 UI와 일치시켜줘"
"테스트를 실행해줘"
"이것을 정확하게 검증해줘"

이러한 경우, 워크플로우는 다음과 같이 격상될 수 있습니다:

Play Mode 확인
EditMode 또는 PlayMode 테스트
스크린샷 캡처
UI 캡처
더 깊은 수준의 Inspector 또는 에셋 상태 확인

핵심은 모든 작업을 무겁게 만드는 것이 아닙니다.
핵심은 작업의 위험도에 맞춰 검증의 깊이를 조절하는 것입니다.

UI Juicy Mode

제가 가장 좋아하는 부분 중 하나는 UI Juicy Mode입니다.
AI가 생성한 UI는 종종 작동은 하지만, 정적인 느낌을 줍니다.
버튼, 패널, 라벨을 배치할 수는 있지만, UI를 살아있는 것처럼 느끼게 만드는 게임 플레이 느낌 (game-feel) 레이어를 잊어버릴 수 있습니다.
UI Juicy Mode가 활성화되면, Hera는 agent_hint를 통해 에이전트에게 게임 플레이 느낌 레시피 (game-feel recipes)를 보낼 수 있습니다.

예시로는 다음과 같은 것들이 있습니다:

버튼 호버 (hover) 피드백
누를 때의 찌그러짐 (press squash)
뗄 때의 튕김 (release bounce)
팝업 오버슈트 (overshoot)
데미지 텍스트 움직임
프로그레스 바 (progress bar) 피드백
가벼운 애니메이션 제안

따라서 에이전트는 단순히 UI 요소를 배치하는 데 그치지 않습니다.
더욱 게임 UI다운 느낌을 주는 UI를 만들도록 유도됩니다.

Unity version support

또한 Unity 버전을 별도로 확인하는 데 시간을 할애했습니다.
지금까지 확인된 버전은 다음과 같습니다:

Unity 2022.3 LTS
Unity 2023.2
Unity 6.3
Unity 6.5

Dogfooding (도그푸딩)

저는 개인 Unity 게임 프로젝트인 NoMoreRolls를 구축하면서 Hera를 직접 사용(dogfooding)하고 있습니다.
README에 Play Mode (플레이 모드) 미리보기를 포함한 이유는, 이 도구가 단순한 명령 목록이 아니라 실제 Unity 워크플로우에서 어떻게 사용되는지 보여주고 싶었기 때문입니다.

배운 점

이 프로젝트를 구축하며 얻은 가장 큰 교훈은 AI 보조 개발 (AI-assisted development)이 단순히 코드 생성에 관한 것이 아니라는 점입니다.
실제 프로젝트를 위해서는 더 중요한 질문이 있습니다:
AI가 실제 제품 환경 내부에서 안전하게 작동할 수 있는가?

Unity의 경우, 그것은 Editor (에디터)를 의미합니다.
웹 앱의 경우, 브라우저를 의미할 수 있습니다.
백엔드 시스템의 경우, 로그, 테스트, 로컬 서비스, 데이터베이스 또는 배포 미리보기(deployment previews)를 의미할 수 있습니다.
패턴은 동일합니다:
AI는 단순히 변경 사항을 작성하는 것에 그쳐서는 안 됩니다.
시스템을 관찰하고, 결과를 검증하며, 스스로 수정할 수 있어야 합니다.
그것이 제가 hera-agent-unity를 통해 탐구하고 있는 방향입니다.

Repository (저장소)