asciinevrdie/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

프로젝트 개요

Askii Never Die는 Progress Quest 6.4 (Delphi 원본)를 Flutter로 100% 동일하게 복제하는 오프라인 싱글플레이어 RPG입니다. 네트워크 기능은 모두 제외되며, 원본 알고리즘과 데이터를 그대로 유지해야 합니다.

빌드 및 실행

# 의존성 설치
flutter pub get

# 실행 (플랫폼 지정 가능: -d macos, -d chrome 등)
flutter run

# 핸드오프 전 필수 검증
dart format --set-exit-if-changed .
flutter analyze
flutter test

아키텍처

디렉토리 구조

lib/
├── main.dart                      # 앱 진입점
├── data/pq_config_data.dart       # PQ 정적 데이터 (Config.dfm 추출)
└── src/
    ├── app.dart                   # MaterialApp 설정
    ├── core/
    │   ├── engine/                # 게임 루프 및 진행 로직
    │   │   ├── progress_loop.dart     # 타이머 기반 메인 루프 (원본 200ms)
    │   │   ├── progress_service.dart  # 틱 처리, 경험치/레벨업 로직
    │   │   ├── game_mutations.dart    # 상태 변경 함수
    │   │   └── reward_service.dart    # 보상 처리
    │   ├── model/
    │   │   ├── game_state.dart        # 핵심 상태: Traits, Stats, Inventory, Equipment, SpellBook, ProgressState, QueueState
    │   │   ├── pq_config.dart         # Config 데이터 접근
    │   │   ├── equipment_slot.dart    # 장비 슬롯 정의
    │   │   └── save_data.dart         # 저장 데이터 구조
    │   ├── storage/                   # 세이브 파일 처리
    │   └── util/
    │       ├── deterministic_random.dart  # 결정론적 RNG (재현 가능)
    │       ├── pq_logic.dart              # 원본 로직 포팅 (odds, randSign 등)
    │       └── roman.dart                 # 로마 숫자 변환
    └── features/
        ├── front/front_screen.dart        # 임시 프론트 화면
        └── game/game_session_controller.dart  # 게임 세션 관리

example/pq/     # Delphi 원본 소스 (참조용, 빌드 대상 아님)
test/           # 단위/위젯 테스트

레이어 구조 (Clean Architecture)

• Presentation (features/) → Domain (core/model/, core/engine/) → Data (data/, core/storage/)
• 역방향 의존 금지: Domain은 Flutter/UI import 불가

핵심 데이터 흐름

1. ProgressLoop가 타이머로 tickOnce() 호출
2. ProgressService.tick()이 GameState 업데이트
3. GameState 스트림으로 UI 갱신
4. 레벨업/퀘스트 완료 시 SaveManager 자동 저장

핵심 규칙

원본 충실도

• example/pq/ 내 Delphi 소스의 알고리즘/데이터를 100% 동일하게 포팅
• 원본 로직 변경 필요 시 반드시 사용자 승인 필요
• 새로운 기능, 값, 처리 로직 추가 금지 (디버깅 로그 예외)

데이터 관리

• 정적 데이터(몬스터, 아이템, 주문 등)는 Config.dfm에서 추출하여 JSON/Dart const로 관리
• 영문 원문 기준 작성, UI 텍스트는 i18n 구조로 분리
• 이미지 파일 미사용

코딩 표준

• 2-space 인덴트, dart format 준수
• 타입 명시적 선언, any/dynamic 지양
• 파일명: snake_case, 클래스: PascalCase, 변수/함수: camelCase
• 파일당 200 LOC 이하, 함수 20 라인 이하 권장
• SRP(Single Responsibility Principle) 준수

화면 구성

• 2개 화면만 사용: 캐릭터 생성 화면, 게임 진행 화면
• 화면 내 요소는 위젯 단위로 분리

원본 소스 참조 (example/pq/)

파일	핵심 함수/라인	역할
Main.pas:523-1040	MonsterTask	전투/전리품/레벨업
Main.pas:267-424	StartTimer	메인 게임 루프
Main.pas:456-521	InterplotCinematic, NamedMonster	시네마틱/명명
NewGuy.pas:55-68	RerollClick	캐릭터 생성 (3d6)
Config.dfm	TMemo 데이터	주문, 몬스터, 아이템, 종족, 직업 등

승인 필요 사항

• pubspec.yaml 의존성 변경
• 플랫폼 빌드 설정 (Android/iOS/desktop)
• 네트워크 접근 도입
• 원본 데이터/알고리즘 수정
• 대규모 파일 삭제 또는 구조 변경

커밋 규칙

type(scope): 한국어 설명

- 변경 상세 내용

Types: feat, fix, refactor, test, docs, style, chore, perf