Revisión de 3 minutos antes del commit: confirma qué tocó Claude Code

Un viernes por la tarde le pedí a Claude Code algo mínimo: “solo cambia el texto del botón del artículo”. Cuando volví y miré git status, había 18 archivos modificados. Lo que debía ser un simple cambio de texto traía además el mapa de enlaces de productos, los artículos relacionados insertados y, “ya que estaba”, también un par de archivos de traducción.

Cada cambio, por separado, era “algo que hizo para ayudar”. Pero si los hubiera enviado todos tal cual, habría arrastrado correcciones sin guardar de otra tarea en la que estaba trabajando, y al día siguiente habría quemado media jornada persiguiendo un error sin causa aparente en el despliegue.

Cuanto más lista es una IA, más se sale del alcance que le pediste. No lo hace con mala intención. Justo por eso hace falta esa pausa de “para aquí y deja que un humano lo mire con sus ojos” en el instante antes de confirmar.

Puntos clave

Aunque Claude Code sea fiel a la petición, el rango de archivos que toca se ensancha en silencio. La revisión previa al commit es el trabajo de cazar ese “desbordamiento”.
La revisión sigue un orden fijo de 3 minutos: confirmar el alcance → revisar el diff → verificar → hacer stage eligiendo archivos. Cuatro pasos.
A la IA le delegas “ejecutar el cambio”; el humano decide “hasta dónde incluir en este commit”. No mezcles esas dos cosas.
Te dejo un script para copiar y pegar. Muestra git status y el resumen del diff en una sola pantalla para reducir lo que se te escapa.
Que el build pase no es motivo para relajarte. El resultado tras publicar y el contenido de las traducciones necesitan otro par de ojos.

Por qué poner la revisión justo antes de confirmar

El mejor momento para revisar no es antes de empezar ni a mitad del trabajo, sino justo antes del commit. La razón es sencilla: solo en ese instante queda fijada la imagen completa de los archivos que la IA tocó de verdad.

Por más que antes de empezar le digas “toca solo esto”, la IA durante el trabajo decidirá meter mano en lo que juzgue que “conviene arreglar de paso”. Si la paras a mitad, como el trabajo no está cerrado, no sabes qué mirar. Cuando todo ha terminado y estás a un paso de confirmar: ahí es cuando por fin puedes contrastar “lo que pediste” contra “lo que realmente cambió”.

Lo que más me suele costar accidentes es la parte que toca los ingresos. Por ejemplo, si un enlace a la página de un producto se desplaza una sola letra, el lector que hace clic acaba en un “página no encontrada”. Por buena que sea la calidad del texto, si el destino del enlace está roto, ahí termina la oportunidad de venta. Por eso, al revisar el diff, lo primero que compruebo es si los destinos de los enlaces han cambiado.

Si todavía no tienes asentado el uso básico de Claude Code, conviene que primero captes el panorama general con la Guía de inicio de Claude Code, porque así el sentido de este procedimiento de revisión queda mucho más claro.

El orden de revisión que recorres en 3 minutos

Si no puedes mantenerlo a diario no sirve de nada, así que el procedimiento se reduce a 4 pasos. No es una auditoría perfecta, es un seguro ligero.

Di el alcance en voz alta. Reformula en una frase cuál era la petición de esta vez. Algo como “corregir el texto del botón del artículo”. Esto se convierte en la vara de medir para las decisiones posteriores.
Mira la lista de archivos cambiados. Con git status revisa qué archivos aparecen. Si alguno se sale de la frase que dijiste, márcalo mentalmente como si le pegaras un pósit.
Lee el diff de los archivos marcados. Mira solo el contenido de los archivos fuera de alcance. Decide uno por uno: si el cambio es útil, lo dejas; si no tiene relación, esta vez lo dejas fuera.
Haz stage solo de los archivos necesarios. No metas todo con git add .. Añade por su nombre únicamente los archivos que necesita la petición de esta vez.

El punto clave es el tercero. No reduzcas el rango que amplió la IA a un “acepto todo” o “rechazo todo”. Uno por uno, un humano decide si lo deja o lo saca. Es poco vistoso, pero si te saltas este paso ocurre el accidente de los 18 archivos del principio.

Lo que delegas a la IA y lo que decides tú

Si dejas esta línea difusa, la propia revisión se queda en pura forma. Yo lo separo así.

Tarea	Responsable	Motivo
Ejecutar la corrección de texto o código	IA	Es mucho volumen y se hace de forma mecánica
Arreglar errores de sintaxis y fallos evidentes	IA	Las reglas son claras y fáciles de automatizar
Decidir si incluir el cambio en este commit	Humano	Solo el humano conoce la intención de la petición
Confirmar destinos de enlaces y la vista tras publicar	Humano	Que el build pase no garantiza el contenido
Borrados, datos de producción y cobros	Humano	Los accidentes irreversibles exigen aprobación humana

Si le delegas a la IA hasta el “decide tú si lo incluyes”, la IA intentará meter como algo natural todo lo que ella misma arregló. Quédate con la decisión en tu mano. Ese es el mayor punto de afinación para reducir accidentes.

Plantilla de prompt para copiar y pegar

Cuando dejas que la IA te ayude con la revisión, el truco es no dejar que se “autocalifique”, sino hacer que “ponga los hechos sobre la mesa”. Puedes pegar esta plantilla tal cual.

Voy a hacer commit. Antes de confirmar, repórtame solo lo siguiente como hechos. La decisión la tomo yo.

1. Resume la petición de esta vez en una frase.
2. Lista los archivos modificados según git status (incluye los no rastreados).
3. De esos, cuáles parecen salirse de la frase de la petición y por qué.
4. Si hay cambios que puedan afectar a enlaces o a la vista tras publicar, indica el lugar exacto.

No escribas "no hay problema". Limítate a alinear el material para que yo decida.

La última frase es la que marca la diferencia. Sin ella, la IA tiende a cerrar tan a gusto con un “no hay ningún problema, puedes hacer commit tranquilo” y el sentido de la revisión desaparece. La forma fina de armar prompts la tengo recogida en Ingeniería de prompts avanzada.

Script de revisión que funciona al copiar y pegar

Como teclear git status y git diff por separado cada vez es un fastidio, te dejo un script que saca la imagen completa de los cambios en una sola pantalla. Preparé versiones para PowerShell y bash. Por dentro solo alinean “la lista de archivos cambiados” y “las líneas añadidas y borradas por archivo”.

Versión PowerShell (Windows).

# precommit-check.ps1
# Antes del commit, revisa archivos cambiados y volumen en una sola pantalla

Write-Host "=== Archivos tocados esta vez ===" -ForegroundColor Cyan
git status --short

Write-Host "`n=== Volumen de cambio por archivo (añadido / borrado) ===" -ForegroundColor Cyan
git diff --stat HEAD

Write-Host "`n=== Checklist de revisión ===" -ForegroundColor Yellow
@(
  "Puedo decir la petición en una frase",
  "No se ha colado ningún archivo fuera de alcance",
  "Revisé los destinos de enlaces y la vista tras publicar",
  "Hago stage solo de los archivos necesarios esta vez"
) | ForEach-Object { Write-Host "  [ ] $_" }

Versión bash (macOS / Linux / Git Bash).

#!/usr/bin/env bash
# precommit-check.sh
# Antes del commit, revisa archivos cambiados y volumen en una sola pantalla

echo "=== Archivos tocados esta vez ==="
git status --short

echo ""
echo "=== Volumen de cambio por archivo (añadido / borrado) ==="
git diff --stat HEAD

echo ""
echo "=== Checklist de revisión ==="
for item in \
  "Puedo decir la petición en una frase" \
  "No se ha colado ningún archivo fuera de alcance" \
  "Revisé los destinos de enlaces y la vista tras publicar" \
  "Hago stage solo de los archivos necesarios esta vez"; do
  echo "  [ ] $item"
done

Para ejecutarlo, solo esto.

bash precommit-check.sh

Este script no decide nada de forma automática. Para no romper la premisa de que la decisión la toma una persona, lo dejé a propósito en “solo alinear y mostrar”. Cuando los 4 puntos de la checklist están todos marcados, añades únicamente los archivos necesarios con git add nombre-del-archivo y haces commit.

Tres situaciones donde funciona en la práctica

1. Antes de publicar artículos o material. Al publicar de golpe artículos en varios idiomas, a veces los archivos de traducción se quedan en inglés. El build pasa, pero el contenido no está traducido. No te conformes con ver solo el nombre del archivo en el diff: en la página ya publicada confirma incluso el idioma del cuerpo.

2. Reescritura de archivos existentes. Crees que solo arreglaste el texto y resulta que cambiaron también los enlaces de la página o los nombres de producto. Si fijas el alcance en una frase como “mejora del texto”, puedes parar un momento y tratar el cambio de enlaces como algo fuera de alcance.

3. Al introducirlo en un equipo. Deja registro de hasta dónde avanzó Claude Code de forma automática y dónde le preguntó a una persona. Si operas con reglas de aprobación difusas (qué operaciones puede hacer solo, en cuáles debe preguntar siempre), cada miembro provocará accidentes de un tipo distinto y se vuelve ingobernable.

Errores frecuentes y cómo corregirlos

Error 1: meterlo todo con git add .. Arrastra hasta los cambios sin guardar de otra tarea. La solución es simple: tomar la costumbre de no usar . y hacer stage de los archivos por su nombre. Aunque te parezca un engorro, es el seguro más rápido.

Error 2: relajarte porque el build pasó. El build solo mira la sintaxis; no comprueba si el destino del enlace es correcto ni si la traducción está traducida de verdad en su contenido. La solución es abrir realmente la página publicada y confirmar con los ojos el título, el cuerpo y el destino de los enlaces. El aprobado de la máquina y el aprobado de la persona son cosas distintas.

Error 3: preguntarle a la IA “¿no hay problema?” y darlo por cerrado. Si se lo pides, la IA tiende a decir “todo bien”. La solución es indicarle, como en la plantilla de prompt anterior, que “no escriba la decisión, solo alinee los hechos”. Cuando devuelves el sujeto de la decisión a la persona, la revisión empieza a funcionar.

Cómo asentar la revisión como hábito lo tengo también recogido en Consejos para aumentar la productividad con Claude Code. El comportamiento oficial de cosas como --stat de git puedes consultarlo en la documentación oficial de Git.

Preguntas frecuentes

P. No tengo margen para dedicar 3 minutos a la revisión cada vez. R. Los días con cambios pequeños terminas en 1 minuto. Los 3 minutos los gastas los días con muchos archivos fuera de alcance, que son justo los días en los que la revisión hace falta. Piensa en la duración como un barómetro del peligro.

P. ¿No puedo dejar que la IA haga también el stage? R. Si es una tarea pequeña que sabes que es segura, puedes dejársela. Pero te recomiendo conservar en la persona al menos la decisión final de “qué archivos incluir”. Ese suele ser el punto de entrada de los accidentes.

P. ¿Qué pongo en el mensaje de commit? R. Dos cosas: “qué cambié” y “con qué lo verifiqué”. Por ejemplo: “corregí el texto del botón, verifiqué el destino del enlace en la página publicada”. Así, al mirarlo más tarde, de un vistazo sabes si se verificó o no.

P. ¿Y si el archivo fuera de alcance era en realidad un cambio que convenía hacer? R. Aun así, esta vez lo dejo fuera. Solo lo separo en otro commit, no lo borro. Si mantienes una intención por commit, después es más fácil seguir el rastro.

Lo que comprobé al probarlo de verdad

Después del incidente de los 18 archivos del principio, empecé a intercalar estos 4 pasos antes de cada confirmación. Lo probé en tres patrones: publicación de artículos, reescritura de archivos y cambios de configuración.

Lo que más me sirvió fue el primer paso: “reformular la petición en una frase”. Con solo decirlo en voz alta, los archivos fuera de alcance empiezan a saltar a la vista. Cuando dejé de teclear git add . después de correr el script de revisión y pasé a hacer stage de los archivos por su nombre, los accidentes de arrastrar otra tarea bajaron a cero.

Y lo que me sorprendió fue el efecto de cambiar la forma de preguntarle a la IA, de “¿no hay problema?” a “solo alinea los hechos”. La misma IA se convirtió de golpe en un socio de revisión útil. En lugar de buscar una IA más lista, devuelve el sujeto de la decisión a la persona. Esa fue, para mí, la jugada más discreta y a la vez la más eficaz.

Cuando quieras llevar el diseño de permisos y las comprobaciones previas a la publicación hasta la operativa de todo el equipo, en Formación y consultoría armamos juntos el diseño concreto.