Plantilla de handoff en Claude Code: conserva contexto para la siguiente persona o agente

Claude Code se vuelve mucho más útil cuando una sesión puede sobrevivir a un handoff. El fallo habitual no es que Claude Code no encuentre los archivos, sino que el trabajo se corta sin dejar contexto. La herramienta investigó, leyó el diff, descartó hipótesis y quizá aplicó parte del arreglo. Luego alguien escribe “lo seguimos mañana” y la siguiente persona vuelve a empezar casi desde cero.

En este artículo, handoff significa una nota breve de traspaso para que otra persona o un agente de IA continúe con seguridad. No es un diario de todo lo ocurrido. Es un paquete operativo con objetivo, estado actual, archivos relevantes, evidencia de verificación, riesgos pendientes y el próximo prompt que se puede pegar en Claude Code.

Para la base oficial, consulta la documentación actual de Claude Code. How Claude Code works explica el bucle agentic, el acceso al proyecto, el estado de git, las sesiones y el contexto. Memory cubre CLAUDE.md y las instrucciones de proyecto. CLI reference resume el uso de la línea de comandos. Como lectura interna, combina esto con buenas prácticas de CLAUDE.md, flujo de verification receipt y reglas de handoff en equipo.

Modelo mental

Un error común de principiantes es mezclar CLAUDE.md con una nota de handoff. CLAUDE.md guarda reglas duraderas: comandos de build, estándares de código, convenciones de arquitectura, política de revisión y rutas delicadas que Claude Code debe tratar con cuidado en cada sesión.

La nota de handoff guarda el estado temporal de una tarea. Dice qué pasó hoy: qué hipótesis falló, qué archivos importan, qué se verificó, qué no se verificó y qué debería hacer primero la siguiente persona. En lenguaje simple, contexto es el trasfondo del trabajo, verification receipt es el recibo de lo comprobado y harness es el marco operativo que mantiene al agente dentro de límites útiles.

flowchart LR
  A["Goal<br/>Qué resultado importa"] --> B["Current state<br/>Dónde se detuvo"]
  B --> C["Evidence<br/>Qué se verificó"]
  C --> D["Risk<br/>Qué sigue incierto"]
  D --> E["Next prompt<br/>Qué pedir primero"]

Con esa cadena, la siguiente sesión no necesita releer toda la conversación antes de ejecutar un paso útil.

Plantilla 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.

El campo más importante es not checked. Que el build local pase no demuestra que la URL pública, el viewport móvil, el enlace de CTA, el evento de analítica o la traducción estén correctos. Declarar lo no verificado evita que la siguiente sesión trabaje con una falsa sensación de cierre.

Ejemplo JSON estructurado

Si el equipo publica handoffs en GitHub Issues, Slack, Notion o un panel interno, añade un resumen JSON junto a la 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 es cómodo para herramientas, pero no sustituye el juicio humano. Deja el razonamiento en Markdown y usa JSON para estado, archivos, checks y próxima acción.

Script Node.js ejecutable

Guarda este archivo como scripts/write-handoff.mjs. Usa solo módulos integrados de Node.js, lee el estado actual de git y crea una nota fechada en 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}`);

Comprueba la sintaxis y luego ejecútalo:

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

Casos de uso prácticos

El primer caso es publicación de contenido multilingüe. Cuando un slug tiene archivos en japonés, inglés, chino, coreano, español, francés, alemán, portugués, hindi e indonesio, el problema no es editar un archivo. El problema es recordar qué locale aún necesita revisión de naturalidad, escaneo de mojibake, longitud de description, enlaces internos y CTA hacia /products/ y /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.

El segundo caso es una investigación de bug que se detiene a mitad. Si el hallazgo real es “a 390px el CTA se desborda porque la tarjeta de precios conserva un min-width fijo”, escribe eso. “Miré CSS” obliga a repetir el análisis.

El tercer caso es revisión de código riesgosa. Autenticación, pagos, migraciones de base de datos y permisos necesitan una nota que diga qué riesgos ya se revisaron, qué tests faltan y quién debe aprobar antes de mergear.

El cuarto caso es trabajo paralelo con varias personas o agentes. Si otros workers están editando otros slugs o ramas, el handoff debe decir qué archivos están dentro del alcance y cuáles no se deben tocar.

Fallos que debes evitar

Fallo uno: listar rutas sin explicar por qué importan. site/src/pages/products.astro es menos útil que “el min-width de la tarjeta de precio causa overflow a 390px”.

Fallo dos: registrar solo checks exitosos. npm run build puede pasar aunque la URL pública, el layout móvil, el tracking de clics, el formulario o una traducción estén mal.

Fallo tres: escribir un resumen largo de conversación en vez de una nota de siguiente paso. Termina siempre con un prompt que alguien pueda pegar en Claude Code.

Fallo cuatro: filtrar información privada. No pegues API keys, datos de clientes, precios internos ni enlaces privados de incidentes. Usa nombres de secrets o referencias seguras.

CTA y monetización

En un sitio como ClaudeCodeLab, la calidad técnica y el camino de monetización van juntos. Si el artículo pierde enlaces internos, recursos gratuitos, productos o consulta, el lector no sabe qué hacer después. Un lector individual puede empezar con la hoja gratuita. Quien necesite plantillas y checklists puede revisar products. Los equipos que quieren diseñar CLAUDE.md, permisos, revisión, verification receipts y handoffs en un repositorio real deberían mirar Claude Code training and consultation.

El hábito cuesta 30 segundos: antes de cerrar la sesión, escribe objetivo, estado, evidencia, checks pendientes y próximo prompt. Al probarlo en el flujo de publicación de Masa, el beneficio principal fue dejar de buscar al día siguiente dónde se había detenido la sesión anterior.