handoff

세션 핸드오프

핸드오프는 요약이 아니라 재개 가능한 상태다. 다음 세션이 이것만 읽고 같은 자리에서 다음 명령을 칠 수 있어야 한다. "뭘 했는지" 보다 "지금 어디에 서 있고 다음에 뭘 치는지" 가 본체다.

컨텍스트 사용량이 40~50% 에 닿으면 하던 걸 멈추고 이 스킬을 부른다. compaction 은 모델이 뭘 버릴지 스스로 고르므로 안전망일 뿐이다.

어디에 남기나 — 상황당 한 곳

재개 상태를 두 군데에 나눠 적지 않는다. 나눠 적으면 어느 쪽도 혼자서는 재개 가능한 상태가 아니게 되고, 다음에 쓸 때 한쪽 내용이 조용히 빠진다(2026-09-21 실측, 이슈 #152 — 함정·기동 명령은 핸드오프 이슈에만, 새로 확정된 패턴은 다음 이슈 메모에만 있었다).

상황	남기는 곳	다음 세션이 받는 것
이슈 도중 — 작업 이슈가 아직 열려 있다(컨텍스트 40~50% 등)	전용 핸드오프 이슈(레포에 HANDOFF.md 는 만들지 않는다, 아래 "두 갈래")	핸드오프 이슈 URL
이슈 경계 — 작업 이슈를 닫았고 다음 작업 이슈가 이미 있다	다음 작업 이슈에 코멘트 하나 (1-6) — 전용 핸드오프 이슈는 만들지 않는다	다음 작업 이슈 URL
인프라 없음(트래커 없는 폴더)	HANDOFF.md	파일 경로

이슈 경계인데 다음 작업 이슈가 아직 없으면 그 이슈를 먼저 만든다. 다음에 할 일이 정해지지 않았다면 경계가 아니라 그냥 끝난 것이므로 핸드오프를 쓰지 않는다.

두 갈래, 인프라 있으면 원본은 이슈

	하는 일	HANDOFF.md	다음 세션이 받는 것
인프라 있음	본문을 스크래치 파일에 쓰고 그 내용으로 이슈/티켓/스레드를 만든다	만들지 않는다(포인터 파일도 두지 않는다)	전체 URL
인프라 없음	HANDOFF.md 에 전체 내용을 쓴다	본문 그대로 = 원본	파일 경로

이슈 도중에 끊을 때 본문은 항상 만든다. 인프라가 있으면 그 본문은 이슈에 들어가고 레포에는 파일을 남기지 않는다 — 레포에 재개 상태를 평문으로 남기지 않고, 다음 세션은 사용자가 붙여넣는 이슈 URL 하나(또는 handoff 라벨 이슈 목록)로 어디로 가야 하는지 안다. 인프라가 없으면 갈 곳이 없으므로 본문 자체가 HANDOFF.md 에 남는다(파일 모드) — 절차가 멈추지 않는다.

2026-10-06 전에는 인프라가 있어도 레포에 HANDOFF.md 를 남겼다. 거기엔 포인터만(이슈 URL·작성 시각·요약·목록 링크) 적었다. 이제는 만들지 않는다. 레포에 그런 포인터 파일이 남아 있으면 2-1 대로 읽고, 가리키는 이슈에 내용이 다 있는지 확인한 뒤 그 레포의 이슈·MR 로 파일을 지운다.

HANDOFF.yaml — 기계 판독용 짝

본문은 사람이 읽기엔 좋지만, 다음 세션이 서비스 주소·리비전·검증 결과·다음 명령을 뽑아 쓰려면 매번 마크다운을 파싱해야 한다. 같은 상태를 키로 적은 HANDOFF.yaml 을 본문과 함께 쓴다. 둘은 같은 사실을 가리키므로 함께 갱신한다. 한쪽만 고치면 검사기(--pair)가 어긋남을 잡는다.

상황	yaml 을 두는 곳
인프라 없음(파일 모드)	레포 루트 HANDOFF.yaml — HANDOFF.md 옆
인프라 있음	이슈 본문 끝의 ## 기계 판독용 상태 섹션 안 ```yaml 블록 하나. 레포에는 HANDOFF.yaml 을 만들지 않는다

인프라 있음에서 첨부 대신 본문 안에 두는 이유는, 트래커마다 첨부 지원이 달라(Jira·Plane·Slack) 첨부를 쓰면 원본이 둘로 갈라지기 때문이다. 본문 하나가 곧 원본이라는 원칙이 그대로 유지된다.

• 스키마는 아래 본문 템플릿의 ## 기계 판독용 상태 가 원본이다. 프로젝트별 키는 state 밑에 더한다.
• 필수 키는 schema_version·meta·state·last_verification·next_steps 다.
• 날짜·시각·버전은 항상 따옴표로 감싼다. 따옴표가 없으면 YAML 이 2026-10-05 를 날짜로, 1.10 을 1.1 로, yes 를 불리언으로 조용히 바꾼다. 소수는 키 이름에 version·release·revision·tag 가 들어간 값만 따옴표를 요구한다. 진짜 소수 값(progress: 0.5)은 그대로 쓴다.
• 목록은 블록 스타일(- )로 적는다. 같은 키를 두 번 쓰지 않는다. 검사기는 어휘 수준이라 한 줄 흐름 스타일 목록은 항목으로 세지 못하고, 파서는 중복 키의 마지막 값을 쓴다.
• ## 기계 판독용 상태 섹션이 있으면 닫힌 ```yaml 블록이 있어야 한다. 본문 안 yaml 은 같은 본문의 작성·브랜치·HEAD 와 맞춰 본다.
• next_steps 항목마다 대조할 명령(check)을 적는다.
• 값에 시크릿을 넣지 않는다. 키 이름·경로까지만 적는다.
• 검사기는 어휘 수준(필수 키·형 변환 위험·탭)을 보고, PyYAML 이 있으면 실제로 파싱한다.