Cómo hacer segura la primera edición en un repo heredado con Claude Code

El primer día con un repositorio interno que acababa de heredar, la fastidié.

Le pedí a Claude Code algo tan inocente como «lee todo el proyecto y arregla lo que veas raro». Media hora después había 23 archivos modificados. El contenido no estaba mal. El problema es que «de paso» también había ordenado la configuración de despliegue de producción y los archivos de cobros que nadie debía tocar. El diff era tan grande que ni yo mismo sabía qué cambio era realmente necesario. Acabé tirándolo todo y empezando de cero.

Que una IA lista provoque un accidente no es un problema de capacidad. Es que nadie decidió hasta dónde podía meter mano antes de entrar. Hoy vamos a rehacer ese primer día para que todo sea reversible, verificable y termine de verdad.

Puntos clave

El día que entras por primera vez en código ajeno, lo primero es resumir en una página: «qué puedo leer, qué está prohibido tocar y qué comando de verificación ejecuto al terminar».
No le encargues una gran reforma desde el principio. Empieza por una edición pequeña y reversible (ordenar nombres de tests, añadir un comentario, etc.).
Antes del «ya está hecho», ejecuta siempre un comando de verificación y guarda el resultado.
Borrados, base de datos de producción, cobros y force push quedan fijados el primer día en «requiere confirmación humana». Solo automatizas después lo que ya sabes que es seguro.
Cuando el diff empieza a hincharse, antes de retocar el prompt, reduce los archivos que la IA puede tocar.

Por qué decidir el alcance el primer día

Un repositorio nuevo es una ciudad sin mapa. Qué archivo es el corazón del sistema y cuál se rompe si lo tocas no lo ve nadie al principio.

Si en ese momento le pides a Claude Code «míralo todo y arréglalo», la IA, por amabilidad, mete mano por todas partes. La culpa no es de la IA. El origen está en la persona que no le dio un alcance. Si a alguien en su primer día de trabajo le dices «deja la tienda bien» y te cambia hasta la configuración de la caja registradora, el problema es de quien dio la instrucción, ¿no?

Por eso lo primero no es escribir un prompt ingenioso, sino dibujar un mapa. La estantería que puede leer, el cajón que no debe abrir y el cierre que reviso antes de irme. Con solo escribir esas tres cosas en papel, los accidentes del primer día casi desaparecen.

Las tres fronteras que decides primero

El orden importa. Las fijas de arriba abajo.

Qué decides	Ejemplo concreto	Por qué decidirlo antes
Qué puede leer	`src/`, `docs/`, archivos de tests	Si le dejas leer todo, tiende a proponer cambios sin relación
Qué está prohibido tocar	`.env`, cobros, autenticación, migraciones de BD, config de despliegue de producción	Romper esto no tiene marcha atrás
Qué verificas al terminar	`npm run build`, un test	Para dejar siempre una «prueba de que funciona»

Estas tres cosas escritas en un papel (vale un archivo de texto) yo las dejo en un ONBOARDING.md en la carpeta de trabajo. Es también el primer archivo que le hago leer a Claude Code. Primero comparto el mapa y luego le dejo caminar por la ciudad.

Qué delegar en la IA y qué decides tú

Mezclar esto provoca accidentes. Vamos a trazar la línea con claridad.

Trabajo que sí puedes delegar en Claude Code

Leer el repositorio por encima y resumir su estructura.
Buscar «en qué archivo está esta función».
Borradores de mejoras pequeñas y reversibles: ordenar nombres de tests, añadir comentarios, completar tipos.
Ejecutar el comando de verificación, leer el log de error y hacerse una idea de la causa.

Trabajo que siempre decide una persona

Permitir o no un cambio que entra en zona prohibida.
Borrar archivos, operar sobre la BD de producción, tocar procesos de cobro, hacer force push.
La decisión final de si se fusiona un cambio de diseño grande.
Si hay que parar cuando el diff se extiende más de lo previsto.

Mi criterio es simple. Lo que «aunque me equivoque puedo revertir con git» se lo dejo a la IA. Lo que «no se puede revertir» lo aprieto yo el botón. Con solo respetar esa línea, no hay desastres desde el primer día.

Plantilla de prompt lista para copiar

Antes de entrar en la primera edición, le lanzo esto. El truco está en no dejar que escriba código de golpe, sino hacer que devuelva primero un plan.

Este es un repositorio existente que toco por primera vez. Respeta estas reglas.

[PUEDES LEER] solo src/ y docs/ y los archivos de tests
[NO TOQUES] .env / autenticación / cobros / migraciones de BD / config de despliegue de producción
[OBJETIVO DE HOY] una sola mejora pequeña y reversible (ej.: ordenar nombres de tests)
[VERIFICACIÓN] tras el cambio ejecuta siempre `npm run build` y pega el resultado

Todavía no modifiques código.
Primero devuélveme el plan de "qué archivo vas a arreglar y cómo" y
una reformulación de las reglas de arriba con tus propias palabras.

Si el plan que devuelve reformula bien mis restricciones, está aprobado. Si intenta ampliar el alcance, lo paro ahí mismo. Si el plan es bueno, avanzo con «pues hazlo tal cual, y ejecuta hasta el build».

Guardar las fronteras también en código

Las reglas en papel se olvidan. Por eso yo dejo el plan de onboarding también en un formato que la máquina pueda leer. El script de abajo funciona tal cual. Sustituye su contenido por el de tu propio repositorio.

#!/usr/bin/env bash
# Reúne el plan de onboarding del repo existente en un solo JSON
set -euo pipefail

cat > onboarding-plan.json <<'JSON'
{
  "goal": "terminar de forma segura la primera edicion en un repo existente",
  "readOnlyCommands": [
    "git status --short",
    "git ls-files | head -50",
    "grep -rn \"TODO\\|FIXME\" src | head -20"
  ],
  "protectedAreas": [".env", "billing", "auth", "db/migrations", "deploy/prod"],
  "firstTask": "una mejora pequena y reversible en docs o tests",
  "proofCommand": "npm run build",
  "rollback": "git diff -- path/to/changed-file && git checkout -- path/to/changed-file"
}
JSON

echo "=== Plan de onboarding ==="
cat onboarding-plan.json

echo ""
echo "=== Diff actual (vacio si no se ha editado) ==="
git status --short

Este script no tiene nada de espectacular. Su valor es que antes de empezar a trabajar puedes fijar en un archivo la “zona prohibida” y el “comando de prueba”. Con solo reescribir protectedAreas con los lugares peligrosos de tu repositorio, ya tienes el mapa del primer día.

Conviene tener también un comando de verificación. En un proyecto de Node.js, una comprobación mínima como esta confirma de forma mecánica si «sigue sin romperse».

// check.mjs : script mínimo que solo comprueba si el build pasa
import { execSync } from "node:child_process";

try {
  // sustituye por el comando de verificación de tu propio proyecto
  execSync("npm run build", { stdio: "inherit" });
  console.log("Verificación OK: el build pasa. Revisa el diff.");
} catch (e) {
  console.error("Verificación FALLIDA: el build se cae. No fusiones; revisa la causa.");
  process.exit(1);
}

Si node check.mjs sale verde, pasas el diff a revisión; si sale rojo, paras. Con solo tener esta pieza desaparece el accidente de fusionar pensando «debería funcionar».

Cómo usarlo en tres escenarios reales

Si tienes una situación parecida, no rehagas el procedimiento: cambia solo los nombres por los de tu propio contexto.

1. Heredar un sitio de contenido Hazle leer primero dónde están los datos de los artículos, la carpeta de imágenes, el comando de build y las páginas de producto. La primera edición es solo «arreglar un enlace roto». Si el build pasa, lo mandas a revisión. Las grandes reescrituras del cuerpo, solo cuando ya sepas que es seguro.

2. La base de código de un SaaS Deja por escrito que autenticación, cobros y migraciones de BD son zona prohibida. La primera tarea la acotas a algo como «hacer más claros los textos descriptivos de los tests» y avanzas solo tras la aprobación de una persona. Si aquí te relajas, te entra una «amable mejora» en la lógica de pagos y se te hiela la sangre.

3. Un repositorio legacy antiguo «Moderniza todo» es una frase prohibida. El diff alcanza un tamaño imposible de leer. En su lugar, da un paso pequeño que el build pueda verificar: corregir un typo en el nombre de una función, ordenar nombres de tests. Cuando uno sale bien, das el siguiente paso con el mismo molde.

Todos los ejemplos tienen un «punto de parada». Porque hay punto de parada, el trabajo no se extiende sin fin.

Casos de fallo y cómo arreglarlos

Lo escribo con honestidad. Las primeras veces la fastidié en todas.

Pedí sin escribir la zona prohibida → el diff quedó tan grande que era imposible de revisar y tuve que tirarlo entero. La solución es simple: antes de pulir el texto de la petición, reduce los archivos que puede leer. Cuanto más estrecho el alcance, más estrecho el margen de desmadre de la IA.

Construí el build solo cuando ya estaban todos los cambios hechos → dejé de saber qué edición lo rompió. Ahora ejecuto la verificación cada vez que arreglo un archivo. Como queda registrado el instante exacto en que se rompió, la causa salta enseguida.

Confié la comprobación solo a mis propios ojos → en un día ajetreado siempre se te escapa algo. Lo que «la máquina puede saber» déjaselo literalmente a la máquina: si el build pasa, el resultado de los tests, los enlaces rotos. Los ojos humanos, solo para las decisiones de diseño que la máquina no puede captar. Con esto, las revisiones de madrugada se redujeron mucho.

Dejo los tropiezos en el artículo porque con solo casos de éxito el lector no se da cuenta de su propio estado peligroso. Anotar en corto qué petición se extendió demasiado y qué verificación faltó evita que tu yo futuro pise el mismo hoyo.

Preguntas frecuentes

P. ¿Qué elijo para la primera edición? R. Elige algo que «aunque te equivoques puedas revertir con git checkout». Ordenar nombres de tests, añadir comentarios o corregir erratas son seguros. Funcionalidades nuevas o cambios de configuración no van bien el primer día.

P. ¿Hasta qué nivel de detalle escribo la zona prohibida? R. Basta con «los lugares que, si se rompen, no tienen marcha atrás». .env, autenticación, cobros, config de despliegue de producción y migraciones de BD. Si al principio cubres estos cinco, evitas casi todos los accidentes fatales.

P. ¿No puedo ahorrarme el paso de hacer que devuelva un plan? R. Te recomiendo no ahorrártelo. Ese pequeño esfuerzo de hacerle reformular el plan te permite detectar la desviación de alcance antes de editar. Es mucho más barato que darte cuenta cuando el código ya está escrito.

P. ¿Basta con el build como comando de verificación? R. El primer día basta con el build. Cuando cojas práctica, añade un test relacionado. Si intentas correr toda la batería de tests desde el principio, es tan pesado que no lo mantienes. Empieza pequeño y amplía cuando se acumulen logs de éxito.

P. ¿Qué cuidados hay al introducirlo en un equipo? R. Escribe las fronteras en un archivo compartido como ONBOARDING.md, para que todos usen el mismo mapa. Si la zona prohibida varía según la persona, el criterio de revisión también tiembla.

Lo que comprobé al probarlo de verdad

Después del «accidente de los 23 archivos» del principio, cambié el orden del onboarding. Dejé de buscar el prompt perfecto y fijé primero la zona prohibida y el comando de verificación en onboarding-plan.json. Solo con esto, los accidentes que metían mano en cobros o en config de producción bajaron a cero.

El día que acoté la primera edición a «ordenar nombres de tests», el diff se quedó en 8 líneas y el build pasó a la primera. La revisión no llega ni a dos minutos. En cambio, otro día que pedí sin definir el alcance, el diff volvió a hincharse y lo tiré todo. La diferencia no estaba en lo lista que era el modelo, sino en si había dibujado el mapa antes de entrar.

Si quieres consolidar este molde de tocar código ajeno con seguridad usando casos reales de tu propio equipo, en formación y consultoría montamos juntos la forma de introducirlo adaptada a tu trabajo. Para empezar hoy, prueba a escribir las cinco zonas prohibidas de tu propio repositorio.