유니티 클로드 코드 공식 스킬 31장은 설명서의 어디를 읽고 움직이나

"유니티는 왜 이걸 직접 냈나요?"

유니티 공식 스킬을 다룬 다른 영상 댓글에서 가장 위에 올라 있던 질문입니다. 저는 이 질문에 설명서 구조로 답해 보려고 합니다. 유니티가 없던 제 PC에서 클로드 코드와 유니티 공식 설명서 31장으로 3D 서바이벌 게임을 만들었고, 그 과정에서 어느 설명서가 언제 불려 나왔는지 기록해 뒀거든요.

클로드 코드에 설명서를 처음 깔아 보려는 분, 같은 구조로 내 설명서를 만들어 보려는 분께 맞춘 글입니다. 결론은 이렇습니다. 설명서는 맨 윗줄 한 줄로 불려 나오고, 긴 본문과 참고 자료는 그 뒤에 필요할 때만 읽힙니다. 그래서 31장을 전부 켜 둬도 평소 부담은 종이 한 장 분량에도 못 미칩니다. 반면 게임 규칙과 그림, 난이도는 어느 설명서에도 없었어요.

유니티가 공식 설명서를 직접 낸 배경

유니티는 2026년 9월 9일 클로드 코드용 공식 묶음을, 9월 16일 코덱스(Codex)용 묶음을 발표했습니다. 유니티 블로그는 클로드 코드용에 설명서 29장이 들어 있다고 적었고, 코덱스용은 31장입니다. 제가 설치한 건 이와 별도로 깃허브에 공개된 설명서 저장소로, 9월 22일 기준 31장이었어요.

유니티 블로그의 설명은 "유니티 엔지니어가 쓰고 보안 검토를 거쳐 엔진 문서와 맞춘 설명서"입니다. 해외 매체 더 디코더는 같은 발표를 "에이전트가 낡은 튜토리얼을 베끼는 걸 막으려는 것"으로 읽었고요. 제 실연에서 확인한 건 결과 쪽입니다. 부탁한 문장은 짧았는데, 설명서가 붙은 카메라와 타일, 길찾기 작업은 한 번에 맞춰졌어요.

설명서 한 장은 규칙 파일 하나다

설명서 한 장의 정체는 규칙 파일(SKILL.md)과, 필요하면 딸린 폴더 몇 개입니다. 파일 맨 위 머리말에는 이름과 설명 줄(description) 두 가지가 들어가요. 뼈대만 옮기면 이런 모양입니다.

---
name: my-skill-name
description: Use when the user asks to ... (이 설명서가 불려 나올 상황)
---

# 본문: 시킬 일만 순서대로

설명 줄에는 이 설명서가 무엇을 하는지보다 언제 불려 나와야 하는지를 적습니다. 유니티 저장소의 기여 안내도 이 줄을 에이전트가 맞춰 보는 조건으로 규정하고, "이럴 때 써라" 꼴로 쓰길 권해요. 설명서를 만들 땐 이 한 줄부터 적으면 됩니다.

클로드 코드가 시작할 때 읽는 양

클로드 코드는 시작할 때 깔린 설명서를 다 읽지 않습니다. 이름과 설명 줄만 기억해 두고, 본문은 그 설명서가 불려 나올 때 읽어요. 참고 자료는 본문이 가리킬 때 펼칩니다.

읽는 때	무엇을	양(설명서 31장 기준)
시작할 때 늘	이름 + 설명 줄	한 장에 약 3050토큰, 31장이면 약 9301,550토큰
불려 나올 때	규칙 파일 본문	25줄에서 543줄까지
본문이 가리킬 때	참고 폴더(references)의 파일	필요한 파일만

1,550토큰은 영어 1,000단어쯤이니 인쇄하면 한 쪽이 안 됩니다. 표에서 볼 곳은 가운데 줄이에요. 543줄짜리 설명서도 불려 나오기 전까지는 한 줄 값만 치릅니다. 설명서를 많이 깔아도 부담이 크지 않은 이유가 여기 있어요.

불려 나오는 기준은 설명 줄 한 줄이다

확대해도 도트가 번지지 않게 해 달라는 한 문장만 넣었을 때, 클로드는 픽셀을 딱 맞춰 주는 설명서를 알아서 불러냈습니다. 설명서 이름을 부른 적은 없어요. 그 설명서의 설명 줄이 흐릿하거나 깨지는 레트로 도트 화면을 가리키고 있었기 때문입니다.

꺼낸 다음엔 본문대로 움직였습니다. 화면 그리는 방식을 먼저 확인하고, 설명서에 딸린 카메라 설정 파일을 그대로 적용해 카메라에 픽셀 고정 부품을 붙였어요. 기준 해상도 320×180, 16픽셀을 한 단위로 맞추는 값까지 한 번에 들어갔습니다. 부탁은 한 문장이었고, 나머지는 설명 줄과 본문이 채웠어요.

긴 참고 자료는 본문 밖으로 뺀다

유니티 설명서 본문에는 시킬 일만 적혀 있습니다. 긴 배경 설명과 예제 코드는 참고 폴더로 빠져 있어요. 기여 안내에도 규칙 파일은 지시에 집중하라고 적혀 있습니다.

설명서	하는 일	본문 길이
셰이더 그래프 사용자 노드 만들기	그림 계산 부품 하나를 코드로 추가	25줄
구형 화면 방식에서 새 방식으로 옮기기	프로젝트 전체의 그리는 방식을 교체	543줄

두 설명서는 20배 넘게 차이 나지만 짜임은 같았습니다. 같은 폴더에 긴 문서를 그냥 두면 설치기가 폴더째 가져가서 에이전트가 평소에도 읽을 거리가 늘어나요. 내 설명서도 긴 설명은 참고 폴더로 옮기세요.

큰 흐름을 맡은 설명서는 명령을 직접 짜지 않는다

새 프로젝트 만들기 설명서는 순서만 쥐고 있습니다. 실제 명령은 유니티 명령창 설명서와 패키지 관리 설명서에 넘겨요. 원문에는 "다시 만들지 말라"는 문장이 들어 있습니다.

제 실연에서도 그렇게 흘러갔습니다. 빈 프로젝트를 만들 때 클로드는 새 프로젝트 설명서에서 순서를 읽고, 명령창 설명서에서 틀 목록과 만들기 명령을 가져왔어요. 2D 틀로 빈 프로젝트가 1분 20초 만에 생겼습니다. 명령이 한 설명서에만 적혀 있으니 고칠 곳도 한 곳뿐이에요. 내 설명서가 여러 장이 되면 흐름 담당 한 장과 명령 담당 여러 장으로 나누세요.

사람이 정할 값은 기다리게 적어 둔다

바닥에 깔 사각형 타일 팔레트를 부탁했을 때 클로드는 바로 만들지 않았습니다. 이름을 뭘로 할지, 격자를 어떤 모양으로 할지 되물어 왔어요. 타일 팔레트 설명서 본문에 '사용자가 값을 줄 때까지 대기'라는 지시가 들어 있었습니다.

'바닥'이라는 이름을 알려 주고 나서야 움직였고, 만드는 일은 설명서 폴더에 미리 들어 있던 코드 파일이 맡았습니다. 에이전트가 매번 코드를 새로 쓰지 않으니 결과가 흔들리지 않아요. 그림 파일이 하나도 없어서 작은 타일을 코드로 찍어 냈고, 바닥에는 타일 4,800개가 깔렸어요. 사람이 정해야 하는 값이 있으면 설명서에 "기다려라"를 적어 두세요.

네 장이 빠진 날 드러난 설명서의 경계

31장을 다 깔면 화면 글자든 충돌이든 설명서가 알아서 챙겨 줄 것처럼 보입니다. 실제로는 31장 중 27장만 들어왔어요. 설치기가 네 장의 머리말 형식을 해석하지 못해 건너뛰었고, 그 이유가 화면에 찍혔습니다. 재실행해도 결과는 같았어요.

빠진 네 장 가운데 하나가 화면 글자 요청을 세 가지 방식 중 어디로 보낼지 정하는 입구 설명서였습니다. 그래서 "화면 글자 만들어 줘"가 방식 선택 흐름을 타지 못했고, 제가 새 화면 방식 설명서를 직접 지목해야 했어요. 그렇게 만든 화면은 글자와 버튼이 전부 하늘색 덩어리로 나왔습니다. 설명서는 화면 설정 파일이 꼭 있어야 한다는 데까지만 말하고, 테마 파일 연결은 짚지 않았거든요. 테마 파일 한 줄을 만들어 연결하자 제대로 돌아왔습니다.

빠진 네 장에는 3D 충돌 진단 설명서도 있었습니다. 나중에 화살이 적을 맞히지 못해 처치 수가 0에 머문 문제가 바로 충돌이 안 일어나는 증상이었어요. 클로드는 화살에 물리 부품이 없다는 원인을 찾아 고쳤습니다. 그 설명서가 깔려 있었다면 더 빨리 잡혔을지는 확인하지 못했습니다.

유니티는 네 장을 그날 바로 고쳤고, 9월 29일 기준 저장소에는 33장이 있어요. 지금 깔면 이 경계는 겪지 않습니다. 다만 설명서가 있어도 빈틈은 남을 수 있으니, 결과 화면을 한 번은 눈으로 확인하세요.

설명서가 다루지 않는 것

설명서 31장이 맡은 건 유니티를 다루는 방법입니다. 무엇을 만들지는 맡지 않아요.

• 게임 규칙: 제일 가까운 적을 자동 조준하는 마법 화살, 강화 카드 셋 중 하나 고르기, 금화 다섯 개로 포탑 세우기, 5분 버티면 승리. 전부 클로드가 설명서 없이 짰습니다.
• 그림: 설명서는 그림을 만들어 주지 않습니다. 3D 판은 누구나 공짜로 가져다 써도 되는 그림 재료 두 묶음을 받아 붙였어요.
• 난이도: 설명서에 기준이 없었습니다. 클로드가 직접 판을 돌리며 고쳤고, 첫 판 23초에서 여섯 번 손본 끝에 143초가 됐어요.
• 방향: 코드로 찍은 도트에서 3D로 바꾸자고 정한 건 저였습니다.

실시간 연결 서버 없이도 편집 프로그램을 움직인 방법

유니티 편집 화면을 실시간으로 조종하는 연결 서버에는 구독이 필요합니다. 2026년 5월 20일 유니티 직원이 공식 토론 게시판에 그렇게 답했어요. 이번 실연에선 이 서버를 빼고 진행했습니다.

대신 유니티 명령창으로 명령 수신용 부품을 프로젝트에 설치하고 편집 프로그램을 열었습니다. 90초쯤 뒤 '준비됨'이 뜨자, 클로드가 쓴 코드 파일을 편집 프로그램 안에서 바로 실행할 수 있었어요. 편집 프로그램이 받아 주는 명령은 100개가 넘었습니다. 경기장, 길찾기 그물, 조명, 화면 글자를 깐 것도 이 통로였어요. 설명서와 명령창만으로 3D 게임 한 판까지는 충분했습니다.

명령창은 결과를 글자로 돌려준다

유니티 명령창 설명서에는 판정 규칙이 하나 적혀 있습니다. 결과의 성공 여부 표시만 보고 판단하라는 거예요. 실패해도 출력에는 멀쩡해 보이는 결과가 통째로 찍히기 때문입니다. 끝날 때 돌려주는 번호도 정해져 있어서 3이면 로그인 문제, 4면 조건이 덜 갖춰진 상태예요.

이 규칙에도 한계는 있었습니다. 윈도우용 빌드는 106메가 결과물을 내고 성공 표시로 끝났어요. 그런데 그 실행 파일을 켜면 바로 닫혔고, 이유는 아직 찾지 못했습니다. 성공 표시가 알려 준 건 빌드가 끝났다는 데까지였어요. 결과물은 직접 한 번 실행해 보세요.

내 설명서에 옮겨 올 구조

유니티 설명서에서 본 구조를 내 설명서에 그대로 옮기면 이렇습니다.

my-skill-name/
  SKILL.md        머리말(이름, 이럴 때 써라) + 시킬 일
  references/     긴 설명, 예제
  scripts/        미리 짜 둔 실행 코드

빈 폴더에 규칙 파일 하나만 넣어도 목록에 뜹니다. 머리말에 이름과 불려 나올 상황만 적으면 돼요. 사용자에게 물어야 할 값이 있으면 본문에 기다리라고 적고, 여러 장이 되면 흐름 담당과 명령 담당을 나누세요.

이 글의 숫자가 틀릴 수 있는 곳

설명서 개수는 움직입니다. 촬영일인 9월 22일엔 31장, 29일엔 33장이었어요. 한 장에 30~50토큰이라는 값은 공개 자료에 기댄 대략치라 설명 줄 길이에 따라 달라집니다. 25줄과 543줄은 9월 22일 저장소를 직접 세어 본 값이에요. 최신 값은 유니티 공식 저장소에서 다시 확인하세요.

설명서는 한 줄로 불려 나오고, 만들 것은 따로 정한다

설명서가 27장뿐이던 날에도 클로드는 설명 줄 한 줄을 보고 필요한 설명서를 꺼냈습니다. 반대로 게임 규칙과 난이도는 클로드가 직접 짰고, 어떤 게임으로 갈지는 제가 정했어요.

내 작업 중 매번 같은 순서로 반복하는 일이 있나요? 그 일에 불려 나올 상황 한 줄을 붙이면 설명서 한 장이 됩니다. 전 과정은 이 글 위의 영상에 담았고, 설명서 요약표와 뼈대 폴더는 카카오 오픈채팅 '방구석모각코'에 올려 뒀습니다(https://open.kakao.com/o/picxsxwi).