Runbook de la primera tarea en Claude Code: prompts seguros, revisión diff y handoff

La primera tarea decide si Claude Code se siente seguro

Justo después de instalar Claude Code, es tentador pedir una función completa, una refactorización grande o “arregla todo este repo”. Muchas primeras sesiones fallan ahí. Normalmente el problema no es que Claude Code no pueda ayudar, sino que todavía no están acordados el alcance, la verificación, los permisos y el contexto del proyecto.

Este runbook es para la primera tarea práctica en un repositorio real. Un runbook es una lista de operación repetible. Aquí, la primera tarea no es “construye la función”, sino un flujo pequeño: pedir bien, confirmar el plan, hacer un cambio acotado, revisar el diff y dejar una nota de handoff.

Si todavía estás aprendiendo lo básico, empieza por la guía de inicio de Claude Code. Cuando quieras capturar reglas del proyecto, combínala con las plantillas de CLAUDE.md para Claude Code. Como referencias oficiales, usa Claude Code overview, memory y CLAUDE.md, permission modes, common workflows y la CLI reference.

flowchart LR
  A["Leer el repositorio"] --> B["Proponer 3 opciones seguras"]
  B --> C["Elegir 1 tarea"]
  C --> D["Revisar el plan primero"]
  D --> E["Hacer el diff mínimo"]
  E --> F["Verificar tests y diff"]
  F --> G["Escribir una nota de handoff"]

Qué tiene una buena primera tarea

La primera tarea no se mide por el tamaño del resultado. Sirve para comprobar si puedes seguir confiando en el flujo. Las mejores tareas iniciales tienen cinco rasgos.

Rasgo	Significado simple	Buen ejemplo
Local	No toca producción, datos de clientes ni envíos externos	Revisar comandos del README o añadir una assertion
Acotada	Se ven los archivos y el punto de parada	Un componente, un test, un documento
Verificable	Un comando, página o diff prueba el éxito	`npm.cmd run test`, `git diff --check`
Reversible	Si sale mal, se descarta rápido	Archivos fuente normales, no exports generados
Explicable	Una persona puede seguir la razón del cambio	Razón, riesgo e incertidumbre quedan escritos

Pedir “rehaz la autenticación”, “moderniza todo el código” o “arregla CI y despliega” es mala primera tarea. Mezcla contexto insuficiente, permisos, tests débiles y diffs difíciles de revisar.

Menú de tareas seguras

Para onboarding de equipos, elige desde este menú antes de inventar una tarea.

Tarea	Para qué sirve	Condición de éxito
Mapear el repo	Comprueba comprensión antes de editar	Identifica entry points, comandos y zonas riesgosas
Resumir un test fallido	Muestra la granularidad de debugging	Quedan claros fallo, hipótesis y siguiente paso
Corregir un comando viejo del README	Prueba una edición real de bajo riesgo	El comando corre y el diff es pequeño
Añadir una assertion a un test existente	Evalúa intención y criterio de testing	La assertion protege un comportamiento claro
Cambiar una frase de UI	Comprueba búsqueda y cambio mínimo	Solo cambia el componente objetivo
Corregir una advertencia de lint	Mide disciplina de cambio local	Desaparece una advertencia sin cambiar comportamiento
Crear un `CLAUDE.md` mínimo	Mejora sesiones futuras	Comandos, límites y revisión están escritos de forma breve

La clave es “pequeño pero real”. Debe conectarse con onboarding, diagnóstico de bugs, documentación, tests o calidad de revisión.

Prompts listos para copiar

Empieza pidiendo a Claude Code que lea y proponga, no que edite.

Lee este repositorio y todavía no edites.

Devuelve:
1. entry points principales
2. comandos habituales de build/test/lint
3. directorios riesgosos o archivos generados
4. 3 opciones seguras para una primera tarea de 30 minutos
5. cómo verificar y revertir cada opción

Cuando proponga opciones, elige una y exige plan.

Avanza solo con la opción 2. Todavía no edites.
Primero escribe los archivos que tocarías, la razón del cambio, el diff esperado,
el comando de verificación y los riesgos. Si el alcance crece, propone una opción menor.

Solo entonces autoriza la edición.

Sigue el plan aprobado y haz el diff más pequeño posible.
No toques archivos fuera de la petición.
Después de editar, resume los comandos de verificación ejecutados, checks fallidos u omitidos
y riesgos restantes.

Usa otro prompt para la revisión antes del commit.

Haz una revisión antes del commit.

1. Lee git diff y busca cambios fuera de la petición
2. Detecta tests faltantes o verificación débil
3. Revisa riesgos de seguridad, pérdida de datos y configuración
4. Encuentra archivos que no deberían entrar al commit
5. Señala decisiones que aún debe tomar una persona

Termina con un solo veredicto: "listo para commit", "corregir antes" o "detener".

Flujo de 30 minutos

Dedica los primeros cinco minutos a fijar el estado actual antes de delegar. En Windows PowerShell:

Get-Location
git status --short
git branch --show-current
rg --files | Select-Object -First 40

En macOS o Linux:

pwd
git status --short
git branch --show-current
rg --files | head -n 40

Si el worktree ya está sucio, di qué cambios son humanos y no deben tocarse. Si no lo haces, el diff final será difícil de juzgar.

Usa los siguientes diez minutos para elegir una tarea. Buenas opciones son un comando viejo del README, una assertion en un test o el resumen de un test fallido. Evita funciones nuevas en la primera sesión.

Alrededor del minuto veinte, prioriza prueba sobre más cambios. Un cambio correcto y explicado vale más que tres cambios sin verificar.

git diff --stat
git diff --check
git diff
git status --short

Reserva los últimos cinco minutos para una nota de handoff. Es una nota corta para la siguiente persona o la siguiente sesión de Claude Code. Importa porque las conversaciones largas pueden perder límites, y la próxima sesión necesita un punto limpio de arranque.

Cuatro casos de uso concretos

Caso 1: onboarding de una persona nueva

No entregues un issue grande el primer día. Pide a Claude Code un mapa del repo, comandos clave, directorios peligrosos y primeros archivos para leer.

Prompt: “Crea una nota de onboarding para una persona nueva. Separa hechos de suposiciones. Incluye salida de comandos cuando puedas.” El éxito es que la nota agregue contexto práctico más allá del README, como archivos generados, settings locales o diferencias entre CI y local.

Caso 2: nota de reproducción para un bug visible

Si el bug es “a veces falla”, no empieces por el fix. Pide condiciones, resultado esperado, resultado real, archivos relevantes y logs faltantes. Combina bien con la plantilla de bug report de Claude Code.

El éxito no es un patch. Es una nota que una persona pueda verificar. Si no se reproduce, la salida debe decirlo y listar los logs o datos necesarios.

Caso 3: documentación o texto de UI

Sitios de marketing, herramientas admin y dashboards internos suelen funcionar bien para una primera sesión porque un cambio de texto es visible y reversible. Mantén el alcance: un CTA, una explicación de settings o un párrafo.

El éxito significa que solo cambiaron los archivos objetivo, el significado sigue igual y el resultado se puede revisar localmente. En sitios multilingües, revisa también que no actualizaste un idioma dejando los demás inconsistentes.

Caso 4: mejora pequeña de test

Si el proyecto ya tiene tests, añadir una assertion es más seguro que añadir una función. Añade un caso de borde, una expectativa de mensaje de error o un caso de lista vacía.

Que los tests pasen no basta. Claude Code debe explicar qué comportamiento protege la assertion. Una assertion que no se puede explicar se vuelve ruido de mantenimiento.

Revisión diff antes del commit

Después de que Claude Code edite, vuelve a revisión humana. En la primera tarea, evita commits y pushes automáticos. Los permission modes cambian comodidad por supervisión, así que empieza con revisión normal o plan mode. Evita modos potentes como bypass permissions salvo en entornos aislados.

Checklist antes del commit

[ ] Solo cambiaron los archivos pedidos
[ ] No entraron generados, secretos ni settings locales
[ ] Hay test o verificación alternativa registrada
[ ] Checks fallidos u omitidos están declarados
[ ] No queda diff inexplicable
[ ] La nota de handoff contiene el siguiente TODO

Empieza con git diff --stat para ver el alcance. Ejecuta git diff --check para higiene de whitespace y patch. Luego lee el diff buscando refactors sorpresa, cambios de nombres o cambios de comportamiento sin tests.

Fallos comunes

El primer fallo es el alcance demasiado grande. Di “verifica el mensaje de error de login con un test”, no “arregla login”. Da autonomía cuando ya haya confianza en tareas pequeñas.

El segundo fallo es aceptar “listo” sin prueba. Si no hay tests, define una prueba sustituta: página renderizada, type check, git diff --check, comparación de logs o un comando del README.

El tercer fallo es aprobar prompts de permisos sin mirar. Cuando aparezca uno, pregunta qué comando corre, qué rutas toca y si incluye red o borrado. Si los prompts se repiten, aprueba comandos estrechos en vez de abrirlo todo.

El cuarto fallo es la pérdida de contexto. Las conversaciones largas difuminan el límite inicial. Guarda límite, comandos ejecutados y riesgo restante en la nota de handoff. No mezcles reglas permanentes de CLAUDE.md con notas de una sesión.

El quinto fallo es dañar trabajo no commiteado. En repos compartidos, otra persona u otro agente puede tener cambios. Empieza con git status --short y protege explícitamente los cambios no relacionados.

Plantilla de handoff

Pega esto al final de la primera tarea.

## Handoff note

- Task:
- Changed files:
- Verification run:
- Verification not run:
- Important diff points:
- Remaining risks:
- Do not touch next time:
- Suggested next smallest task:

Esta nota es más amplia que un mensaje de commit. Antes de commit sirve como borrador de PR. Sin commit, sirve como punto de inicio para la siguiente sesión.

Próximos pasos y rutas de pago

Después de que la primera tarea salga bien, crea repetibilidad. Si trabajas solo, convierte reglas recurrentes en plantillas de CLAUDE.md. Si approvals y sandbox todavía no están claros, lee la guía de approval y sandbox de Claude Code.

Para plantillas, checklists y material de onboarding listos para usar, visita /products/. Para despliegue en equipos, onboarding adaptado al repositorio, diseño de permisos y flujos de revisión, usa /training/. Una primera tarea segura se puede resolver con este artículo. Un rollout de equipo necesita reglas, evidencia y formación antes de ampliar el uso.

En la prueba real de Masa, el patrón más estable fue: leer el repo primero, editar solo un archivo, revisar git diff juntos y dejar una nota de handoff. Las sesiones que empezaron con una petición grande generaron más trabajo de revisión del que ahorraron. Las que triunfaron con una tarea de 30 minutos hicieron más fácil acotar la segunda tarea y explicarla al equipo.