핸드오프
새로운 세션은 현재 세션보다 더 나은 QA와 리뷰를 수행합니다. 컨텍스트가 적고 코드에 대한 애착이 없기 때문입니다. 이는 의도적인 실천이며, 핸드오프의 성패에 달려 있습니다. 이 스킬은 모든 핸드오프를 그 수준으로 만듭니다.
운영 원칙
- 사실은 기억이 아니라 검증된 것입니다. 블록의 모든 개수, 경로, ID는 지금 실행된 명령어에서 비롯됩니다:
git rev-list --count origin/<branch>..HEAD,git worktree list,ls QA-<slug>.md, QA 파일에서 가져온 fixture ID. 개수가 5인데 "3개의 커밋이 푸시되지 않았을 수 있습니다"라고 말하면 다음 세션은 잘못된 방향으로 진행됩니다. - 읽는 사람은 블록만 가지고 있습니다. "como vimos"나 이 채팅에 대한 언급은 없습니다. 호출할 스킬, 읽을 파일, 실행할 명령어를 지정합니다.
- 기본적으로 채팅에 표시됩니다. 블록은 복사-붙여넣기를 위해 펜스 처리된 코드 블록으로 채팅에 렌더링됩니다.
HANDOFF-<slug>.md파일 (임시 루트 파일,profile.ephemeral_patterns: gitignored, 절대 커밋되지 않음)은 사용자가 파일을 요청하거나 블록이 약 60줄을 초과할 때만 생성됩니다. - 프로덕션에 영향을 미치는 단계는 이름과 함께 이유가 명시됩니다. "8단계 조심"이 아니라 무엇을, 어디에 쓰는지, 그리고 왜 되돌릴 수 없는지 설명합니다.
- 다른 곳과 마찬가지로 PII 규율을 따릅니다: ID와 이름만; 이메일은 업무 식별자이므로 나타날 수 있음; 주민등록번호, 전화번호, 주소는 절대 안 됩니다.
사용 시기
cdv-finalize마무리 (이 템플릿을 사용하여 QA 핸드오프 자체를 출력합니다).- 사용자가 다른 세션에서 조사를 계속하거나, 리뷰를 실행하거나, QA를 실행하기 위한 프롬프트를 요청합니다.
- 세션의 컨텍스트가 커져서 (압축 임박, "점점 길어지고 있습니다") 세션을 버려야 할 상황이 됩니다.
워크플로우
0단계 — 프로필과 확장 프로그램 로드
.claude/harness/profile.yaml을 읽고,profile.local.yaml이 있으면 함께 읽습니다 (로컬 키가 우선).profile.yaml이 없으면 중단하고 알립니다: 이 스킬은 저장소의 cdv-harness 프로필이 필요하며, 값을 추측하지 않습니다.<profile.extension_dir>/cdv-handoff.md가 있으면 읽습니다. 확장 프로그램은 추가하거나 제한만 합니다; 이 스킬과 확장 프로그램이 다르면 이 저장소의 경우 확장 프로그램이 우선합니다. 아래에서profile.<key>는 프로필의 값입니다. 키가 없거나none이면 저장소에 해당 항목이 없는 것입니다: 해당 단계를 건너뜁니다.
1단계 — 종류 결정 및 사실 수집 (모두 읽기 전용)
종류 ∈ qa | review | investigation | continue-implementation. 그런 다음 실행하고 원시 출력을 유지합니다:
git branch --show-current
git worktree list --porcelain
git rev-list --count origin/<branch>..HEAD 2>/dev/null # 푸시되지 않은 커밋 (원격이 없으면 '?')
git rev-list --count HEAD..origin/<profile.default_branch> # 기본 브랜치보다 뒤처짐
git status --porcelain | grep -v '^??' # 추적되지 않은 커밋되지 않은 파일
ls QA-<slug>.md STATE-<slug>.md <slug>-pr.md decisions-<slug>.md 2>/dev/null
grep -n 'PRODUCTION-AFFECTING' QA-<slug>.md 2>/dev/null
qa의 경우: fixture는 QA 파일 자체의 단계에서 가져옵니다 (ID + 표시 레이블, cdv-interactive-qa에 필요한 방식). review의 경우: cdv-code-review/scripts/resolve-ticket-id.sh를 통한 티켓 ID와 <profile.pr_review_dir_prefix><TICKET>/가 이미 존재하는지 여부. investigation의 경우: cdv-debug 보고서의 가설 블록과 증거 테이블을 그대로 가져옵니다. continue-implementation의 경우: STATE-<slug>.md의 단계 상태, ## Finalize seed, ## Verificação 존재 여부.
2단계 — 블록 렌더링
펜스 처리된 코드 블록, profile.language_ui로 (아래 PT-BR 섹션 제목은 그대로 유지), 이 순서대로; 섹션이 완전히 비어 있을 때만 섹션을 삭제하고 그렇게 명시합니다 (Sem fixtures pré-consultadas.):
<VERBO> da branch <branch> (<uma frase do que ela entrega>).
ONDE ESTÁ O CÓDIGO
- <worktree path | checkout principal `profile.main_checkout`>
- <N> commits à frente de origin/<profile.default_branch>; <M> commits NÃO pushados (confira: git rev-list --count origin/<branch>..HEAD)
- <uncommitted tracked files, or "árvore limpa">
ARMADILHA DO AMBIENTE (코드가 워크트리에 있고 `profile.worktree_runner`가 `none`이 아닌 경우에만)
- O worktree não tem o ambiente do checkout principal (dependências, `.env`); `profile.cmd_container_exec` testa o checkout principal, não este.
- Todo gate por: <profile.worktree_runner> <worktree> <comando de teste> <filtro>
- Para QA na tela: trazer a branch com <profile.bring_branch_script> --check <branch> e depois sem --check. Se recusar, PARE e pergunte — é WIP de outra sessão. Nunca git stash.
- Baseline atual: <N passed (M assertions)>, formatador <PASS>, análise estática <OK>.
O QUE FAZER
- Invoque a skill <cdv-interactive-qa | cdv-code-review | cdv-debug | cdv-plan-feature>.
- <roteiro/arquivo a ler, with path> | <ticket id> | <report to start from>
FIXTURES REAIS (validadas em <data>)
- <entidade> <id> (<label como a tela mostra>) — <estado que interessa>
- ...
PASSOS QUE ESCREVEM FORA DO LOCAL [PRODUCTION-AFFECTING]
- Passo <n>: escreve <o quê> em <sistema externo, de `profile.production_writing_integrations`>; irreversível porque <motivo>. Só o usuário roda, depois de confirmar <o quê>.
- (ou) Nenhum — tudo é leitura ou escrita só no banco local.
CONTEXTO QUE MUDA A EXPECTATIVA
- <버그처럼 보일 수 있는 한두 가지 사실: "export 명령이 결정에 따라 exit 0으로 종료됨", "export는 새벽에만 실행됨 — 수동 명령어로 테스트하는 것이 정상">
NÃO FAÇA
- Não troque a branch do checkout principal por cima de WIP alheio; não use git stash.
- <사용자가 제외한 모든 것: "중복된 두 레코드를 조사하지 마십시오">
<VERBO>는 Rode o QA interativo, Faça o code review, Continue a investigação 또는 Continue a implementação입니다.
3단계 — 출력 전 자체 점검
- 모든 숫자는 1단계의 명령어에서 비롯되었습니다 (트리가 변경된 경우 다시 실행).
- 모든 경로가 존재합니다 (
ls). - 이 채팅 없이도 이해할 수 있는 문장입니다.
- PRODUCTION-AFFECTING 섹션이 있습니다 (내용 포함 또는 "Nenhum").
구성
cdv-finalize— 마무리 시qa종류를 이 템플릿을 사용하여 출력합니다; finalize 후에 이 스킬이 단독으로 호출되면 상태 보고서의 숫자를 다시 파생하지 않고 재사용합니다.cdv-interactive-qa,cdv-code-review,cdv-debug,cdv-plan-feature— 수신자입니다. 블록은 호출할 스킬을 지정합니다.cdv-code-review타사 모드 — 동료의 PR에 대한 리뷰 핸드오프는 명시적으로 표시합니다 (branch de terceiro: sem apply-review).
예시 (qa 종류, 요약)
Rode o QA interativo da branch fix/export-stale-file (o export escrevia o arquivo de ontem
depois de uma nova execução manual; agora grava o arquivo do dia e remove o anterior).
ONDE ESTÁ O CÓDIGO
- worktree .claude-worktrees/export-stale-file
- 5 commits à frente de origin/<branch padrão>; 2 NÃO pushados (git rev-list --count origin/fix/export-stale-file..HEAD)
- árvore limpa
ARMADILHA DO AMBIENTE
- Worktree sem o ambiente do checkout principal: gates pelo executor de worktree; para a tela, o script de trazer a branch com --check primeiro.
- Baseline: suíte de testes verde, formatador PASS, análise estática OK.
O QUE FAZER
- Invoque cdv-interactive-qa; roteiro em QA-export-stale-file.md (6 passos).
FIXTURES REAIS (validadas na data do handoff)
- relatório 7 (Vendas — semana) — exportado ontem, o arquivo antigo ainda existe (o caso a reparar)
- relatório 8 (Estoque — semana) — nunca exportado (o caso limpo)
PASSOS QUE ESCREVEM FORA DO LOCAL
- Passo 4: o one-off LÊ a API externa real (uma chamada por item) para conferir os totais; nunca escreve nela. Se algo sugerir escrita, pare.
- Nenhum outro — o export grava só no disco local.
CONTEXTO QUE MUDA A EXPECTATIVA
- O export roda só de madrugada — testar com o comando manual é o esperado.
NÃO FAÇA
- Não troque a branch do checkout principal por cima de WIP alheio; não use git stash.