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 실행
2026-04-11 01:25:22 +09:00 · 2026-04-11 01:25:22 +09:00 · d2cb1c0166
commit d2cb1c0166
parent b386733d1e
2 changed files with 383 additions and 0 deletions
--- a/.claude/skills/session-handoff/SKILL.md
+++ 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)