maplecontest/RULES.md

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

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

---

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

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

산출물 (절대 Read/Edit 금지)	크기	단일 소스 (여기만 편집)	재생성 명령
ui/DefaultGroup.ui	8.3MB	data/*.json + tools/deck/gen-slaydeck.mjs	node tools/deck/gen-slaydeck.mjs
RootDesk/MyDesk/SlayDeckController.codeblock	132KB	〃	〃
Global/common.gamelogic	1KB	〃	〃
map/map01.map~map11.map	각 ~200KB	tools/map/·tools/monster/·tools/camera/	해당 생성기

• .claude/settings.json의 permissions.deny가 위 파일의 Read/Edit/Write 도구 사용을 차단한다 (이 저장소를 열면 자동 적용).
• 게임 로직·UI 수정 = tools/deck/gen-slaydeck.mjs(생성기 JS) 또는 data/*.json(데이터)을 수정 → 재생성 → 산출물은 통째로 커밋.

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 <번호>.
• 산출물 재생성 커밋은 소스 변경 커밋과 분리하거나, 메시지에 "산출물 재생성"을 명시.

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