chore: session handoff 준비 — Mac 이어받기 단서 문서 + /session-handoff 스킬
- 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 실행
This commit is contained in:
yunchan8804
parent
b386733d1e
commit
d2cb1c0166
2 changed files with 383 additions and 0 deletions
210
.claude/skills/session-handoff/SKILL.md
Normal file
210
.claude/skills/session-handoff/SKILL.md
Normal file
|
|
@ -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)
|
||||||
173
memory/handoff-latest.md
Normal file
173
memory/handoff-latest.md
Normal file
|
|
@ -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`를 순서대로 읽고, 환경 검증 후 다음 작업을 제안합니다.
|
||||||
Loading…
Add table
Add a link
Reference in a new issue