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는 "디지털 판타지" 세계관의 오프라인 싱글플레이어 방치형 RPG입니다. ASCII 아트 비주얼과 자동 전투 시스템이 특징이며, 네트워크 기능은 제외됩니다.

빌드 및 실행

# 의존성 설치
flutter pub get

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

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

아키텍처

디렉토리 구조

lib/
├── main.dart                          # 앱 진입점
├── data/                              # 정적 데이터 (Config.dfm 추출 + 확장)
│   ├── pq_config_data.dart            # 게임 원본 정적 데이터
│   ├── class_data.dart                # 직업 데이터
│   ├── race_data.dart                 # 종족 데이터
│   ├── skill_data.dart                # 스킬 데이터
│   ├── potion_data.dart               # 포션 데이터
│   ├── story_data.dart                # 스토리 데이터
│   └── game_text_l10n.dart            # 게임 텍스트 번역
├── l10n/                              # 앱 UI 다국어 리소스 (arb)
└── src/
    ├── app.dart                       # MaterialApp 설정
    ├── core/
    │   ├── engine/                    # 게임 루프 및 진행 로직
    │   │   ├── progress_loop.dart         # 타이머 기반 메인 루프
    │   │   ├── progress_service.dart      # 틱 처리, 경험치/레벨업 로직
    │   │   ├── game_mutations.dart        # 상태 변경 함수
    │   │   ├── reward_service.dart        # 보상 처리
    │   │   ├── combat_calculator.dart     # 전투 계산
    │   │   ├── combat_tick_service.dart   # 전투 틱 처리
    │   │   ├── arena_service.dart         # 아레나 시스템
    │   │   ├── skill_service.dart         # 스킬 시스템
    │   │   ├── item_service.dart          # 아이템 처리
    │   │   ├── potion_service.dart        # 포션 시스템
    │   │   ├── shop_service.dart          # 상점 시스템
    │   │   ├── story_service.dart         # 스토리 진행
    │   │   └── ...                        # 기타 서비스
    │   ├── model/                     # 게임 상태 및 데이터 모델
    │   ├── infrastructure/            # 외부 서비스 (광고, IAP 등)
    │   ├── audio/                     # 오디오 서비스
    │   ├── storage/                   # 세이브/설정 저장소
    │   ├── notification/              # 알림 서비스
    │   └── util/                      # 유틸리티 (RNG, 로직 헬퍼 등)
    ├── features/
    │   ├── front/                     # 타이틀/세이브 선택 화면
    │   ├── new_character/             # 캐릭터 생성 화면
    │   ├── game/                      # 게임 진행 화면 (메인)
    │   │   ├── controllers/           # 전투 로그, 오디오 컨트롤러
    │   │   ├── managers/              # 통계, 부활, 속도 부스트 등
    │   │   ├── pages/                 # 탭별 페이지 (장비, 인벤토리, 퀘스트 등)
    │   │   └── widgets/              # UI 위젯
    │   ├── arena/                     # 아레나 전투 화면
    │   ├── hall_of_fame/              # 명예의 전당
    │   └── settings/                  # 설정 화면
    └── shared/                        # 공통 테마/위젯

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/는 참조용으로 유지
• 원본 알고리즘은 참고하되 독자적 확장/수정 허용

데이터 관리

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

코딩 표준

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

화면 구성

• 주요 화면: 프론트, 캐릭터 생성, 게임 진행, 아레나, 명예의 전당, 설정
• 화면 내 요소는 위젯 단위로 분리

원본 소스 참조 (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

작업 프로토콜

3자 교차 토론 (Three-Party Cross-Debate)

모든 에이전트/스킬 실행 결과는 Claude, Gemini, Codex 3자가 독립 분석 후 토론하여 합의된 결과만 사용자에게 제공한다.

AI	역할	초점
Claude	전략가/종합자	비즈니스 로직, 설계, 최종 종합
Gemini	논리 비평가	논리적 모순, UX 갭, 엣지 케이스
Codex	기술 감사자	구현 실현성, 인프라 제약, 보안, 코드 품질

[Round 1: 초안 + 병렬 리뷰]
1. Claude 에이전트 실행 → 초안 생성
2. 병렬 실행:
   a. gemini -y -p "{초안 + 리뷰 프롬프트}" -o text
   b. codex exec "{초안 + 리뷰 프롬프트}" --full-auto
3. Claude가 3자 관점 비교 → 합의/불일치 식별

[Round 2: 불일치 토론 (불일치 있을 때만)]
4. gemini -y -r latest -p "{불일치 + 반론}" -o text
5. codex exec "{전체 컨텍스트 + 불일치}" --full-auto
6. Claude 최종 종합

[합의 규칙]
- 합의 시: 합의 내용만 출력
- 미합의 시: "[NO CONSENSUS]" 표기 + 3자 의견 병기

에이전트/스킬 활용

• 에이전트 정의: .claude/agents/ (origin에서 복사)
• 스킬 정의: .claude/skills/ (origin에서 복사)
• 비사소한 작업은 반드시 에이전트를 병렬 배포하여 진행
• 작업 완료 조건: Gemini 토론 합의 완료

프로젝트 분석 리포트

• analysis/full-audit-2026-03-27.md — 9개 에이전트 전체 감사 (Health Score: 49/100)
• analysis/supply-chain-review.md — 의존성/라이선스/CVE 분석