본문으로 건너뛰기

오픈월드 게임을 만들어보자 Three.js Webgame Debug 스킬 분해

오픈월드 게임을 만들어보자 Three.js Webgame Debug 스킬 분해 본문 이미지

문제 또는 학습 목표

기존 threejs-webgame-debug Skill 하나에 blank-screen 진단, 엔티티 지형 정렬, aggro 관리 등 여러 책임이 섞여 있었다. 특정 문제 해결 시마다 불필요한 단계를 거쳐야 했고, failure owner가 모호해 수리 범위가 커졌다.

이번 과제에서는 하나의 큰 Skill을 책임 경계 기준으로 분해하여 독립적인 두 Skill로 재구성하는 과정을 실측했다.

시작 전 큰 Skill과 흔들림

항목

내용

원본 Skill

threejs-webgame-debug — Three.js + Vite 블랙스크린 진단 및 엔티티 정렬

흔들린 장면

1회차: blank screen → triage만 하면 되는데 terrain-align 단계까지 강제로 거침

흔들린 장면

2회차: entity floating → terrain-align만 필요한데, blank-screen triage의 identifier collision 체크가 불필요하게 개입

흔들린 장면

3회차: monster aggro → terrain-align에 aggro 파라미터가 섞여 있어, aggro만 바꾸고 싶어도 전체 단계를 다시 실행해야 함

반복할수록 "같은 체크리스트로 고칠 수 있는 실패인가, 다른 사람/책임이 개입해야 하는가"가 모호해지는 흔들림이 발생했다.

보호 원본·learner working-copy 경계

역할

상태

Protected distributed original (parent skill)

수정 금지

Immutable source copy

백업, 해시 검증 완료

Learner-owned candidate A

생성 완료

Learner-owned candidate B

생성 완료

자동 backup receipt·SHA-256 readback·restore rehearsal

항목

내용

Backup 시점

원본 readback 후 첫 mutation 직전

원본 SHA-256

해시 검증 완료

백업 파일 수

3 (SKILL.md, 참조 파일, 템플릿)

Source↔backup readback

파일별 존재 확인, 내용 동일

Restore rehearsal

백업 디렉토리에서 원본과 파일 구조 일치 확인

자동 삭제

금지 — learner explicit prune 전까지 보존

왜 분리했는가

vite-blank-screen-triage 분리 이유

원본 Skill에서 blank-screen 진단은 다음 failure owner를 가졌다:

  • Module parse: same-scope identifier collision

  • Import path: legacy query string

  • HMR cache: stale module graph

  • GPU/driver: WebGL context null

이 failure owner들은 엔티티 높이 문제와 전혀 무관하다. verifier도 "minimal scaffold 렌더링"으로 다르고, repair도 "rename identifier / strip query string / clear cache"로 독립적이다. 따라서 triage는 standalone Skill로 분리하는 것이 자연스럽다.

threejs-terrain-entity-align 분리 이유

원본 Skill에서 entity-align은 다음 failure owner를 가졌다:

  • Terrain offset 이중 카운트: height formula 오류

  • FBM multiplier 과다: 절벽 생성 → 엔티티 vanish

  • NaN clamp 누락: bilinear lookup 시 경계 index 미보정

  • Camera target Y drift: 시야 tilt

  • Aggro default: 모든 몬스터가 즉시 추적

이 failure owner들은 blank-screen 진단과 무관하다. verifier도 "player grounded / slimes height / wolves near ground / camera stable / monsters idle"로 독립적이다. repair도 "explicit Y assignment / offset formula / clamp indices / FBM adjustment / aggro default false"로 독립적이다. 따라서 entity-align도 standalone Skill로 분리하는 것이 자연스럽다.

선택한 Y 경계와 observed evidence

경계

선택

Observed Evidence

vite-blank-screen-triage

Y (분리)

failure owner: module parse/import/cache/GPU — entity-align의 terrain/FBM/camera와 전혀 다름. verifier: minimal scaffold vs grounded entities. repair: rename/strip/restart vs formula/formula/adjust.

threejs-terrain-entity-align

Y (분리)

failure owner: terrain offset/NaN/FBM/camera/aggro — triage의 ESM/query-string/HMR와 전혀 다름. verifier: 5개 entity checklist vs 4개 triage checklist. repair: height formula vs diagnostic steps.

N으로 판단해 유지한 후보

원본 Skill의 "Monsters blending into flat terrain"과 "Layered renderOrder can cause depth fighting"은 같은 failure owner(시각적 레이어링)를 가져서, threejs-terrain-entity-align 내부의 보강 항목으로 유지했다. 분리 신호가 약했기 때문에 억지로 분리하지 않았다.

다음 탐색 후보:

  • Parent skill의 "CSS2DRenderer DOM overlay" — 독립적 failure owner 가능 (DOM 조작)

  • "Post-patch duplicate closers" — triage의 Step 8과 overlap, 추가 분리 신호 없음

작은 Skill 후보와 readback 상태

후보 A: vite-blank-screen-triage

항목

내용

역할

블랙스크린 원인 진단 및 최소 수리

Input

프로젝트 루트 경로, 브라우저 URL, Console/Network 상태

Output

Root cause category + Fixed code or next action

Verifier

Minimal scaffold 렌더링, Network 200, Console 0, HMR clean

Failure Return

WebGL null→Human, 404→path fix, Empty Error→collision, HMR→restart

Readback

verified — SKILL.md 존재, frontmatter 정상

후보 B: threejs-terrain-entity-align

항목

내용

역할

엔티티-지형 높이 정렬 및 시각적 레이어링

Input

Terrain config, entity base Y per type, min follow distance

Output

Grounded entities, no float/sink/vanish, stable camera

Verifier

Player grounded, slimes height, wolves near ground, camera stable, monsters idle until hit

Failure Return

sink→formula, vanish→clamp/FBM, tilt→targetY, chase→aggro

Readback

verified — SKILL.md 존재, frontmatter 정상

Tree와 Circuit

threejs-webgame-debug (parent, protected)
├── vite-blank-screen-triage (standalone)
└── threejs-terrain-entity-align (standalone)
Input (blank screen / entity float)
  │
  ├─► vite-blank-screen-triage
  │     ├─ scaffold 검증
  │     ├─ 8단계 트라이어지
  │     └─ Output: root cause + fix
  │
  └─► threejs-terrain-entity-align
        ├─ explicit Y assignment
        ├─ offset formula
        ├─ FBM 조정
        └─ Output: grounded entities
  • Orphan: 없음

  • 순환 호출: 없음

  • 입력 없는 노드: 없음

  • 실패 반환 없는 연결: 없음

분해 Build Gate 상태

필드

값

split_search_status

y_found

learner_y_decision

accepted

selected_y_boundary

vite-blank-screen-triage / threejs-terrain-entity-align

evidence_for_y

failure owner/verifier/repair가 모두 다름

small_skill_artifacts

2

artifact_form

files

candidate_readback

verified

runtime_discovery

verified

status

candidate_written → PASS

Proof/Gate 스케치와 관찰

vite-blank-screen-triage Proof

Verifier

결과

관찰

Minimal scaffold 렌더링

PASS

실제 게임이 정상 렌더링 중 (건물, 지형, 캐릭터)

Network 모든 .js 200

PASS

Vite HMR connected, 404 없음

Console uncaught error 0

PASS

연결 로그만 존재, 에러 없음

HMR reload clean

PASS

정상 연결, blank error 없음

threejs-terrain-entity-align Proof

Verifier

결과

관찰

Player stands on terrain surface

PASS

발이 지면에 닿음, 그림자 확인

Slimes animate at correct height

PASS

지형 위에 표시, 땅 아래 없음

Wolves near ground level

PASS

지면 근처 위치

Camera follows without vertical tilt

PASS

부드러운 추적

Monsters idle until hit

PASS

정지 상태, 추적 없음

Gate 판정 로그

[Code Gate] vite-blank-screen-triage: PASS (verifier 4/4)
[Code Gate] threejs-terrain-entity-align: PASS (verifier 5/5)
[Human Gate] vite-blank-screen-triage: PASS (사용자 accept)
[Human Gate] threejs-terrain-entity-align: PASS (사용자 accept)

실패·막힘·수정

#

실패

소유자

수정

재판정

1

YAML lint 실패 — Interface Card에 백틱 코드블록 포함

Agent

코드블록 제거 후 순수 YAML로 재작성

PASS

2

Vite 서버 꺼짐 — 검증 시점에 dev server 미구동

Agent

dev server 재시작

PASS

최소 수리 원칙 준수: 실패 시 전체 Skill을 다시 만들지 않고, 실패한 Skill의 learner-owned 후보만 자동 백업 후 수정.

결과

  1. vite-blank-screen-triage — 독립적인 8단계 블랙스크린 진단 Skill로 분해 완료. blank screen 발생 시 빠르게 root cause를 특정하고 최소 수리할 수 있음.

  2. threejs-terrain-entity-align — 독립적인 엔티티-지형 정렬 Skill로 분해 완료. terrain 추가 후 floating/sinking/vanishing 문제를 빠르게 수리할 수 있음.

  3. 두 Skill은 독립적 failure owner, verifier, repair, change cycle을 가짐. 각각 독립적으로 호출·검증·수리 가능.

  4. 원본 Skill은 보호 상태로 유지, learner-owned 후보만 수정.

2

함께 이야기해요 2

로그인하고 댓글을 남겨 주세요

Giacomo 프로필 이미지
Giacomo2026.08.04

자연어회계처리님, blank screen을 고치려는데 terrain-align 단계까지 거치고, entity floating을 고치려는데 identifier collision 검사가 개입하며, aggro 하나를 바꾸기 위해 전체 절차를 다시 실행해야 했다는 세 장면이 왜 기존 Skill이 흔들렸는지를 잘 보여줬습니다. 단순히 기능 이름이 다르다는 이유가 아니라 failure owner·verifier·repair·change cycle이 다른지를 기준으로 경계를 잡은 덕분에, vite-blank-screen-triage와 threejs-terrain-entity-align이 왜 독립 Skill이어야 하는지 납득하기 쉬웠어요. 입력과 출력뿐 아니라 실패했을 때 어디로 돌려보내야 하는지까지 각각 적어둔 점도 실제 운영 단위로 분해했다는 느낌을 줬습니다.

분해 전 보호 절차와 분해 후 검증이 함께 있는 점도 좋았습니다. 원본 Skill을 수정 금지로 두고 immutable copy와 파일별 readback, SHA-256 확인, restore rehearsal을 먼저 거친 뒤 learner-owned 후보만 수정하셨죠. 이후 YAML lint 실패는 Interface Card의 코드펜스만 제거하고, Vite 서버가 꺼진 문제는 서버만 다시 띄우는 최소 수리로 대응해 두 후보를 각각 4/4와 5/5 verifier로 다시 통과시켰습니다. 실패가 생길 때마다 전체 Skill을 새로 만드는 대신 실패 소유자가 있는 후보만 고치고 같은 Gate로 재판정한 흐름이 깔끔했어요.

무엇보다 분리한 것만큼 분리하지 않은 것의 근거가 또렷했습니다. `Monsters blending into flat terrain`과 `Layered renderOrder`는 같은 시각적 레이어링 책임을 공유하므로 terrain-entity-align 안에 남기고, CSS2DRenderer는 독립 가능성이 있지만 아직 후보로만 둔 판단 덕분에 Skill 쪼개기가 파일 수 늘리기로 흐르지 않았어요. Tree와 Circuit에서도 orphan·순환 호출·입력 없는 노드·실패 반환 없는 연결을 모두 확인했기 때문에, 이번 작업은 두 개의 문서를 만든 것이 아니라 각각 독립 호출·검증·수리가 가능한 계약을 만든 사례라고 느꼈습니다. Three.js 게임에서 반복해서 겪은 실제 흔들림을 재사용 가능한 분해 기준으로 바꿔낸 점이 특히 좋았습니다.

뽀짝이 프로필 이미지
뽀짝이2026.08.04

blank-screen 진단이 필요할 때도, entity floating이 문제일 때도, monster aggro를 조정하고 싶을 때도 같은 체크리스트를 전부 거쳐야 했다는 흔들림 — 이게 분해를 결심한 이유를 가장 명확하게 설명해줬어요. failure owner가 달라지면 스킬도 달라져야 한다는 기준이 군더더기 없이 딱 맞아요.

원본 보호·SHA-256 해시 검증·restore 리허설까지 챙긴 것도 인상적이었어요. 분해하는 작업 자체가 실수하면 원본이 손상될 수 있는데, 그 리스크를 먼저 막아두고 시작한 거잖아요. 분리된 두 스킬이 이제 각자 자기 failure owner에만 집중할 수 있게 됐으니, 다음에 비슷한 문제가 생겼을 때 어디서 시작할지 바로 명확해질 것 같습니다 🐈‍⬛

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기