# 세션 교대 키트: HANDOFF.md 네 제목 + 프롬프트 두 개 + 30만 토큰 알림 훅

해민웨이 글 「대화가 길어지면 새 세션으로 갈아탑니다」(haeminway.com/ko/tech/handoff-rollover)에 딸린 파일입니다.

## 1. 언제 갈아타나

- 맡은 일이 남았고, 대화가 30만 토큰(300K)을 넘었거나 주제가 바뀌었을 때
- 일이 끝났으면 갈아타지 않고 닫는다
- 도구를 쓰는 도중에는 끼워 넣지 않는다. 돌던 작업은 끝나길 기다리거나 식별자를 인계에 적는다
- Claude Code에서 지금 길이는 `/context`로 본다

## 2. 이전 대화에 붙여 넣을 프롬프트

```text
지금까지 대화를 새 세션에 넘기려고 한다. 이 폴더의 HANDOFF.md에
아래 네 제목으로 적고, 그 파일만 커밋해 줘(git이 아니면 저장만).
- 정한 것: 이 대화에서 내가 확정한 결정과 근거 파일 경로
- 맡은 일: 내가 맡긴 일 중 남은 것. 돌고 있는 작업은 식별자·상태·로그 위치까지
- 상시 작업: 이 창을 닫으면 멈추는 서버·감시·반복 실행.
  없으면 정확히 "상시 작업: 없음"
- 참고: 설명, 다른 사람 몫, 내 승인을 기다리는 것(실행하지 않음)
추측은 적지 말고, 확인하지 못한 것은 "미확인"이라고 적어.
```

## 3. 새 대화의 첫 메시지

```text
이전 세션에서 이어받는다. HANDOFF.md를 읽고 두 줄로만 답하고 멈춰.
1줄: 이 파일의 sha256 해시(직접 계산)
2줄: 정한 것·맡은 일 한 줄 요약
```

확인할 것:

- 해시가 내 터미널의 `sha256sum HANDOFF.md`(맥은 `shasum -a 256 HANDOFF.md`) 값과 같은가
- 한 줄 요약이 내가 맡긴 일과 맞는가(해시는 파일 판만 확인한다. 내용 이해는 요약으로 본다)

둘 다 맞으면 이어서 보낸다.

```text
맡은 일을 이어서 해. 참고에 있는 건 실행하지 마.
```

인계 파일을 쓰게 한 뒤에는 이전 대화에 새 지시를 보내지 않는다. 생각난 말은 새 대화에 보낸다.

## 4. HANDOFF.md 템플릿

```markdown
# 인계 (날짜, 한 줄 상황)

- 정한 것:
  - [확정된 결정] → 근거: [파일 경로 또는 커밋]
- 맡은 일:
  - [남은 일 1]: 지금 상태, 끝나면 할 다음 단계
  - [돌고 있는 작업]: 식별자 [ID] · 상태 [진행 중/끝남] · 결과 위치 [경로]
- 상시 작업: 없음
- 참고:
  - [설명·도구 위치·다른 세션 파일]
  - 승인 대기(실행 금지): [항목]
```

창을 닫으면 멈추는 프로세스가 있다면:

```markdown
- 상시 작업:
  - 미리보기 서버 [포트]: 이 창을 닫으면 멈춤. 다시 띄우기: [명령]
```

### 상시 작업 칸에서 자주 틀리는 모양

| 모양 | 고치는 법 |
|---|---|
| 제목 아래 줄에 `  - 없음` | `- 상시 작업: 없음` 한 줄로 |
| `없음 (서버는 세션 임시라 꺼도 됨)` | 괄호 설명은 참고 칸으로 |
| 칸을 비워 둠 | `없음`이라도 적는다 |
| 운영체제 서비스·타이머를 적음 | 창을 닫아도 안 멈추니 참고 칸으로 |

### 맡은 일 한 줄

```text
나쁜 예: - 모바일 작업 계속
좋은 예: - A 세로판 08은 08a·08b 두 장으로 나뉘어 있음
           → 위아래로 합쳐 하나로 만들고 08a·08b 삭제
```

## 5. 30만 토큰 알림 훅(Claude Code)

`context-budget-hook.py`(같은 폴더, haeminway.com/downloads/context-budget-hook.py)를 내려받아 설치한다.

```bash
mkdir -p ~/.claude/hooks
cp context-budget-hook.py ~/.claude/hooks/ && chmod +x ~/.claude/hooks/context-budget-hook.py
```

`~/.claude/settings.json`의 `"hooks"`에 추가:

```json
"UserPromptSubmit": [
  { "hooks": [ { "type": "command",
      "command": "$HOME/.claude/hooks/context-budget-hook.py", "timeout": 3 } ] }
]
```

- 메시지를 보낼 때마다 대화 기록 끝 2MiB만 읽고 마지막 응답의 입력 토큰(캐시 포함)을 센다
- 30만·40만·50만을 처음 넘을 때 한 번씩만 "새 세션을 권하라"는 문장을 AI에게 넘긴다
- 기준은 command 앞에 `CONTEXT_BUDGET_TOKENS=150000 `처럼 붙여 바꾼다
- 설치 전에 `/context`로 대화 창 크기를 본다. 창이 20만 토큰이면 그 근처에서 자동 요약이 먼저 돌아 30만에 닿지 않으니 15만 정도로 낮춘다
- 실패하면 아무것도 출력하지 않아 대화를 막지 않는다

## 6. 지시 파일에 넣는 한 줄(예)

```text
- 맡은 일이 남았는데 대화가 약 30만 토큰을 넘거나 주제가 바뀌면,
  HANDOFF.md(정한 것 / 맡은 일 / 상시 작업 / 참고)를 쓰고 그 파일만 커밋한 뒤
  새 세션으로 넘어가자고 한 줄로 권한다.
```