kyoung5seo
8833e52fab
파일 역할 분담 개선
ProjectSS/
├── CLAUDE.md ← 규칙 (거의 안 변함) · Claude Code용
├── AGENTS.md ← 프로젝트 정체성 (거의 안 변함) · Hermes용
├── ROADMAP.md ← Phase별 계획·완료 기준 (기존 그대로)
└── docs/
└── DEVLOG.md ← 신규: 날짜별 작업 이력 + 미해결 이슈
110 lines
5.3 KiB
Markdown
110 lines
5.3 KiB
Markdown
# Project SS — CLAUDE.md
|
||
|
||
> **위치:** repo root (`ProjectSS/CLAUDE.md`) — Claude Code는 root에서 실행한다.
|
||
> **이 파일의 역할:** 규칙만 담는다. 작업 이력·진행 상황은 `docs/DEVLOG.md`, Phase 계획은 `ROADMAP.md`.
|
||
> **상위 규칙:** 전역 정체성·개발 철학은 `~/.hermes/SOUL.md`, 프로젝트 정체성은 `AGENTS.md`에 있다.
|
||
> 이 파일은 그 위에 얹히는 **코드 레벨 규칙**만 다룬다.
|
||
|
||
---
|
||
|
||
## 작업 시작 전 체크
|
||
|
||
**⚠️ 병렬 브랜치 확인 (필수)**
|
||
이 폴더가 유일한 작업 사본이 아니라면, 작업 시작 전 반드시:
|
||
|
||
```bash
|
||
git fetch
|
||
git log origin/main..HEAD # 내가 안 올린 커밋
|
||
git log HEAD..origin/main # 내가 안 받은 커밋
|
||
```
|
||
|
||
과거에 다른 세션이 origin에 푸시한 커밋을 로컬이 받지 못한 채 Phase 2~4를 독립적으로
|
||
재구현해 대형 충돌이 난 적이 있다. 경위는 `ROADMAP.md` 상단 박스 참고.
|
||
|
||
---
|
||
|
||
## 코드 컨벤션
|
||
|
||
- 전체 구조·아키텍처 원칙(상태 배치, `engine/` 경계, world 스냅샷 패턴) → @docs/architecture_design.md
|
||
- 실제 앱은 `client/` 안에 있음. npm 명령은 `cd client` 후 실행.
|
||
- 로컬에 Node.js LTS 설치되어 `npm run dev`로 실기 검증 가능 (Playwright 플레이 확인까지 완료).
|
||
- 플레이테스트는 리포 루트의 `playtest.bat` 더블클릭 (dev 서버 + 브라우저 자동 오픈).
|
||
파일명은 ASCII만 사용 — 한글/`chcp`를 넣으면 cmd.exe가 배치 파싱을 깨뜨린다(과거에 겪음).
|
||
- 스타일: 컴포넌트별 개별 `.css` (글로벌 클래스, CSS Modules 아님)
|
||
- 상태관리: `useState` / `useReducer`만 사용. 외부 상태관리 라이브러리 도입 금지.
|
||
- 영구 저장: `localStorage` (도감 엔딩 저장 용도)
|
||
- 카드 데이터는 `client/src/data/cards.csv`를 papaparse로 런타임 파싱함
|
||
- `GameScreen.jsx`에 상태가 집중되어 있음 — 수정 시 주의, 리팩토링 필요 가능성
|
||
- 오염 카드 주입은 반드시 `client/src/engine/pollution.js`의 `previewPollution()`을 경유한다.
|
||
예고·주입·사후 알림이 이 단일 기준을 공유하므로, 우회해서 오염 카드를 만들지 말 것.
|
||
튜닝 수치는 `pollution.js` 상단 상수 블록에 모여 있다.
|
||
|
||
---
|
||
|
||
## ⛔ 보호 파일 (직접 수정/실행 금지 — 변경 제안은 가능)
|
||
|
||
- `client/update_csv.js` — cards.csv 전처리 스크립트
|
||
- `client/update_csv_tags.js` — 내러티브 태그 매핑 스크립트
|
||
|
||
**이유:** 두 스크립트의 출력 포맷이 바뀌면 이를 읽는 게임 코드(papaparse 파싱)가 깨지거나
|
||
데이터를 잘못 읽을 수 있다.
|
||
|
||
**규칙:** 직접 고쳐서 실행하지 말 것. 스키마 변경이 실제로 필요하면(예: 새 컬럼/태그 카테고리 추가)
|
||
어떤 변경이 왜 필요한지 설명하고 변경안(diff)을 먼저 보여준 뒤 승인을 받고 적용할 것.
|
||
|
||
## 데이터 파일 다루는 법
|
||
|
||
`cards.csv` / `narrative_tags.json` 등 **데이터 내용**(카드 텍스트, 수치, 태그)은 자유롭게 다뤄도 된다.
|
||
단, 이 게임은 카드 밸런스와 스토리 개연성이 핵심이므로:
|
||
|
||
- 자동 생성으로 일괄 채우지 말 것
|
||
- 몇 개씩 초안을 보여주고 피드백을 받아 반영하는 방식으로 진행
|
||
- 통짜로 대량 생성해서 덮어쓰지 말 것
|
||
|
||
> ℹ️ SOUL.md의 "완성도보다 검증 속도 우선"은 **코드**에 적용된다.
|
||
> 데이터(카드 텍스트·밸런스)는 예외로, 디자이너가 직접 검토할 수 있는 속도로 제안한다.
|
||
|
||
---
|
||
|
||
## 기획 문서 참조 (게임 규칙의 원본)
|
||
|
||
코드 작성 시 항상 원본 문서를 기준으로 한다. **게임 규칙 수치를 이 파일에 복사하지 말 것.**
|
||
|
||
- 카드 타입별 스와이프 결과, 파라미터, 의회 액션 → @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 5 착수 조건:** 외부 플레이어 그레이박스 테스트를 마치고 그 피드백을 반영한 뒤에만 시작한다.
|
||
Phase별 상세 계획과 완료 기준은 `ROADMAP.md`, 각 Phase에서 남은 주의사항과 작업 이력은
|
||
`docs/DEVLOG.md` 참고.
|
||
|
||
---
|
||
|
||
## 작업 지시 방법
|
||
|
||
```
|
||
/goal Phase 5 진행해줘 # 그레이박스 테스트 완료 후에만
|
||
```
|
||
|
||
**작업 완료 후 반드시:**
|
||
1. 위 **Phase 진행 순서** 블록의 체크박스를 갱신한다.
|
||
2. `docs/DEVLOG.md` 맨 위에 무엇을 왜 바꿨는지 기록한다.
|
||
(미해결 이슈나 디자이너 확인이 필요한 사항이 생겼으면 DEVLOG 상단 "열린 이슈"에 추가) |