docs(session): add restart-safe recovery workflow

Context: - codex cli 중단 후에도 작업 품질과 맥락을 안정적으로 복구하기 위해 Changes: - docs/00~07, 90 문서 세트 추가/정리 - commit convention 문서 및 .gitmessage-session.txt 템플릿 추가 - scripts/session/recover-context.sh 추가 - package.json에 session:recover 스크립트 추가 Validation: - npm run session:recover Session-State: session recovery docs, template, and script are in place Session-Next: apply this commit format to feature and refactor commits Session-Risks: legacy commits before this change do not include session trailers
2026-02-27 13:27:20 +09:00
parent d2be0b866a
commit ecb17a485a
14 changed files with 519 additions and 1 deletions
--- a/docs/00_project_brief.md
+++ b/docs/00_project_brief.md
@@ -0,0 +1,44 @@
+# 00. Project Brief
+
+## 프로젝트 목적
+
+VibeRoom Web은 몰입 공간 경험을 빠르게 실험하기 위한 프론트엔드 목업 프로젝트다.  
+핵심 목표는 실제 기능 완성보다 UX 흐름, 화면 구조, 상호작용 톤을 안정적으로 검증하는 것이다.
+
+## 기술 스택
+
+- Next.js (App Router)
+- TypeScript
+- TailwindCSS
+- 상태: React state + 일부 Zustand
+
+## 유지보수 역할 정의
+
+이 프로젝트에서 엔지니어의 역할:
+
+- FSD 구조를 지키며 화면/기능을 지속적으로 리팩터링한다.
+- View 계층을 조합 중심으로 유지하고 로직이 새지 않게 막는다.
+- 감성/저자극 톤을 유지하며 과한 강조 UI를 억제한다.
+- 실제 서비스 로직은 구현하지 않고, 더미 데이터와 토스트로 흐름만 검증한다.
+
+## 범위와 비범위
+
+범위:
+
+- 라우트/위젯/피처 단위 UI 개선
+- 더미 데이터 기반 상태 표현
+- 모달, 토글, 탭, 선택, 토스트
+
+비범위:
+
+- 실시간 인원수/presence 정확도 보장
+- 타이머 카운트다운 실제 동작
+- 오디오 재생 엔진
+- 서버/DB/API 연동 완성
+
+## Definition of Done
+
+- 요구사항 화면이 동작하고, 기존 톤과 충돌하지 않는다.
+- FSD, 뷰 무로직, 500줄 분리 규칙을 지킨다.
+- `/app`, `/space` 등 관련 라우트에서 UX 흐름이 깨지지 않는다.
+- `docs/90_current_state.md`에 DONE/NEXT/RISKS/CHANGED FILES가 갱신된다.
--- a/docs/01_ui_guidelines.md
+++ b/docs/01_ui_guidelines.md
@@ -0,0 +1,38 @@
+# 01. UI Guidelines
+
+## 디자인 톤
+
+- 기본 톤: 감성, 저자극, 차분함
+- 금지 톤: 과한 대비, 과한 번쩍임, 과도한 채도, 공격적인 카피
+- CTA는 명확하되 조용한 위계로 구성한다.
+
+## 컬러/표현 원칙
+
+- 다크 + 글래스 분위기를 유지한다.
+- 포인트 색상은 1차 액션에만 제한적으로 사용한다.
+- 2차/3차 액션은 outline/ghost/텍스트 링크로 무게를 낮춘다.
+
+## CTA 위계 규칙
+
+- Primary: 사용자 목표를 즉시 달성하는 액션 1개만 강조
+- Secondary: 대안 액션, 가시성은 유지하되 무게는 낮춤
+- Tertiary: 텍스트 링크 또는 작은 아이콘 액션
+- 데스크탑에서는 불필요한 풀폭 CTA를 지양한다.
+
+## 반응형 규칙
+
+- 모바일: 터치 우선, 충분한 높이/패딩, 필요 시 풀폭 CTA 허용
+- 데스크탑: 내용폭 기반 컴팩트 CTA 그룹 권장
+- 텍스트 길이에 따라 버튼 폭이 과도하게 늘어나지 않게 `min-w + px`를 사용
+
+## 마이크로카피 규칙
+
+- 실시간/확정처럼 보이는 문구를 신중히 사용한다.
+- 초기 데이터가 비어도 어색하지 않은 카피를 기본값으로 사용한다.
+- 숫자 기반 과장 표현보다 분위기/큐레이션 중심 문구를 우선한다.
+
+## 접근성/상호작용
+
+- 아이콘 버튼은 `sr-only` 텍스트를 제공한다.
+- 포커스 링을 유지한다.
+- 실제 미구현 기능은 토스트로 피드백하되, 실제 동작처럼 오해되지 않게 `(더미)`를 명시한다.
--- a/docs/02_arch_fsd_rules.md
+++ b/docs/02_arch_fsd_rules.md
@@ -0,0 +1,51 @@
+# 02. Architecture & FSD Rules
+
+## 레이어 구조
+
+```text
+src/
+  app/       # 라우트 진입점, 조합 전용
+  widgets/   # 화면 섹션 단위 조합
+  features/  # 사용자 액션/유즈케이스 단위
+  entities/  # 도메인 타입/더미 데이터
+  shared/    # 공용 UI/유틸
+  store/     # 전역 상태(필요 최소)
+```
+
+## 핵심 규칙
+
+1. `page.tsx`는 조합만 수행한다.
+2. 비즈니스 로직은 `features` 또는 `entities`로 이동한다.
+3. UI 상태(토글/선택)만 컴포넌트 내부에서 최소 허용한다.
+4. 파일 길이 500줄 이상이면 즉시 분리한다.
+5. 하위 레이어가 상위 레이어를 import하지 않는다.
+
+## Import 방향 규칙
+
+- `app` -> `widgets`, `features`, `entities`, `shared`
+- `widgets` -> `features`, `entities`, `shared`
+- `features` -> `entities`, `shared`
+- `entities` -> `shared`
+- `shared` -> 외부 의존성 또는 `shared` 내부
+
+금지:
+
+- `features` -> 다른 `features` 직접 참조 (강한 결합 유발)
+- `shared` -> `entities/features/widgets/app` 참조
+- `page.tsx`에 도메인 로직/세부 UI 구현 누적
+
+## 구현 정책 (이 프로젝트 전용)
+
+- 실제 타이머/오디오/서버/DB 기능은 구현하지 않는다.
+- 기능 트리거는 토스트 또는 더미 상태 전환으로 표현한다.
+- 도메인 표시는 `entities` 데이터에서 읽고 뷰 하드코딩을 지양한다.
+
+## 파일 분리 기준
+
+- 조건:
+  - 파일 500줄 이상
+  - 하나의 파일에 2개 이상의 독립 관심사가 혼재
+- 분리 대상 예시:
+  - UI 파트 -> `ui/*`
+  - 상태/핸들러 -> `model/*`
+  - 타입 -> `model/types.ts`
--- a/docs/03_routes_map.md
+++ b/docs/03_routes_map.md
@@ -0,0 +1,46 @@
+# 03. Routes Map
+
+## 라우트 개요
+
+- `/` -> `src/app/(landing)/page.tsx`
+- `/login` -> `src/app/(auth)/login/page.tsx`
+- `/app` -> `src/app/(app)/app/page.tsx`
+- `/space` -> `src/app/(app)/space/page.tsx`
+- `/stats` -> `src/app/(app)/stats/page.tsx`
+- `/settings` -> `src/app/(app)/settings/page.tsx`
+
+## 주요 라우트 조합
+
+### `/app` (허브)
+
+- Page: `src/app/(app)/app/page.tsx`
+- Core Widget: `src/widgets/app-hub/ui/AppHubWidget.tsx`
+- 주요 구성:
+  - `StartRitualWidget`
+  - `RoomsGalleryWidget`
+  - `CustomEntryWidget`
+- 데이터 소스:
+  - room 목록: `entities/room`
+  - 목표/타이머/사운드 프리셋: `entities/session`
+
+### `/space` (집중 화면)
+
+- Page: `src/app/(app)/space/page.tsx`
+- Core Widget: `src/widgets/space-shell/ui/SpaceSkeletonWidget.tsx`
+- 주요 구성:
+  - `SpaceTimerHudWidget`
+  - `SpaceToolsDockWidget`
+  - `features/restart-30s` (HUD 내 조합)
+
+## `/space` 쿼리 파라미터
+
+- `room`: 공간 id
+- `sound`: 사운드 preset id
+- `timer`: 타이머 라벨
+- `goal`: 목표 한 줄 (선택)
+
+## 변경 시 체크포인트
+
+- 라우팅 변경 시 `/app -> /space` 진입 흐름이 깨지지 않는지 확인
+- query param 기본값 처리 유지
+- page 파일에 로직 누수 여부 확인
--- a/docs/04_coding_rules.md
+++ b/docs/04_coding_rules.md
@@ -0,0 +1,34 @@
+# 04. Coding Rules
+
+## 공통 코딩 규칙
+
+- TypeScript 타입을 명시하고 `any`를 피한다.
+- 명확한 이름 사용:
+  - 핸들러: `handle*`
+  - 훅: `use*`
+  - UI 컴포넌트: 역할이 드러나는 `*Widget`, `*Panel`, `*Card`
+- 중복 스타일 문자열은 공용 컴포넌트/유틸로 흡수한다.
+
+## React/Next 규칙
+
+- 클라이언트 컴포넌트는 필요한 곳에만 `'use client'` 선언
+- page는 조합 전용, 세부 구현은 widgets/features로 이동
+- URL 파라미터/검색 파라미터 파싱은 widget/model 레이어에서 처리
+
+## Tailwind 규칙
+
+- 하드코딩 hex 남발 금지
+- 클래스 길이가 길어지는 경우 의미 단위로 줄바꿈
+- hover/focus 상태는 기본 접근성 스타일과 함께 제공
+
+## 더미 기능 정책
+
+- 미구현 기능 트리거는 토스트로 피드백한다.
+- 토스트 제목에 `(더미)` 또는 설명으로 mock 상태를 명확히 전달한다.
+- 실데이터처럼 오해될 수 있는 숫자/실시간 문구 사용을 지양한다.
+
+## 검증 절차
+
+- 타입체크: `npx tsc --noEmit`
+- 빌드: `npm run build`
+- lint는 플러그인 누락 이슈가 있을 수 있으니 환경 상태를 먼저 확인한다.
--- a/docs/05_handoff_checklist.md
+++ b/docs/05_handoff_checklist.md
@@ -0,0 +1,32 @@
+# 05. Handoff Checklist
+
+Codex CLI가 중단되거나 컨텍스트가 초기화된 뒤 재개할 때 사용하는 체크리스트.
+
+## 재개 시작 (5분)
+
+1. `docs/README.md`에서 우선 읽기 5개 문서를 순서대로 확인
+2. `git status --short`로 작업 트리 상태 파악
+3. `docs/90_current_state.md`의 `NEXT` 1순위부터 착수
+
+## 구현 중 체크
+
+1. 뷰 로직 누수 여부 확인 (`page.tsx` 조합 유지)
+2. 레이어 import 방향 위반 여부 점검
+3. 파일 500줄 초과 여부 점검
+4. UI 톤(감성/저자극)과 CTA 위계 유지 확인
+
+## 종료 전 체크
+
+1. 타입체크 또는 빌드 최소 1회 실행
+2. 변경 파일 경로/의도 요약 정리
+3. `docs/90_current_state.md` 갱신:
+   - DONE
+   - NEXT
+   - RISKS
+   - CHANGED FILES
+
+## 커밋 단위 가이드
+
+- 1커밋 1의도 원칙
+- 구조 변경(FSD)과 스타일 변경(UI)은 가능하면 분리
+- 커밋 메시지는 "무엇을 왜 바꿨는지" 중심으로 작성
--- a/docs/06_commit_convention.md
+++ b/docs/06_commit_convention.md
@@ -0,0 +1,49 @@
+# 06. Commit Convention
+
+## 목적
+
+세션이 끊겨도 커밋 이력만으로 복구 가능하도록, 메시지를 사람이 읽기 쉬우면서 기계적으로도 파싱 가능한 형태로 통일한다.
+
+## 기본 형식 (Conventional Commits)
+
+```text
+<type>(<scope>): <summary>
+```
+
+예시:
+
+- `feat(app-hub): compact CTA layout for desktop`
+- `refactor(room): replace member count with vibe metadata`
+- `docs(session): add recovery playbook and state template`
+
+## type 규칙
+
+- `feat`: 사용자 가시 기능 추가/변경
+- `fix`: 버그 수정
+- `refactor`: 동작 동일한 구조 개선
+- `style`: UI 스타일/카피 조정
+- `docs`: 문서 추가/수정
+- `chore`: 설정/스크립트/의존성 정리
+
+## 권장 본문 템플릿
+
+```text
+Context:
+- 왜 이 변경이 필요한지
+
+Changes:
+- 실제 변경 사항
+
+Validation:
+- 실행한 검증 (예: npx tsc --noEmit)
+
+Session-State: <현재 상태 한 줄>
+Session-Next: <다음 우선순위 한 줄>
+Session-Risks: <남은 리스크 한 줄>
+```
+
+## 커밋 크기 규칙
+
+- 1커밋 1의도 원칙
+- 화면 변경과 구조 변경이 모두 크면 분리 커밋
+- 대규모 리팩터링은 중간 checkpoint 커밋을 남긴다
--- a/docs/07_session_recovery.md
+++ b/docs/07_session_recovery.md
@@ -0,0 +1,41 @@
+# 07. Session Recovery
+
+## 결론
+
+커밋 이력 기반 복구는 가능하다.  
+다만 커밋만 의존하면 "왜/다음 할 일/리스크"가 누락되기 쉬우므로 아래 하이브리드 방식을 기본으로 쓴다.
+
+## 권장 방식 (Hybrid)
+
+1. 커밋 메시지: Conventional + Session trailer
+2. 상태판: `docs/90_current_state.md` 유지
+3. 복구 커맨드: `npm run session:recover`
+
+이 3가지를 함께 쓰면, 새 세션에서 3~5분 안에 맥락 복구가 가능하다.
+
+## 복구 절차
+
+1. `npm run session:recover`
+2. `docs/90_current_state.md`의 `NEXT` 1순위 확인
+3. `git show <최근 커밋>`로 세부 diff 확인
+
+## 커밋 예시
+
+```text
+docs(session): add recovery workflow and commit template
+
+Context:
+- codex cli 중단 시 작업 맥락 손실을 줄이기 위해
+
+Changes:
+- docs/06_commit_convention.md 추가
+- docs/07_session_recovery.md 추가
+- scripts/session/recover-context.sh 추가
+
+Validation:
+- bash scripts/session/recover-context.sh
+
+Session-State: recovery docs and script are in place
+Session-Next: apply workflow to next feature commit
+Session-Risks: legacy commits have no trailers
+```
--- a/docs/90_current_state.md
+++ b/docs/90_current_state.md
@@ -0,0 +1,55 @@
+# 90. Current State
+
+Last Updated: 2026-02-27
+
+## DONE
+
+- 세션 복구 운영 문서 추가:
+  - `docs/06_commit_convention.md`
+  - `docs/07_session_recovery.md`
+- 복구 스크립트 추가:
+  - `scripts/session/recover-context.sh`
+- `npm run session:recover` 명령 추가
+- `/app` Start Ritual에서 절차감을 높이던 `건너뛰기` 제거
+- `/app`에서 `다시 시작(30초)` 제거
+- `/space` HUD에 `features/restart-30s` 기반 `↻ 다시 시작 + 30초 배지` 추가
+- `/app` 룸 카드의 인원수 기반 정보 제거
+- `entities/room`에 분위기/추천 필드 추가:
+  - `recommendedSound`
+  - `recommendedTime`
+  - `vibeLabel`
+- 룸 카드 정보 표현을 큐레이션 중심으로 전환
+
+## NEXT
+
+1. `/space` 상단 카피의 인원수 문구(`현재 n명`)를 분위기형 문구로 전환
+2. `RoomSheetWidget`/도크 패널의 인원수 기반 UI를 큐레이션형 정보로 재정의할지 정책 확정
+
+## RISKS
+
+- `npm run build`는 네트워크 제한 시 Google Font fetch 실패 가능
+- 현재 워크트리는 다수 파일이 수정/추가된 상태라 커밋 단위 분리가 중요
+- 일부 문구가 여전히 실시간 지표처럼 읽힐 수 있으므로 카피 가이드 지속 점검 필요
+
+## CHANGED FILES
+
+- `docs/06_commit_convention.md`
+- `docs/07_session_recovery.md`
+- `.gitmessage-session.txt`
+- `scripts/session/recover-context.sh`
+- `package.json`
+- `src/widgets/start-ritual-widget/ui/StartRitualWidget.tsx`
+- `src/widgets/app-hub/ui/AppHubWidget.tsx`
+- `src/entities/room/model/types.ts`
+- `src/entities/room/model/rooms.ts`
+- `src/features/room-select/ui/RoomPreviewCard.tsx`
+- `src/features/restart-30s/index.ts`
+- `src/features/restart-30s/model/useRestart30s.ts`
+- `src/features/restart-30s/ui/Restart30sAction.tsx`
+- `src/widgets/space-timer-hud/ui/SpaceTimerHudWidget.tsx`
+
+## QUICK VERIFY
+
+1. `/app`: 건너뛰기/다시 시작 노출 없음
+2. `/app`: 룸 카드에 사람 수 문구 없음, 추천 정보 노출
+3. `/space`: HUD 근처 `↻ 다시 시작` 클릭 시 토스트 노출
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,25 @@
+# Docs Index
+
+Codex CLI가 중간에 끊겨도 같은 품질로 작업을 이어가기 위한 운영 문서 모음입니다.
+
+## 우선 읽기 순서
+
+1. [00_project_brief.md](./00_project_brief.md)
+2. [01_ui_guidelines.md](./01_ui_guidelines.md)
+3. [02_arch_fsd_rules.md](./02_arch_fsd_rules.md)
+4. [03_routes_map.md](./03_routes_map.md)
+5. [90_current_state.md](./90_current_state.md)
+
+## 추가 실무 가이드
+
+- [04_coding_rules.md](./04_coding_rules.md)
+- [05_handoff_checklist.md](./05_handoff_checklist.md)
+- [06_commit_convention.md](./06_commit_convention.md)
+- [07_session_recovery.md](./07_session_recovery.md)
+
+## 운영 원칙
+
+- 구현 범위는 항상 UI 목업 + 더미 데이터 + 토스트 수준으로 유지한다.
+- `page.tsx`는 조합만 담당하고 비즈니스 로직은 `features/widgets/entities`로 이동한다.
+- 작업 종료 시 `90_current_state.md`를 반드시 업데이트한다.
+- 세션 복구는 `npm run session:recover`로 시작한다.
--- a/docs/skills/continue.md
+++ b/docs/skills/continue.md
@@ -0,0 +1,34 @@
+너는 이 레포의 유지보수 엔지니어다. 세션 컨텍스트는 없다고 가정하고, 레포 안의 문서를 “유일한 컨텍스트”로 사용해 작업을 이어간다.
+
+[Step 0: 컨텍스트 로드]
+아래 파일을 먼저 읽고, 핵심 규칙/현재 상태/다음 작업을 10줄 내로 요약해라.
+
+- docs/00_project_brief.md
+- docs/01_ui_guidelines.md
+- docs/02_arch_fsd_rules.md
+- docs/03_routes_map.md
+- docs/04_coding_rules.md
+- docs/05_handoff_checklist.md
+- docs/06_commit_convention.md
+- docs/07_session_recovery.md
+- docs/90_current_state.md
+
+[Step 1: 현재 상태 점검]
+
+- 현재 브랜치/변경사항(git status) 확인
+- 관련 라우트(/app, /space)에서 최근 변경된 파일을 찾아라
+- FSD 규칙 위반(뷰 로직, 500줄 초과, 레이어 침범)이 있는지 빠르게 점검해라
+
+[Step 2: 다음 작업 실행]
+docs/90_current_state.md의 “NEXT” 섹션에 적힌 우선순위 1번 작업을 수행해라.
+
+- 실제 비즈니스 기능 구현 금지(UI 목업 + 더미 + 토스트만)
+- View는 조합만, 로직은 features/widgets/entities로 이동
+- 파일 500줄 넘으면 분리
+
+[Step 3: 작업 종료 정리(필수)]
+
+- docs/90_current_state.md를 업데이트해라:
+  - DONE / NEXT / RISKS / CHANGED FILES
+- 필요하면 docs/01_ui_guidelines.md 또는 docs/02_arch_fsd_rules.md에 결정사항을 추가해라
+- 변경사항이 합리적인 단위로 커밋될 수 있도록 커밋 메시지 초안을 제안해라