Files

gahusb 65ad2fe854 chore(harness): 토큰 가드 하네스 — 산출물 접근 차단·RULES.md·CLAUDE.md

- .claude/settings.json: ui/DefaultGroup.ui(8.3MB)·map/*.map·SlayDeckController.codeblock
  Read/Edit/Write 도구 차단 (생성 산출물 — 단일 소스는 data/*.json + tools/)
- RULES.md: 협업 공용 하네스 규칙 (카운트 검증·탐색 경로 제한·gitea-pr 절차·이중 구현 동기화)
- CLAUDE.md: RULES.md 임포트로 Claude Code 자동 적용
- .gitignore: .claude/settings.json만 커밋 예외 (local 설정은 계속 제외)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-12 11:01:13 +09:00

4.0 KiB

Raw Blame History

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`

4.0 KiB Raw Blame History