문제 또는 학습 목표
기존 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 후보만 수정.
집과 나무가 있는 도시의 3D 이미지
