# CODEX 작업 방식표

이 문서는 `HIU DUNGEON` 프로젝트에서 Codex가 매 요청마다 먼저 읽고 따를 작업 기준이다. 목적은 크레딧 소모를 줄이면서도 기존 기능을 망가뜨리지 않고, 분리 파일 구조를 유지하며, 필요한 검증만 수행하는 것이다.

## 1. 기본 원칙

| 항목 | 기준 |
| --- | --- |
| 파일 구조 | 현재 분리 구조를 유지한다. `index.html`, `css/`, `js/`를 다시 하나로 합치지 않는다. |
| 새 기능 위치 | 기존 책임에 맞는 파일에 넣고, 장기적으로 커질 기능은 새 파일로 분리한다. |
| 읽기 범위 | 요청과 관련된 파일/함수 주변만 읽는다. 전체 검색과 대량 출력은 피한다. |
| 수정 범위 | 요청한 기능과 직접 관련된 부분만 수정한다. 정상 작동 중인 시스템을 임의로 재작성하지 않는다. |
| 문서 갱신 | 작은 수정은 짧은 변경 기록만 남긴다. 큰 시스템 변경 때만 종합 기획서를 자세히 갱신한다. |
| 버전 | 게임 코드/구조/기획에 의미 있는 변경이 있으면 버전을 올린다. 단순 작업 지침 문서만 추가하는 경우는 버전 증가를 생략할 수 있다. |
| 배포 zip | 게임 실행물 수정이 있을 때만 `Hiu_Dungeon_(수정버전).zip`을 재생성한다. 문서만 수정한 경우에는 기본적으로 생략한다. |
| 전투 연결 | 새 공격은 반드시 `takeDamage`, `EnemyProjectile`, `damageHostileTargetsInCircle`, `damageHostileTargetsOnSegment` 경로를 사용해 패링/무적/피해태그가 작동하게 한다. |
| 자동 등록 | 새 무기/아이템/룬/이벤트는 상점, 보상, 도감, 테스트룸이 자동 또는 최소 연결로 읽을 수 있는 데이터 정의를 우선 사용한다. |

## 2. 요청별 작업 강도

| 요청 유형 | 파일 읽기 | 검증 | 문서/zip |
| --- | --- | --- | --- |
| CSS 배치/색상 수정 | 관련 CSS 파일 일부만 확인 | 생략 또는 눈에 띄는 문법만 확인 | zip 필요 시만 |
| 작은 JS 버그 수정 | 관련 JS 함수 주변만 확인 | 수정한 JS 파일만 `node --check` | 짧은 변경 기록 |
| 새 버튼/UI 추가 | `index.html`, 관련 CSS, DOM 참조, 입력 연결만 확인 | 수정 JS만 `node --check`, 새 참조 확인 | zip 재생성 |
| 새 무기/적/상자 등 기능 추가 | 관련 데이터/엔티티/게임 흐름 파일만 확인 | 수정 JS만 우선 검사, 필요 시 참조 확인 | 버전/기획서/zip |
| 새 파일 추가 | 새 파일과 `index.html` 로드 순서 확인 | 로컬 참조 확인 필수 | README 또는 기획서에 파일 역할 추가 |
| 입력/화면 전환/모바일 터치 변경 | 관련 입력 파일과 UI 파일 확인 | 필요 시 부트 스모크 | zip 재생성 |
| 대형 시스템 변경 | 관련 파일 전체 흐름 확인 | 전체 JS 검사 + 참조 확인 + 필요 시 부트 스모크 | 버전/기획서/인수인계/zip |

## 3. 검증 절약 규칙

| 검증 항목 | 기본 실행 여부 | 실행하는 경우 |
| --- | --- | --- |
| 수정 JS `node --check` | 실행 | JS를 수정했을 때 |
| 전체 JS `node --check` | 생략 | 여러 JS 파일을 넓게 수정했거나 전역 구조를 바꿨을 때 |
| `index.html` 로컬 참조 확인 | 조건부 실행 | CSS/JS 파일 추가, 삭제, 이름 변경, 로드 순서 변경 시 |
| VM 부트 스모크 | 기본 생략 | 전역 초기화, DOM 참조, 로드 순서, 입력 이벤트를 바꿨을 때 |
| HTTP 서버/curl 확인 | 기본 생략 | 모바일 실행 문제, CSS/JS 로딩 문제, 새 파일 로딩 문제가 의심될 때 |
| zip 무결성 검사 | 기본 생략 | 새 파일을 zip에 넣었거나 배포 파일 누락이 걱정될 때 |
| 브라우저/스크린샷 테스트 | 기본 생략 | UI 겹침, 캔버스 렌더링, 모바일 터치 문제를 직접 확인해야 할 때 |

## 4. 크레딧 절감 작업 습관

| 상황 | 할 일 | 피할 일 |
| --- | --- | --- |
| 위치가 명확한 수정 | 해당 파일의 해당 함수 주변만 읽기 | `rg`로 프로젝트 전체를 넓게 반복 검색 |
| 문서 갱신 | 필요한 항목만 짧게 수정 | 기획서와 인수인계 전체를 매번 크게 읽기 |
| 검증 | 수정 범위에 맞는 최소 검증 선택 | 모든 요청마다 전체 JS/HTTP/부트/zip 검증 풀코스 실행 |
| zip 생성 | 게임 실행물이 바뀐 경우에만 생성 | 문서만 바꿨는데 zip 재생성 |
| 결과 보고 | 변경 파일, 핵심 변경, 수행 검증만 짧게 보고 | 긴 로그나 전체 파일 목록 붙여넣기 |

## 5. 분리 파일 책임표

| 영역 | 주요 파일 |
| --- | --- |
| 설정/DOM/전역 상태 | `js/00-config-state-dom.js` |
| 가방 아이템 데이터 | `js/data/01-bag-items.js` |
| 무기 룬/도감 데이터 | `js/data/02-weapon-runes-codex.js` |
| 보상상자 등급/드랍 | `js/data/03-treasure-chests.js` |
| 던전 생성 | `js/systems/04-dungeon-generation.js` |
| 튜토리얼 | `js/systems/10-tutorial.js` |
| 플레이어 | `js/entities/05-player.js` |
| 무기/투사체 | `js/entities/06-weapons-projectiles.js` |
| 적 AI | `js/entities/07-enemies.js` |
| 소환수/드랍/NPC/상점 | `js/entities/08-summons-pickups-shop.js` |
| 이펙트/오브젝트/상자 | `js/entities/09-effects-objects.js` |
| 게임 본체/전투/렌더링 | `js/core/11-game.js` |
| 화면 전환 | `js/12-app-flow.js` |
| HUD/인벤토리/도감 UI | `js/13-ui-hud-inventory-codex.js` |
| 입력/루프 이벤트 | `js/14-loop-events-input.js` |
| 물리/상태 유틸 | `js/15-physics-status-utils.js` |
| 초기 실행 | `js/16-boot.js` |
| 메인/도감 CSS | `css/00-base-menu-codex.css` |
| HUD CSS | `css/01-game-hud.css` |
| 모바일 조작 CSS | `css/02-mobile-controls.css` |
| 테스트룸/인벤토리 CSS | `css/03-testroom-inventory.css` |
| 대화창 CSS | `css/04-dialogue-responsive.css` |

## 6. 신규 콘텐츠 연결 규칙

### 6.1 새 몬스터/보스

새 몬스터를 추가할 때는 아래 연결을 한 묶음으로 처리한다.

| 연결 지점 | 해야 할 일 |
| --- | --- |
| `js/entities/07-enemies.js` | 적 클래스와 패턴 구현 |
| `Game.createEnemyByKind` | kind 문자열로 생성 가능하게 연결 |
| 테스트룸 소환 | 새 몬스터는 테스트룸에서 반드시 소환 가능하게 추가 |
| 던전 enemy pool | 실제 던전에 등장해야 하면 `enemyPool`에 추가 |
| 도감 | `CODEX_STATIC_ENTRIES.enemies`에 외형/설명/스탯 추가 |
| 패링 | 모든 공격이 패링 가능한 피해 경로를 지나게 확인 |

공격 구현 규칙:

- 투사체는 `EnemyProjectile` 또는 `game.enemyProjectiles`에 들어가는 클래스를 사용한다.
- 근접, 레이저, 장판, 폭발, 접촉 피해는 `player.takeDamage`, `game.damageHostileTargetsInCircle`, `game.damageHostileTargetsOnSegment`를 사용한다.
- `damageTagOptions(...)`로 피해 태그를 붙인다.
- 패링으로 완전히 막혀야 하는 공격은 `parryBlocksHit: true`를 붙인다.
- 플레이어 HP를 직접 빼지 않는다.
- 보스/엘리트는 패링 기절 면역이므로 강인도 감소와 경고 연출을 우선 확인한다.

### 6.2 새 무기

새 무기를 추가할 때는 아래 연결을 확인한다.

- `createWeaponById`에 무기 정의 추가.
- `CODEX_STATIC_ENTRIES.weapons`에 추가. 상점/보상 자동 풀과 도감 표시의 기준이다.
- 기본공격, 차징공격, 스킬, 대시공격, 소환수 피해에 태그를 붙인다.
- 무기 정보창과 도감에서 공격 정보가 표시되는지 확인한다.
- 투사체 수/크기/튕김/유도/치명타/폭발/소환수 룬이 적용되는지 확인한다.

### 6.3 새 아이템/룬

- 가방 아이템은 `js/data/01-bag-items.js`의 정의, 외형, 히트박스, 레벨 표시를 함께 확인한다.
- 신규 비소모 가방 아이템은 `RUNE_DEFS`와 `BAG_ITEM_GEOMETRY`를 항상 같이 추가한다. 전용 PNG를 쓰지 않는다면 `size`와 `hitboxes`를 반드시 넣어 기본 격자 외형으로 떨어지지 않게 한다.
- 룬은 `js/data/02-weapon-runes-codex.js`에 정의하고, 실제 무기 계산 경로에서 보너스를 읽는지 확인한다.
- 룬도 가방에 들어가는 아이템처럼 취급된다. 가방 탭과 무기 탭 양쪽 표시를 확인한다.
- 바닥에 버릴 때 다른 드랍과 겹치지 않게 배치한다.

### 6.4 새 이벤트

- `EVENT_ROOM_DEFS`에 등록한다.
- 테스트 이벤트 NPC 선택지와 실제 던전 이벤트방이 같은 카탈로그를 읽게 유지한다.
- 대화 후 선택지가 뜨는지, 방 비우기 시 NPC/오브젝트가 정리되는지 확인한다.
- 이벤트 NPC가 일반 테스트룸 NPC와 겹치지 않게 배치한다.

## 7. 최종 보고 형식

작업 완료 후에는 아래만 간단히 보고한다.

- 변경 요약
- 수정한 주요 파일
- 수행한 최소 검증
- 실행 링크와 다운로드 링크는 게임 실행물이 바뀌어 zip을 재생성한 경우에만 포함

문서만 수정한 경우에는 zip을 만들지 않고, 문서 파일 링크만 제공한다.
