diff --git a/docs/05_handoff_checklist.md b/docs/05_handoff_checklist.md index f471e5c..30b206f 100644 --- a/docs/05_handoff_checklist.md +++ b/docs/05_handoff_checklist.md @@ -4,9 +4,13 @@ Codex CLI가 중단되거나 컨텍스트가 초기화된 뒤 재개할 때 사 ## 재개 시작 (5분) -1. `docs/README.md`에서 우선 읽기 5개 문서를 순서대로 확인 +1. `docs/README.md`에서 지금 작업할 화면 섹션과 우선 읽기 문서를 확인 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` ## 구현 중 체크 diff --git a/docs/README.md b/docs/README.md index 9df36f0..3ea4f7a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,28 +1,119 @@ # Docs Index -Codex CLI가 중간에 끊겨도 같은 품질로 작업을 이어가기 위한 운영 문서 모음입니다. +이 문서는 `web/docs`의 **메인 인덱스**다. +문서를 찾을 때는 항상 여기서 시작한다. -## 우선 읽기 순서 +문서 상태는 3가지로 본다. -1. [work.md](./work.md) -2. [session_brief.md](./session_brief.md) -3. [90_current_state.md](./90_current_state.md) -4. [context_core.md](./context_core.md) +- `source-of-truth`: 현재 기획/구현의 기준 문서 +- `ops`: 작업 운영, 핸드오프, 세션 복구용 문서 +- `legacy`: 과거 맥락을 이해할 때만 보는 참고 문서 -## 추가 실무 가이드 +## 가장 먼저 읽기 -- [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) diff --git a/docs/context_core.md b/docs/context_core.md index fe949d6..2366c92 100644 --- a/docs/context_core.md +++ b/docs/context_core.md @@ -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 상태(토글/선택)만 최소 허용한다. -- 파일이 500줄 이상이면 분리한다. -- import 방향: +## 현재 화면 기준 + +### `/app` + +- 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` - `widgets -> features/entities/shared` - `features -> entities/shared` - `entities -> shared` - - `shared -> shared/external` +- UI는 premium ambient focus 톤을 유지한다. +- 한 화면에는 primary CTA를 1개만 둔다. -## UI 핵심 규칙 +## 작업 시작 순서 -- 톤: 감성/저자극, 과한 대비/강조 금지 -- CTA 위계: Primary 1개 중심, Secondary/Tertiary는 무게 낮게 -- 모바일은 접근성 우선, 데스크톱은 과한 풀폭 버튼 지양 +1. [work.md](./work.md) +2. [session_brief.md](./session_brief.md) +3. [90_current_state.md](./90_current_state.md) +4. 지금 건드릴 화면의 source-of-truth spec -## 커밋 규칙 (요약) +## 주의 -- 주제별 1커밋 -- 한국어 Conventional Commit -- 본문 형식: - - `맥락` - - `변경사항` - - `검증` - - `세션-상태 / 세션-다음 / 세션-리스크` - -## 세션 복구 규칙 - -- 시작: `npm run session:recover` -- 상태판: `docs/90_current_state.md` 기준으로 다음 작업 결정 +- 오래된 `/app` single-goal gate 문서는 legacy다. +- 문서가 충돌하면 [README.md](./README.md)의 `source-of-truth` 분류가 우선이다.