로블록스 기획서의 “작게”와 코드의 102스터드
- 공유 링크 만들기
- X
- 이메일
- 기타 앱
지난 게임에서는 하네스를 마지막 날에 붙였다. 이번엔 하네스를 코드보다 먼저 놨다. 하루 만에 게임 두 개가 돌아갔고 테스트도 전부 통과했는데, 열어보니 맵이 어이없게 작았다.
내가 저주대전 저장소를 열어보니 순서가 그대로 남아 있었다. 코드는 2주에 걸쳐 쌓였는데 .claude/agents/ 의 첫 파일은 마지막 날에야 생겼다. tests/ 디렉터리는 아예 없다. 교차 참조 검사기도 규칙 문서 서버도 다 코드를 쓴 뒤에 따라왔다.
하네스를 붙이던 커밋 메시지에 스스로 진단이 적혀 있다.
chore: 하네스 구성 — 정적 검증은 L3 인데 실기 검증만 L0(산문)이었다
교차 참조 검사 24종은 커밋을 막을 만큼 갖춰져 있었는데, 그동안 "스튜디오에서 실제로 봤는가"는 인계 문서의 산문 표에 47행까지 쌓여 있었다. 스튜디오에서 확인했다고 적을 곳이 없어서 세션마다 그 47개를 다시 읽고도 무엇이 끝났는지 몰랐다. 코드를 다 쓴 다음에야 그 비대칭이 보였다.
같은 커밋의 마지막 줄은 이렇다. "하네스 자체는 실제 작업으로 돌려본 적이 없다. 정적 검증까지다."
그래서 이번엔 순서를 바꿔봤다. 로블록스 게임 두 개를 같은 날 시작하면서 기획서와 하네스를 코드보다 먼저 놨다. 하루 만에 둘 다 실행됐고 테스트도 전부 통과했다. 그래도 돌아가긴 하네, 싶었는데 열어보니 맵이 작았다. 그 많은 단언 중에 맵이 충분히 큰지 물어본 건 하나도 없었다.

오늘 나는 로블록스 게임 두 개를 동시에 시작했다. 「우리 학교가 이상하다」(1~4인 협동 관찰 공포, 전투 없음)와 「몬스터 군도 탐험대」(1~4인 협동 액션 RPG). 먼저 출시한 저주대전의 코드는 한 줄도 가져오지 않았다.
파일 만든 시간을 보면 순서가 그대로 남아 있다. 점심 먹고 기획서부터 만들고, 설계서, 에이전트랑 스킬까지 대략 30분 안에 다 깔고 나서야 첫 코드 파일이 생겼다. 군도도 대략 30분쯤 뒤에 똑같이 했다.
기획서는 미리 ChatGPT에 맡겨둔 것을 그대로 가져왔다. 지난번엔 코드가 최상류였고 문서가 코드를 뒤따라갔는데, 이번엔 코드 위에 문서 두 개가 먼저 서 있었다. 무엇을 만드는지를 정하는 기획서, 그리고 그것을 서비스 경계와 리모트 스키마로 번역한 계약 문서.
플랫폼 학습노트와 제작 워크플로우 문서는 저주대전 시절에 쌓아둔 것을 그대로 이월하고 2026 기준으로 갱신만 했다. 새 프로젝트를 두 개 여는 데 학습 비용이 거의 안 든 이유다. 첫 게임 때는 만들기 전에 플랫폼부터 공부시키느라 이 두 문서를 만드는 데만 하루를 썼다.
양쪽 다 하루 만에 코드와 문서와 테스트가 한 벌씩 갖춰졌고 둘 다 실행됐다. 저주대전을 2주 동안 쌓아 만든 것에 견주면 하루에 나온 양이 훨씬 많았다. 학교는 tools/build_rbxlx.py 로 .rbxlx 를 직접 뽑아 스튜디오에서 열었고, 군도는 Open Cloud REST로 올렸다.
하네스가 실제로 무슨 일을 했는지도 파일에 남아 있다. 오케스트레이터 스킬 맨 앞에서 일이 얼마나 큰지부터 나누게 해 뒀다. Config 숫자 하나 바꾸는 정도면 에이전트 부르지 말고 그냥 고치고 끝내라고. 그런 데 전체 검증을 돌리면 그게 오히려 잘못이라고까지 적어 놨다.
서비스 경계가 표로 먼저 못 박혀 있었던 게 컸다. 군도는 SaveService 가 DataStore I/O와 세션 락을 소유하되 게임 로직 판단은 하지 않고, CombatService 가 히트 판정과 데미지 공식을 소유하되 스킬이 무엇을 하는지는 모른다. 이 표가 코드보다 40분 먼저 있어서, 14개 서비스가 쏟아져 나오는 동안 "일단 여기 넣자"가 한 번도 안 나왔다.
여기까지가 의도한 대로 된 부분이다.
테스트
두 저장소의 CLAUDE.md 변경 이력에는 테스트 수가 적혀 있다. 군도는 "테스트 260개", 학교는 "테스트 97 단언". 숫자를 적은 것도 검사를 받는 것도 같은 에이전트라서 직접 돌려보고 싶었다.
러너는 lune 이 있어야 도는데 이 기기엔 lune 도 그 주변 도구도 하나도 없다. 그대로면 검증 전체를 건너뛰어야 했다. luau 인터프리터만 있길래 러너를 대충 직접 짜서 스펙 모듈을 물려봤다. 군도부터 돌렸다.
Formulas 36 단언
RateLimit 6 단언
Util 19 단언
Data 199 단언
passed 260 / failed 0
260개. 적어 둔 숫자랑 딱 맞았다. 199개는 루프로 도는 거라 우연히 맞을 리는 없고, 어디선가 한 번은 진짜로 돌렸던 것 같다.
학교는 달랐다.
RoundSchedule 11 단언
RateLimit 5 단언
Grade 8 단언
LOAD FAIL AnomalySpawn: ../Shared/Config.luau:137: attempt to index nil with 'fromRGB'
LOAD FAIL Config: ../Shared/Config.luau:137: attempt to index nil with 'fromRGB'
SchoolLayout 70 단언
합계: 통과 94 / 실패 0
6개 스위트 중 2개가 로드조차 안 된다. Config.luau 137번째 줄이 Color3.fromRGB(5, 5, 10) 이다. 조명 색을 밸런싱 수치와 같은 파일에 넣어뒀고, Color3 는 로블록스 런타임 밖에 없다.
규칙 두 개가 여기서 부딪혔다. 절대 규칙 4번은 "밸런싱 숫자는 Shared/Config.luau 에만 둔다"이고, 테스트 원칙은 "로블록스 API에 의존하는 코드는 유닛 테스트하지 않는다"이다. 조명 색은 밸런싱 수치이면서 로블록스 타입이다. 두 규칙을 다 지키면 Config.spec 은 존재할 수 없다. 그런데 Config.spec 은 존재하고, 15개 단언이 들어 있고, 한 번도 실행된 적이 없다. 실행됐다면 첫 줄에서 터졌을 테니까.
같은 저장소의 AnomalySpawn.spec 은 이 문제를 이미 알고 있다는 흔적까지 남겼다. 주석에 "AnomalyDefs 자체는 Roblox API 를 require 하므로 lune 에서 못 읽는다"고 적고 정의 테이블을 스펙 안에 손으로 복사해뒀다. 한 파일에서는 그렇게 피해 갔는데, 바로 옆 파일은 같은 벽에 부딪혔다.
그런데 오늘 실제로 부딪힌 문제는 이게 아니었다.
두 게임을 열어보니 나한테도 바로 보였다.
학교 쪽은 좌표가 SchoolLayout.luau 하나에 모여 있어서 계산이 금방 된다. 복도가 20 × 120 이고, 방들은 대략 한 변이 24~40 스터드 정도다.
방 7개, 전체가 102 × 176 스터드다. walkSpeed 가 14니까 복도 끝에서 끝까지 8.6초면 간다. 학교를 대각선으로 가로질러도 15초가 안 걸린다. 근데 한 판은 8~12분짜리로 설계돼 있다. 8.6초짜리 복도에서 8분을 보내는 게임이다.
이 맵에는 회귀 테스트가 붙어 있다. SchoolLayout.spec 이 70단언이고, 상단 주석에 왜 만들었는지가 적혀 있다.
실제로 났던 버그: 방 벽에 문만 뚫고 방↔복도 사이 통로 바닥을 만들지 않아, 모든 방 입구가 2~6스터드짜리 구멍이 되어 플레이어가 추락사했다.
좋은 테스트다. 실제로 난 사고를 좌표로 고정했고, 새 방을 추가할 때 같은 실수가 다시 나지 않는다. 통로가 벽에 닿는지, 폭이 문 너비와 같은지, 방끼리 겹치지 않는지를 전부 본다. 70개 중 맵이 충분히 큰지 묻는 건 하나도 없다.
기획서
기획서 §6 맵 구성이 맵 크기에 대해 말하는 건 첫 줄이 전부다.
맵은 길을 잃지 않을 정도로 작게 만든다.
그다음은 아스키 다이어그램 하나와 방별 설명이다. 일반 교실이면 "책상, 의자, 칠판, 시계". 책상이 몇 개인지, 교실이 몇 평인지, 경비실에서 음악실까지 몇 초 걸려야 하는지는 없다.
기획서 전체를 크기 관련 말로 검색해 봤는데 몇 줄 안 걸렸다. 거의 MVP 범위 목록이고, 크기를 말하는 건 저 "작게" 하나뿐이었다.
군도도 같다. 메인섬에 주요 지역 11개가 목록으로 있고 26개 절 어디에도 스터드 값이 없다. Vertical Slice 범위는 "메인섬 일부"다. 코드는 그 "일부"를 420 × 420 스터드 섬 하나로 정했다. 어디서 나온 숫자인지는 아무 데도 안 적혀 있다.
기획서가 대충 만들어졌다는 얘기는 아니다. 학교 기획서에는 「기술 검토로 확정된 제약」이 꽤 촘촘하게 붙어 있다. 콘텐츠 등급 Mild 고정, 조사 대상에 ProximityPrompt 를 안 쓰기, StreamingEnabled = false, 손전등은 플레이어당 1개, Max Players = 4, 사운드를 그래픽보다 먼저. 기술설계서에도 확정 결정이 6개 더 있다.
다 근거가 붙은 결정이고 나중에 바꾸기 어려운 것들이다. 근데 전부 범주형이다. Mild냐 Moderate냐, 켜느냐 끄느냐, 코드냐 에셋이냐. 얼마나 크냐를 정한 결정은 하나도 없다. Max Players = 4 와 손전등 1개 도 숫자처럼 보이지만 종류를 고른 것이다.
하네스도 같은 모양을 물려받았다. 학교 오케스트레이터 스킬의 「반복 발생하는 실패」 여섯 개도, 군도의 절대 규칙 10개도 전부 예/아니오로 답할 수 있는 항목이다. 예/아니오라서 검사로 옮길 수 있었고 실제로 옮겼다.
여기서 규칙을 만든 순서가 보였다. 예/아니오로 답할 수 있는 것부터 규칙이 됐다. 검사로 옮기기 쉬워서였지 그게 더 중요해서가 아니었다. 맵이 얼마나 커야 하는가는 예/아니오가 아니라서 규칙 목록에 한 번도 못 올랐고, 오늘 게임을 망친 건 그 문제였다.
기획서 전체에서 크기에 관한 정량 기준은 딱 하나였다. 군도 Vertical Slice 통과 기준 1번이다.
플레이어가 15분 안에 직업 스승을 발견할 수 있다.
시작 화면에서 직업을 고르지 않는 게 이 게임의 차별점이라, 스승을 못 찾으면 플레이어가 무기 없이 헤매다 나간다. 그래서 시간 상한을 걸어 둔 것이다.
좌표로 재 보면 스폰에서 폭포 뒤 동굴에 있는 스승까지 직선으로 220스터드쯤이다. 기획서 의도대로 소문 NPC 셋을 다 들러도 400스터드가 안 되고, 걸어서 25초 정도다.
기준은 15분이었다. 한참 여유 있게 통과한다. 근데 이건 검증이라기보다 맵이 작다는 증거에 가까웠다. "스승이 너무 멀지 않나" 물으려고 만든 기준인데 답이 25초면, 그 기준은 뭐 아무것도 못 거른다.
여기까지 오니 354개 단언이 무엇을 검사하고 있었는지가 다르게 보였다.
Config.spec 의 15개는 chaseSpeed < sprintSpeed, walkSpeed < chaseSpeed, serverRange > aimRange, 가중치 합이 1, 임계값이 오름차순 같은 것들이다. 전부 두 숫자 사이의 관계이거나 부호이거나 합이다. 절대값이 적절한지 묻는 단언은 하나도 없다. SchoolLayout.spec 의 70개도, 군도의 260개도 같은 모양이다.
관계는 문서 없이도 검사할 수 있다. 스프린트가 탈출 수단이라는 서술 한 줄이면 chaseSpeed < sprintSpeed 가 따라 나온다. 크기는 다르다. 102 × 176이 학교로 적절한지는 코드 안 어디를 봐도 알 수 없다. 그건 문서에 숫자가 있어야만 검사할 수 있는데, 문서에는 "작게"라고 적혀 있었다.
숫자끼리 맞는지는 하네스가 잘 본다. 숫자가 적당한지는 기획서에 기준이 있어야만 검사할 수 있다. 지금 나는 그 경계를 이렇게 보고 있다.
하나 더 신경 쓰이는 게 있다. 학교 기획서의 다이어그램에는 복도가 세 개 그려져 있고 노드가 아홉 개다. 실제 SchoolLayout.rooms 에는 방이 일곱 개고 복도는 Hallway 하나다. 그 축소를 기록한 문장은 어디에도 없다. 코드가 조용히 정했다.
그런데 테스트는 그 결과를 이미 계약으로 취급한다. 복도를 뺀 모든 방에 통로가 정확히 하나 있어야 하고, 복도 개구부 수가 통로 수와 같아야 한다. 기획서대로 복도를 셋으로 되돌리면 이 단언들이 먼저 깨진다.
기획서에 숫자가 없고, 코드가 임의로 채우고, 회귀 테스트가 그 값을 고정했다. 어느 단계에서도 규칙을 어기지 않았고 테스트를 단 건 오히려 잘한 일인데, 아무도 결정한 적 없는 숫자가 저장소에서 가장 단단한 것이 됐다.
저주대전에서는 맵이 작다는 걸 알아도 어디를 고쳐야 하는지 찾는 게 일이었다. 좌표가 코드 여기저기에 흩어져 있었으니까. 오늘 학교는 SchoolLayout.luau 하나를 열면 방 일곱 개의 좌표가 아홉 줄 안에 다 있고, 숫자를 바꾸고 테스트를 돌리면 어디가 깨지는지 바로 나온다.
결과물이 나아진 건 아니고, 어디를 봐야 하는지를 더 빨리 알게 됐다. 손볼 곳은 하네스보다 위, 기획서다. 기획서에 크기를 숫자로 적는 항목을 반드시 두게 해야 한다.
재밌는 건 시간 기준은 이미 적혀 있었다는 거다. 학교에 "한 판 8~12분", 군도에 "15분 안에". 시간에 대해서는 감이 서 있었고 공간에 대해서는 안 서 있었다. 8~12분과 8.6초짜리 복도가 같은 문서에 나란히 있다. 다음 기획서에는 최소한 이 세 줄이 필요하다. 플레이어가 A에서 B까지 몇 초, 한 구역에 상호작용 대상 몇 개, 한 판에 방문할 구역 몇 개.
「작게」 같은 형용사는 코드로 옮길 수가 없다. "길을 잃지 않을 정도로 작게"는 102가 될 수도 있고 1,020이 될 수도 있는데 둘 다 그 문장을 만족한다. 어느 걸 골라도 위반이 아니니 하네스는 통과시킨다.
다음엔 기획서에 크기를 숫자로 적고 그 숫자로 맵을 다시 지어볼 생각이다. 그때 SchoolLayout.spec 의 70단언 중 몇 개가 깨지는지가 궁금하다. 많이 깨지면 그 테스트들이 실은 맵의 모양이 아니라 오늘 우연히 정해진 크기를 지키고 있었다는 뜻이고, 하나도 안 깨지면 관계만 검사하고 있었다는 얘기다.
- 공유 링크 만들기
- X
- 이메일
- 기타 앱
댓글
댓글 쓰기