Session Handoff

세션 간 작업 인수인계 도구. 컨텍스트가 차서 다른 세션·디바이스에서 이어가야 할 때, 자기완결 텍스트 한 장으로 작업 환경과 다음 STEP을 넘긴다.

왜?

긴 작업이 한 세션에서 안 끝나거나 컨텍스트가 차서 새 세션을 열 때, 다음 세션의 Claude(또는 본인)가 5분 안에 환경 복구 + 작업 재개할 수 있어야 한다. 핸드오프는 이를 위한 표준 텍스트 메모.

특징:

멀티 디바이스 동기화 — 맥미니에서 저장한 핸드오프를 맥북·iPhone Claude Code 세션에서 즉시 회수
7일 자동 purge — 서버 측 TTL. 영구 보존 필요 시 메모리 또는 dev doc 으로 이전
시각 단위 다중 저장 — 같은 날 같은 토픽 여러 번 저장 가능 (HHMM 접미사)

도구

Tool	용도
`handoff_save`	핸드오프 생성/덮어쓰기
`handoff_get`	단일 핸드오프 본문 회수
`handoff_list`	최근 핸드오프 목록 (옵션: 프로젝트 필터)

⚠️ handoff_list / handoff_get 호출 시 7일 지난 핸드오프 자동 purge 가 같이 실행됨 (side effect). 자동화 에이전트는 destructive 한 maintenance call 로 취급.

저장 (Save)

mcp__ainote__handoff_save({
  project: "logi",            // 영문 소문자 + 숫자 + 하이픈만
  topic:   "phase-d-port",
  content: "<자기완결 본문>",
  date:    "2026-05-13",      // optional, 생략 시 서버 today
  time:    "1555"             // optional, HHMM (KST). 같은 날 다중 저장 시 접미사
})

저장 경로: handoffs/{project}-{topic}-[{HHMM}-]{YYYY-MM-DD}.txt

작성 원칙:

자기완결: 다음 세션은 이전 대화 메시지를 못 봄. 파일 하나만으로 환경 복구
사실만: "잘 동작" 대신 "BUILD SUCCESSFUL" 같은 검증 가능한 표현
절대 경로 + 줄 번호 명시 → 다음 세션이 grep/Read 즉시 가능
다음 STEP 은 명령 단위 ("테스트 작성" X → "/path/X.kt 작성, 케이스 A/B/C" O)
알려진 함정 필수 — 이번 세션에서 부딪힌 빌드/타입/import 함정은 재발 가능성 큼
비밀값 평문 금지 — "ENV 의 X (1Password 'logi' 항목)" 식으로 참조만

복구 (Restore) — 시간대 cluster 가져오기

여러 프로젝트를 같은 시간대에 몰아서 저장한 경우 (예: 오전에 5개), 하나만 회수하면 인접 핸드오프를 놓칠 위험이 있다. 복구 모드는 최근 cluster + 직전 cluster 의 메타데이터를 묶어 보여줘서 빠뜨림 없이 작업을 재개하도록 돕는다.

알고리즘

handoff_list({limit: 50}) 호출 (응답은 updated_at 내림차순)
Cluster 탐지 (gap 기반):
- 기본 GAP_THRESHOLD = 30분
- 인접 항목 간 gap 계산. gap ≤ 30분 → 같은 cluster, 초과 시 break
반환 범위: 최신 cluster + 직전 cluster 1개 (빠진 것 확인용)
출력: cluster 별 표 (HHMM KST / project / topic) — 본문은 fetch 하지 않음
사용자가 선택 시 단일 메시지에서 병렬 handoff_get 호출

출력 예시

## Cluster 1 — 2026-05-19 08:18~08:36 KST (5건, 18분 span)
| 시각 | project / topic |
|---|---|
| 08:36 | tennis / bracket-share-button-universal-links-0830 |
| 08:35 | refra / v2-deploy-step1-done-0834 |
| 08:30 | krx / listing-phase-10-complete-0830 |
| 08:24 | krx / listing-testflight-build2-uploaded-0824 |
| 08:18 | tennis / bracket-predict-feature-0818 |

## Cluster 2 (직전) — 2026-05-19 00:16~00:30 KST (2건)
| 00:30 | ainote / web-logout-cookie-fix-0030 |
| 00:16 | tennis / bracket-predict-feature-0016 |

옵션

"오전만"/"오후만" → KST hour 필터 (06~12 / 12~18)
"프로젝트 X 만" → project/topic 필터 후 cluster
"이전 cluster 더" → 직전 1개 → 2~3개로 확장
"본문 전부 펴줘" → cluster 내 모든 항목 병렬 fetch

구현

별도 MCP tool 없이 기존 handoff_list + 클라이언트의 in-conversation cluster 추론으로 처리. Claude Code 사용자는 session-handoff 스킬의 §복구 섹션 알고리즘 자동 발동.

Claude Code 트리거 예시

저장:

"이어서 다른 세션", "핸드오프 만들어", "다음 세션 넘기기"
"바탕화면에 핸드오프 만들어" (Desktop fallback)

복구:

"오전 핸드오프 복구해줘", "최근 핸드오프 복구"
"이어서 작업 가져와", "오늘 작업한 거 묶어서 보여줘"

안티패턴

❌ "잘 진행됨" 같은 측정 불가 표현
❌ 절대 경로 없이 "feature/auth 의 XXX" — 다음 세션이 못 찾음
❌ STEP 에 "테스트 추가" 같은 추상적 한 줄
❌ 비밀값 평문 포함
❌ project/topic 슬러그에 한글·이모지·공백 (slugify 가 비-ASCII 를 - 로 변환)
❌ 복구 시 메타데이터 없이 곧바로 모든 본문 fetch (토큰 낭비)
❌ cluster 경계 무시하고 임의로 N개 자름

Session Handoff ​

왜? ​

도구 ​

저장 (Save) ​

복구 (Restore) — 시간대 cluster 가져오기 ​

알고리즘 ​

출력 예시 ​

옵션 ​

구현 ​

Claude Code 트리거 예시 ​

안티패턴 ​