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입니다. 네트워크 기능은 제외됩니다.

## 빌드 및 실행

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