[보관됨] Unity Claude Template — 클로드 코드와 유니티를 이용해서 나만의 게임을 만드세요!

한국어 · English

[!WARNING]
이 저장소는 2026년 8월 19일부로 보관되었으며 더 이상 유지보수하지 않습니다.
기존 프로젝트는 최종 상태 그대로 계속 사용할 수 있습니다. 새 프로젝트와 향후 업데이트는
설치형·에이전트 중립 후속 프로젝트인 **Unity Agent Kit**에서 진행합니다.
기존 사용자는 파일을 직접 지우기 전에 마이그레이션 안내를 확인해 주세요.

이 리포지터리는 "내 유니티 게임을 Claude 와 함께 만들기 시작하는 바탕 파일"입니다.
AI 에이전트가 씬도 꾸미고, 스크립트도 쓰고, 프리팹도 만들 수 있도록 필요한 장치가 미리 엮여 있어요.

그냥 빈 프로젝트만 보면 감이 잘 안 오니까, 솔리테어 한 판을 먼저 같이 만들어 봅니다 — 도구들이 어떻게 맞물려 돌아가는지 감을 잡는 연습이에요. 그 뒤에 솔리테어를 말끔히 걷어 내고, 여러분이 정말 하고 싶은 장르(퍼즐·플랫포머·RPG·리듬 게임 — 무엇이든) 로 갈아타시면 됩니다.

프로그래밍을 해본 적이 없어도 괜찮습니다. 대화만 주고받으시면 Claude 가 알아서 움직여요.

이 문서가 여러분을 데려가는 길

준비물 (10분쯤) — 유니티·Claude Code·이 템플릿 내려받기
자동 세팅 (1분쯤) — /setup 한 줄로 브릿지·MCP 다 연결
연습판: 솔리테어 만들어 보기 — 도구들 감 잡기
정리하기 — 솔리테어 걷어 내고 템플릿을 다시 깨끗하게
여러분 게임으로 갈아타기 — 장르별 가이드 + 바로 쓸 수 있는 말투
스킬 상세 — 도구 하나하나 자세히 (디버깅·QA 포함)
병렬 작업 — 에이전트 여러 명을 동시에 굴리는 법

1. 준비물

갖춰야 할 것	어디서 받나요
Unity Hub + Unity 2022.3 LTS	unity.com/download 에서 받아 설치 마법사대로 진행
Claude Code 데스크탑 앱	claude.com/claude-code — 맥·윈도우 모두 지원. 앱을 받아 설치 마법사대로 진행
이 템플릿	오른쪽 위 Use this template 로 내 계정에 복제하거나, 초록색 Code 단추 → Download ZIP 으로 받아 압축 풀기

압축은 ~/Documents/my-game 처럼 알아보기 쉬운 자리에 풀어 주세요. 폴더 이름에 한글·띄어쓰기가 없는 편이 유니티가 읽다가 삐끗하는 일을 줄여 줍니다.

파이썬·pipx·Filesystem MCP 는 더 이상 필요 없습니다. /setup 이 알아서 uv (파이썬 환경 매니저) 설치부터 브릿지 연결까지 챙겨 줘요. uv 가 없다면 /setup 이 OS 에 맞는 설치 명령 한 줄을 안내해 줍니다 (맥·리눅스·윈도우 모두 1줄씩).

2. 자동 세팅 — `/setup` 한 줄

1) Claude Code 데스크탑 앱을 실행합니다.

2) 상단 Code 탭 으로 들어가 새 세션을 시작합니다. 프롬프트 영역 위의 Project folder 를 눌러 여러분이 압축을 푼 템플릿 폴더 (예: ~/Documents/my-game) 를 선택합니다. 폴더를 창에 드래그 앤 드롭 해도 됩니다.

3) Claude Code 가 이 프로젝트의 .mcp.json 을 자동으로 읽어 브릿지 MCP 서버를 올립니다. 권한 승인 다이얼로그가 뜨면 Approve 를 눌러 주세요.

4) 프롬프트 상자에 슬래시(/) 를 쳐서 커맨드 자동완성을 띄우거나, 그냥 이렇게 부탁하세요:

/setup 해 줘.

이 뒤부터는 Claude 가 직접 Bash 로 실행해서 알아서 끝냅니다 — 사용자가 터미널에 명령을 복사·붙여넣기 할 필요 없어요:

OS 를 감지하고 (darwin / win32 / linux)
uv --version 으로 설치 여부 확인 (무해한 명령이라 권한 프롬프트 없음)
uv 가 없으면 Claude 가 curl ... | sh (맥/리눅스) 또는 PowerShell 1줄 (윈도우) 을 직접 실행. 네트워크 다운로드라 이때만 승인 다이얼로그 1회 — Approve 버튼만 눌러 주시면 됩니다
.mcp.json 이 프로젝트 루트에 있는지 확인 (템플릿엔 기본 포함)
unity_bridge_status 로 유니티 에디터 감지 여부와 프로젝트 경로가 잘 잡혔는지 확인
빠진 것만 한 줄씩 정리해서 보고

여러분이 직접 타이핑할 건 단 두 가지: (a) /setup, (b) uv 가 안 깔려 있었다면 설치 승인 Approve 버튼. 그 외 모든 명령은 Claude 가 자기 Bash 툴로 돌립니다. 복잡한 설치 순서·환경 변수·경로 확인 같은 건 신경 쓰지 않아도 됩니다.

5) 끝났으면 이런 보고가 나옵니다:

세팅 점검 결과
  ✓ uv 설치 확인
  ✓ .mcp.json 발견
  ✓ Unity Editor 감지: /Applications/Unity/Hub/Editor/2022.3.45f1/...
  ✓ Bridge MCP 응답: project_root = /Users/.../my-game

다음 단계
  · /run editor 로 Unity 띄우기
  · §3 "솔리테어 연습" 로 넘어가기

왜 이렇게 단순한가요? Claude Code 데스크탑 앱은 프로젝트 루트의 .mcp.json 을 자동으로 읽어 MCP 서버를 올려 줍니다. 이 템플릿은 uv run 으로 브릿지를 돌리게 설정해 뒀어요. uv 는 맥·윈도우·리눅스 공통으로 돌아가고 가상환경까지 자기가 관리하므로, pipx·pip·PATH 세팅 같은 복잡한 사전 작업이 사라졌습니다.

업데이트할 때: git pull 한 번이면 끝. 브릿지 코드가 바뀌었어도 다음번 uv run 호출 때 자동으로 반영됩니다.

Claude Code CLI 를 쓰신다면 데스크탑 앱과 동일하게 .mcp.json 이 자동으로 잡힙니다 (cd ~/Documents/my-game && claude). 설정 파일(.mcp.json, ~/.claude.json, settings.json, CLAUDE.md, skills) 은 앱과 CLI 가 모두 공유해요.

Claude Desktop (chat 앱) 은 별개 입니다. claude_desktop_config.json 은 이 템플릿과 상관없는 파일이라, 거기에 브릿지를 등록하려면 이 README 가 아니라 .claude/skills/setup/SKILL.md §5 "대체 경로" 의 pipx 지침을 따라 주세요 — 권장하지 않습니다.

3. 연습판: 솔리테어를 같이 만들어 보기

여기는 도구들이 어떻게 엮여 돌아가는지 손에 익히는 연습 단계입니다. 나중에 이 결과물을 정리하고 여러분 게임으로 넘어갈 거예요. 그러니 "솔리테어 만드는 법" 보다는 "Claude 한테 뭘 어떻게 시킬 수 있는지" 를 눈에 익혀 두신다는 느낌으로 봐 주세요.

아래 글을 Claude Code 프롬프트 상자에 그대로 붙여 넣어 주세요:

나 유니티 처음 써봐. 이 폴더가 unity-claude-template 이야. 연습 삼아 클론다이크 솔리테어를 만들어 보자.

단계를 잘게 쪼개서 하나씩 진행해 줘. 프로그래밍은 몰라서 코드는 네가 알아서 써. 나는 유니티 창에서 결과만 눈으로 확인할게.

Claude 가 대략 이런 식으로 움직입니다.

CLAUDE.md, RULES.md, .claude/INDEX.md 를 훑어서 약속 사항 챙기기
만들 순서를 서너 개쯤 제안하기
"첫 단계부터 시작할까요?" 하고 여쭤보기

"응" 만 답해 주시면 Claude 가 알아서 진행해요. 도중에 유니티 창을 띄워야 하면 Claude 가 /run editor 로 스스로 띄우고, 카드 프리팹이 필요하면 /make-asset 으로 즉석에서 만듭니다. 하트 같은 작은 기호는 SVG 도형을 직접 그려서 PNG 로 뽑아 유니티에 넣어 두기까지 해요.

끝나면 유니티의 ▶ 재생 단추를 누르세요. 카드가 분배되는 첫 화면이 뜨면 성공입니다.

막히면: 오류 메시지를 그대로 붙여 넣으시고 "고쳐줘" 라고 하시면 대체로 해결됩니다. 아예 말씀을 안 하셔도 Claude 가 콘솔을 읽고 스스로 고치기도 해요.

4. 솔리테어 걷어 내고 템플릿을 깨끗하게

연습이 끝났으면 솔리테어를 말끔히 정리하고 빈 바탕으로 돌아갑니다. 이것도 Claude 한테 시키시면 됩니다:

이제 솔리테어 연습 끝났어. 다음 네 가지를 해줘:

솔리테어 관련 파일 전부 지워 줘 — Assets/Scripts/_Core/Card*.cs, Deck*.cs, Solitaire*.cs / Assets/Prefabs/Card.prefab / Assets/Scenes/Solitaire.unity / 관련 Variant 프리팹들.

Assets/Art/Cards/ 는 남길지 지울지 한 번 물어봐. 다른 게임에서도 쓸 수 있을 것 같으면 남기고, 아니면 지워 줘.

네가 지우는 각 파일을 한 줄씩 내게 먼저 보여 주고 "지워도 돼?" 확인받아.

다 지운 뒤에 컴파일 오류나 끊긴 참조가 있는지 살펴보고, 있으면 고쳐 줘.

Claude 가 지워도 되는지 묻는 파일을 하나하나 확인받고 정리해 줄 거예요. 솔리테어에서 배운 패턴은 .claude/domain/ 이나 매뉴얼에 남길 만한 게 있는지도 함께 살펴봐 줍니다.

빈 바탕으로 완전히 돌아가고 싶으시면 이 한 줄이면 됩니다:

/task-start 와 /task-done 까지 다 쓰면서, 솔리테어 흔적을 남김없이 지워 원래 템플릿 상태로 돌려 줘. 내 허락 없이 Assets/Editor/, scripts/, .claude/ 아래는 건드리지 마 — 템플릿의 뼈대니까.

5. 여러분 게임으로 갈아타기

이제 진짜 여러분 게임을 시작할 시간이에요. 세 단계면 충분합니다.

5-1. 게임 이름·네임스페이스 바꾸기

템플릿 기본값은 Project.Core, Project.UI 같은 네임스페이스를 씁니다. 여러분 게임 이름으로 바꾸셔야 깔끔해요.

내 게임 이름은 "무지개 낚시" 야. 이 템플릿의 Project.* 네임스페이스를 RainbowFishing.* 으로 바꿔 줘. .asmdef 의 name 필드, 모든 .cs 의 namespace, CLAUDE.md 안의 설명 전부 포함해서. 그리고 ProjectSettings/ProjectSettings.asset 의 productName 도 "Rainbow Fishing" 으로 고쳐 줘.

5-2. 어셈블리 골조 장르에 맞게 고치기

템플릿 기본 뼈대는 _Core, _UI, _Combat, _Rendering 네 개예요. 여러분 장르에 쓸모없는 건 지우고, 더 필요한 영역이 있으면 더하시면 됩니다.

장르	추천 어셈블리 골조
퍼즐 / 카드 / 보드	`_Core`, `_UI`, `_Gameplay` (← `_Combat` 리네임), `_Rendering` 지움
플랫포머 / 액션	`_Core`, `_UI`, `_Player`, `_Level`, `_Combat`, `_Rendering`
RPG / 어드벤처	`_Core`, `_UI`, `_Battle`, `_Inventory`, `_Dialog`, `_Quest`, `_Rendering`
리듬 / 음악	`_Core`, `_UI`, `_Audio`, `_Chart`, `_Input`, `_Rendering` 지움
시뮬레이션 / 경영	`_Core`, `_UI`, `_Economy`, `_AI`, `_Time`
레이싱 / 스포츠	`_Core`, `_UI`, `_Vehicle`, `_Track`, `_Physics`, `_Rendering`

Claude 에게는 이렇게 부탁해 보세요:

나 퍼즐 게임 만들 거야. 현재 _Combat, _Rendering 어셈블리는 지우고, _Puzzle 어셈블리 하나 새로 만들어 줘. 네임스페이스는 RainbowFishing.Puzzle. .asmdef 에서 의존 관계도 맞게 설정하고 autoReferenced: false 유지해 줘.

5-3. 기획 들려 주고 /design 으로 쪼개기

이제 여러분 게임 기획을 자연어로 들려 주세요. Claude 가 분야별로 쪼개고 각 단계마다 "이 프롬프트 그대로 다음 작업에 붙여넣으면 돼요" 수준으로 작업서를 만들어 줍니다.

/design 으로 다음 기획을 쪼개 줘:

무지개 낚시 — 2D 탑다운 낚시 퍼즐. 플레이어는 물고기를 색깔별로 낚아서 일곱 빛깔 무지개를 완성한다. 시간 제한은 90초. 같은 색깔 세 마리 잡으면 보너스 시간 5초.

분야는 _Core (데이터·룰), _UI (타이머·무지개 게이지·점수), _Puzzle (낚시 판정·스폰). 각 분야의 1단계 작업은 다음 에이전트가 바로 실행할 수 있게 구체적으로 써 줘.

그러면 Claude 가 design/rainbow-fishing/ 폴더 안에 영역별 작업서 파일을 떨어뜨려 놓습니다. 이후 하나씩 "이 작업서대로 해 줘" 라고 맡기시면 돼요.

5-4. 장르별 첫 어셋 예시 프롬프트

퍼즐

/make-asset — 3×3 격자 타일 프리팹. 클릭하면 색이 바뀌는 간단한 동작. 색은 빨·파·노 세 가지, Inspector 에서 고를 수 있게.

플랫포머

/make-asset — 플레이어 임시 모델. 프리미티브 Capsule 로 몸통, Cube 로 모자. _Player 네임스페이스 아래 PlayerController.cs 붙을 수 있게 Assets/Prefabs/Player/Player.prefab.

RPG

/make-asset particle — 회복 마법 파티클. 연초록색 빛이 머리 위로 부드럽게 올라가는 느낌. 2초쯤 지속.

리듬 게임

/make-asset ui — 박자 판정 링. 바깥 테두리는 흰색, 안으로 줄어드는 링은 노란색. 256×256 프리팹으로.

낚시·시뮬레이션

/make-asset icon — 낚시찌 아이콘 128×128. 빨간 공에 아래쪽 하얀 막대. SVG 로 그려서 넣어 줘.

6. 뭔가 어긋났을 때

Claude 가 오류를 만나면 대체로 스스로 해결해요. "그 오류 고쳐줘" 한마디로 충분할 때가 많습니다. 원인이 애매하면 /debug, "이거 스펙대로 된 건가?" 가 궁금하면 /qa — 자세한 건 §7 에 적어 뒀어요.

유니티가 안 열리면: 터미널에서 ./scripts/run-editor.sh 를 직접 돌리시거나, Unity Hub 에서 이 프로젝트 폴더를 Add 하고 두 번 눌러 여세요.

브릿지가 대답 안 한다고 하면: 에디터에서 Window → Claude Bridge → Start 눌러 주셨는지 살펴봐 주세요. 그래도 안 되면 에디터를 닫고 Claude 에게 "/run bridge 로 돌려줘" 라고 하시면 유니티 창 없이도 처리가 됩니다.

정리하다가 중요한 걸 지운 것 같으면: 패닉하지 마세요. 템플릿은 깃(Git) 리포라 언제든 되돌릴 수 있어요. Claude 에게 "되돌려 줘, 방금 지운 것 중 뭐가 중요한지 짚어 줘" 라고 하시면 됩니다.

7. 쓸 수 있는 스킬들

Claude 에게 /스킬명형식으로 시킬 수 있는 작업 묶음이에요. 여러분이 굳이 부르지 않아도 클로드가 알아서 쓸 수 있는 스킬은 자동 표시를 붙였습니다. 각 스킬이 해주는 일과 예시 프롬프트를 함께 적어 뒀어요.

`/setup` — 프로젝트 자동 세팅 (맨 처음 1회)

이 템플릿을 처음 클론했을 때 한 번 돌리는 부트스트랩이에요. OS 감지 → uv 확인 → .mcp.json 확인 → Unity Editor 감지 → Bridge MCP 연결 테스트까지 Claude 가 순서대로 점검하고 빠진 것만 고쳐 줍니다. 맥·윈도우·리눅스 모두 지원.

할 수 있는 일

uv 미설치 시 OS별 1줄 설치 명령 안내 (맥: curl, 윈도우: PowerShell)
.mcp.json 확인·복구 (템플릿 기본 포함)
mcp__claude-bridge__unity_bridge_status 로 프로젝트 경로·유니티 에디터 감지 확인
완료 후 체크리스트 형태로 한 번에 보고 (✓ / ✗ 와 다음 단계)

예시 프롬프트

/setup 해 줘.

/setup — 다른 컴퓨터에서 처음 여는 거야. 세팅 처음부터 끝까지 봐 줘.

`/task-start` — 작업 시작 채비 (자동)

새 작업을 맡기기 전에 범위를 짜고 꼭 필요한 매뉴얼만 골라 읽는 루틴입니다. .claude/INDEX.md 로 키워드를 훑어 관련된 지식만 펼쳐 봐요. 덕분에 긴 매뉴얼을 매번 통째로 읽지 않아도 됩니다.

할 수 있는 일

작업 주제 키워드로 .claude/knowledge/*, .claude/rules/*, RULES.md 중 관련 파일만 추려 읽기
이번 작업에서 건드릴 파일을 미리 그레프로 찾아 보고 범위 선언
autoReferenced: false 같은 프로젝트의 절대 규칙 확인
어디까지가 이번 작업인지 한 줄로 요약해 보여 주기

예시 프롬프트

/task-start 점수판 HUD 만들어 줘. _UI 어셈블리만 건드리고 다른 어셈블리는 손대지 마.

/task-start 플레이어 점프 로직 고치는데, 이중 점프가 두 번 넘게 안 되게 할 거야. 관련 파일 찾아 주고 시작하자.

`/task-done` — 작업 마무리 (자동)

작업을 끝낼 때 결과를 정리하고 이 프로젝트만의 새 지식을 매뉴얼로 올리는 루틴이에요. 다음 에이전트가 같은 실수를 반복하지 않도록 돕습니다.

할 수 있는 일

이번에 건드린 파일·컴포넌트를 묶어서 바뀐 점 요약
임시로 끈 코드·주석·디버그 로그 같은 찌꺼기 청소
도메인 지식(기획·시스템·관계)을 .claude/domain/*.md 새 파일로 승격 제안
필요하면 바로 /self-update 로 이어 가기
빌드나 테스트가 잘 돌아가는지 짧게 검증

예시 프롬프트

여기까지 잘 됐어. /task-done 해줘.

/task-done 하면서 혹시 매뉴얼에 넣어 두면 좋을 배움이 있으면 같이 정리해줘.

`/self-update` — 배운 걸 매뉴얼로 올리기

이번 세션에서 알게 된 실수·함정·패턴을 어느 매뉴얼 계층에 올리는 게 맞을지 Claude 가 제안해 주는 루틴입니다. 올리기 전에 늘 여러분 승인을 받아요.

할 수 있는 일

다섯 단계 지식 계층(RULES / knowledge / domain / CLAUDE / local) 중 알맞은 자리 찾기
"어디에, 어떤 문장으로 넣을지" 구체 수정안 보여 주기
이미 있는 지식과 겹치지 않는지 대조
한 줄짜리 팁처럼 자잘한 건 덜어 내기 (매뉴얼이 두꺼워지지 않도록)

예시 프롬프트

오늘 RectTransform 의 anchor 가지고 계속 헤맸어. /self-update 해서 매뉴얼에 팁 넣자.

/self-update — 이번에 낚싯대 콜라이더에서 배운 거 어디 넣으면 좋을지 봐 줘.

`/design` — 기획을 작업 프롬프트로 쪼개기

자연어로 쓴 기획이나 노션 링크를 받아 분야별로 나누고, 각 분야마다 다음 에이전트가 그대로 쓸 수 있는 프롬프트로 만들어 주는 스킬입니다. 혼자가 아니라 여러 에이전트가 나눠 일할 때 특히 좋아요.

할 수 있는 일

기획을 _Core / _UI / _Puzzle / _Player 같은 영역별로 나누기
각 단계의 산출물·검증 방법·제약을 함께 적어 주기
design/{slug}/ 폴더에 단계별 마크다운 파일로 떨어뜨리기
단계 사이 의존 관계(먼저 해야 할 일, 나중에 해도 되는 일) 표시

예시 프롬프트

/design 무지개 낚시 — 90초 동안 물고기 낚아서 일곱 빛깔 모으기. _Core, _UI, _Puzzle 세 영역으로 쪼개 줘.

이 노션 링크 읽고 /design 으로 작업 계획 쪼개 줘: https://notion...

`/run` — 유니티 돌리기 (자동)

상황에 따라 세 갈래로 갈라집니다. 에이전트가 스스로 골라 쓸 수 있어요.

인자 1. (없음 또는 플랫폼 이름) — 빌드해서 실행

mac / win / linux / webgl / android / ios
결과는 프로젝트 옆 builds/{이름표}-{브랜치}-{짧은커밋}-{대상}-{시간}/ 에 차곡차곡 쌓여요
빌드가 끝나면 해당 바이너리를 바로 띄워 줍니다 (웹GL 은 서빙 명령을 안내)

인자 2. editor — 유니티 에디터 창 열기

빌드 없이 에디터만 켜 주는 모드
같은 프로젝트로 이미 유니티가 떠 있으면 그 창이 앞으로 올라옵니다

인자 3. bridge — 쌓여 있는 명령 한꺼번에 돌리기

유니티 창을 안 켜 둬도, .claude-bridge/inbox/ 에 쌓인 JSON 명령들을 헤드리스로 전부 처리해요
결과 요약 + 실패한 명령 목록을 돌려줍니다

예시 프롬프트

/run — 지금 내 맥으로 빌드해서 바로 띄워 줘.

/run editor — 유니티 좀 켜 줘, Hierarchy 직접 보고 싶어.

/run bridge — 아까 쌓아 둔 명령들 한 번에 처리해 줘.

/run webgl — 웹에서도 해볼 수 있게 빌드.

`/make-asset` — 어셋 만들기 (자동)

유니티 어셋을 즉석에서 만들어 주는 스킬이에요. 씬을 짜는데 프리팹이 없거나, 스크립트가 어떤 참조를 기대하는데 그 자리가 비어 있으면 Claude 가 먼저 이걸 꺼내 듭니다.

할 수 있는 일

UGUI 프리팹 — 단추·패널·글자판 같은 것을 RectTransform · Image · Text · Button 조합으로. 상태별 Variant 까지.
파티클 — 타격·폭발·반짝임·치유 오라 같은 느낌으로 ParticleSystem 프리팹
프리미티브 placeholder 모델 — 실제 3D 모델 오기 전에 Cube · Sphere · Cylinder 로 조합한 임시 모델
SVG 로 직접 그린 아이콘 — 하트·별·체크·X·화살표·카드 슈트처럼 간단한 도형은 Claude 가 SVG 를 써서 바로 그리고, PNG 로 뽑아 유니티에 Sprite 로 불러옵니다. 이미지 파일을 따로 주시지 않아도 돼요.
사용자 이미지 임포트 — 사진·복잡한 일러스트는 파일이나 링크를 주시면 Sprite 로 설정까지 마무리

요구 사항이 뚜렷하지 않으면 크기·색·쓰이는 자리 같은 걸 먼저 여쭤봅니다. 답이 없으면 "임시로 색 블록 만들어 두고 나중에 바꿀 수 있게 해 둘게요" 식으로 안전하게 진행해요.

예시 프롬프트

/make-asset — 퍼즐 타일 프리팹. 3×3 격자에 놓을 거니까 Inspector 에서 색 바꿀 수 있게.

/make-asset particle — 플레이어 점프할 때 밑에서 먼지 툭 튀는 느낌. 짧고 가볍게.

/make-asset icon — 체력 하트 아이콘 128×128. 빨간색, 테두리 살짝 어둡게. SVG 로 그려서 넣어 줘.

/make-asset prefab — 대화창 팝업. 가운데 글자판, 아래에 "다음" 단추. 스킨은 나중에 바꿀 거니까 기본 스타일로.

/make-asset model — 플레이어 임시 모델. 프리미티브 Capsule 몸통에 Sphere 머리, 파란색.

`/debug` — 에이전트가 직접 디버깅

버그·예외·오작동을 만났을 때 여러분에게 "Play 해 보세요 / 브레이크포인트 걸어 주세요" 를 시키지 않는 스킬입니다. 에이전트가 LSP 로 소스 호출 그래프를 타고 → 필요하면 Bridge 로 유니티를 직접 돌려서 런타임 값을 찍어 원인을 짚어요.

할 수 있는 일

NullRef·미할당 참조: LSP findReferences / goToDefinition 으로 대입 지점 전수 훑기
이벤트 중복 호출·구독 누수: += / -= 쌍 매칭 후 Bridge 로 실제 델리게이트 체인 조회
물리 버그(점프 2회·미끄러짐): 관련 호출 위치 확인 + Bridge 로 isGrounded 같은 상태 폴링
도메인 리로드 상태 오염: Play 모드 2회 재진입 후 static 필드값 비교
Adragna 10가지 디버깅 원칙(가정 의심 → 버그 분류 → 증상 vs 원인 구분) 순서로 접근

예시 프롬프트

/debug 점프가 가끔 두 번 먹혀. 재현해서 원인 짚어 줘. 나한테 Play 눌러 보라 하지 말고 네가 Bridge 로 직접 확인해.

/debug — 콘솔에 NullReferenceException at ScoreSystem.Update 떴어. 어디서 null 인지 추적해서 고쳐 줘.

/debug — Play 두 번 눌렀을 때 점수가 이전 세션 값으로 시작돼. 도메인 리로드 쪽 같은데 확인하고 고쳐 줘.

`/qa` — 기획·규칙 대비 구현 검증

"이상하면 말씀해 주세요" 안 시키고, 합격 기준을 먼저 박은 뒤 기준별 Pass/Fail + 증거로 리포트하는 스킬입니다. RULES.md·기획서·코딩 규약 대비 검증.

할 수 있는 일

RULES.md 여섯 개 불변 제약 스캔(static 초기화, async CancellationToken, 물리는 FixedUpdate, .meta 편집 여부 등)
이벤트 구독/해제 쌍, GetComponent 캐싱, 네임스페이스 규약 위반 전수
기획서 조항별 구현 지점(파일:라인) 찾아 실제 값까지 Bridge 로 확인
Fail 은 항상 파일:라인 + 제안 수정 문장까지 붙여 보고

예시 프롬프트

릴리즈 전이야. /qa — RULES.md 여섯 개랑 기획서 핵심 조항 훑어서 Pass/Fail 리포트 줘.

/qa — 방금 머지한 변경 범위에서 async 메서드가 CancellationToken 다 받고 있는지 확인해 줘.

/qa 점수 계산 로직 — 콤보 3 이상 보너스 5초 조항, 실제로 값 잘 들어가는지 Bridge 로 재현해 보여 줘.

디버깅·QA 는 다 Claude 한테 맡기세요. 증상 말씀만 해 주시면 돼요. 오류 메시지를 붙여 넣으시거나 "점수가 이상해" 한마디 해주시면, Claude 가 /debug 로 원인을 짚고 /qa 로 스펙 대비 검증까지 합니다. 여러분이 Play 버튼 눌러서 눈으로 확인해 주셔야 하는 일은 없어요.

8. 병렬로 여러 에이전트 동시에 굴리기

작업 하나 진행할 땐 필요 없습니다. 다만 _UI 하나, _Combat 하나, 기획서 쪼개기 하나 — 이렇게 겹치지 않는 영역을 동시에 진행하고 싶을 때, 워크트리를 쓰면 Claude 창을 여러 개 띄워 각자 다른 영역을 맡길 수 있어요.

왜 쓰나요

같은 프로젝트를 그냥 여러 창으로 열면 유니티 라이브러리 락이 걸려 충돌
워크트리로 스크립트만 격리하고 Art·Audio·Library 는 심링크로 공유 → 디스크·빌드 캐시 낭비 없음
각 에이전트가 자기 브랜치에서 일하므로 나중에 합칠 때 깔끔

준비 (한 번만)

./scripts/create-symlinked-worktrees.sh 3

../worktrees/agent-0, agent-1, agent-2 세 개가 생기고 각각 agent/worker-0, agent/worker-1, agent/worker-2 브랜치에 붙습니다. 숫자만 바꾸면 원하는 만큼 만들 수 있어요.

정리할 땐:

./scripts/cleanup-worktrees.sh

돌리는 법

각 워크트리 폴더에서 Claude Code 창을 따로 띄워 작업을 맡깁니다. 창 하나 = 에이전트 하나.

cd ../worktrees/agent-0
claude   # 이 창은 _UI 담당

예시 프롬프트

먼저 메인 창에서 /design 으로 기획을 조각낸 뒤, 각 조각을 다른 워크트리 창에 맡기는 패턴을 추천합니다.

메인 창 — 기획 쪼개기

/design 무지개 낚시 — 2D 탑다운 낚시 퍼즐. _Core, _UI, _Puzzle 세 영역으로 쪼개고, 각 영역의 1단계 작업서를 design/rainbow-fishing/ 에 마크다운으로 떨어뜨려 줘. 단계 사이 의존 관계도 표시해 줘.

agent-0 창 — _UI 담당

여기는 워크트리 agent-0, _UI 담당이야. design/rainbow-fishing/ui-step1.md 읽고 /task-start 부터 /task-done 까지 끝까지 진행해 줘. 다른 어셈블리는 건드리지 마.

agent-1 창 — _Core 담당

여기는 워크트리 agent-1, _Core 담당이야. design/rainbow-fishing/core-step1.md 읽고 /task-start 부터 /task-done 까지 끝까지 진행해 줘. _UI·_Puzzle 은 절대 수정하지 마.

agent-2 창 — _Puzzle 담당

여기는 워크트리 agent-2, _Puzzle 담당이야. design/rainbow-fishing/puzzle-step1.md 읽고 /task-start 부터 /task-done 까지 끝까지 진행해 줘. 완성되면 /qa 로 기획서 조항 대비 Pass/Fail 리포트까지 뽑아 줘.

주의 사항

심링크 폴더(Assets/Art, Assets/Audio, Assets/Prefabs 등)는 읽기 전용입니다. 병렬 창에서 여기 파일을 새로 만들거나 수정하면 모든 워크트리에 전파되어 충돌이 나요. (RULES.md RULE-02)
각 에이전트에게 서로 다른 어셈블리를 맡기세요. 같은 파일을 두 창에서 동시에 수정 = merge 지옥.
병렬 시작 전 반드시 /design 으로 작업 경계를 먼저 그려 두세요. 경계 없는 병렬은 감당 안 됩니다.
멀티 에디터도 됩니다. 각 워크트리마다 전용 ArtifactDB·SourceAssetDB·ScriptAssemblies(컴파일된 DLL)·Bee(빌드 작업 폴더)·락 파일을 복사해 두고 Temp/UnityLockfile 도 워크트리별로 따로 생기게 해놔서, 에이전트마다 유니티 에디터를 따로 띄워 놓고 동시에 컴파일해도 서로 DLL 을 덮어쓰지 않아요. 각자 맡은 어셈블리가 겹치지 않아야 한다는 원칙은 그대로입니다.
작업이 끝나면 각 워크트리에서 메인 브랜치로 PR·머지 → 마지막에 ./scripts/cleanup-worktrees.sh 로 정리.

9. 템플릿 안쪽 구경하기 (원하실 때만)

연습판만 돌릴 거면 지금 안 읽으셔도 돼요. 본격적으로 만들기 시작하실 때 한 번 훑어보시면 됩니다.

Claude 가 따르는 약속들

파일	하는 일
`CLAUDE.md`	세션 시작할 때 자동으로 읽히는 "팀 공유 매뉴얼". 여러분 게임 개요도 여기에 적어 두면 좋아요
`RULES.md`	어기면 유니티가 실제로 어긋나는 절대 규칙 여섯 가지
`.claude/INDEX.md`	어떤 지식이 어디 있는지 알려 주는 차림표 (에이전트가 제일 먼저 봐요)
`.claude/knowledge/`	유니티 성능, C# 언어, 에디터 자동화 같은 널리 쓰이는 지식
`.claude/rules/`	경로·파일 종류별 규칙 (예: `.asmdef` 는 이렇게 다뤄)
`.claude/domain/`	여러분 게임만의 기획·시스템 지식이 차곡차곡 쌓이는 자리

스킬들이 담긴 자리

.claude/skills/ 아래에 §7 의 스킬 파일들이 있어요. 직접 열어 보시면 각 스킬이 더 자세히 기술되어 있습니다.

유니티 에디터 자동화 도구

경로	하는 일
`.mcp.json`	프로젝트 루트의 MCP 서버 등록 파일. Claude Code 가 자동으로 읽어 `uv run` 으로 브릿지를 올립니다 — 맥·윈도우·리눅스 공통
`Assets/Editor/ClaudeBridge/`	파일로 주고받는 다리 + 리플렉션으로 돌아가는 op 스물두 가지 (씬 / 게임오브젝트 / 컴포넌트 / 프리팹 / 어셋 / 리플렉션). 유니티 창이 열려 있을 때도, 닫혀 있을 때도 모두 대응
`scripts/claude-bridge-mcp/`	파이썬으로 쓴 얇은 MCP 서버. Claude Code 가 `unity_call(op, args)` 한 번으로 유니티를 다룰 수 있게 해줘요
`scripts/run.sh` / `run-editor.sh` / `bridge-run.sh`	`/run` 스킬이 상황 따라 부르는 세 가지 실제 셸 파일
`Assets/Editor/ParallelAgentSetup.cs`	Domain Reload 를 꺼서 Play 모드 진입이 거의 순식간
`scripts/create-symlinked-worktrees.sh`	깃 워크트리 + 심링크로 여러 에이전트를 동시에 돌릴 수 있게 도와주는 셸 파일

어셈블리 뼈대

기본은 _Core, _UI, _Combat, _Rendering 그리고 테스트 두 개입니다. §5-2 의 장르별 추천표를 참고해서 필요 없는 건 지우고 필요한 건 더하세요.

10. 이 템플릿의 바탕이 된 글

더 깊은 설계 이야기가 궁금하시면:

참조 링크

템플릿 코드: MIT
카드 그림(연습판에만 쓰임): 케니(Kenney) 플레잉 카드 묶음 (CC0) — 자세한 약속은 Assets/Art/Cards/License.txt. 연습이 끝나면 지우셔도 됩니다.

[보관됨] Unity Claude Template — 클로드 코드와 유니티를 이용해서 나만의 게임을 만드세요!

이 문서가 여러분을 데려가는 길

1. 준비물

2. 자동 세팅 — /setup 한 줄

3. 연습판: 솔리테어를 같이 만들어 보기

4. 솔리테어 걷어 내고 템플릿을 깨끗하게

5. 여러분 게임으로 갈아타기

5-1. 게임 이름·네임스페이스 바꾸기

5-2. 어셈블리 골조 장르에 맞게 고치기

5-3. 기획 들려 주고 /design 으로 쪼개기

5-4. 장르별 첫 어셋 예시 프롬프트

6. 뭔가 어긋났을 때

7. 쓸 수 있는 스킬들

/setup — 프로젝트 자동 세팅 (맨 처음 1회)

/task-start — 작업 시작 채비 (자동)

/task-done — 작업 마무리 (자동)

/self-update — 배운 걸 매뉴얼로 올리기

/design — 기획을 작업 프롬프트로 쪼개기

/run — 유니티 돌리기 (자동)

/make-asset — 어셋 만들기 (자동)

/debug — 에이전트가 직접 디버깅

/qa — 기획·규칙 대비 구현 검증

8. 병렬로 여러 에이전트 동시에 굴리기

왜 쓰나요

준비 (한 번만)

돌리는 법

예시 프롬프트

주의 사항

9. 템플릿 안쪽 구경하기 (원하실 때만)

Claude 가 따르는 약속들

스킬들이 담긴 자리

유니티 에디터 자동화 도구

어셈블리 뼈대

10. 이 템플릿의 바탕이 된 글

참조 링크

Reviews (0)

2. 자동 세팅 — `/setup` 한 줄

`/setup` — 프로젝트 자동 세팅 (맨 처음 1회)

`/task-start` — 작업 시작 채비 (자동)

`/task-done` — 작업 마무리 (자동)

`/self-update` — 배운 걸 매뉴얼로 올리기

`/design` — 기획을 작업 프롬프트로 쪼개기

`/run` — 유니티 돌리기 (자동)

`/make-asset` — 어셋 만들기 (자동)

`/debug` — 에이전트가 직접 디버깅

`/qa` — 기획·규칙 대비 구현 검증