AI 스터디 · 7주차

handoff
— 컨텍스트를 이식하는 기술: 세션이 끝나도 맥락은 살아남는다

mattpocock/skills의 handoff 스킬 해부 — "쓰면 이렇게 됩니다"가 아니라 "이런 프롬프트·지시문·저장 위치라서 그 결과가 나옵니다"를 실제 소스로 확인

왜 handoff인가? (1~6주차와의 연결) 1주차 OT · 2주차 하네스 · 3주차 LLM Wiki · 4주차 OMC/Octopus · 5주차 superpowers · 6주차 Vectorless RAG. 이번 주는 에이전트 세션 사이의 연결고리를 다룬다 — 컨텍스트 한계를 맞닥뜨렸을 때 맥락을 어떻게 다음 에이전트에게 이식하는가.
리포: mattpocock/skills (130k★, MIT, npx skills@latest add mattpocock/skills로 설치)

출처: github.com/mattpocock/skills — skills/productivity/handoff/SKILL.md

문제

컨텍스트 한계 — 누구나 겪은 그 순간

긴 세션 끝에 새 창을 열면
"아까 하던 거 다시 설명해줄 수 있어요?"

에이전트는 이전 세션을 기억하지 못한다. 우리는 매번 배경을 다시 설명하고, 결정 맥락을 복붙하고, "아 그거 지난번에…"를 반복한다.

흔한 패턴

  • 새 세션에 이전 대화 전체를 붙여넣기
  • 같은 배경 설명을 세 번째 반복
  • 민감한 정보(API 키·PII)가 그대로 노출
  • 이미 만든 PRD·ADR을 또 첨부

원하는 그림

  • 새 에이전트가 "어디까지 왔는지" 즉시 파악
  • 다음 세션의 목적에 맞게 정제된 문서
  • 민감 정보는 자동 제거
  • 기존 아티팩트는 경로 참조로 대체

출처: mattpocock/skills — skills/productivity/handoff/SKILL.md

순진한 접근

"그냥 대화 전체를 복붙하면 되잖아요?"

🚫 막는 추측: 이전 세션의 원문 그대로가 곧 최선의 컨텍스트다

비유: 인수인계를 하는데 3개월치 업무 메신저 전체를 출력해서 건네는 것. 내용은 다 있지만 — 읽는 사람은 어디가 핵심인지 모른다.

원문 붙여넣기는 세 가지를 무시한다:

  1. 토큰 폭발: 긴 대화는 컨텍스트 창을 즉시 소비, 새 작업 공간이 없어진다
  2. 중복: 이미 PRD·커밋·ADR에 기록된 내용을 또 실어나른다
  3. 민감 정보 노출: 대화 중 언급한 API 키, 비밀번호, PII가 그대로 전달된다
결과: 새 에이전트가 토큰의 절반을 이전 컨텍스트 소화에 쓰고, 실제 작업 여유가 줄어든다. 그리고 복붙은 "다음 세션에서 무엇을 해야 하는가"를 명확히 하지 않는다.

출처: mattpocock/skills — handoff SKILL.md (중복 배제·민감정보 제거 지시 근거)

왜 부족한가

세 가지 문제를 하나씩 들여다보면

문제원인결과
토큰 폭발 대화 원문은 탐색·실수·반복을 포함한 미가공 데이터 새 에이전트 컨텍스트 창의 상당 부분 소비, 새 작업 여유 감소
중복 아티팩트 PRD·ADR·이슈·커밋 diff에 이미 기록된 결정을 대화에서 또 설명 같은 정보가 두 곳에 — 나중에 어느 쪽이 최신인지 혼란
민감 정보 개발 대화엔 API 키·DB 자격·PII가 섞이기 쉬움 핸드오프 문서가 민감 데이터 유출 경로가 됨
단순 요약(Claude Code 내장 /compact)도 도움이 되지만 — 같은 세션 내부에서만 작동한다. 다른 에이전트·도구·팀원에게 넘길 수 없고, 민감 정보를 능동적으로 걷어내지 않는다.

출처: mattpocock/skills — handoff SKILL.md

핵심 내부 동작 원리

handoff는 어떻게 작동하는가 — SKILL.md 해부

handoff에는 바이너리도 API도 없다. 구현체는 SKILL.md 한 파일 — YAML frontmatter + 마크다운 지시문이다. "압축(compaction)"의 실체는 LLM이 대화를 다시 읽고 구조화된 요약 파일을 쓰는 것이다.

---
description: "Compact the current conversation into a handoff document
             for another agent to pick up."
args:
  - name: focus
    description: "What will the next session be used for?"
    required: false
---
# handoff

Write a handoff document summarising the current conversation so a
fresh agent can continue.

Save it to the temporary directory of the user's OS — NOT the current workspace.

Do NOT duplicate content already in other artifacts (PRDs, plans, ADRs,
issues, commits, diffs) — reference them by path or URL instead.

Redact sensitive info (API keys, passwords, PII).

The document MUST include a "suggested skills" section recommending
skills the next agent should invoke.

각 지시문이 하는 일: LLM에게 무엇을, 어디에, 어떻게 쓸지를 명령한다 — 이것이 "스킬"의 전부다.

포인트: handoff는 LLM의 "읽기-쓰기" 능력을 활용해 컨텍스트를 재구성한다. 마법이 아니라 잘 쓴 프롬프트 파일 — 그래서 누구나 읽고 수정할 수 있다.

출처: mattpocock/skills — skills/productivity/handoff/SKILL.md (frontmatter 및 지시문 원문)

/compact 와의 차이

내장 /compact vs handoff — 언제 무엇을?

Claude Code 내장 /compactmattpocock/skills handoff
범위 현재 세션 내부 — in-context 요약 외부 파일 생성 — 세션 밖으로 이동 가능
저장 위치 메모리(세션 종료 시 소멸) OS 임시 디렉토리(/tmp 등) — 영속
대상 같은 에이전트·같은 세션 다른 에이전트·다른 세션·다른 도구
민감 정보 별도 처리 없음 능동적 redact 지시
중복 배제 별도 처리 없음 기존 아티팩트는 경로 참조로 대체
suggested skills 없음 필수 포함 — 다음 에이전트가 할 일 제안
비유: /compact는 포스트잇 메모(책상 위에서만 유효), handoff는 인수인계 보고서(누가 읽어도 이해 가능, 어디에나 전달 가능).

출처: mattpocock/skills — handoff SKILL.md

실제 흐름 사용 흐름

실제로 어떻게 쓰는가

1. 설치
npx skills@latest add mattpocock/skills
→
2. 세션 진행
평소처럼 작업
→
3. 호출
/handoff [focus]
→
4. 문서 생성
/tmp/handoff-*.md
→
5. 새 세션
문서 전달 → 즉시 재개

focus 인자를 활용하면

handoff는 선택적 인자 "What will the next session be used for?"를 받는다. 이 값이 있으면 LLM이 다음 세션 목적에 맞게 문서 구조를 조정한다:

/handoff "다음 세션은 PR 리뷰에 집중"
→ 생성 문서: 리뷰 관련 컨텍스트 강조, 무관한 탐색 과정 생략

/handoff "다음 에이전트가 배포를 이어받음"
→ 생성 문서: 배포 상태·환경 변수·미완 단계 앞에 배치
생성 문서에 반드시 포함되는 것: 현재까지의 요약 · 결정 사항과 근거 · 미완 작업 · suggested skills(다음 에이전트가 호출할 스킬 목록) · redact된 민감 정보 표시

출처: mattpocock/skills — handoff SKILL.md (args·저장 위치·suggested skills 지시 원문)

트레이드오프

handoff가 해결하는 것과 해결하지 않는 것

해결하는 것

  • 세션 간 컨텍스트 단절
  • 새 에이전트에게 배경 재설명 비용
  • 중복 아티팩트(PRD·ADR 재첨부)
  • 민감 정보의 무심한 전달
  • 다음 에이전트가 "무엇부터 할지" 모름

해결하지 않는 것

  • 코드·파일 자체의 이동 (경로 참조만)
  • LLM 품질에 의존 — 요약 정확도는 보장 없음
  • 문서를 새 세션에 자동 주입하지 않음 (수동 첨부 필요)
  • 팀 협업 버전 관리(개인용 /tmp 저장)
중요한 한계: handoff 문서는 LLM이 생성하므로 요약의 정확도·완전성은 보장되지 않는다. 중요한 결정은 PRD·ADR·커밋 메시지에 먼저 기록하고, handoff는 경로 참조로 연결하는 것이 권장 패턴이다.

출처: mattpocock/skills — handoff SKILL.md

정리

handoff가 가르치는 한 가지

요소내용
스킬 정체SKILL.md 한 파일 — YAML frontmatter + 마크다운 지시문. 바이너리 없음
동작 방식LLM이 대화를 읽고 구조화된 요약을 OS 임시 디렉토리에 저장
핵심 규칙중복 배제(경로 참조) · 민감 정보 redact · suggested skills 포함
/compact 차이in-context(소멸) vs 외부 파일(이동 가능·영속)

컨텍스트는 대화 안에 갇혀 있을 필요가 없다.
잘 만든 핸드오프 문서 하나가 맥락을 어디든 이식한다

그래서 handoff는 단순 "요약 도구"가 아니다 — 에이전트 간 프로토콜이다. 다음 에이전트가 어디서부터 시작할지, 무슨 스킬을 쓸지, 무엇을 건너뛸지를 구조화한 문서로 정의한다.
이번 주에 해볼 것 (딱 하나): 긴 세션 끝에 /handoff 한 번 호출해보기. 생성된 /tmp 문서를 열어 — "이게 내가 오늘 한 일의 요약인가?" 확인. 부족한 부분이 보이면 그게 다음 세션의 시작점.

출처: mattpocock/skills — handoff SKILL.md

감사합니다

질문 / "세션 컨텍스트 단절" 경험 공유

참고 자료

출처: github.com/mattpocock/skills

1 / 10← / → 넘기기 · a: 스크롤 · n: 노트