Unity 프로젝트에서 AI를 효율적으로 사용하기 위한 토큰 절약 기술

서론 (Introduction)

개발 중이거나 이미 프로덕션 단계에 있는 Unity 프로젝트에서 AI 코딩 에이전트 (AI coding agents)를 사용하면 조사, 구현 및 검토 속도를 크게 높일 수 있습니다.

동시에, 프로젝트의 규모가 커질수록 다음과 같은 문제에 직면할 가능성이 높아집니다:

• 에이전트가 관련 없는 디렉토리를 읽음.
• Library/ 또는 Temp/와 같은 생성된 파일들을 검사하려고 시도함.
• 거대한 Scene / Prefab / ScriptableObject YAML 파일들을 통째로 읽음.
• Addressables 출력물이나 대규모 로그를 읽음으로써 토큰을 소비함.
• 매 채팅마다 동일한 프로젝트 설명을 반복해야 함.
• AGENTS.md / CLAUDE.md에 너무 많은 내용을 작성하여, 에이전트가 이를 덜 신뢰성 있게 따르기 시작함.

AI를 효과적으로 사용하는 중요한 부분은 단순히 강력한 모델을 선택하는 것이 아닙니다.

그것은 AI가 무엇을 읽어야 하고, 무엇을 읽지 말아야 하는지를 설계하는 것입니다.

이 기사는 Unity 프로젝트에 초점을 맞추어 AI 에이전트를 사용할 때 토큰 사용량을 줄이는 실질적인 방법들을 요약합니다. 마지막에는 Unity 및 UE5 프로젝트 모두에 맞춰 조정할 수 있는, 복사해서 붙여넣기 좋은 AGENTS.md 및 CLAUDE.md 템플릿을 포함했습니다.

AGENTS.md / CLAUDE.md를 영어로 작성하는 것을 권장합니다

이 기사의 샘플들은 AGENTS.md와 CLAUDE.md를 영어로 작성합니다.

여기에는 네 가지 주요 이유가 있습니다.

첫째, 대부분의 코드베이스는 이미 영어를 중심으로 구성되어 있습니다. 클래스 이름 (Class names), 메서드 이름 (Method names), 파일 이름 (File names), API 이름 (API names), 에러 메시지 (Error messages), 그리고 CLI 명령 (CLI commands)은 대개 영어입니다. 지침 (Instructions) 또한 영어로 작성되면 코드 내의 이름들과 자연스럽게 매핑됩니다.

둘째, 영어 규칙은 Codex, Claude Code, Gemini CLI, Cursor와 같은 여러 AI 에이전트 전반에 걸쳐 재사용하기가 더 쉽습니다. 일본어 지침도 작동하지만, 기계 대상 팀 규칙 (machine-facing team rules)에는 일반적으로 영어가 더 안전합니다.

셋째, 영어 지침은 짧게 유지하기가 더 쉽습니다. Do not edit generated files.와 같은 규칙은 일본어의 정중한 문장에 비해 짧고 명확합니다.

넷째, 어떤 경우에는 컨텍스트 크기 (context size)를 약간 줄여줄 수 있습니다. 이것이 영어가 항상 일본어보다 극적으로 적은 토큰을 생성한다는 의미는 아닙니다. 이는 모델, 토크나이저 (tokenizer), 그리고 텍스트가 어떻게 작성되었는지에 따라 달라집니다. 그럼에도 불구하고, 기계가 읽는 짧은 규칙 (machine-facing rules)의 경우, 영어는 압축적인 경향이 있어 불필요한 설명을 제거하기가 더 쉽습니다.

그렇다고 해서 영어로 전환하는 것만으로 토큰 사용량이 마법처럼 줄어드는 것은 아닙니다. 더 큰 효과는 중복을 줄이고, 디렉토리를 명확하게 제외하며, 대용량 파일을 전체적으로 읽는 것을 피하는 데서 옵니다.

따라서 모든 것을 영어로 작성할 필요는 없습니다. 사람이 읽는 노트, 내부 용어, 그리고 배경 컨텍스트 (background context)는 일본어나 팀에서 사용하는 언어로 작성해도 됩니다.

저의 권장 사항은 다음과 같습니다:

AI가 반드시 따라야 하는 짧은 규칙은 영어로 작성하고, 팀원들을 위한 보충 설명은 팀이 선호하는 언어로 작성하세요.

하지만 팀이 영어 규칙을 확신을 가지고 검토할 수 없다면, 모든 것을 영어로 강제하는 것은 위험합니다. 실무적으로는 AI가 읽는 규칙은 짧은 영어로 유지하고, 사람이 읽는 배경 지식과 예외 사항은 팀이 관리할 수 있는 언어로 추가하는 것이 가장 좋습니다.

제1원칙: 지침 파일은 강제 수단이 아니다

AGENTS.md와 CLAUDE.md는 유용하지만, 먼저 바로잡아야 할 오해가 하나 있습니다.

이 파일들은 AI 에이전트 (AI agents)를 위한 **컨텍스트 (context)**입니다.
이것들은 강제적인 설정 (hard enforcement settings)이 아닙니다.

예를 들어, 다음과 같이 작성하더라도:

Do not inspect Library/

AI가 Library/를 절대 읽지 않을 것이라는 보장은 없습니다.

물론, 작성하는 것이 작성하지 않는 것보다 훨씬 낫습니다. 이는 에이전트의 첫 움직임을 안내하고 불필요한 읽기를 줄여줍니다. 하지만 이는 강제 규칙 (hard rule)이라기보다는 요청이나 작업 정책 (working policy)에 더 가깝습니다.

더 강력한 보장이 필요하다면, 지침 파일에만 의존하지 마세요. 다음과 같은 계층과 결합하여 사용해야 합니다:

• .gitignore
• .sembleignore
• Claude Code의 claudeMdExcludes
• Claude Code hooks
• Codex sandbox / approval / config
• CI / lint / tests
• 애초에 생성된 파일들을 Git에서 제외하기

토큰 절약을 위한 첫 번째 방어선은 .gitignore입니다.
Unity의 Library/ 및 Temp/, 그리고 Unreal의 Intermediate/ 및 Saved/ 폴더는 일반적으로 Git에서 추적하지 않아야 합니다.

AI 에이전트는 로컬 디스크의 추적되지 않는 파일(untracked files)을 여전히 읽을 수 있으므로, .gitignore가 완벽한 차단책은 아닙니다. 하지만 생성된 파일들을 검색 대상, 인덱스(indexes), 그리고 차이점(diffs)에서 제외해주기 때문에 여전히 매우 중요합니다.

AI가 모든 것을 읽게 하지 마세요

대규모 프로젝트에서 할 수 있는 최악의 행동은 에이전트에게 다음과 같이 모호하게 질문하는 것입니다:

이 Unity 프로젝트를 살펴보고 문제를 해결해 주세요.

이는 사람에게 "이 회사의 모든 파일을 읽고 무언가를 개선해 보세요"라고 말하는 것과 같습니다.
AI는 성실하게 수행하려고 노력하며 광범위하게 검색할 것이고, 이는 종종 관련 없는 파일들을 읽게 된다는 것을 의미합니다.

더 나은 요청 방식은 처음부터 검색 범위를 좁히는 것입니다:

로그인 화면의 입력 유효성 검사(input validation)만 조사해 주세요.
먼저 Semble을 사용하여 관련 파일을 찾은 다음, 후보 파일들과 그것들이 중요한 이유를 보고하세요.
그 이후에 최소한으로 필요한 파일들만 읽으세요.

핵심은 **조사 대상(investigation target)**과 **검색 프로세스(search process)**를 사전에 지정하는 것입니다.

다음과 같은 사항들을 명확히 하세요:

• 어떤 기능이 연관되어 있는가?
• 어떤 디렉토리를 검사해야 하는가?
• 어떤 디렉토리는 검사하면 안 되는가?
• 어떤 검색 방법을 먼저 사용해야 하는가?
• 파일을 즉시 수정해도 되는가?
• 변경 사항을 적용하기 전에 조사 결과를 먼저 보고해야 하는가?

이러한 사항들을 명시하는 것만으로도 불필요한 읽기 작업을 크게 줄일 수 있습니다.

Unity 프로젝트에서 토큰을 쉽게 소비하는 파일들

Unity 프로젝트에는 AI 에이전트가 검사하기에 무거운 요소들이 많이 포함되어 있습니다.

일반적인 예시는 다음과 같습니다:

반면에, 에이전트가 보통 가장 먼저 검사해야 할 위치는 예측 가능한 경우가 많습니다.

Unity 및 Addressables 버전에 따라, AddressableAssetsData에도 생성된 파일이 포함될 수 있습니다. 대규모 .bin 파일이나 카탈로그(catalogs)를 전체 읽기(full reads) 하는 것은 피하고, 추출(extraction) 방식을 선호하세요.

Semble 검색으로 시작하기

대규모 코드베이스에서는 grep이나 rg를 사용한 뒤 여러 파일을 읽는 것만으로도 많은 토큰을 소비할 수 있습니다.

로컬 시맨틱 코드 검색 (Local semantic code search)이 도움이 될 수 있습니다. 이 글에서는 Semble을 예시로 사용합니다.

Semble 및 관련 사례 연구에 대한 자세한 정보는 마지막의 참고 문헌(References) 섹션에 포함되어 있습니다. Semble이 처음이라면 해당 링크들을 먼저 훑어보는 것도 좋습니다.

Semble은 AI 에이전트를 위한 코드 검색 라이브러리입니다. 자연어 쿼리(natural language queries)를 사용하여 코드 스니펫(code snippets)을 검색하고, 파일 전체 대신 관련 스니펫을 반환할 수 있습니다. MCP, CLI 또는 AGENTS.md 내의 지침을 통해 사용할 수 있습니다.

공식 문서에 따르면 grep + read 방식과 비교했을 때 토큰 감소 효과를 보여줍니다. 또한 Claude Code와 함께 semble을 사용할 때의 토큰 사용량 감소를 측정한 일본 Zenn 기사도 있습니다.

이러한 수치는 저장소(repository), 인덱스 대상(index targets), 검색 쿼리(search queries), 그리고 AI 에이전트가 결과를 읽는 방식에 따라 크게 달라집니다. 이 글에서 저는 Semble을 고정된 감소율을 보장하는 도구가 아니라, 검색 우선 워크플로(search-first workflows)를 구현하는 하나의 실질적인 방법으로 다룹니다.

또한, Semble은 마법이 아닙니다. .gitignore 또는 .sembleignore가 설정되지 않아 생성된 파일들이 인덱싱되면, 검색 결과 자체가 노이즈(noisy)가 될 수 있습니다.

Semble에는 다음과 같은 한계도 있습니다:

• 잘못된 쿼리는 관련 없는 결과를 반환합니다.
• 생성된 파일과 거대한 데이터 파일이 인덱스를 오염시킬 수 있습니다.
• 최종 확인을 위해서는 여전히 소스 파일을 검사해야 합니다.
• 정확한 API 이름이나 식별자(identifiers)를 찾는 데는 rg가 더 빠르고 정확할 수 있습니다.

실질적인 구분은 다음과 같습니다:

의미로 검색: Semble
정확한 문자열 검색: rg / grep
대용량 파일 검사: 추출 스크립트 (extraction scripts)
...

유용한 AGENTS.md 규칙은 다음과 같습니다:

## 검색 정책 (Search policy)

사용 가능하고 적절한 경우, 의미론적 코드 검색 (semantic code search)을 위해 Semble을 우선적으로 사용하십시오.
...

폴더 구조를 미리 작성하기

AI가 매번 프로젝트 구조를 추론하게 만드는 것은 낭비입니다.

AGENTS.md에 최소한의 폴더 맵을 작성하세요.

## 프로젝트 레이아웃 (Project layout)

- `Assets/Scripts/`
...

많은 경우 이것만으로 충분합니다.
모든 디렉터리를 문서화할 필요는 없습니다.

중요한 점은 AI가 어디서 시작해야 할지, 무엇을 피해야 할지를 빠르게 파악할 수 있게 하는 것입니다.

AGENTS.md / CLAUDE.md에 포함할 내용

AGENTS.md와 CLAUDE.md는 전체 사양서(specifications)가 아닙니다.
이것들은 AI 에이전트(AI agents)를 위한 작업 가이드입니다.

유용한 범위는 대략 다음과 같습니다:

• 프로젝트 개요 (Project overview)
• 사용된 기술 (Technologies used)
• 중요한 디렉터리 (Important directories)
• 피해야 할 디렉터리 (Directories to avoid)
• 검색 정책 (Search policy)
• 생성된 파일 정책 (Generated file policy)
• 코딩 규칙 (Coding rules)
• 작업 프로세스 (Work process)
• 검증 방법 (Verification methods)
• 변경하지 말아야 할 사항 (Things not to change)

다음과 같은 내용으로 파일을 과도하게 채우지 않도록 주의하십시오:

• 기술 스택에 대한 일반적인 설명
• 긴 설계 철학 (design philosophy)
• 오래된 사양 (outdated specifications)
• 거의 사용되지 않는 절차
• 특정 기능 하나만을 위한 상세 규칙
• README에서 중복되는 방대한 설명

AI가 매 세션마다 읽는 파일은 짧게 유지되어야 합니다.

Claude Code 문서에서도 긴 CLAUDE.md 파일은 컨텍스트 (context)를 소비하며 지시 이행 (instruction-following)의 신뢰도를 떨어뜨릴 수 있다고 설명합니다. Codex 또한 AGENTS.md 지침의 결합된 크기에 제한이 있습니다.

대략적인 가이드라인으로서, 루트(root) AGENTS.md는 100~200줄 정도로 유지하고, 상세한 절차는 별도의 파일로 이동시키십시오.

## 플레이북 (Playbooks)

관련이 있는 경우에만 읽으십시오:
...

하지만, Claude Code의 @path 임포트 (import)는 내용이 로드될 때 임포트된 콘텐츠를 컨텍스트로 확장합니다.

파일을 분할한다고 해서 토큰이 자동으로 줄어드는 것은 아닙니다.

분할의 목적은 유지보수성 (maintainability)을 향상시키고, 에이전트 (agent)가 관련이 있는 경우에만 세부 사항을 읽을 수 있는 경로를 만드는 것입니다.

Codex와 Claude Code의 차이점

Codex는 주로 AGENTS.md를 사용합니다.
~/.codex/AGENTS.md에 있는 전역 지침 (global instructions)을 저장소 로컬 (repository-local) AGENTS.md 파일과 결합할 수 있습니다.

Claude Code의 표준 파일 이름은 CLAUDE.md입니다.
이미 AGENTS.md를 사용 중이라면, CLAUDE.md에서 이를 임포트 (import)할 수 있습니다.

@AGENTS.md

## Claude Code 전용 규칙
...

이를 통해 AGENTS.md에 공유 규칙을 중앙 집중화하고, CLAUDE.md에는 Claude Code 전용 규칙만 유지할 수 있습니다.

한 가지 중요한 주의 사항이 있습니다: Codex에는 CLAUDE.local.md와 동일한 역할을 하는 표준 로컬 파일이 없습니다.
.codex-local.md라는 이름의 파일은 자동으로 읽히지 않습니다.

Codex의 지침 탐색 (instruction discovery)은 기본적으로 디렉토리당 최대 하나의 지침 파일을 로드합니다. 검색 순서는 AGENTS.override.md, 그다음 AGENTS.md, 그다음 project_doc_fallback_filenames에 등록된 이름 순입니다. 만약 동일한 디렉토리에 AGENTS.md가 존재한다면, .codex-local.md를 폴백 (fallback) 이름으로 추가하더라도 CLAUDE.local.md처럼 동작하지는 않습니다.

또한, 이름에서 알 수 있듯이 AGENTS.override.md는 오버라이드 (override) 파일입니다. 이를 저장소 루트 (repository root)에 배치하면, 팀이 공유하는 AGENTS.md를 보완하는 대신 동일한 수준의 AGENTS.md를 대체할 수 있습니다.

Codex를 위한 개인용 규칙을 원한다면 다음 순서를 고려하십시오:

• 저장소 간 공통으로 적용되는 개인 규칙은 ~/.codex/AGENTS.md에 작성합니다.
• 작업 프로필 (working profiles)을 분리하고 싶다면 CODEX_HOME을 사용합니다.
• 팀이 그 의미에 합의했을 때만 저장소 로컬 AGENTS.override.md를 사용합니다.
• 임시 개인 메모의 경우, 세션 시작 시 에이전트에게 수동으로 해당 파일을 읽도록 요청합니다.

팀 공유 규칙을 개인 메모와 분리하는 것이 더 안전합니다. Claude Code에서는 CLAUDE.local.md가 그 용도에 적합합니다.

# 개인용 AI 에이전트 메모
CLAUDE.local.md

Codex와 함께 사용자 정의 이름을 사용하는 경우, 이를 기존 AGENTS.md에 추가하는 보충 자료로 취급하지 말고, AGENTS.md가 없는 디렉토리에 대한 대체 후보(fallback candidate)로 취급하세요.

직접 읽는 대신 대량의 데이터 추출하기

AI가 전체 Scene, Prefab, ScriptableObject, 로그, CSV, JSON 또는 YAML 파일을 직접 읽게 하면 토큰이 빠르게 소모됩니다.

이러한 경우, 파일을 직접 읽는 대신 AI가 추출 스크립트 (extraction script)를 작성하도록 만드는 것이 종종 더 효율적입니다.

예를 들어, Prefab을 조사할 때 전체 YAML을 읽지 마세요. Editor 스크립트를 사용하여 필요한 정보만 출력하도록 하세요.

유용한 AGENTS.md 규칙은 다음과 같습니다:

## 대용량 파일 정책 (Large file policy)

대용량 YAML, JSON, CSV, 로그, scene, prefab 또는 ScriptableObject 파일을 직접 읽지 마십시오.
...

핵심은 처음부터 "모두 읽어라"라고 말하는 것을 피하는 것입니다.

AI가 먼저 데이터를 좁히도록 만드세요. 로그의 경우, 오류 유형과 주변의 몇 줄을 의미합니다. Prefab의 경우, GameObject 경로, 컴포넌트(component) 이름 및 누락된 참조(missing references)를 의미합니다.