corpi/viberoom-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(docs): 문서 인덱스와 화면별 가이드 재정리

Browse Source
This commit is contained in:
corpi
2026-03-16 11:24:14 +09:00
parent 3471c96972
commit acfa8f4f48
3 changed files with 160 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/05_handoff_checklist.md
View File

@@ -4,9 +4,13 @@ Codex CLI가 중단되거나 컨텍스트가 초기화된 뒤 재개할 때 사
## 재개 시작 (5분) ## 재개 시작 (5분)
1. `docs/README.md`에서 우선 읽기 5개 문서를 순서대로 확인 1. `docs/README.md`에서 지금 작업할 화면 섹션과 우선 읽기 문서를 확인
2. `git status --short`로 작업 트리 상태 파악 2. `git status --short`로 작업 트리 상태 파악
3. `docs/90_current_state.md`의 `NEXT` 1순위부터 착수 3. `docs/work.md`와 `docs/90_current_state.md`의 현재 우선순위를 확인
4. 화면 작업이면 해당 source-of-truth spec을 추가로 읽는다
- `/app` -> `19`, `18`, `15`
- `/space` -> `10`, `11`, `13`
- `/stats` -> `14`, `15`
## 구현 중 체크 ## 구현 중 체크

131
docs/README.md
View File

@@ -1,28 +1,119 @@
# Docs Index # Docs Index
Codex CLI가 중간에 끊겨도 같은 품질로 작업을 이어가기 위한 운영 문서 모음입니다. 이 문서는 `web/docs`의 **메인 인덱스**다.
문서를 찾을 때는 항상 여기서 시작한다.
## 우선 읽기 순서 문서 상태는 3가지로 본다.
1. [work.md](./work.md) - `source-of-truth`: 현재 기획/구현의 기준 문서
2. [session_brief.md](./session_brief.md) - `ops`: 작업 운영, 핸드오프, 세션 복구용 문서
3. [90_current_state.md](./90_current_state.md) - `legacy`: 과거 맥락을 이해할 때만 보는 참고 문서
4. [context_core.md](./context_core.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)
- [work.md](./work.md)
- [workFlow.md](./workFlow.md)
- [session_brief.md](./session_brief.md)
## 운영 원칙 1. [work.md](./work.md) `source-of-truth`
2. [session_brief.md](./session_brief.md) `source-of-truth`
3. [90_current_state.md](./90_current_state.md) `source-of-truth`
4. [context_core.md](./context_core.md) `ops`
5. 이 문서에서 지금 다루는 화면 섹션 확인
- 구현 범위는 항상 UI 목업 + 더미 데이터 + 토스트 수준으로 유지한다. ## 제품 전체 기획
- `page.tsx`는 조합만 담당하고 비즈니스 로직은 `features/widgets/entities`로 이동한다.
- 작업 종료 시 `90_current_state.md`를 반드시 업데이트한다. 화면 하나가 아니라 제품 전체 방향을 볼 때 읽는다.
- 세션 복구는 `npm run session:recover`로 시작한다.
- `workFlow.md` 실행 시 기본은 `work + session_brief` 2파일만 로드한다. - [00_project_brief.md](./00_project_brief.md) `source-of-truth`
- 프로젝트 목적, 범위, 현재 제품 성격
- [12_core_loop_execution_roadmap.md](./12_core_loop_execution_roadmap.md) `source-of-truth`
- 어떤 순서로 구현할지 정리한 로드맵
- [16_product_alignment_audit_plan.md](./16_product_alignment_audit_plan.md) `source-of-truth`
- 기획-구현 불일치 점검 계획
- [17_product_alignment_findings.md](./17_product_alignment_findings.md) `source-of-truth`
- 실제 불일치 ledger
- [08_app_reframe_strategy.md](./08_app_reframe_strategy.md) `legacy`
- 초반 `/app` 방향 논의용 아이디어 문서
## 화면별 기획 문서
### `/app`
`/app` 진입 경험, paused gate, review entry를 볼 때 읽는다.
- [19_app_atmosphere_entry_spec.md](./19_app_atmosphere_entry_spec.md) `source-of-truth`
- `goal + duration + atmosphere` 중심의 새 `/app` 설계
- [18_paused_session_reentry_spec.md](./18_paused_session_reentry_spec.md) `source-of-truth`
- paused/running 상태에 따른 `/app <-> /space` 재진입 정책
- [15_app_stats_entry_flow_spec.md](./15_app_stats_entry_flow_spec.md) `source-of-truth`
- `/app -> /stats -> /app` review 진입/복귀 플로우
### `/space`
`/space` HUD, refocus, break/return, goal card를 볼 때 읽는다.
- [10_refocus_system_spec.md](./10_refocus_system_spec.md) `source-of-truth`
- pause/refocus/next-beat/goal-complete 구조
- [11_away_return_recovery_spec.md](./11_away_return_recovery_spec.md) `source-of-truth`
- away/return 감지와 복귀 UX
- [13_space_intent_card_collapsed_expanded_spec.md](./13_space_intent_card_collapsed_expanded_spec.md) `source-of-truth`
- 좌상단 목표 카드 구조
### `/stats`
review 구조와 BM 연결을 볼 때 읽는다.
- [14_weekly_review_reframe_spec.md](./14_weekly_review_reframe_spec.md) `source-of-truth`
- weekly review를 행동 시스템으로 재정의한 문서
- [15_app_stats_entry_flow_spec.md](./15_app_stats_entry_flow_spec.md) `source-of-truth`
- `/stats` 진입/복귀 플로우
## 개발 시 참고 문서
구현 규칙이나 구조를 볼 때 읽는다.
- [01_ui_guidelines.md](./01_ui_guidelines.md) `source-of-truth`
- UI 톤, CTA 위계, premium 품질 기준
- [02_arch_fsd_rules.md](./02_arch_fsd_rules.md) `source-of-truth`
- FSD/레이어 구조 규칙
- [03_routes_map.md](./03_routes_map.md) `source-of-truth`
- 라우트와 주요 화면 진입점
- [04_coding_rules.md](./04_coding_rules.md) `source-of-truth`
- 코드 작성 규칙
- [06_commit_convention.md](./06_commit_convention.md) `source-of-truth`
- 커밋 규칙
## 운영 / 핸드오프 문서
작업 재개, 세션 복구, handoff용 문서다.
- [05_handoff_checklist.md](./05_handoff_checklist.md) `ops`
- [07_session_recovery.md](./07_session_recovery.md) `ops`
- [context_core.md](./context_core.md) `ops`
- [workFlow.md](./workFlow.md) `ops`
- [work.template.md](./work.template.md) `ops`
## 실시간 상태 문서
지금 무엇을 하고 있고, 다음 작업이 무엇인지 볼 때 읽는다.
- [work.md](./work.md) `source-of-truth`
- [session_brief.md](./session_brief.md) `source-of-truth`
- [90_current_state.md](./90_current_state.md) `source-of-truth`
## 빠른 선택 가이드
- `/app`을 수정한다:
- [19_app_atmosphere_entry_spec.md](./19_app_atmosphere_entry_spec.md)
- [18_paused_session_reentry_spec.md](./18_paused_session_reentry_spec.md)
- [15_app_stats_entry_flow_spec.md](./15_app_stats_entry_flow_spec.md)
- `/space` recovery를 수정한다:
- [10_refocus_system_spec.md](./10_refocus_system_spec.md)
- [11_away_return_recovery_spec.md](./11_away_return_recovery_spec.md)
- [13_space_intent_card_collapsed_expanded_spec.md](./13_space_intent_card_collapsed_expanded_spec.md)
- `/stats`를 수정한다:
- [14_weekly_review_reframe_spec.md](./14_weekly_review_reframe_spec.md)
- [15_app_stats_entry_flow_spec.md](./15_app_stats_entry_flow_spec.md)
- 지금 다음 작업이 뭔지 본다:
- [work.md](./work.md)
- [session_brief.md](./session_brief.md)
- [90_current_state.md](./90_current_state.md)

73
docs/context_core.md
View File

@@ -1,43 +1,56 @@
# Context Core (Token-Saving) # Context Core
세션 시작 시 가장 먼저 읽는 핵심 요약본이다. 세션 시작 시 빠르게 읽는 **초단기 핵심 요약본**이다.
## 제품/범위 전체 문서 구조는 [README.md](./README.md)에서 본다.
- VibeRoom Web은 UI 목업 중심 프로젝트다. ## 제품 핵심
- 실제 기능(타이머 카운트다운, 오디오 엔진, 서버/DB)은 구현하지 않는다.
- 더미 데이터 + 토스트 + 화면 상호작용 중심으로 구현한다.
## FSD 핵심 규칙 - VibeRoom Web은 ADHD와 프리랜서를 위한 premium focus service다.
- 핵심 루프는 `commit -> enter -> immerse -> pause/return -> complete -> review`다.
- `/app`은 planning dashboard가 아니라 **entry stage**다.
- `/space`는 dashboard가 아니라 **execution sanctuary**다.
- `/stats`는 summary page가 아니라 **다음 세션 성공률을 높이는 review**다.
- `app/page.tsx`는 조합만 담당한다. ## 현재 화면 기준
- 비즈니스 로직은 `features` 또는 `entities`로 이동한다.
- UI 상태(토글/선택)만 최소 허용한다. ### `/app`
- 파일이 500줄 이상이면 분리한다.
- import 방향: - current session이 `running`이면 `/space`가 우선이다.
- current session이 `paused`이면 `/app` resume gate가 우선이다.
- no-session 상태의 source-of-truth는 `goal + duration + atmosphere` entry shell이다.
- `microStep`은 `/app`에서 입력하지 않는다.
### `/space`
- goal card는 collapsed / expanded rail 구조다.
- `pause`, `return`, `next beat`, `goal complete`는 한 번에 하나만 열린다.
- active session에서는 closure 경로가 항상 남아 있어야 한다.
### `/stats`
- review는 `snapshot / start quality / recovery quality / completion quality / carry forward` 구조다.
- primary entry는 `/app`, secondary entry는 `/space` complete 이후 setup이다.
## 구현 규칙 요약
- `page.tsx`는 조합만 담당한다.
- 레이어 규칙:
- `app -> widgets/features/entities/shared` - `app -> widgets/features/entities/shared`
- `widgets -> features/entities/shared` - `widgets -> features/entities/shared`
- `features -> entities/shared` - `features -> entities/shared`
- `entities -> shared` - `entities -> shared`
- `shared -> shared/external` - UI는 premium ambient focus 톤을 유지한다.
- 한 화면에는 primary CTA를 1개만 둔다.
## UI 핵심 규칙 ## 작업 시작 순서
- 톤: 감성/저자극, 과한 대비/강조 금지 1. [work.md](./work.md)
- CTA 위계: Primary 1개 중심, Secondary/Tertiary는 무게 낮게 2. [session_brief.md](./session_brief.md)
- 모바일은 접근성 우선, 데스크톱은 과한 풀폭 버튼 지양 3. [90_current_state.md](./90_current_state.md)
4. 지금 건드릴 화면의 source-of-truth spec
## 커밋 규칙 (요약) ## 주의
- 주제별 1커밋 - 오래된 `/app` single-goal gate 문서는 legacy다.
- 한국어 Conventional Commit - 문서가 충돌하면 [README.md](./README.md)의 `source-of-truth` 분류가 우선이다.
- 본문 형식:
- `맥락`
- `변경사항`
- `검증`
- `세션-상태 / 세션-다음 / 세션-리스크`
## 세션 복구 규칙
- 시작: `npm run session:recover`
- 상태판: `docs/90_current_state.md` 기준으로 다음 작업 결정