Document verified Android game architecture, rules and development procedures

CLAUDE.md

@@ -0,0 +1,59 @@
+# MagnetismHeroes
+
+5~7세가 구 자석을 직접 모으고 세고 합체·분리하는 모바일 3D 카툰 퍼즐이다.
+현재 한국어·Android·가로 화면·오프라인 체험판이며 30개 스테이지와 성공 후 자유 놀이를 제공한다.
+Unity 6의 URP·Input System·uGUI·TMP를 사용하고 수학 규칙은 순수 C#으로 분리한다.
+
+## 프로젝트 안내
+
+```text
+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`에 남긴다.