6.9 KiB
6.9 KiB
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+lib/+hud/) |
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(오케스트레이터 + codeblock Lua) 또는data/*.json(데이터)을 수정 → 재생성 → 산출물은 통째로 커밋.- UI emit은 HUD별 모듈
tools/deck/hud/*.mjs(charselect·shop·combat·map·deckall·soulshop 등 16종), 공유 헬퍼·상수·데이터·lua 테이블은tools/deck/lib/ui-helpers.mjs·tools/deck/lib/data.mjs. 특정 화면 UI 수정은 해당hud/<name>.mjs만 손대면 된다(의존: orchestrator→hud→lib 단방향). - 리팩터 시 출력 바이트-동일 검증:
node tools/deck/gen-slaydeck.mjs후node tools/verify/diffcheck.mjs(워킹트리 vs HEAD 줄바꿈 정규화 비교 — 산출물 경로를 명령줄에 노출 안 해 deny 회피). 산출물M은 보통 autocrlf churn이니git checkout --로 복원.
- UI emit은 HUD별 모듈
- 보조 생성기(각자 자기 산출물의 단일 소스 — 위 표의 메인
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.configtools/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.codeblocktools/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 <번호>.
- 제목/본문은 UTF-8 spec JSON 파일로 작성 후
- 산출물 재생성 커밋은 소스 변경 커밋과 분리하거나, 메시지에 "산출물 재생성"을 명시.
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 |