# Project SS — CLAUDE.md

> **위치:** repo root (`ProjectSS/CLAUDE.md`) — Claude Code는 root에서 실행한다.
> **이 파일의 역할:** 규칙만 담는다. 작업 이력·진행 상황은 `docs/DEVLOG.md`, 구현 로드맵은
> `docs/ProjectSS_코어시스템_기획서.md` §17.
> **상위 규칙:** 전역 정체성·개발 철학은 `~/.hermes/SOUL.md`, 프로젝트 정체성은 `AGENTS.md`에 있다.
> 이 파일은 그 위에 얹히는 **코드 레벨 규칙**만 다룬다.

---

## 작업 시작 전 체크

**⚠️ 병렬 브랜치 확인 (필수)**
이 폴더가 유일한 작업 사본이 아니라면, 작업 시작 전 반드시:

```bash
git fetch
git log origin/main..HEAD   # 내가 안 올린 커밋
git log HEAD..origin/main   # 내가 안 받은 커밋
```

과거에 다른 세션이 origin에 푸시한 커밋을 로컬이 받지 못한 채 Phase 2~4를 독립적으로
재구현해 대형 충돌이 난 적이 있다. 경위는 `ROADMAP.md` 상단 박스 참고.

---

## 코드 컨벤션

- 신규 개발은 `client/src/core/` 아래에 있다 (`engine/`은 React 의존 없는 순수 로직, `components/`는 UI).
  기존 `client/src/components/`·`client/src/engine/`(구 GameScreen.jsx 중심 구조)는 참조용으로만
  남아있고 더 이상 진입점(`App.jsx`)에서 쓰이지 않는다. 코드 구조는 게임 규칙과 함께 계속
  바뀌는 중이라 별도 아키텍처 문서를 두지 않는다 — 구 `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의 "완성도보다 검증 속도 우선"은 **코드**에 적용된다.
> 데이터(카드 텍스트·밸런스)는 예외로, 디자이너가 직접 검토할 수 있는 속도로 제안한다.

---

## 기획 문서 참조 (게임 규칙의 원본)

코드 작성 시 항상 원본 문서를 기준으로 한다. **게임 규칙 수치를 이 파일에 복사하지 말 것.**

예전에 흩어져 있던 기획 문서 7종(서사형 덱빌딩 시스템 기획서·스토리 바이블·유저플로우·
텍스트 와이어프레임·디자인 토큰·PRD·architecture_design)은 전부 아래 한 문서로 통합됐다.
`docs/` 안에 옛 문서가 남아 보이더라도 참조하지 말 것 — 이제 유일한 원본은 이것뿐이다.

- 게임 규칙·수치·화면 흐름·UI 레이아웃·요구사항 전부 → @docs/ProjectSS_코어시스템_기획서.md
  - 기호 체계(축·등급) → §3 · 책상·페널티(주목도) → §4 · 합본(족보) → §5
  - 파라미터(4대 게이지) → §6 · 명분 → §7 · 경제(상점) → §8
  - 의회(규약·실적감사·13인 위원회) → §9 · 자산 → §10 · 전례(내러티브 태그) → §11
  - 노선 → §13 · 엔딩 → §15 · 텍스트 스타일 가이드 → §16
  - **구현 우선순위·진행 상황(로드맵) → §17** — Phase 계획을 대신한다, 아래 참고

---

## 구현 진행 상황

진행 체크박스를 이 파일에 복제하지 않는다 — 여러 곳에서 따로 갱신하면 어긋나기 쉽다.
`ProjectSS_코어시스템_기획서.md` **§17 "구현 우선순위"** 안의 체크박스가 유일한 진행 상황
원본이다. 지금 뭐가 됐고 안 됐는지 보려면 그 절을 열어볼 것.

각 항목에서 남은 주의사항과 상세 작업 이력은 `docs/DEVLOG.md` 참고. 왜 그렇게 결정했는지는
DEVLOG에서 링크된 결정 노트(아래 "결정 노트" 절) 참고.

---

## 작업 지시 방법

```
/goal 구현 우선순위 3차 진행해줘     # ProjectSS_코어시스템_기획서.md §17 기준
```

**작업 완료 후 반드시:**
1. `ProjectSS_코어시스템_기획서.md` **§17**의 해당 항목 체크박스를 갱신한다.
2. `docs/DEVLOG.md` 맨 위에 무엇을 왜 바꿨는지 기록한다.
   (미해결 이슈나 디자이너 확인이 필요한 사항이 생겼으면 DEVLOG 상단 "열린 이슈"에 추가)
3. 중요한 설계·밸런스 결정을 내렸다면 결정 노트를 남긴다 — 아래 "결정 노트" 절 참고.

---

## 결정 노트 (Decision Notes)

중요한 설계·밸런스 결정을 내렸을 때는 `docs/decisions/YYYY-MM-DD-제목.md` 파일로 따로 남긴다.
"중요한 결정"이란 나중에 왜 이렇게 했는지 되짚어야 할 만한 것 — 여러 대안 중 하나를 고른 경우,
기존 규칙을 뒤집은 경우, 플레이테스트 피드백에 따라 방향을 바꾼 경우 등이다. 사소한 오타 수정이나
명백한 버그 픽스에는 필요 없다.

**양식** (`T-decision.md` 그대로 — 새 결정 노트는 전부 이 형식을 따른다):

```markdown
---
created: YYYY-MM-DD
---
%% 파일명: YYYY-MM-DD-제목. 규칙 문서엔 규칙만, 이유는 여기에 %%

## 결정
- 

## 배경
- 

## 검토했으나 기각한 대안
- **대안:** 기각 이유

## 재검토 조건
- 
```

**DEVLOG 연동:** `docs/DEVLOG.md`에 작업 항목을 적을 때, 그 작업에 해당하는 결정 노트가 있으면
옵시디언 위키링크로 연결한다 — `[[YYYY-MM-DD-제목]]`. DEVLOG는 "무엇을 했다"는 요약만 담고,
"왜 그렇게 했는가"의 자세한 내용은 링크를 눌러 결정 노트에서 확인하는 구조다.