Template de handoff de sessão no Claude Code: preserve contexto para a próxima pessoa ou agente

Claude Code fica muito mais útil quando uma sessão consegue sobreviver a um handoff. O problema comum não é o agente não encontrar os arquivos. Ele encontra, lê o diff, reduz as hipóteses, talvez aplique parte da correção, e a sessão termina com “continuamos amanhã”. A próxima pessoa precisa reconstruir o contexto.

Neste artigo, handoff significa uma nota curta de passagem de trabalho para outro humano ou para a próxima sessão de AI agent. Não é um diário. É um pacote operacional com objetivo, estado atual, arquivos relevantes, evidência de verificação, riscos restantes e o próximo prompt para colar no Claude Code.

Para a base oficial, use a documentação atual do Claude Code. How Claude Code works explica o loop agentic, acesso ao projeto, estado do git, sessões e contexto. Memory cobre CLAUDE.md e instruções de projeto. CLI reference documenta o uso por linha de comando. No ClaudeCodeLab, leia também CLAUDE.md best practices, verification receipt workflow e team handoff rules.

O modelo mental

Iniciantes costumam misturar CLAUDE.md com a nota de handoff. CLAUDE.md guarda regras duráveis do projeto: comandos de build, padrões de código, decisões de arquitetura, critérios de review e caminhos sensíveis.

A nota de handoff guarda o estado temporário da tarefa. Ela registra o que aconteceu hoje: qual hipótese falhou, quais arquivos importam, o que foi verificado, o que ainda não foi verificado e o que a próxima sessão deve pedir primeiro. Em termos simples, contexto é o pano de fundo do trabalho, verification receipt é o recibo do que foi testado, e harness é a estrutura que mantém o agent dentro de limites úteis.

flowchart LR
  A["Goal<br/>Qual resultado importa"] --> B["Current state<br/>Onde o trabalho parou"]
  B --> C["Evidence<br/>O que foi verificado"]
  C --> D["Risk<br/>O que ainda é incerto"]
  D --> E["Next prompt<br/>O que pedir primeiro"]

Com essa cadeia, a próxima pessoa não precisa reler toda a conversa antes de executar um passo útil.

Template Markdown para copiar

# Claude Code session handoff

## Goal
- target outcome:
- explicitly out of scope:

## Current state
- branch:
- dirty files:
- related URL:
- what is known:

## What changed
- changed files:
- reason for change:
- important files not touched:

## Verification receipt
- commands run:
- result:
- manual checks:
- not checked:

## Risks and constraints
- fragile area:
- do not touch:
- requires approval:

## Next prompt
In the next session, compare git status with this handoff, then continue from the unchecked verification items.

O campo mais importante é not checked. Um build local passando não prova que a URL pública, o layout mobile, o link de CTA, o evento de analytics ou a tradução estão corretos. Declarar o que falta verificar torna a próxima sessão menor e mais segura.

Exemplo JSON estruturado

Se sua equipe envia handoffs para GitHub Issues, Slack, Notion ou um painel interno, mantenha um resumo JSON ao lado da nota Markdown.

{
  "slug": "claude-code-session-handoff-template",
  "goal": "Improve the published multilingual article group",
  "status": "draft updated, verification pending",
  "files": [
    "site/src/content/blog/claude-code-session-handoff-template.mdx",
    "site/src/content/blog-en/claude-code-session-handoff-template.mdx"
  ],
  "checksRun": ["frontmatter parse", "code fence scan"],
  "checksMissing": ["production URL check"],
  "nextAction": "Run targeted validation and review locale copy"
}

JSON é ótimo para ferramentas, mas não substitui o raciocínio humano. Use Markdown para contexto e decisões. Use JSON para estado, arquivos, checks e próxima ação.

Script Node.js executável

Salve o código abaixo como scripts/write-handoff.mjs. Ele usa apenas módulos nativos do Node.js, lê o estado atual do git e cria um Markdown datado em handoffs/.

import { execSync } from "node:child_process";
import { mkdirSync, writeFileSync } from "node:fs";
import { join } from "node:path";

function run(command) {
  try {
    return execSync(command, { encoding: "utf8" }).trim() || "(no output)";
  } catch (error) {
    return `ERROR: ${error.message}`;
  }
}

const date = new Date().toISOString().slice(0, 10);
const branch = run("git branch --show-current");
const status = run("git status --short");
const recentCommit = run("git log -1 --oneline");
const outDir = "handoffs";
const outFile = join(outDir, `${date}-session-handoff.md`);

mkdirSync(outDir, { recursive: true });

const body = `# Claude Code session handoff

## Goal
-

## Current state
- branch: ${branch}
- recent commit: ${recentCommit}
- dirty files:
\`\`\`text
${status}
\`\`\`

## What changed
-

## Verification receipt
- commands:
- result:
- missing:

## Risks and constraints
-

## Next prompt
Read this handoff, compare it with git status, and continue from the missing verification items.
`;

writeFileSync(outFile, body, "utf8");
console.log(`Wrote ${outFile}`);

Verifique a sintaxe e execute:

node --check scripts/write-handoff.mjs
node scripts/write-handoff.mjs

Casos práticos de handoff

O primeiro caso é publicação de conteúdo multilíngue. Quando um slug tem arquivos em japonês, inglês, chinês, coreano, espanhol, francês, alemão, português, hindi e indonésio, o desafio é lembrar quais locales ainda precisam de revisão de naturalidade, varredura de mojibake, tamanho de description, links internos e CTAs para /products/ e /training/.

## Goal
- raise the 10-locale article group for slug claude-code-session-handoff-template to publish quality

## Current state
- Japanese canonical body updated
- English and Indonesian reviewed for natural tone
- zh, ko, and hi still need mojibake scan

## Verification receipt
- frontmatter parse: pass
- JSON code block parse: pass
- production URL: not checked

## Next prompt
Check the remaining locale files for mojibake, description length, and missing CTA links. Report only unresolved items.

O segundo caso é uma investigação de bug interrompida. Se a descoberta real foi “em 390px o CTA estoura porque o card de preço mantém min-width fixo”, escreva isso. “Olhei CSS” obriga a próxima pessoa a repetir a investigação.

O terceiro caso é review de código arriscado. Autenticação, cobrança, migração de banco e permissões precisam dizer quais riscos já foram vistos, quais testes faltam e quem deve aprovar antes do merge.

O quarto caso é trabalho paralelo com várias pessoas ou agents. Se outros workers estão editando outros slugs ou branches, o handoff precisa deixar claro quais arquivos estão no escopo e quais não devem ser tocados.

Falhas comuns

Falha um: listar caminhos sem explicar o motivo. site/src/pages/products.astro é menos útil do que “o min-width do card de preço causa overflow em 390px”.

Falha dois: registrar apenas checks bem-sucedidos. npm run build pode passar mesmo com URL pública, mobile, tracking de clique, formulário ou tradução errados.

Falha três: escrever um resumo longo de conversa. Se a próxima ação não aparece, a nota só aumenta o tempo de leitura.

Falha quatro: colar dados privados. API keys, dados de clientes, preços internos e links privados de incidentes não pertencem a uma nota reutilizável.

CTA e monetização

Em um site como ClaudeCodeLab, qualidade técnica e caminho de monetização andam juntos. Se o artigo perde links internos, recurso gratuito, produtos ou consulta, o leitor fica sem próximo passo. Leitores individuais podem começar pelo material gratuito. Quem quer templates e checklists pode ver products. Equipes que precisam desenhar CLAUDE.md, permissões, review gates, verification receipts e handoffs em um repositório real devem usar Claude Code training and consultation.

O ritual leva 30 segundos: objetivo, estado atual, evidência, checks pendentes e próximo prompt. No fluxo de publicação de Masa, o principal ganho foi parar de perder tempo procurando onde a sessão anterior tinha parado.