handoff

name	handoff
description	HANDOFF.md를 작성/업데이트하여 다음 에이전트가 컨텍스트 없이도 작업을 이어받을 수 있게 한다. git 히스토리, 코드베이스, 현재 대화를 분석하여 목표·진행 상황·성공/실패 경험·다음 단계를 정리한다. 트리거 — "handoff", "인수인계", "HANDOFF.md", "핸드오프", "프로젝트 정리", "현재 상태 정리", "다음 세션을 위해 정리", "작업 내용 정리해줘" 등. HANDOFF.md 업데이트 요청 시에도 사용한다.

HANDOFF.md — 에이전트 간 작업 연속성 문서

HANDOFF.md의 목적은 새 에이전트(또는 새 세션의 나)가 컨텍스트 없이 이 문서만 읽고 작업을 이어받을 수 있게 하는 것이다. 사람을 위한 온보딩 문서가 아니라 에이전트를 위한 작업 인계서다.

핵심 원칙

HANDOFF.md에 담아야 하는 것:

• 목표 — 이 프로젝트/작업이 달성하려는 것
• 현재 상태 — 어디까지 왔는지 (되는 것 / 안 되는 것)
• 성공한 접근법 — 다음 에이전트가 따라야 할 패턴
• 실패한 접근법 — 다음 에이전트가 반복하면 안 되는 것 (이유 포함)
• 다음 단계 — 구체적이고 실행 가능한 액션 아이템
• 핵심 기술 결정 — 코드만 봐서는 알 수 없는 "왜"
• 주의사항 — 삽질 포인트, 환경 이슈, 암묵적 제약

HANDOFF.md에 담지 않아야 하는 것:

• 코드를 읽으면 알 수 있는 것 (함수 시그니처, import 관계)
• CLAUDE.md에 이미 있는 코딩 컨벤션
• 변경 가능성이 높은 상세 구현 (코드가 진실의 원천)

실행 흐름

1단계: 정보 수집 (병렬)

a) 기존 HANDOFF.md 확인

• 있으면 → 업데이트 모드 (구조 유지, 변경분만 반영)
• 없으면 → 신규 생성 모드

b) Git 히스토리 분석

git log --oneline --since="<마지막 업데이트 또는 프로젝트 시작>" --reverse

• 기존 HANDOFF.md의 마지막 커밋 이후만 분석
• 관련 커밋은 묶어서 하나의 항목으로 정리

c) 프로젝트 맥락

• 루트 디렉토리 구조, 빌드/실행 스크립트, 환경변수 파일
• README.md, CLAUDE.md 등 기존 문서 참고

d) 현재 대화 컨텍스트

• 이번 세션에서 수행한 작업, 시도한 접근법, 실패 경험
• 사용자가 언급한 향후 계획

2단계: 문서 작성

아래 템플릿을 기반으로 작성한다. 프로젝트 규모와 상황에 맞게 섹션을 조정한다.

문서 구조 템플릿

# {프로젝트명} — Handoff

## 목표
{이 프로젝트가 달성하려는 것 — 1~3줄}

## 현재 상태 ({날짜})

### 완료된 작업
| 커밋 | 내용 |
|------|------|
| `abc1234` | 주요 기능/변경 설명 |

### 동작하는 기능
{현재 실제로 작동하는 기능 목록}

### 알려진 이슈
{현재 발생하는 문제, 미해결 버그}

---

## 성공한 접근법
{효과가 검증된 패턴이나 방식 — 다음 에이전트가 따라야 할 것}

## 실패한 접근법
{시도했지만 실패한 것 — 왜 실패했는지 이유 포함, 다음 에이전트가 반복하지 않도록}

---

## 핵심 기술 결정
{왜 이 기술/구조/방식을 선택했는지 — 코드만 봐서는 알 수 없는 배경}

---

## 실행 방법
{빌드/실행 명령어, 필수 환경변수, 런타임 의존성}

---

## 다음 단계

### 즉시 해야 할 것
{구체적 액션 아이템 — 바로 실행 가능한 수준으로}

### 이후 할 것
{우선순위순 할 일 목록}

---

## 주요 파일 위치
{핵심 파일 디렉토리 트리 — 변경 빈도 높은 파일 위주}

---

## 주의사항
{함정, 환경별 차이, 암묵적 규칙, 디버깅 팁}

업데이트 규칙

기존 HANDOFF.md를 업데이트할 때:

1. 날짜 갱신 — 현재 상태 섹션의 날짜를 오늘로
2. 커밋 추가 — 새 커밋을 완료된 작업에 추가 (관련 커밋은 범위로 묶기)
3. 성공/실패 추가 — 이번 세션에서 발견한 것 반영
4. 다음 단계 갱신 — 완료된 것 제거, 새로 발견된 것 추가
5. 주의사항 추가 — 배포/운영 중 발견된 이슈
6. 사소한 fix는 병합 — 빌드 오류 수정 등은 관련 기능에 합치거나 생략

작성 스타일

• 간결하게 — 문장보다 키워드·구(phrase) 중심
• 구체적으로 — "설정 기능" 대신 "시스템 설정에서 토큰 단가 관리 (USD/1M tokens)"
• 실행 가능하게 — 명령어는 복사해서 바로 쓸 수 있도록
• 커밋 해시 포함 — git show로 상세 확인할 수 있게
• 사용자의 CLAUDE.md에 언어 설정이 있으면 해당 언어로 작성

마무리

문서 저장 후 사용자에게 파일 경로를 알려준다. 새 세션에서 @HANDOFF.md로 바로 컨텍스트를 전달할 수 있다.