Claude Code로 긴 작업을 하다 보면 컨텍스트 창이 차오르고, 선택지는 둘로 좁혀진다. 창 안에서 히스토리를 요약해 버티는 compact, 그리고 현재 상태를 문서로 적어 새 세션에 넘기는 핸드오프 파일. 둘은 “요약을 다음으로 넘긴다”는 원리만 같다. 무엇이 남을지에 대한 통제권, 다음 세션의 재개 비용, 어울리는 상황이 전부 다르다. 내가 정한 기준은 하나다 — 세션을 내 손으로 끊을 수 있으면 핸드오프 파일, 끊을 수 없는 자동 실행에는 자동 안전망.
이 기준은 이론에서 나온 게 아니다. 블로그 자동화 리포 하나를 8주 동안 핸드오프 문서 13건으로 이어붙여 굴렸고, 그 사이에 문서가 사고를 막은 날과 문서가 없어서 사고가 터진 날을 둘 다 겪었다. 그 기록으로 두 방식의 차이와, 자동 안전망을 붙여야 했던 순간까지 정리한다.
핸드오프 파일, compact와 무엇이 다른가
compact는 Claude Code의 네이티브 기능이다. 지금까지의 대화 히스토리를 모델이 요약해서 컨텍스트 창 안에서 통째로 교체한다. 핸드오프 파일은 그런 압축 절차가 아니라, “현재 상태·내린 결정·다음 할 일”을 담은 별도의 마크다운 문서를 새로 쓰는 것이다. compact를 내부적으로 돌려서 만드는 게 아니라 그냥 문서 한 장을 새로 작성한다 — 이 구분을 알고 나서야 두 방식을 언제 갈라 쓸지가 보였다.
| 축 | compact | 핸드오프 파일 |
|---|---|---|
| 동작 | 히스토리 요약 후 창 안에서 교체 | 상태·결정·할 일을 담은 문서 신작 |
| 통제권 | 무엇이 남고 버려지는지 불투명 | 보존할 내용을 작성자가 전부 결정 |
| 재개 비용 | 세션을 이어가며 히스토리 비용 재지불 | 새 세션이 문서 하나만 읽고 출발 |
| 맞는 상황 | 세션을 끊을 수 없는 도중 | 작업 단위가 끊기는 시점을 통제할 때 |
Anthropic의 Claude Code 베스트 프랙티스도 태스크 사이에 컨텍스트를 자주 비우라고 권한다. 문제는 “비운 다음”이다 — 비우기 전의 맥락을 어디에 실어 나를 것인가가 두 방식의 갈림길이다.
재개 비용 — 문서 하나면 다음 세션이 바로 출발한다
compact로 버틴 세션은 요약본 위에 다시 히스토리가 쌓이고, 다음 재개 때도 그 비용을 다시 치른다. 핸드오프 쪽은 계산이 단순하다. 새 세션이 읽는 것은 문서 한 장, 몇백 토큰이다.
오늘 아침 세션이 그대로 실측이었다. 어제 남긴 46줄짜리 핸드오프 문서 하나를 읽자마자, 새 세션은 이전 세션이 멈춘 지점의 다음 단계를 곧바로 집었다. 어제 무엇을 검증했고 무엇이 사람 몫으로 남았는지 설명을 반복할 필요가 없었다. 컨텍스트 창이 작업 기억이고 차오를수록 흐려진다는 이야기는 컨텍스트 관리 글에서 따로 다뤘다 — 이 글은 그 다음 질문, “그래서 무엇으로 넘길 것인가”에 대한 답이다.
문서 13건으로 굴려본 운영 — 양식이 절반이다
문서의 품질은 양식에서 갈렸다. 13건을 쓰면서 정착한 구성은 4개 절이다. ①완료한 일(검증 결과까지), ②실측과 막힘(이번에 빠진 함정), ③남은 사람 몫, ④다음 세션 착수점. 특히 ②가 값을 했다. “후크의 상대경로는 프로젝트 루트가 아니라 세션 위치 기준으로 풀린다”라는 한 줄을 적어둔 덕에, 다음 세션은 같은 구멍에 빠지지 않고 절대경로로 등록했다.
쌓이는 문서가 부담이 되지 않게 만든 규약도 있다. 각 문서가 바로 앞 문서를 링크해서, 새 세션은 최신 1건만 읽으면 된다. 계보 표에는 “남은 미결” 열을 둬서 어떤 일이 어느 문서에서 끊겼는지 추적한다. 같은 날 두 갈래 작업이 돌면 핸드오프도 트랙별로 2건을 나눠 쓴다.
반대 사례도 있었다. 인벤토리 파일이 7월 18일에 멈춰 있다는 상태를 아무 문서도 나르지 않았고, 3주 뒤에야 신규 글 18편이 색인 대기열에서 통째로 빠져 있는 것을 발견했다. 문서가 상태를 나르지 않으면, 도구는 조용히 낡은 데이터로 돌아간다.
자동 안전망은 언제 붙이나
수동 핸드오프 파일에는 전제가 있다 — 끊는 시점을 사람이 정한다는 것. 장시간 자동 실행(전체 파이프라인을 맡기거나, 검증 통과까지 반복시키는 모드)에서는 그 전제가 무너진다. 개입 없이 방치하면 보존 지시 없는 자동 압축으로 맥락이 뭉개진다.
여기가 oh-my-claudecode(OMC) 같은 자동 안전망의 자리다. 세션 상태·계획·인수인계를 파일로 기록해 다음 세션에 주입하고, 창이 75% 차면 미리 압축을 유도하며, 압축 뒤에도 핵심 상태를 파일에서 복원한다. 품질은 compact 요약의 한계에 종속되지만, 할 일 목록과 지시사항이 살아남는 것과 전부 날아가는 것의 차이는 크다.
다만 자동이 돌고 있다는 가정 자체를 검증해야 한다. 우리 리포에서는 백그라운드 실행이 소리 없이 멈춘 채 몇 시간이 지난 적이 있다 — 안전망도 결국 감시 대상이다. 그래서 병행 기준은 이렇게 정리됐다. 안전망은 깔아두되, 세션을 끊을 수 있는 타이밍이 오면 핸드오프 파일로 직접 넘긴다.
핵심 요약
- compact는 창 안 요약 교체, 핸드오프 파일은 상태 문서 신작 — 통제권과 재개 비용이 다르다.
- 끊을 수 있으면 핸드오프 파일, 끊을 수 없는 자동 실행에는 자동 안전망을 병행한다.
- 양식 4절(완료·함정·사람 몫·착수점)과 “최신 1건만 읽는” 연결 규약이 문서 부담을 없앤다.
함께 읽으면 좋은 글
핸드오프 문서가 쌓이는 동안 항상 로딩되는 규칙 문서도 함께 비대해진다 — 그쪽 다이어트는 별도 기술이다.
세션 운영 이전에, 시작 설정(플랜 모드·초기 문서)부터 잡고 싶다면 이 글이 먼저다.
