Unity AI를 코드 작성 파트너로 쓰는 기준
Unity에서 AI를 쓴다는 것은 코드를 통째로 대신 맡긴다는 뜻이 아니다. 더 정확히 말하면, 구현 의도를 Unity Editor 안에서 바로 설명하고, 초안 코드와 작업 계획을 빠르게 받아 검토하는 방식이다. 검색창, 문서, IDE, 에디터를 오가며 반복하던 시간을 줄이는 데 효과가 있다.
Unity AI는 Unity 6 이상 Editor 안에서 사용하는 AI 제작 도구 흐름으로, Assistant, AI Gateway, MCP Server 같은 구성 요소를 포함한다. 이 가운데 Assistant는 질문과 오류 분석에 쓰는 Ask 모드, 실행 전에 여러 단계 작업을 정리하는 Plan 모드, 스크립트 작성이나 씬 수정 같은 변경을 수행하는 Agent 모드로 나누어 사용할 수 있다.1 Ask 모드는 기본적으로 프로젝트를 바꾸지 않는 읽기 중심 모드이고, Plan 모드는 사람이 계획을 검토한 뒤 승인하는 흐름이며, Agent 모드는 권한 설정에 따라 실제 프로젝트 변경을 실행한다. 이 장에서는 MCP 자동화보다 먼저, Unity Editor 안에서 AI Assistant를 이용해 작은 기능을 만들고 검토하는 기본 흐름을 다룬다.
좋은 사용 순서는 단순하다.
Ask 모드에서 구현 방향을 질문한다.
Plan 모드에서 작업 단계를 확인한다.
필요한 범위만 승인한 뒤 Agent 모드로 작은 변경을 실행한다.
생성된 코드와 씬 변경 사항을 사람이 검토한다.
Play 모드와 콘솔 로그로 결과를 확인한다.
처음부터 큰 시스템을 맡기지 않는다. 플레이어 이동, 카메라 추적, 버튼 클릭 이벤트처럼 입력과 결과가 분명한 기능부터 시작하는 것이 좋다. Unity AI는 계속 업데이트되는 도구이므로, 패키지 버전과 권한 설정에 따라 메뉴 이름이나 세부 동작이 조금씩 달라질 수 있다는 점도 함께 기억해 둔다.
AI 생성 이미지
자연어 요청은 기능 명세처럼 작성한다
AI에게 "플레이어 이동 만들어 줘"라고 요청하면 결과가 넓게 흔들린다. 2D인지 3D인지, Rigidbody를 쓸지 CharacterController를 쓸지, 새 Input System을 쓰는지 구 Input Manager를 쓰는지 알 수 없기 때문이다.
요청은 목표, 현재 상태, 제약, 검증 기준을 함께 적는다.
목표: 3D 플레이어가 WASD로 이동하고 마우스로 좌우 회전하게 해 주세요.
현재 상태: 씬에 Player 오브젝트가 있고 CharacterController 컴포넌트가 붙어 있습니다.
제약: Rigidbody는 사용하지 않습니다. 이동 속도와 회전 속도는 Inspector에서 조정할 수 있어야 합니다.
검증 기준: Play 모드에서 WASD 입력으로 이동하고, 콘솔에 NullReferenceException이 없어야 합니다.
작업 방식: 먼저 필요한 스크립트 구조를 설명하고, 그다음 C# 스크립트를 작성해 주세요.이런 요청은 AI가 추측해야 할 범위를 줄인다. 특히 Unity에서는 같은 기능도 구현 방식이 여러 가지다. 이동 기능만 해도 Transform 직접 이동, Rigidbody 물리 이동, CharacterController 이동, NavMeshAgent 이동이 모두 가능하다. 사람은 먼저 프로젝트의 기준을 알려 주어야 한다.
카메라 추적 기능도 마찬가지다.
목표: Main Camera가 Player를 부드럽게 따라가게 해 주세요.
현재 상태: Player 태그가 붙은 오브젝트가 씬에 있습니다.
제약: Cinemachine은 사용하지 않습니다. 카메라와 플레이어의 거리 offset은 Inspector에서 수정 가능해야 합니다.
검증 기준: 플레이어가 움직일 때 카메라가 끊기지 않고 따라오며, Player를 찾지 못하면 경고 로그를 출력해야 합니다.UI 버튼 이벤트 요청은 Figma에서 정리한 화면 구조와 연결하면 더 좋다.
목표: StartButton을 누르면 GameScene을 로드하는 UI 이벤트를 만들어 주세요.
현재 상태: Canvas 아래에 StartButton 오브젝트가 있고 Button 컴포넌트가 있습니다.
제약: 씬 이름은 Inspector에서 문자열로 설정하게 해 주세요. 버튼 참조는 [SerializeField]가 붙은 private 필드로 받습니다.
검증 기준: 버튼을 누르면 지정한 씬이 로드되고, 버튼 참조가 비어 있으면 에러가 아니라 경고를 출력해야 합니다.핵심은 AI에게 "무엇을 만들지"뿐 아니라 "어떤 방식은 피할지"와 "어떻게 확인할지"를 알려 주는 것이다. 이렇게 적어 두면 AI가 만든 코드가 마음에 들지 않았을 때도 다시 요청하기 쉽다. "아까 조건 중 Rigidbody를 쓰지 말라는 제약을 지키지 않았습니다. CharacterController 기준으로 다시 작성해 주세요"처럼 바로 수정 방향을 줄 수 있기 때문이다.
생성된 C# 스크립트는 세 가지를 먼저 본다
AI가 만든 코드는 초안이다. 실행 전에 최소한 세 가지를 확인해야 한다.
첫째, MonoBehaviour 생명주기가 맞는지 본다. MonoBehaviour는 Unity 컴포넌트 스크립트의 기본 클래스다. Awake, Start, Update, FixedUpdate, OnEnable, OnDisable 같은 메서드가 언제 실행되는지에 따라 버그가 생길 수 있다.
예를 들어 입력을 매 프레임 읽는 코드는 보통 Update에 둔다. 물리 기반 이동은 FixedUpdate를 고려한다. 버튼 이벤트 등록은 OnEnable에서 하고 해제는 OnDisable에서 하는 방식이 안전할 때가 많다. AI가 Start에서 한 번만 값을 읽고 끝내는지, 매 프레임 갱신해야 하는 값을 놓치지 않았는지 확인한다.
둘째, Inspector에서 조정해야 할 값이 [SerializeField]로 열려 있는지 본다. [SerializeField]는 private 필드를 Unity Inspector에 노출할 때 쓰는 C# 속성이다. 외부 코드에서 마음대로 바꾸지 못하게 하면서도 디자이너나 기획자가 값은 조정할 수 있다.
예를 들어 이동 속도, 회전 속도, 카메라 offset, 버튼 참조, 씬 이름은 하드코딩하지 않는 편이 좋다. AI가 코드 안에 숫자를 직접 박아 넣었다면 다음처럼 다시 요청한다.
방금 생성한 스크립트에서 이동 속도, 회전 속도, 카메라 offset을 [SerializeField]가 붙은 private 필드로 바꿔 주세요. 기본값을 지정하고, Inspector에서 음수 값이 들어가지 않도록 OnValidate에서 보정하는 방법도 제안해 주세요.셋째, NullReferenceException 가능성을 본다. NullReferenceException은 비어 있는 참조를 사용하려 할 때 발생하는 대표적인 Unity 오류다. 씬 오브젝트를 찾지 못했거나, Inspector에 연결해야 할 필드를 비워 두었거나, 런타임에 파괴된 오브젝트를 계속 참조할 때 자주 발생한다.
AI가 GameObject.Find, FindObjectOfType, 태그 검색 같은 전역 검색 방식에 지나치게 의존한다면 주의해야 한다. 작은 프로토타입에서는 가능하지만, 실제 프로젝트에서는 명시적인 참조 연결이나 초기화 검증이 더 안전하다. 코드에 다음 요소가 있는지 확인한다.
필수 참조가 비어 있을 때 경고를 남기는가
비어 있는 참조를 바로 사용하지 않는가
버튼 이벤트를 중복 등록하지 않는가
씬 이름, 태그 이름, 레이어 이름 같은 문자열이 한곳에서 관리되는가
Play 모드에서 껐다 켰을 때 같은 동작을 반복해도 문제가 없는가
AI에게 코드 리뷰를 요청할 때도 이 기준을 그대로 주면 된다.
아래 스크립트를 Unity 초보자 기준으로 리뷰해 주세요. MonoBehaviour 생명주기 사용이 적절한지, [SerializeField]로 열어야 할 값이 있는지, NullReferenceException 가능성이 있는지 중심으로 봐 주세요. 수정 제안은 이유와 함께 제시해 주세요.AI Gateway로 기존 AI 사용 환경을 Editor 안으로 가져온다
이미 Claude Code, Codex, Gemini CLI, Cursor CLI 같은 외부 AI 작업 흐름에 익숙한 팀이라면 Unity AI Gateway가 유용하다. AI Gateway는 Unity Editor의 Assistant 창 안에서 외부 코딩 에이전트를 사용할 수 있게 연결하는 기능이다. 공식 문서에서는 Claude Code, Codex, Gemini, Cursor 같은 에이전트를 Assistant 안에서 선택해 사용할 수 있다고 설명한다.2
구조는 이렇게 이해하면 쉽다.
Unity Editor는 현재 프로젝트, 콘솔, 씬, 에셋 정보를 가진 작업 공간이다.
외부 AI 에이전트는 코드 작성과 추론에 익숙한 도구다.
AI Gateway는 둘 사이를 연결해, 기존 AI 구독이나 API 키 기반 작업 흐름을 Unity 안으로 가져온다.
설정은 Assistant 창에서 에이전트를 선택하고, 필요한 경우 에이전트 설치와 인증 정보를 등록하는 방식으로 진행한다. Gateway 설정은 Unity Editor의 Unity > Settings > Preferences > AI > Gateway에서 확인할 수 있다. 다만 운영체제와 Unity 버전에 따라 Preferences로 들어가는 메뉴 이름은 조금 다르게 보일 수 있으므로, Assistant가 표시하는 Gateway 링크를 따라가도 된다. 에이전트 실행 파일 경로가 비어 있으면 CLI Path를 지정하고, 필요한 환경 변수나 API 키를 등록한다. 예를 들어 Claude Code는 ANTHROPIC_API_KEY, Gemini CLI는 GEMINI_API_KEY 같은 환경 변수를 요구할 수 있다.3
여기서 중요한 점은 보안이다. API 키는 저장소에 커밋하지 않는다. 팀 프로젝트에서는 개인 키와 조직 키를 구분하고, 사용 권한이 있는 좌석이 제대로 배정되어 있는지도 확인해야 한다. AI Gateway는 편리한 연결 통로이지만, 권한 관리까지 대신해 주지는 않는다.
또 하나 기억할 점은 Gateway가 "검토 책임"을 없애 주지는 않는다는 것이다. 외부 에이전트가 Unity Editor 안에서 더 편하게 동작하더라도, 생성된 코드가 프로젝트 규칙을 지키는지, 씬을 불필요하게 바꾸지 않았는지, 비용과 API 사용량이 적절한지는 팀이 확인해야 한다.
디버깅 요청에는 콘솔과 씬 상태를 함께 준다
AI에게 "에러 고쳐 줘"라고만 쓰면 정확도가 낮다. Unity 오류는 코드 한 줄만 보고 판단하기 어려운 경우가 많다. 콘솔 로그, 스택 트레이스, 씬 오브젝트 상태, 컴포넌트 연결 상태를 함께 제공해야 한다.
좋은 디버깅 요청은 다음 형식으로 작성한다.
문제: Play 버튼을 누르면 플레이어 이동이 되지 않습니다.
콘솔 로그: NullReferenceException이 PlayerMovement.Update 32번째 줄에서 발생합니다.
관련 코드: 아래 PlayerMovement 스크립트 전체를 붙입니다.
씬 상태: Player 오브젝트에는 CharacterController가 붙어 있습니다. CameraRig는 비활성화되어 있습니다.
Inspector 상태: moveSpeed는 5, controller 필드는 비어 있습니다.
원하는 답변: 원인 후보를 우선순위로 정리하고, 초보자가 확인할 순서와 수정 코드를 제시해 주세요.컴파일 에러도 마찬가지다. 에러 메시지에는 파일명, 줄 번호, 에러 코드가 들어 있다. 예를 들어 CS0103은 현재 문맥에서 이름을 찾을 수 없다는 뜻이고, CS0246은 타입이나 네임스페이스를 찾을 수 없다는 뜻일 때가 많다. AI에게는 에러 메시지를 요약하지 말고 그대로 제공한다.
Unity Console의 컴파일 에러를 분석해 주세요.
에러 원문: Assets/Scripts/CameraFollow.cs(18,12): error CS0103: The name 'target' does not exist in the current context
상황: CameraFollow 스크립트를 AI가 생성한 뒤 변수명을 수정했습니다.
요청: 왜 발생했는지 설명하고, 변수명 불일치인지 필드 선언 누락인지 확인하는 절차를 알려 주세요. 수정 코드는 최소 변경으로 제안해 주세요.AI가 원인을 제시하면 바로 믿지 말고, Unity Console에서 에러가 사라졌는지 확인한다. 그다음 Play 모드에서 기능이 실제로 동작하는지 본다. 컴파일 성공은 기능 완성이 아니다. 버튼은 눌러 봐야 하고, 카메라는 움직여 봐야 하며, 플레이어 이동은 입력 장치별로 확인해야 한다.
작은 기능 단위로 반복한다
Unity AI를 잘 쓰는 팀은 큰 요청을 한 번에 던지지 않는다. "인벤토리 시스템 전체를 만들어 줘"보다 "아이템 슬롯 UI를 클릭했을 때 선택 상태를 표시해 줘"가 낫다. "전투 시스템을 구현해 줘"보다 "공격 버튼 입력 시 애니메이션 트리거를 호출하고 쿨다운을 적용해 줘"가 낫다.
작은 단위로 요청하면 검증도 쉬워진다. 문제가 생겨도 원인을 좁힐 수 있다. AI가 만든 코드가 프로젝트 스타일과 맞지 않으면 바로 수정 요청을 할 수 있다.
반복 흐름은 다음처럼 잡는다.
기능 목표를 한 문장으로 정한다.
현재 씬과 오브젝트 상태를 적는다.
사용할 Unity 방식과 피할 방식을 정한다.
AI에게 계획을 먼저 요청한다.
스크립트 생성 후 생명주기,
[SerializeField], null 검사를 확인한다.콘솔 오류와 Play 모드 결과를 다시 AI에게 제공한다.
수정된 내용을 커밋 전에 사람이 리뷰한다.
Unity AI의 장점은 구현 의도를 에디터 작업과 가깝게 연결한다는 데 있다. 하지만 최종 품질은 여전히 사람이 책임진다. AI는 검색과 반복 코딩 시간을 줄여 주고, 초안을 빠르게 만든다. 설계 기준, 입력 방식, 성능 목표, 사용자 경험은 팀이 정해야 한다.
이 기준을 지키면 Unity AI는 단순한 코드 생성기가 아니라, 기능 구현과 디버깅을 빠르게 반복하는 실무 도구가 된다.
참고
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.