maplecontest/RULES.md

RULES.md — SlayMaple 하네스 엔지니어링 규칙

AI 에이전트(Claude Code 등)와 협업자가 이 저장소에서 토큰을 낭비하지 않고 안전하게 작업하기 위한 공용 규칙. Claude Code는 CLAUDE.md가 이 파일을 임포트하므로 자동 적용된다. 다른 도구(Codex 등)를 쓰면 세션 시작 시 이 파일을 읽혀라.

---

1. 생성 산출물은 읽지도, 고치지도 않는다 (가장 중요)

이 저장소의 큰 파일들은 전부 생성기 산출물이다. 직접 읽으면 토큰이 증발하고, 직접 고치면 다음 재생성 때 사라진다.

산출물 (절대 Read/Edit 금지)	크기	단일 소스 (여기만 편집)	재생성 명령
ui/DefaultGroup.ui	~7.1MB	data/*.json + tools/deck/gen-slaydeck.mjs	node tools/deck/gen-slaydeck.mjs
RootDesk/MyDesk/SlayDeckController.codeblock	~270KB	〃	〃
Global/common.gamelogic	~1KB	〃	〃
map/map01.map~map05.map, map/lobby.map	각 ~210KB	tools/map/·tools/monster/·tools/camera/·tools/player/ (↓ 보조 생성기)	해당 생성기
RootDesk/MyDesk/CombatMonster.codeblock	~2KB	tools/monster/gen-combat-monster.mjs	node tools/monster/gen-combat-monster.mjs
RootDesk/MyDesk/PlayerLock.codeblock	~2KB	tools/player/gen-player-lock.mjs	node tools/player/gen-player-lock.mjs
RootDesk/MyDesk/MapCamera.codeblock	~2KB	tools/camera/gen-camera.mjs (값: data/camera.json)	node tools/camera/gen-camera.mjs
RootDesk/MyDesk/LobbyNpc.codeblock·LobbyMobility.codeblock	각 ~2-3KB	tools/player/gen-lobby-npc.mjs	node tools/player/gen-lobby-npc.mjs
Global/SectorConfig.config	~1KB	tools/map/gen-maps.mjs·gen-lobby-map.mjs (패치)	해당 생성기

• .claude/settings.json의 permissions.deny가 위 파일의 Read/Edit/Write 도구 사용을 차단한다 (이 저장소를 열면 자동 적용). deny는 glob — ui/*.ui·map/*.map·RootDesk/MyDesk/*.codeblock·Global/common.gamelogic·Global/SectorConfig.config. 따라서 메이커 저작 codeblock/UI(Monster·MonsterAttack·PlayerAttack·PlayerHit·UIPopup·UIToast.codeblock, ui/PopupGroup.ui·ui/ToastGroup.ui)도 Read/Edit 금지 — 이들은 생성기가 없으니 메이커에서 편집한다(텍스트 도구로 X). codeblock은 한 줄짜리 JSON이라 Read 시 토큰 폭발.
• 게임 로직·UI 수정 = tools/deck/gen-slaydeck.mjs(생성기 JS) 또는 data/*.json(데이터)을 수정 → 재생성 → 산출물은 통째로 커밋.
• 보조 생성기(각자 자기 산출물의 단일 소스 — 위 표의 메인 gen-slaydeck.mjs 외):
  • tools/camera/gen-camera.mjs → MapCamera.codeblock + map01~05 카메라 부착 (값 data/camera.json)
  • tools/map/gen-maps.mjs → map02~05 + Global/SectorConfig.config (map01 템플릿 클론)
  • tools/map/gen-lobby-map.mjs → map/lobby.map + SectorConfig.config
  • tools/map/gen-map-encounters.mjs → map01~05 노드 타입별 몬스터 그룹 재구성
  • tools/monster/gen-combat-monster.mjs → CombatMonster.codeblock + map01~05 부착
  • tools/monster/freeze-turn-monsters.mjs → 몬스터 .model·맵 AI 컴포넌트 제거
  • tools/player/gen-player-lock.mjs → PlayerLock.codeblock + map01~05 부착
  • tools/player/gen-lobby-npc.mjs → LobbyNpc.codeblock·LobbyMobility.codeblock
  • tools/player/freeze-turn-player.mjs → Global/DefaultPlayer.model 이동 0 고정
  • tools/deck/gen-cardhand.mjs → DefaultGroup.ui 카드핸드 보조 패처

2. 산출물 검증은 카운트로, 내용 출력 금지

재생성 결과 확인이 필요하면 본문을 출력하지 말고 존재/개수만 확인한다:

node tools/deck/gen-slaydeck.mjs                       # 성공 메시지 1줄
grep -c "TreasureHud" ui/DefaultGroup.ui               # 개수만
grep -c "CalcPlayerAttack" RootDesk/MyDesk/SlayDeckController.codeblock

• ⚠️ codeblock은 한 줄이 수만 자(JSON 직렬화)다. grep(내용 출력)·sed -n 광역 범위 출력은 한 줄만 걸려도 토큰 폭발 → grep -c/grep -l/grep -o '짧은패턴'만 사용.
• Claude Code의 Grep 도구를 산출물에 쓸 때는 output_mode: count 또는 files_with_matches만. content 모드 금지.
• 진짜 내용 확인이 필요하면 좁은 grep -o 또는 python으로 슬라이스해서 수 줄 이내로.

3. 탐색 규칙

• 코드 탐색은 tools/·data/·docs/만 대상으로. 저장소 전체 grep은 산출물이 걸리므로 경로를 지정한다.
• git add -A 전 git status --short로 산출물 외 의도치 않은 변경이 없는지 확인 (산출물 diff는 보지 않는다 — 생성기가 결정적이므로 소스 리뷰로 충분).
• 게임 동작 확인은 메이커 플레이테스트(스크린샷·로그)로 한다. 산출물 정독으로 동작을 추론하지 않는다.

4. Git/PR 절차

• 브랜치 → 커밋(기능 단위) → push → PR은 반드시 node tools/git/gitea-pr.mjs로 (인라인 curl -d 한글 본문은 Windows에서 CP949로 깨짐 — PR #34~41 사고).
  • 제목/본문은 UTF-8 spec JSON 파일로 작성 후 create <spec.json> / merge <번호>.
  • PR 제목과 본문은 한국어로 작성한다.
• 산출물 재생성 커밋은 소스 변경 커밋과 분리하거나, 메시지에 "산출물 재생성"을 명시.

5. 메이커(MSW) 연동 주의

• git pull 후 메이커에서 로컬 워크스페이스 reload 필수 (안 하면 메이커의 stale 상태가 디스크를 덮어씀).
• 재생성 후 메이커가 켜져 있으면 refresh → 빌드 콘솔 0 에러 확인.
• 카드/유물/물약 이미지는 공식 maplestory 리소스 RUID만 (계정 업로드 리소스는 로컬 워크스페이스에서 흰 박스).

6. 밸런스·맵 규칙 동기화

전투 규칙과 맵 생성은 Lua(생성기 내장)와 JS가 이중 구현이다. 한쪽을 고치면 반드시 다른 쪽도:

영역	Lua (gen-slaydeck.mjs 내)	JS 미러	테스트
전투 규칙	PlayCard·CalcPlayerAttack 등	tools/balance/sim-balance.mjs	node --test tools/balance/sim-balance.test.mjs
맵 생성	GenerateMap	tools/map/rogue-map.mjs	node --test tools/map/rogue-map.test.mjs

7. UI 숫자 표기

• UI 텍스트에서는 정수값인 숫자에 .0을 붙이지 않는다. 1.0/1.0이 아니라 1/1처럼 표시한다.
• 생성기 내 Lua UI 코드에서 number 또는 숫자 문자열을 텍스트에 붙일 때는 FormatNumber 같은 포맷 헬퍼를 우선 사용한다.
• 소수부가 플레이어에게 의미 있을 때만 소수점 표기를 유지한다.