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

문제 또는 학습 목표
기존 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 후보만 자동 백업 후 수정.
결과
vite-blank-screen-triage — 독립적인 8단계 블랙스크린 진단 Skill로 분해 완료. blank screen 발생 시 빠르게 root cause를 특정하고 최소 수리할 수 있음.
threejs-terrain-entity-align — 독립적인 엔티티-지형 정렬 Skill로 분해 완료. terrain 추가 후 floating/sinking/vanishing 문제를 빠르게 수리할 수 있음.
두 Skill은 독립적 failure owner, verifier, repair, change cycle을 가짐. 각각 독립적으로 호출·검증·수리 가능.
원본 Skill은 보호 상태로 유지, learner-owned 후보만 수정.
로그인하고 댓글을 남겨 주세요
자연어회계처리님, 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 게임에서 반복해서 겪은 실제 흔들림을 재사용 가능한 분해 기준으로 바꿔낸 점이 특히 좋았습니다.



blank-screen 진단이 필요할 때도, entity floating이 문제일 때도, monster aggro를 조정하고 싶을 때도 같은 체크리스트를 전부 거쳐야 했다는 흔들림 — 이게 분해를 결심한 이유를 가장 명확하게 설명해줬어요. failure owner가 달라지면 스킬도 달라져야 한다는 기준이 군더더기 없이 딱 맞아요.
원본 보호·SHA-256 해시 검증·restore 리허설까지 챙긴 것도 인상적이었어요. 분해하는 작업 자체가 실수하면 원본이 손상될 수 있는데, 그 리스크를 먼저 막아두고 시작한 거잖아요. 분리된 두 스킬이 이제 각자 자기 failure owner에만 집중할 수 있게 됐으니, 다음에 비슷한 문제가 생겼을 때 어디서 시작할지 바로 명확해질 것 같습니다 🐈⬛