gaesup-world: Instructions file for Codex

gaesup-world

gaesup-world는 React Three Fiber, Three.js, Rapier와 Zustand를 기반으로 하는 3D world library와 이를 소비하는 Vite showcase를 함께 관리한다. 장기 목표는 Blender asset authoring, persistent WorldDocument, WebGPU-first rendering, world creator, multiplayer와 social interaction을 연결하는 data-oriented 3D social world platform이다.

AGENTS.md, .codex/agents/*.toml의 위치와 필수 형식은 Codex 공식 문서를 따른다. 절차형 스킬은 .claude/skills/**/SKILL.md에 있으며(add-domain, add-subpath-export, verify, start-epoch, close-epoch) Codex에서도 해당 파일을 문서로 읽어 같은 절차를 따른다. 4개 역할 분리, context 문서, invariant와 epoch workflow는 현재 저장소 분석을 바탕으로 한 추론한 설계다.

저장소 규칙

• 기존 동작과 사용자 변경을 보존하고 요청 범위의 최소 migration slice만 수정한다.
• reset, checkout, restore, revert로 기존 변경을 제거하지 않는다.
• dist/, demo-dist/, node_modules/와 대용량 asset을 직접 수정하지 않는다.
• 이미 실행 중인 dev server를 다시 실행하거나 종료하지 않는다.
• 전체 재작성보다 strangler migration을 우선한다.
• 존재하지 않는 경로나 API를 추측하지 않고 현재 저장소를 확인한다.

코딩 규칙

• TypeScript strict를 유지하고 any를 사용하지 않는다.
• 데이터 타입은 type으로 정의한다. 기존 interface는 해당 작업이 직접 다루지 않으면 기계적으로 변경하지 않는다.
• 코드 식별자는 영어로 작성한다.
• 불필요한 주석, 빈 줄, magic number와 중복 코드를 추가하지 않는다.
• 타입은 가능한 경우 같은 domain의 types.ts에 분리한다.
• 컴포넌트는 <Name>/index.tsx, styles.css, types.ts 구조를 우선한다.
• console.log, console.warn, console.error 대신 project logger를 사용한다.
• store는 selector로 필요한 상태만 구독하고 전체 store를 구독하지 않는다.
• Props event는 on*, 내부 handler는 handle*, 상수는 UPPER_SNAKE_CASE를 사용한다.
• 프로젝트의 Prettier와 ESLint 설정을 따른다.

Architecture 원칙

• Persistent world state는 React에 의존하지 않는다.
• Three.js와 Rapier 객체는 canonical persistent state가 아니다.
• Editor와 Runtime은 장기적으로 같은 World Model을 projection한다.
• Persistent mutation은 하나의 canonical write path를 가진다.
• Network와 save contract는 engine-neutral serializable data를 사용한다.
• WebGPU는 목표 primary renderer이고 WebGL-specific 구현은 compatibility boundary에 격리한다.
• 기존 typed-array, spatial, visibility, culling과 GPU upload 구현은 측정 근거 없이 객체 중심 구조로 교체하지 않는다.
• React component lifetime과 persistent entity lifetime을 결합하지 않는다.
• migration 중 old/new path가 공존하면 canonical path를 문서와 코드에서 명시한다.