smart-handoff

Smart Handoff v2 — 블록 · 스키마 · 검증 · 세션 격리 (한국어)

핵심 관점: 이 작업은 "요약"이 아니라 상태 관리다. 긴 히스토리를 한 덩어리로 줄이지 말고, ① 의미 있는 작업 블록으로 나눠 ② 정해진 스키마로 압축하고 ③ 압축 후에도 다음 행동에 필요한 상태가 남았는지 스스로 검증(replay) 한 뒤 핸드오프하라. 손실은 다음 turn이 아니라 지금 잡는다.

⚠️ 사용자는 같은 폴더에서 여러 세션을 동시에 돌린다. 그래서 핸드오프 파일은 session_id로 격리해 동시 compact 충돌을 원천 차단한다.

전체 대화를 분석하여 컨텍스트 핸드오프를 준비하세요. 아래 절차를 순서대로 수행합니다.

0. 세션 식별자 · KST 시간 · 출력 경로 확보 (Bash로 먼저)

다음을 Bash로 구한다:

SID=$(printenv CLAUDE_CODE_SESSION_ID | cut -c1-8)
KST=$(TZ='Asia/Seoul' date +%Y%m%d_%H%M%S)

• SID가 비어 있으면 → $ARGUMENTS로 받은 백업 파일명의 ...-<8자리hex>.md 패턴에서 추출한다. 그래도 없으면 manual.
• 출력 경로:
  • 최신본(재독 진입점): context/WORKING-${SID}.md
  • 이력 스냅샷(영구 보존): context/handoffs/${KST}_KST__${SID}.md
• context/handoffs/ 디렉토리가 없으면 만든다 (mkdir -p context/handoffs).

분석 대상 결정:

• $ARGUMENTS 에 파일 경로가 있으면 → 그 파일(PreCompact hook이 남긴 transcript 백업 .md)을 분석.
• 없으면 → 지금까지의 전체 대화를 분석.

1. 작업 블록 분해

세션을 시간·인과 순서대로 의미 있는 작업 블록(block) 으로 나눈다. 단위는 message가 아니라 "하나의 의미 있는 작업 구간"이다.

• 블록 예: 요구사항 확정 → 증거·자료 수집 → 구현/코드 수정 → 테스트·디버그 → 사용자 정정 반영
• 각 블록은 append-only로 고정한다 (이미 끝난 블록의 결론을 뒤에서 바꾸지 말 것).
• 블록은 보통 3~7개. 너무 잘게 쪼개지 말고, "이 구간만 떼어 다른 사람에게 넘겨도 말이 되는가"를 기준으로 자른다.

2. 🔒 절대 보존 레인 (압축 금지)

다음은 절대 요약·삭제하지 말고 원문 그대로 핸드오프 파일 최상단에 보존한다. 압축은 여기에 손대지 않는다.

• 사용자의 명시적 지시·금지사항 (예: "rm 직접 삭제 금지", "한도 코드 고정", 특정 계정/경로 고정 등)
• acceptance criteria / 완료 조건 / "이게 끝나야 끝" 기준
• 보안·권한·인증·비용·rate limit 제약

3. 블록별 스키마 압축

각 블록을 아래 5필드로만 압축한다. "폐기" 칸은 적극적으로 버린다 — 폐기 규율이 곧 압축률이자 정확도다.

필드	보존해야 할 것	버려도 되는 것
intent	이 블록의 목표, 완료 기준	반복된 재진술
evidence	출처 포인터: 파일:라인 / 도구결과 / 커밋 해시 / URL	재조회 가능한 원문 전문
decision	선택지, 채택한 결정, 근거	장황한 사고 과정
risk	미해결 이슈, 반대 증거, 함정	이미 해결된 임시 가설
handoff	다음 행동, 그에 필요한 컨텍스트	종료된 하위 작업 로그

철칙: evidence·decision의 모든 주장에는 포인터(파일:라인 / 도구결과 / 커밋 / URL)를 반드시 붙인다. 포인터로 뒷받침되지 않는 결론은 적지 않는다 (압축 후 모델이 "지어내는" 것을 막는 장치다).