smart-handoff-parallel

Smart Handoff (Parallel) — 블록 병렬 압축 + merge verifier + 세션 격리

언제 쓰나: 세션이 길고 작업 구간이 많아 단일 핸드오프로는 손실이 우려될 때. 짧은 세션이면 그냥 /smart-handoff를 쓴다.

핵심 관점: 압축은 멈춤이 아니라 배치(deployment) 다. 긴 히스토리를 한 번에 줄이지 말고 블록별로 병렬 워커가 압축하고, merge verifier가 손실을 먼저 잡은 뒤 통과분만 핸드오프한다.

⚠️ 사용자는 같은 폴더에서 여러 세션을 동시에 돌린다. 핸드오프 파일은 session_id로 격리한다.

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

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

• SID가 비면 → $ARGUMENTS 백업 파일명의 ...-<8hex>.md에서 추출, 그래도 없으면 manual.
• 최신본: context/WORKING-${SID}.md / 이력: context/handoffs/${KST}_KST__${SID}.md

분석 대상:

• $ARGUMENTS 에 파일 경로가 있으면 → 그 transcript 백업 .md.
• 없으면 → 지금까지의 전체 대화.

1. 블록 분해 (메인이 직접)

세션을 시간·인과 순서대로 의미 있는 작업 블록 N개로 나눈다 (요구사항 확정 / 증거 수집 / 구현 / 디버그 / 정정 등). 블록마다 메모: 블록 이름, 대략 범위, 건드린 핵심 파일/도구결과.

🔒 절대 보존 레인(사용자 지시·금지사항, acceptance criteria, 보안/권한/비용 제약)은 압축 대상에서 제외하고 메인이 원문 그대로 보관한다. 서브에이전트에 위임하지 않는다.

2. 블록별 병렬 압축 (서브에이전트 fan-out)

블록 1개당 서브에이전트 1개를 띄워 동시에 압축한다.

⚠️ 리소스 안전 (CLAUDE.md OOM 규칙): 한 번에 스폰하는 서브에이전트는 최대 4~8개. 블록이 8개를 넘으면 배치로 나눠 순차 처리한다.

각 서브에이전트(Explore 또는 general-purpose)에게 주는 지시 템플릿:

다음 작업 블록을 5필드 스키마로 압축하라. 자유 요약 금지 — 정확히 이 5필드만.
블록: "[블록 이름]" / 범위: [대략 범위] / 관련 파일·도구결과: [목록]

- intent: 이 블록의 목표·완료 기준 (반복 재진술은 버려라)
- evidence: 핵심 사실마다 포인터(파일:라인 / 도구결과 / 커밋 / URL). 재조회 가능한 원문 전문은 버려라
- decision: 선택지 → 채택 결정 → 근거 (장황한 사고 과정은 버려라)
- risk: 미해결 이슈·반대 증거·함정 (해결된 임시 가설은 버려라)
- handoff: 다음 행동 + 그에 필요한 컨텍스트 (종료된 하위 로그는 버려라)

철칙: evidence·decision의 모든 주장에는 포인터를 반드시 붙여라. 포인터 없는 결론은 적지 마라.
출력: 위 5필드만 담은 간결한 구조(마크다운). 그 외 텍스트 금지.

3. merge verifier (메인 또는 별도 검증 에이전트)

블록 요약을 모은 뒤, 예쁘게 다듬는 게 아니라 손실을 검출하는 gate로서 4가지를 검사한다:

1. coverage check: 각 블록의 5필드가 병합 결과에 남았는가.
2. contradiction check: 한 블록의 결정과 다른 블록의 정정이 충돌하는가 (어느 게 최종인지 명시).
3. evidence check: 모든 claim에 source pointer가 있는가. 없으면 그 블록 반려.
4. replay check: "다음 턴에 가장 먼저 할 일 + 근거 파일", "최우선 미해결 risk와 위치"를 병합 결과만 보고 답할 수 있는가.