---
name: create-handoff
version: 1.0.0
description: 작업을 다른 세션이나 다른 에이전트가 이어받을 수 있도록 핸즈오프 기록을 남기는 공통 스킬. "핸즈오프 남겨", "인수인계 작성", "다른 세션에서 이어가게 정리", "작업을 이어받도록 기록" 같은 요청에 사용한다.
---

# Create Handoff

## 목적

현재 작업 상태를 중단 없이 이어받을 수 있도록 짧고 검증 가능한 핸즈오프 기록을 남긴다.
핸즈오프는 새 구현 계획이나 코드 변경을 시작하는 절차가 아니라, 현재 상태와 다음 진입점을 보존하는 절차다.

## 언제 호출할지

- 사용자가 작업을 다른 세션, 다른 에이전트, 또는 이후 자기 자신이 이어가게 정리해 달라고 할 때
- 긴 작업 중 현재 판단, 변경 파일, 남은 검증, 차단 사항을 지속 가능한 문서에 남겨야 할 때
- 구현을 계속하지 않고 현재 위치만 안전하게 넘겨야 할 때
- 실패한 검증이나 외부 환경 상태를 다음 세션이 오해하지 않도록 남겨야 할 때

## 입력

- `handoff-request`: 사용자가 남기라고 한 핸즈오프 요청 문장 (필수)
- `target`: 현재 작업 대상 Phase, Milestone, plan, review, task group, issue, PR, 파일 경로 등 (선택)
- `evidence`: 이번 세션에서 확인한 명령, 테스트, 로그, 외부 상태, 사용자 결정 (선택)

## 먼저 확인할 것

- [ ] 현재 작업 대상이 명시되어 있으면 해당 활성 문서나 파일을 확인한다.
- [ ] 대상이 없으면 로컬 current, 활성 PLAN/CODE_REVIEW/USER_REVIEW, git diff, 최근 대화 맥락 중 가장 좁은 충분한 대상으로 정한다.
- [ ] 기존 핸즈오프 섹션이나 `HANDOFF.md`가 있으면 새 위치를 만들기 전에 갱신 후보로 본다.
- [ ] archive 경로는 일반 작업에서 읽지 않는다. 사용자가 archive 확인을 명시했거나 활성 문서가 특정 archive evidence를 가리킬 때만 필요한 파일을 좁게 읽는다.
- [ ] secret, token, private endpoint 원문, 서명값, 개인 credential은 핸즈오프에 기록하지 않는다.

## 실행 절차

1. **상태 수집**
   - `git status --short`로 변경 파일과 untracked 파일을 확인한다.
   - 필요한 경우 대상 파일의 diff 또는 관련 문서를 읽어 이번 세션에서 실제로 바뀐 내용과 바뀌지 않은 내용을 분리한다.
   - 실행 중인 서버, 원격 runner, 외부 provider 같은 live 상태가 handoff에 영향을 주면 secret 없이 요약한다.

2. **기록 위치 선택**
   - 활성 Milestone이 작업의 장기 기준이면 해당 Milestone의 `작업 컨텍스트` 아래에 `핸즈오프(<YYYY-MM-DD>)` 항목을 추가하거나 갱신한다.
   - 활성 plan/review/task group이 작업의 실행 기준이면 그 디렉터리의 기존 `PLAN-*.md`, `CODE_REVIEW-*.md`, `USER_REVIEW.md`, 또는 `HANDOFF.md` 중 가장 직접적인 파일에 남긴다.
   - 적절한 활성 문서가 없으면 새 파일을 만들기보다 최종 답변에만 남길지 판단하고, 지속 기록이 필요하면 가장 좁은 활성 작업 디렉터리 아래 `HANDOFF.md`를 만든다.
   - 같은 내용을 여러 곳에 중복 기록하지 않는다. 필요하면 한 곳에 기록하고 다른 문서에는 짧은 링크만 남긴다.

3. **핸즈오프 작성**
   - 현재 타겟과 다음 세션의 첫 진입 파일을 적는다.
   - 이번 세션에서 실제로 한 일과 하지 않은 일을 분리한다.
   - 남은 작업을 실행 순서로 적되, 구현 세부 계획으로 과하게 확장하지 않는다.
   - 검증한 명령과 결과, 생략한 검증과 사유를 남긴다.
   - dirty worktree, untracked 파일, 원격 환경, 외부 provider 상태처럼 다음 세션이 오해하기 쉬운 조건을 남긴다.
   - 사용자 결정이나 명시 금지 사항을 그대로 보존한다.

4. **검증**
   - 수정한 Markdown이나 text 파일에 대해 `git diff --check`를 실행한다.
   - 새 `HANDOFF.md`를 만들었다면 경로가 active 작업 범위 안인지 확인한다.
   - 핸즈오프가 완료/검토중/통과 같은 상태 전환을 암시하지 않는지 확인한다.

5. **결과 보고**
   - 핸즈오프를 남긴 경로를 보고한다.
   - 다음 세션이 바로 열어야 할 파일 1~3개를 보고한다.
   - 검증 명령과 결과를 보고한다.

## 실행 결과 검증

- [ ] 핸즈오프가 지속 가능한 활성 문서나 가장 좁은 작업 디렉터리에 남아 있다.
- [ ] 현재 타겟, 실제 변경, 남은 작업, 검증 상태, 주의사항이 구분되어 있다.
- [ ] secret 또는 credential 원문이 기록되지 않았다.
- [ ] archive 문서를 불필요하게 읽거나 최신 형식으로 재작성하지 않았다.
- [ ] `git diff --check`가 통과했다.
- 검증 실패 시: 핸즈오프 문서만 보완하고, 본 작업 구현이나 상태 전환은 진행하지 않는다.

## 출력 형식

```markdown
## 핸즈오프 완료

- 위치: `<handoff-path>`
- 현재 타겟: `<target>`
- 다음 진입점: `<file-or-command>`
- 검증: `<command>` PASS
- 남은 주의: `<요약 또는 없음>`
```

## 금지 사항

- 핸즈오프 요청만 받았는데 새 구현, 테스트 보강, 리팩터링, 원격 배포를 시작하지 않는다.
- evidence 없이 완료, 검토중, PASS, archive 같은 상태 전환을 하지 않는다.
- secret, token, private signing key, password, 원문 credential을 기록하지 않는다.
- 여러 문서에 같은 핸즈오프 전문을 중복 작성하지 않는다.
- 사용자 또는 다른 에이전트가 만든 unrelated 변경을 되돌리지 않는다.