100 lines
5.4 KiB
Markdown
100 lines
5.4 KiB
Markdown
# Project SS — CLAUDE.md
|
|
> **위치:** repo root (`ProjectSS/CLAUDE.md`) — Claude Code는 root에서 실행한다.
|
|
> **규칙:** 작업 완료 후 "현재 Phase 상태" 블록을 반드시 업데이트한다.
|
|
|
|
---
|
|
|
|
## 개발 전략
|
|
|
|
**그레이박스 우선 (Greybox First)**
|
|
게임플레이 재미 검증 → 그레이박스 테스트 → 비주얼 폴리싱 순서로 진행한다.
|
|
Phase 5(비주얼 폴리싱)는 그레이박스 테스트 피드백 반영 완료 후에만 착수한다.
|
|
|
|
---
|
|
|
|
## 코드 컨벤션 (package.json으로 알 수 없는 것)
|
|
|
|
- 실제 앱은 `client/` 안에 있음. npm 명령은 `cd client` 후 실행.
|
|
- 스타일: 컴포넌트별 개별 `.css` (글로벌 클래스, CSS Modules 아님)
|
|
- 상태관리: `useState` / `useReducer`만 사용. 외부 상태관리 라이브러리 도입 금지.
|
|
- 영구 저장: `localStorage` (도감 엔딩 저장 용도)
|
|
- 카드 데이터는 `client/src/data/cards.csv`를 papaparse로 런타임 파싱함
|
|
- `GameScreen.jsx`에 상태가 집중되어 있음 — 수정 시 주의, 리팩토링 필요 가능성
|
|
|
|
## ⛔ 보호 파일 (직접 수정/실행 금지 — 변경 제안은 가능)
|
|
|
|
- `client/update_csv.js` — cards.csv 전처리 스크립트 (데이터 변환 규칙: 컬럼 구조, 인코딩, 파싱 로직 등)
|
|
- `client/update_csv_tags.js` — 내러티브 태그 매핑 스크립트
|
|
|
|
**이유:** 두 스크립트의 출력 포맷(변환 규칙)이 바뀌면, 이를 읽는 게임 코드(papaparse 파싱 부분)가
|
|
깨지거나 데이터를 잘못 읽을 수 있다.
|
|
|
|
**규칙:** 이 스크립트들을 직접 고쳐서 실행하지 말 것. 단, Phase 진행상 스키마 변경이 실제로 필요한
|
|
경우(예: 새 컬럼/태그 카테고리 추가) 코드를 바로 바꾸지 말고, 어떤 변경이 왜 필요한지 설명하고
|
|
변경안(diff)을 먼저 보여준 뒤 승인을 받고 나서 적용할 것.
|
|
|
|
**단, `cards.csv` / `narrative_tags.json` 등 데이터 내용(카드 텍스트, 수치, 태그)은 자유롭게 다뤄도 된다.**
|
|
이 게임은 카드 밸런스와 스토리 개연성이 핵심이라, 데이터는 자동 생성으로 일괄 채우지 말고
|
|
디자이너가 직접 열어보고 검토·조정할 수 있는 형태로 제안할 것 (예: 몇 개씩 초안을 보여주고
|
|
피드백을 받아 반영하는 방식). 통짜로 대량 생성해서 덮어쓰지 말 것.
|
|
|
|
---
|
|
|
|
## 기획 문서 참조 (게임 규칙의 원본 — 코드 작성 시 이쪽을 기준으로)
|
|
|
|
- 카드 타입별 스와이프 결과, 파라미터, 의회 액션 → @docs/Project_SS_서사형_덱빌딩_게임_시스템_기획서.md
|
|
- 파벌 12종 우호도 조건, 엔딩 매트릭스, 세계관 → @docs/Project_SS_스토리_바이블_v3_0.md
|
|
- 화면 전환/분기 로직 → @docs/ProjectSS_유저플로우.md
|
|
- UI 레이아웃 → @docs/ProjectSS_텍스트_와이어프레임.md
|
|
- 컬러/타이포/햅틱 수치 → @docs/ProjectSS_디자인_토큰.md
|
|
- 요구사항 정의 → @docs/ProjectSS_PRD.md
|
|
|
|
게임 규칙 수치를 이 파일에 복사하지 말 것. 항상 원본 문서를 참조한다.
|
|
|
|
---
|
|
|
|
## 현재 Phase 상태
|
|
|
|
```
|
|
Phase 0 [x] 환경 세팅 & 아키텍처
|
|
Phase 1 [x] 코어 루프 프로토타입
|
|
Phase 2 [x] 자원 경제 & 덱빌딩
|
|
Phase 3 [x] 정치 시스템 & 스토리 페이징
|
|
Phase 4 [x] 멀티 엔딩 & 연대기 ← 그레이박스 테스트 시작 가능
|
|
Phase 5 [ ] 비주얼 폴리싱 & UX ← 그레이박스 테스트 완료 후에만 착수
|
|
```
|
|
|
|
`[x]` 완료 · `[~]` 부분 완료 · `[ ]` 미착수
|
|
|
|
**Phase 2 완료 시 남은 주의사항:** 오염 카드(신화/조직저항/사회공황/이사회압박) 콘텐츠는
|
|
등급별 1종씩만 채운 초안이다. 자세한 내용은 `ROADMAP.md` Phase 2 참고.
|
|
|
|
**Phase 3 완료 시 남은 주의사항:** 상임 이사회 8명의 투표는 아직 `성향 태그` 시스템이 없어
|
|
위험 수용 계수 기반 확률 처리로 남아있다. 자세한 내용은 `ROADMAP.md` Phase 3 참고.
|
|
|
|
**Phase 4 완료 시 남은 주의사항:** 엔딩 도감 localStorage 키를 `ss_endings_v2`로 교체했다
|
|
(기존 `ss_endings`는 제목 문자열 기반이라 취약했음). 이전 플레이테스트 기록은 새 키와
|
|
호환되지 않는다. 내러티브 태그는 재사용 가능한 태그 풀(`narrative_tags.json`, 10종) 방식으로,
|
|
선별된 카드의 좌/우 선택지에서만 얻는다. 페이즈 전환 문턱은 "고유 태그 3종/6종 획득". 자세한
|
|
내용은 `ROADMAP.md` Phase 4 참고.
|
|
|
|
**⚠️ 2026-07-09 병렬 브랜치 병합:** 이 폴더가 유일한 작업 사본이 아니라면, 작업 시작 전
|
|
`git fetch` 후 `git log origin/main..HEAD`와 `git log HEAD..origin/main`으로 분기 여부를
|
|
반드시 확인할 것. 과거에 다른 세션이 origin에 푸시한 커밋을 이 로컬이 받지 못한 채 Phase 2~4를
|
|
독립적으로 재구현해 대형 충돌이 났던 적이 있다. 자세한 경위는 `ROADMAP.md` 상단 박스 참고.
|
|
|
|
Phase 0~4 그레이박스 구간이 모두 완료됐다. 다음은 외부 플레이어 그레이박스 테스트이며,
|
|
Phase 5(비주얼 폴리싱)는 그 피드백 반영 후에만 착수한다.
|
|
|
|
로컬에 Node.js LTS가 설치되어 `npm run dev`로 실기 검증이 가능하다
|
|
(Playwright로 실제 플레이까지 확인 완료).
|
|
|
|
---
|
|
|
|
## 작업 지시 방법
|
|
|
|
```
|
|
/goal Phase 5 진행해줘 # 그레이박스 테스트 완료 후에만
|
|
```
|
|
|
|
작업 완료 후 이 파일의 **현재 Phase 상태** 블록을 업데이트한다. |