Claude Code 대화 리셋 후에도 맥락을 100% 유지하는 '핸드오프(Handoff)' 설정 & 활용법

토큰 비용 90% 절감과 작업 연속성을 동시에 잡는 프롬프트 엔지니어링 가이드

Claude Code를 활용해 개발 작업을 진행하다 보면 대화가 길어질수록 속도가 느려지고 토큰 소비가 급증하는 현상을 경험하게 됩니다. 특히 1시간 이상 잠시 자리를 비우면 **프롬프트 캐시(Prompt Cache)가 만료**되어 다음 메시지 하나에 엄청난 토큰 비용이 청구되기도 합니다.

⚠️ 핵심 문제점
대화가 30만~50만 토큰을 넘어갈 때 /clear를 하지 않으면, 불필요한 과거 맥락 때문에 컨텍스트 오염(Context Rot)이 발생하고 비용이 20배 이상 늘어납니다.

이 문제를 완벽하게 해결하는 방법이 바로 **'핸드오프(Handoff)' 시스템**입니다. 진행 중인 작업 내역을 마크다운 문서로 디스크에 자동 기록하고, /clear로 대화를 깨끗이 초기화한 후 해당 문서만 읽어 들여 작업을 이어나가는 방식입니다.

1. 핸드오프(Handoff) 커스텀 스킬 설치 방법

Claude Code가 자동으로 핸드오프 문서를 생성하도록 프로젝트 설정 파일에 스킬을 추가합니다.

단계 1: `.claude/skills` 폴더 생성

프로젝트 최상위 디렉토리에 스킬 폴더를 생성하고 `handoff.md` 파일을 만듭니다.

단계 2: `handoff.md` 스킬 코드 작성

아래 코드를 복사하여 .claude/skills/handoff.md 파일로 저장합니다.

---
name: handoff
description: 현재 작업 맥락, 진행 상황, 다음 단계를 HANDOFF.md 파일로 기록합니다.
---

현재 대화 내역과 작업 상태를 분석하여 프로젝트 루트에 `HANDOFF.md` 파일을 생성 또는 업데이트하세요.

파일에는 다음 내용을 포함해야 합니다:
1. **작업 목표**: 현재 세션에서 달성하려 한 핵심 목표
2. **완료된 작업**: 수정되거나 새로 생성된 주요 파일 및 구현 기능
3. **현재 상태**: 어디까지 진행되었으며 현재 직면한 이슈/버그
4. **다음 수행 과제**: 대화 리셋 후 바로 시작해야 할 2~3가지 핵심 작업 step
5. **주요 파일 참조**: 다음 세션에서 읽어야 할 핵심 파일 경로 목록

문서 작성이 완료되면 `HANDOFF.md에 최신 작업 내역이 기록되었습니다. /clear 후 작업을 이어갈 수 있습니다.` 메시지를 출력하세요.

2. 구체적인 활용 및 실전 모범 사례

핸드오프 시스템을 실제 개발 워크플로우에 적용하는 3단계 순서입니다.

STEP 1. 휴식 전 또는 대화가 길어졌을 때 핸드오프 실행

Claude Code 터미널 입력창에 명령어 실행:

/handoff

→ Claude가 현재까지의 작업 내용을 요약하여 루트에 HANDOFF.md 파일을 생성합니다.

STEP 2. 대화 세션 초기화

이전의 방대한 토큰 맥락을 삭제하고 캐시 비용을 리셋합니다:

/clear

STEP 3. 핸드오프 문서로 새 세션 시작

초기화된 새 대화창에서 저장된 문서를 읽도록 지시합니다:

HANDOFF.md 파일을 읽고 '다음 수행 과제'부터 구현을 시작해 줘.

3. 핸드오프 도입 시 얻게 되는 3가지 이점

토큰 비용 80~90% 절감: 수십만 토큰에 달하는 대화 기록을 매번 재전송하지 않고 핵심 요약 문서(약 1~2천 토큰)만 입력으로 사용하여 프롬프트 캐시 읽기 비용을 극단적으로 낮춥니다.
환각(Hallucination) 감소: 지시사항이 누적되면서 생기는 지시 이행 능력 저하 현상을 방지하고 깔끔한 상태에서 정확한 코드를 생성합니다.
작업 복구 시간 단축: 하루 뒤나 일주일 뒤에 다시 프로젝트를 열어도 `HANDOFF.md`만 보면 어디까지 진행했는지 즉시 파악이 가능합니다.

이 블로그 검색

최신 AI 뉴스