From d2cb1c01665fbb9cf81656e8ef1e2f3e228a009f Mon Sep 17 00:00:00 2001 From: yunchan8804 Date: Sat, 11 Apr 2026 01:25:22 +0900 Subject: [PATCH] =?UTF-8?q?chore:=20session=20handoff=20=EC=A4=80=EB=B9=84?= =?UTF-8?q?=20=E2=80=94=20Mac=20=EC=9D=B4=EC=96=B4=EB=B0=9B=EA=B8=B0=20?= =?UTF-8?q?=EB=8B=A8=EC=84=9C=20=EB=AC=B8=EC=84=9C=20+=20/session-handoff?= =?UTF-8?q?=20=EC=8A=A4=ED=82=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - memory/handoff-latest.md: 5차 사이클 스냅샷 (마지막 커밋, 한 일, 미완, Mac 셋업 체크리스트, 환경 차이, 의존성 버전, 검증 상태, 누적 통계, 참고 문서 링크) - memory/handoff-archive/ 디렉토리 생성 - .claude/skills/session-handoff/SKILL.md: save/resume 2모드 스킬 - save: git clean 확인 → 스냅샷 수집 → handoff-latest.md 작성 → 아카이브 → push - resume: git pull → 필수 문서 로드 → 환경 검증 → sanity build → 요약 보고 Mac에서 재개할 때: /session-handoff resume 실행 --- .claude/skills/session-handoff/SKILL.md | 210 ++++++++++++++++++++++++ memory/handoff-latest.md | 173 +++++++++++++++++++ 2 files changed, 383 insertions(+) create mode 100644 .claude/skills/session-handoff/SKILL.md create mode 100644 memory/handoff-latest.md diff --git a/.claude/skills/session-handoff/SKILL.md b/.claude/skills/session-handoff/SKILL.md new file mode 100644 index 0000000..ab54c9a --- /dev/null +++ b/.claude/skills/session-handoff/SKILL.md @@ -0,0 +1,210 @@ +--- +name: session-handoff +description: Windows ↔ Mac ↔ CI 간 세션 핸드오프 — Claude 세션을 넘기거나 이어받을 때 상태를 정렬하고 단서를 모은다. 인자로 "save" 또는 "resume" 전달. +argument-hint: "[save | resume]" +allowed-tools: Read Write Edit Bash Glob Grep +--- + +# Session Handoff + +다른 머신(Windows→Mac, Mac→Windows, CI 등)에서 Claude 세션을 **바로 이어받을 수 있도록** 상태를 저장/복원하는 하네스 명령. + +## 사용법 + +``` +/session-handoff save # 현재 기기에서 다른 기기로 넘기기 전에 실행 +/session-handoff resume # 다른 기기에서 작업 재개할 때 가장 먼저 실행 +``` + +## 0. 공통: 상태 파일 위치 + +``` +memory/ + project_status.md # 상시 갱신되는 프로젝트 현황 (SSOT) + handoff-latest.md # 가장 최근 핸드오프 세션 스냅샷 + handoff-archive/ # 과거 핸드오프 아카이브 (YYYY-MM-DD-HHMM.md) +CLAUDE.md # 프로젝트 컨벤션/규칙 +docs/v2/ # V2 페이즈 설계서 +``` + +--- + +## SAVE 모드 (`/session-handoff save`) + +**목적**: 현재 세션에서 한 일을 다른 기기로 넘기기 위해 단서를 응축해서 저장. + +### 1. 사전 조건 +- Git working tree가 clean (커밋되지 않은 변경 없음) — 아니면 커밋 유도 +- `memory/project_status.md`가 최신 상태 반영 — 안 되어 있으면 먼저 갱신 + +### 2. 스냅샷 수집 + +다음을 모두 조사: + +```bash +git status --porcelain +git log --oneline -20 +git remote -v +git rev-parse HEAD +git branch --show-current +``` + +추가로: +- 최근 5개 커밋의 상세 diff 요약 +- 현재 실행 중인 dev/build 태스크가 있는지 (있으면 종료) +- `node_modules` 설치 여부 (package-lock.json hash) +- 방금 끝난 사이클의 주요 결정사항 (project_status.md에서 발췌) +- 남은 TODO / 다음 사이클 후보 +- 환경 의존성 (Node version, Python sidecar, Ollama, Supabase env 등) + +### 3. `memory/handoff-latest.md` 작성 + +템플릿: + +```markdown +# Session Handoff — {YYYY-MM-DD HH:MM} + +> From: {현재 OS + 호스트명} +> Last commit: {HEX} — "{제목}" +> Branch: {branch} +> Remote: {origin URL} + +## ✅ 이번 세션에서 한 일 +- … + +## 🚧 진행 중 / 미완 +- … + +## 🧭 다음 사이클 계획 +- … + +## 🔑 Mac에서 이어받을 때 즉시 확인할 것 +1. `git pull origin {branch}` — 마지막 커밋 `{HEX}` 까지 동기화 됐는지 확인 +2. `npm install`로 워크스페이스 재설치 +3. 플랫폼별 native 모듈 재빌드 — `npx @electron/rebuild@3 --version=33.4.11` +4. `brew install sox` (없으면 audio capture 실패) +5. `supabase db push` 필요한 마이그레이션 있으면 먼저 적용 + +## ⚠️ 환경 차이 주의 +- **Windows 전용 코드 없음** (V2-5 플랫폼 감사 완료) +- Mac에서는 Accessibility/마이크/Apple Events 권한 필요 (첫 실행 시 다이얼로그) +- `resources/sox/`는 gitignored — Mac에서 별도 `bash scripts/install-sox.sh` 실행 + +## 📦 의존성 버전 +- Node: {version} +- Supabase JS: {version} +- Next.js: {version} +- Expo SDK: {version} +- Electron: {version} + +## 🧪 마지막 검증 상태 +- desktop typecheck: ✅ +- desktop build: ✅ +- web typecheck: ✅ +- web build: ✅ ({라우트 수} 라우트) +- api-client test: ✅ ({테스트 수} passed) +- mobile: workspace 제외 (별도 install 필요) + +## 🔗 참고 문서 +- `docs/v2/phase-V2-5-mac-guide.md` — Mac 환경 전체 가이드 +- `docs/v2/phase-V2-2-setup.md` — Supabase 배포 가이드 +- `memory/project_status.md` — 현재 전체 현황 +- 이 파일 (`memory/handoff-latest.md`) — 지금 이 스냅샷 +``` + +### 4. 아카이브 + +현재 `handoff-latest.md`가 이미 있으면 `handoff-archive/{YYYY-MM-DD-HHMM}.md`로 이동. + +### 5. 커밋 & 푸시 + +```bash +git add memory/handoff-latest.md memory/project_status.md +git commit -m "chore: session handoff — {요약}" +git push origin {branch} +``` + +푸시 실패 시 사용자에게 보고하고 수동 푸시 유도. + +--- + +## RESUME 모드 (`/session-handoff resume`) + +**목적**: 다른 기기에서 넘어온 세션을 이어받을 때 가장 먼저 실행. 컨텍스트를 재구성하고 환경을 검증. + +### 1. 원격 동기화 + +```bash +git status +git fetch origin +git log HEAD..origin/{branch} --oneline # 받아올 커밋 확인 +git pull origin {branch} +``` + +### 2. 필수 문서 로드 + +**반드시 이 순서로 Read**: +1. `memory/handoff-latest.md` — 이전 세션의 단서 +2. `memory/project_status.md` — 현재 전체 현황 +3. `CLAUDE.md` — 프로젝트 컨벤션/규칙 +4. `docs/v2/00-v2-master-plan.md` (V2 작업 시) +5. 지금 이어갈 Phase의 `docs/v2/phase-*.md` (해당 시) + +### 3. 환경 검증 + +```bash +# Node.js workspace 설치 확인 +npm install # 루트에서 + +# Native 모듈 재빌드 (플랫폼 바뀌었으면 필수) +npx @electron/rebuild@3 --version=33.4.11 + +# Mac인 경우 시스템 의존성 확인 +command -v sox || echo "brew install sox 필요" +command -v python3 || echo "Python 3.11+ 필요" +command -v ollama || echo "Ollama 설치 권장 (로컬 LLM)" +``` + +### 4. Sanity build + +```bash +cd apps/desktop && npx tsc --noEmit +cd ../web && npx tsc --noEmit && rm -rf .next && npm run build +cd ../.. && npx vitest run --root packages/api-client +``` + +모두 통과해야 다음 작업 진행 가능. 하나라도 실패하면 먼저 복구. + +### 5. 사용자에게 요약 보고 + +```markdown +## 핸드오프 수신 완료 + +**From**: {handoff.From} +**Last commit**: {SHA} + +### 이전 세션에서 한 일 (요약) +- … + +### 지금 이어갈 수 있는 것 +- … + +### 환경 검증 +- ✅/❌ git pull +- ✅/❌ npm install +- ✅/❌ native rebuild +- ✅/❌ typecheck +- ✅/❌ build +- ✅/❌ tests + +어떻게 진행할까요? +``` + +--- + +## 규칙 + +- **Save**는 git이 clean일 때만 수행 (아니면 먼저 커밋) +- **Resume**은 항상 `handoff-latest.md` → `project_status.md` → `CLAUDE.md` 순서로 로드 +- 핸드오프 문서 갱신 시 **덮어쓰지 말고 아카이브**로 이동 후 새로 작성 +- `memory/project_status.md`는 두 모드 모두에서 상시 참조 (SSOT) diff --git a/memory/handoff-latest.md b/memory/handoff-latest.md new file mode 100644 index 0000000..69db08c --- /dev/null +++ b/memory/handoff-latest.md @@ -0,0 +1,173 @@ +# Session Handoff — 2026-04-10 + +> From: Windows 11 Pro (Yun Chan PC) +> Last commit: b386733 — "feat(V2-5차): pgvector 시맨틱 검색 + chat 스트리밍 + doc 편집 + VoiceAction + Realtime + storage + 메모" +> Branch: main +> Remote: https://gitlab.twentyoz.kr:8443/d3r0/voice.git +> 총 push 대기: 20 commits (이전 origin/main 대비) + +## ✅ 이번 세션에서 한 일 (1M 세션 5 사이클) + +### 1차 사이클: V2-1 ~ V2-8 전체 1차 구현 +- V2-1a/b/c/d — Monorepo 전환 (npm workspaces + Turborepo 설정, packages/core/ui/i18n 추출) +- V2-2 — Supabase 인프라 (12 테이블 + RLS + triggers + storage + 4 Edge Functions) +- V2-3 — Web App MVP (Next.js 15, 11 라우트) +- V2-4 — Desktop ↔ Supabase 동기화 (CloudSyncService, OAuth deep link, push only) +- V2-5 — macOS 빌드 (paths.ts 플랫폼 분기, electron-builder mac, entitlements, CI workflow) +- V2-6 — Mobile MVP (Expo, workspace 제외) +- V2-7 — 팀 기능 (web /teams) +- V2-8 — 결제 (Stripe Edge Functions + /billing) + +### 2차 사이클: 고도화 A~D +- Settings CloudSyncSection 통합 +- Web Sidebar 공유 layout (app/(app)/) +- 11개 locale 번역 +- V2-4b pull 동기화 (history/dictionary) +- V2-8b Stripe webhook HMAC-SHA256 검증 + Customer Portal +- packages/ui-native (RN DS 컴포넌트) + +### 3차 사이클: E~J +- V2-4b pull 확장 (meetings/memos/documents) +- api-client types interface→type 전환 +- apps/mobile을 @d3ro/ui-native로 실제 교체 +- V2-7b 이메일 invite flow (team_invites 테이블 + team-invite/accept Edge Functions + /accept-invite) +- Realtime transcripts 구독 (LiveTranscriptList) +- api-client 유닛 테스트 19 passed + web E2E 스캐폴딩 + +### 4차 사이클: K~P +- @supabase/ssr 0.10 + supabase-js 2.103 bump → **Database 제네릭 완전 주입** +- /chat 페이지 (ChatPanel + llm-proxy 호출) +- /knowledge 페이지 (knowledge_documents/chunks + tsvector + AddKnowledgeForm) +- team-invite Resend 이메일 발송 +- Expo Push notification (push_tokens + send-push + expo-notifications) +- meetings/[id] AI 문서 생성 (GenerateDocumentButton 4종 템플릿) + +### 5차 사이클: Q~V +- **pgvector** 활성화 + embedding(1536) + match_knowledge_chunks RPC + embed-chunks/search-knowledge Edge Functions + /knowledge 검색 UI +- **/chat SSE 스트리밍** — llm-proxy가 Anthropic 스트림 프록시, chat-panel progressive 렌더 +- **DocumentEditor** — MUI Dialog 기반 마크다운 편집/삭제 +- **/actions** (VoiceAction 이식) — 자연어 → JSON 파싱 → 실행 +- **Desktop CloudSync Realtime** — meetings/history/dictionary 변경 구독 + 자동 pullAll +- **Record → Storage 업로드** + 자동 meetings INSERT +- **MemoForm** — 회의 상세에서 메모 작성 +- **11개 locale** nav.chat/knowledge/actions 키 + +## 🚧 미완 / 남은 것 + +### 사용자 액션 필요 (환경 작업) +1. **Supabase 프로젝트 생성 + `db push`** — `docs/v2/phase-V2-2-setup.md` +2. **Google/GitHub OAuth Provider** 등록 +3. **Google Cloud STT API 키** + **Anthropic API 키** + **OpenAI API 키** (임베딩용) +4. **Stripe** 계정 + Price ID + Webhook secret +5. **Resend** API 키 (초대 이메일) +6. Mac에서 `npm run dev` 검증 — `docs/v2/phase-V2-5-mac-guide.md` + +### 코드 레벨 후보 (6차 사이클) +1. E2E 실제 실행 (Playwright browsers install) +2. Mermaid 렌더 (DocumentEditor에 마크다운 미리보기) +3. 회의 오디오 재생 (audio_storage_key → signed URL + 플레이어) +4. Dashboard 위젯 차트 (회의 시간/문서 수 추이) +5. Knowledge 파일 업로드 (PDF/docx 파싱) +6. Voice Input (/actions에 마이크 아이콘) +7. 다크모드 토글 (현재 다크 고정) +8. 팀 대시보드 + 알림 센터 + +## 🔑 Mac에서 이어받을 때 즉시 확인할 것 + +```bash +# 1. Git pull +git clone https://gitlab.twentyoz.kr:8443/d3r0/voice.git # 또는 git pull +cd voice +git log --oneline -5 # b386733 까지 있는지 + +# 2. 시스템 의존성 +brew install sox node@22 python@3.11 +# Ollama 선택 (로컬 LLM) +brew install ollama && ollama pull qwen3:4b + +# 3. npm workspace 설치 +npm install + +# 4. native 모듈 재빌드 +npx @electron/rebuild@3 --version=33.4.11 + +# 5. 검증 +cd apps/desktop && npx tsc --noEmit # desktop +cd ../web && npx tsc --noEmit && npm run build # web +cd ../.. && npx vitest run --root packages/api-client # tests + +# 6. dev 실행 +npm run dev # Electron 앱 뜸 +# 별도 터미널: cd apps/web && npm run dev # Next.js 앱 http://localhost:3000 + +# 7. mobile (선택) +cd apps/mobile && npm install # workspace 제외라 별도 +npm start # Expo dev +``` + +## ⚠️ 환경 차이 주의 + +- **Windows 전용 코드 없음** — V2-5에서 플랫폼 감사 완료 +- Mac: **Accessibility/마이크/Apple Events 권한** 첫 실행 시 다이얼로그 +- `resources/sox/`는 gitignored — `bash scripts/install-sox.sh`로 Homebrew sox 번들 (dist 빌드 시) +- `resources/icons/`에 실제 아이콘 파일 없음 — `docs/v2/phase-V2-5-mac-guide.md` §5 참고 +- Mac에서 `npm run dist` 하려면 아이콘 + sidecar 빌드 필요 (`python scripts/build-sidecar.py`) +- `apps/mobile/`은 workspace 제외 — 별도 `cd apps/mobile && npm install` + +## 📦 의존성 버전 + +| 패키지 | 버전 | +|---|---| +| Node.js | 22.12.0 | +| @supabase/supabase-js | 2.103.0 | +| @supabase/ssr | 0.10.2 | +| Next.js | 15.5.14 | +| Expo SDK | ~51 | +| Electron | 33.4.11 | +| React | 19 | +| MUI | 7 | +| TypeScript | 5.7+ | + +## 🧪 마지막 검증 상태 + +| 게이트 | 상태 | +|---|---| +| desktop typecheck | ✅ | +| desktop build | ✅ | +| web typecheck | ✅ | +| web build | ✅ (15 라우트) | +| api-client test | ✅ (19 passed) | +| mobile | workspace 제외 (별도 install 필요) | + +## 📊 누적 통계 + +- 총 커밋: 20개 (V2 시작 이후) +- Edge Functions: 12개 +- SQL 마이그레이션: 8개 +- 웹 라우트: 15개 +- 모바일 화면: 5개 +- 패키지: 6개 (core/ui/ui-native/i18n/api-client + 앱) +- 테스트: 19 passed +- 코드 추가: ~15,000줄+ + +## 🔗 참고 문서 + +| 파일 | 내용 | +|---|---| +| `memory/project_status.md` | 프로젝트 전체 현황 (SSOT) | +| `docs/v2/00-v2-master-plan.md` | V2 마스터 플랜 + 로드맵 | +| `docs/v2/phase-V2-5-mac-guide.md` | Mac 환경 전체 가이드 | +| `docs/v2/phase-V2-2-setup.md` | Supabase 배포 가이드 | +| `docs/v2/phase-V2-2.md` | Supabase 상세 설계 | +| `docs/v2/phase-V2-3.md` | Web App 설계 | +| `docs/v2/phase-V2-4.md` | 데스크톱 동기화 설계 | +| `.claude/skills/session-handoff/` | 이 핸드오프 스킬 | +| `.claude/skills/implement-phase/` | 구현 스킬 | + +## 🏁 Mac에서 재개 시 첫 명령 + +``` +/session-handoff resume +``` + +이 skill이 `memory/handoff-latest.md` → `project_status.md` → `CLAUDE.md`를 순서대로 읽고, 환경 검증 후 다음 작업을 제안합니다.