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의 핵심 메커니즘을 기반으로, 독자적 세계관("디지털 판타지")과 확장된 시스템으로 재구성한 오프라인 싱글플레이어 방치형 RPG입니다. 네트워크 기능은 제외됩니다.

빌드 및 실행

# 의존성 설치
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            # PQ 원본 정적 데이터
│   ├── 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/                     # 게임 상태 및 데이터 모델
    │   ├── 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 분석