/handoff — 교차 도구 작업 이관
어떤 AI 코딩 도구도 다른 도구의 대화 기록을 읽을 수 없습니다: Claude Code는 세션을 ~/.claude/projects/<변형된-cwd>/<uuid>.jsonl에 잠그고, Codex/OpenCode는 자체 저장소에, Antigravity는 암호화된 .pb에 저장합니다. 도구 간에 이식 가능한 유일한 것은 자체 포함된 문서입니다. 이 스킬은 그 문서를 작성합니다 — 현재 목표, 결정 사항, 그리고 정확한 미커밋 편집 내용을 포함하여 — 다른 AI 에이전트가 다시 설명할 필요 없이 중단한 지점에서 작업을 계속할 수 있도록 합니다.
이 스킬을 사용해야 할 때 사용자가 토큰이 부족할 때, 작업 중간에 도구를 전환하려 할 때, 다른 머신으로 이동할 때, 또는 "handoff" / "continue elsewhere" / "out of tokens"라고 말할 때입니다.
이 스킬은 자체 포함되어 있습니다: git + 셸만 있으면 작동합니다. PATH에 specweave 바이너리가 있을 때 선택적 가속기로 specweave handoff를 호출합니다(고정밀, 증분 인식) — 하지만 SpecWeave 설치에 대한 하드 의존성은 없습니다.
결정: 어떤 경로를 선택할지
command -v specweave >/dev/null 2>&1 && echo "ACCELERATOR" || echo "STANDALONE"
- 가속기 (PATH에
specweave있음) → 엔진을 실행하고 출력을 표시합니다. 경로 A로 이동합니다. - 독립 (
specweave없음) →git+ 짧은 인터뷰를 통해 직접 문서를 작성합니다. 경로 B로 이동합니다.
두 경로 모두 동일한 문서 형식과 동일한 붙여넣기 프롬프트를 출력하므로(아래 표준 템플릿 참조), 어느 경로로 생성되었든 모든 도구에서 이관을 계속할 수 있습니다.
경로 A — 가속기 (PATH에 specweave 있음)
엔진을 실행하고, 저렴하게 제공할 수 있는 짧은 컨텍스트를 전달합니다:
specweave handoff [증분Id] [--reason "..."] [--summary "..."] [--next "..."] [--gotcha "..."] [--decision "..."] [--inline]
그런 다음 stdout을 그대로, 순서대로 표시합니다(재정렬하거나 의역하지 마십시오):
- 절대 문서 경로를 일반 텍스트로 (첫 번째), 2. 클릭 가능한 마크다운 링크, 3.
.diff경로, - 펜싱된 복사-붙여넣기 재개 프롬프트, 5. 도구별 "소스 세션 찾기" 팁.
완료. 엔진이 작업 공간 감지, 작업/AC 파싱, git 캡처, 전체 diff 덤프, 비밀 정보 스크러빙, 렌더링을 처리했습니다.
경로 B — 독립 (specweave 없음)
셸만 사용하여 바이트 호환 문서를 작성합니다.
B1. git 상태 캡처 (무료 — 토큰 불필요)
ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
mkdir -p "$ROOT/.handoff"
printf '*\n' > "$ROOT/.handoff/.gitignore" # handoff나 그 diff가 git에 들어가지 않도록 함
BRANCH="$(git -C "$ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo '(no git)')"
SHA="$(git -C "$ROOT" rev-parse --short HEAD 2>/dev/null || echo '(no commits)')"
STATUS="$(git -C "$ROOT" status --porcelain 2>/dev/null)"
STAT="$(git -C "$ROOT" diff --stat 2>/dev/null)"
# 전체 미커밋 편집 → 형제 .diff (작업 트리 + 스테이징), 핵심 정확성 아티팩트
{ git -C "$ROOT" diff HEAD 2>/dev/null; git -C "$ROOT" diff --cached 2>/dev/null; } > "$ROOT/.handoff/handoff.diff"
B2. 다섯 가지 질문 인터뷰 (파생 불가능한 필드만)
사용자에게 질문하세요 (~5개의 짧은 문자열로 유지 — 토큰이 부족해도 저렴함):
- reason — 왜 이관하나요? (예: "토큰 부족")
- summary — 한 줄: 현재 상황은 어떤가요?
- next — 정확한 다음 단계는 무엇인가요?
- gotcha — 다음 에이전트가 절대 하지 말아야 하거나 / 알아야 할 사항이 있나요?
- decisions — 이미 내린 주요 결정 사항 (세미콜론으로 구분).
B3. 비밀 정보 스크러빙 (쓰기 전 — 일반 텍스트와 diff 모두)
일치 항목을 [REDACTED-<type>]으로 바꾸고 패턴별로 개수를 셉니다. 패턴 (12개):
sk-, ghp_, gho_, ghs_, AKIA, ASIA, -----BEGIN, vsk_, xox[bap]-, Bearer , password=, api_key=.
# 캡처된 diff를 제자리에서 스크러빙, 예:
sed -i.bak -E \
-e 's/sk-[A-Za-z0-9_-]+/[REDACTED-sk]/g' \
-e 's/gh[pos]_[A-Za-z0-9_-]+/[REDACTED-gh-token]/g' \
-e 's/(A[KS]IA[0-9A-Z]{16})/[REDACTED-aws-key]/g' \
-e 's/vsk_[A-Za-z0-9_-]+/[REDACTED-vsk]/g' \
-e 's/xox[bap]-[A-Za-z0-9-]+/[REDACTED-slack]/g' \
-e 's/Bearer [A-Za-z0-9._-]+/Bearer [REDACTED-bearer]/g' \
-e 's/(password=)[^[:space:]]+/\1[REDACTED-password]/g' \
-e 's/(api_key=)[^[:space:]]+/\1[REDACTED-api_key]/g' \
"$ROOT/.handoff/handoff.diff" && rm -f "$ROOT/.handoff/handoff.diff.bak"
스크러빙은 휴리스틱입니다 — 빈 수정 목록이 파일이 깨끗하다는 것을 보장하지는 않습니다.
B4. 문서 작성
아래 표준 템플릿을 $ROOT/.handoff/HANDOFF.md에 작성하고, 캡처된 + 인터뷰 필드를 채웁니다.
소유권 센티넬: 루트 ./HANDOFF.md가 이미 존재하고 Doc format v1 마커를 포함하지 않으면, 외부 파일입니다 — 덮어쓰지 말고 .handoff/HANDOFF.md에 작성하십시오(여기가 기본값입니다).
B5. 출력 — 절대 경로 우선, 이 순서로
.handoff/HANDOFF.md의 절대 경로를 일반 텍스트로.- 해당 파일에 대한 클릭 가능한 마크다운 링크.
.handoff/handoff.diff의 절대 경로.- 펜싱된 붙여넣기 프롬프트 (아래 참조).
- 도구별 "소스 세션 찾기" 팁.
표준 handoff 문서 템플릿 (인라인 — 단일 진실 공급원)
다음 섹션을 이 정확한 순서로 렌더링하고, Doc format v1 푸터 마커로 끝냅니다. 대괄호 자리 표시자는 캡처된 git 상태 + 인터뷰로 채워집니다. 이는 specweave의 handoff-doc-format.ts를 미러링하므로 여기서 생성된 문서는 CLI에서 생성된 문서와 바이트 호환됩니다.
# 작업 이관[: <알려진 경우 제목>]
- 문서 경로: <ABSOLUTE_DOC_PATH>
- 문서 링크: [<ABSOLUTE_DOC_PATH>](<ABSOLUTE_DOC_PATH>)
- Diff 파일: <ABSOLUTE_DIFF_PATH>
- 생성일: <ISO_TIMESTAMP>
- 작업 공간: <ROOT> (비-SpecWeave)
- Git: 브랜치 `<BRANCH>` @ `<SHA>`
## 내가 중단한 지점
**이관 사유:** <reason>
**요약:** <summary>
_활성 SpecWeave 증분 없음 — git + 인터뷰 handoff입니다._
## 완료 / 보류
_증분 작업/AC 상태 없음._
## 주요 결정 사항 및 주의 사항
- <decision 1>
- <decision 2>
**주의 사항:** <gotcha>
## 수정된 파일
**미커밋** — 파괴적인 작업을 하기 전에 커밋, 스태시 또는 편집을 계속하십시오.
<git status --porcelain>
<git diff --stat>
전체 미커밋 diff: `<ABSOLUTE_DIFF_PATH>` — 읽거나 `git apply --check`를 실행하여 정확한 편집 내용을 확인하십시오.
## 정확한 다음 단계
<next>
## 재개 방법
위의 문서 경로가 이 문서를 읽고 있는 머신에 존재하지 않으면, 중단하고 사용자에게 handoff를 붙여넣도록 요청하십시오 — 컨텍스트를 임의로 구성하지 마십시오.
원본 대화 기록을 복구하려면(선택 사항), 도구별로 소스 세션을 찾으십시오:
### Claude Code
- 세션 찾기: ls ~/.claude/projects/<변형된-cwd>/ (변형: 모든 비알파벳숫자 문자 → "-", 실행은 축소되지 않음; 예: /Users/antonabyzov/Projects/github/specweave-umb/.claude-worktrees/x → -Users-antonabyzov-Projects-github-specweave-umb--claude-worktrees-x)
- 재개: `claude -r <uuid>`
### Codex
- 세션 찾기: ls ~/.codex/sessions/ (가장 최근 디렉토리 = 가장 최근 세션)
- 재개: `codex resume <uuid> (또는: codex resume --last)`
### OpenCode
- 세션 찾기: opencode sessions list
- 재개: `opencode -s <id> (긴 형식: opencode --session <id>)`
### Gemini CLI
- 세션 찾기: Gemini 세션 내에서 /chat list를 실행하여 저장된 태그 확인
- 재개: `/chat resume <tag>`
### Antigravity
- 세션 찾기: Antigravity 에이전트 관리자를 열고 이전 작업 스레드 선택
- 재개: `Antigravity 에이전트 관리자에서 스레드 재개`
### Aider
- 세션 찾기: aider는 리포지토리 루트에 .aider.chat.history.md를 유지합니다.
- 재개: `aider --restore-chat-history`
## 수정 사항
- <N> `<type>` 문자열 마스킹됨
_스크러빙은 휴리스틱입니다(정규식 기준). 빈 수정 목록이 이 파일이 깨끗하다는 것을 보장하지는 않습니다 — 공유하거나 커밋하기 전에 검토하십시오._
---
<!-- Doc format v1 -->
템플릿 참고 사항:
- 미커밋 변경 사항이 없으면 Files Touched 본문을
_작업 트리 깨끗함 — 미커밋 편집 없음._(또는 git이 없을 때_git 리포지토리가 아님 — diff가 캡처되지 않음._)으로 바꿉니다. - 결정 사항이 없으면 Key Decisions 본문은
_기록된 결정 사항 없음._입니다; gotcha가 제공되지 않았으면 Gotcha: 줄을 생략합니다. - 마스킹된 항목이 없으면 Redaction 본문은
_토큰과 유사한 문자열이 감지되지 않았습니다._입니다. - 푸터 마커
<!-- Doc format v1 -->는 필수이며 마지막 줄이어야 합니다 — 이것이 소유권 센티넬입니다.
붙여넣기 프롬프트
기본 (파일 접근 가능):
내 작업을 재개하십시오. 다음 위치에서 handoff 문서를 읽으십시오: <ABSOLUTE_DOC_PATH>
해당 경로가 이 머신에 존재하지 않으면, 중단하고 handoff를 붙여넣도록 요청하십시오 — 컨텍스트를 임의로 구성하지 마십시오.
정확한 미커밋 편집 내용은 다음 파일에 있습니다: <ABSOLUTE_DIFF_PATH>
--inline (머신 간, 파일 접근 불가): 전체 문서 본문을 마커 사이에 포함시켜 프롬프트 자체에서 이동할 수 있도록 합니다:
아래의 자체 포함된 handoff를 사용하여 내 작업을 재개하십시오.
이것은 전체 handoff 문서입니다 — 마커 사이의 모든 것을 진실로 간주하십시오. `.diff` 경로가 이 머신에 존재하지 않으면 diff를 붙여넣도록 요청하십시오.
BEGIN HANDOFF
<렌더링된 전체 handoff 문서, Doc format v1 푸터 포함>
END HANDOFF
안전 기본값
- 문서 + diff는 기본적으로 gitignored됩니다(
.handoff/.gitignore=*) 절대 자동 커밋되지 않습니다.git add힌트를 출력하지 마십시오. - 비밀 정보 스크러빙은 쓰기 전에 일반 텍스트와 diff 모두에 대해 실행됩니다.
- 스크러빙은 휴리스틱입니다 — 공유하거나 커밋하기 전에 사용자에게 검토를 권고하십시오.