MagnetismHeroes/CLAUDE.md

MagnetismHeroes

5~7세가 구 자석을 직접 모으고 세고 합체·분리하는 모바일 3D 카툰 퍼즐이다. 현재 한국어·Android·가로 화면·오프라인 체험판이며 30개 스테이지와 성공 후 자유 놀이를 제공한다. Unity 6의 URP·Input System·uGUI·TMP를 사용하고 수학 규칙은 순수 C#으로 분리한다.

프로젝트 안내

MagnetismHeroes/
├── AGENTS.md → 작업 시작과 핵심 경계
├── CLAUDE.md → 동일한 작업 시작 지침
├── docs/
│   ├── architecture.md → 구성과 데이터 흐름
│   ├── business-rules.md → 학습·조작·진행의 판정
│   ├── security.md → 로컬 데이터·제작 자산 보호
│   ├── standards.md → 변경·참조·검증 기준
│   ├── engineering-notes.md → 실제 실패 원인과 대응
│   ├── operations.md → 에디터 실행·빌드·제작 절차
│   ├── contracts.md → JSON·명령행 입출력 계약
│   └── tracking/
│       ├── status.md → 구현·검증과 후속 범위
│       ├── findings.md → 해결되지 않은 재현 문제
│       └── decisions/
│           ├── index.md → 설계 결정 목록
│           ├── 0001-rules-boundary.md → 규칙과 Unity 분리
│           ├── 0002-stage-authoring.md → 고정 스테이지 제작
│           ├── 0003-local-progress.md → 로컬 이어하기
│           ├── 0004-prebaked-voice.md → 파일 기반 학습 음성
│           └── 0005-hybrid-assets.md → 혼합 자산 제작
├── Assets/MagnetismHeroes/
│   ├── Core/AGENTS.md → 순수 규칙·진행·저장 검증
│   ├── UnityRuntime/AGENTS.md → 입력·표현·파일 연결
│   └── Editor/AGENTS.md → 자산 제작·Android 빌드
├── SourceAssets/AGENTS.md → 원본·출처·채택 이력
└── tools/
    ├── AGENTS.md → 검증 진입점
    ├── android/AGENTS.md → 실제 앱 입력·저장·PCM 검사
    ├── audio/AGENTS.md → 로컬 음성 생성·후보 내보내기
    └── models/AGENTS.md → Blender 소품 제작

핵심 경계

• 합체·분리·이동으로 구의 ID와 총량을 잃거나 복제하지 않는다. 숫자와 실제 소속 구 수를 일치시킨다.
• 모양·위치·풀이 순서를 새로운 정답 조건으로 만들지 않는다. 선택한 구가 떨어져 있어도 두 친구로 나눈다.
• 완료 기록·퍼즐별 미완료 상태·최근 자유 놀이를 혼합하지 않는다. 성공의 기록 변경은 한 단위로 확정한다.
• Unity 입력·연출이 순수 수학 규칙을 소유하지 않는다. 미리보기·애니메이션 중간값을 확정 상태로 저장하지 않는다.
• 실제로 평가되지 않은 검사를 통과로 기록하지 않는다. 설치 APK와 실행 증거를 같은 소스·파일 해시로 연결한다.

작업 전에

docs/standards.md, docs/engineering-notes.md와 대상 모듈의 AGENTS.md를 읽는다. 수학·진행·힌트 변경은 docs/business-rules.md의 수집/계수·목표·재플레이 경계를, 저장 변경은 docs/contracts.md의 필드·손상 복구와 docs/security.md의 데이터 보존을 확인한다. 입력·씬·자산 작업은 docs/architecture.md의 상태 소유와 docs/operations.md의 초기 builder 주의사항을 확인한다. 음성 변경은 승인 파일·원본 이력과 제작/런타임 분리를 먼저 확인한다.

요구된 아이의 행동과 합격 결과를 먼저 정하고 최소 변경으로 구현한다. 실제 기기·iOS 등 현재와 후속의 구분은 docs/tracking/status.md에서 확인한다. 검사·Editor·ADB·녹음의 실행 소유자를 한 명으로 유지한다.

문제 대응

구 소실·복제나 잘못된 숫자 판정, 완료/이어하기 손실·덮어쓰기, 미승인 자산 채택, 요청하지 않은 런타임 외부 전송이 발견되면 관련 변경을 멈추고 증거와 영향을 사용자에게 즉시 알린다. 다른 문제는 먼저 재현·원인 확인·수정을 시도하고 실제로 해결할 수 없는 경우에만 이유와 영향·가능한 대응을 docs/tracking/findings.md에 남긴다.