Tu primer día con Claude Code en un repo ajeno: elegir la primera tarea sin romper nada

A los tres días de entrar en la empresa me pasaron unos 150 archivos de la parte de pagos. Documentación, casi nada. A quien preguntaba, todos respondían lo mismo: “funciona, así que mejor no tocarlo”. Así que le solté a Claude Code lo primero que se me ocurrió: “entiende este repositorio y arregla lo que veas raro”.

Diez minutos después, Claude me contestó muy seguro de sí mismo: “He ordenado 20 archivos”. Abrí el diff y se me heló la sangre. Había reformateado los SQL de las migraciones, reordenado el .env.example y, por su cuenta, había “optimizado” el tiempo de espera de los reintentos de pago dejándolo a la mitad. Era código que funcionaba, sí. Pero si eso llega a producción, el teléfono no habría parado de sonar con quejas por cobros duplicados.

El problema no era lo listo que es Claude. Era que el primer día le di un terreno demasiado amplio. Para delegar con seguridad un código ajeno y gigante, antes de buscar una IA más inteligente conviene decidir en 30 minutos cuatro cosas: qué leer primero, qué no debe tocar, cuál es la primera tarea pequeña y cómo se confirma que terminó. Solo con eso, los accidentes del primer día casi desaparecen. Hoy te cuento qué va dentro de esos 30 minutos, en formato copiar y pegar.

Puntos clave

El primer día en un código heredado, “míralo todo y arréglalo” es lo más peligroso: arrancas con el alcance difuso.
En los primeros 30 minutos no construyes un documento de arquitectura, sino una nota de una página para elegir con seguridad la primera tarea.
En esa nota solo van cuatro cosas: el orden de lectura, las zonas prohibidas, la primera tarea pequeña y el comando que confirma que está hecho.
La primera tarea se limita a sitios “fáciles de revertir”: textos, etiquetas de botones, nombres de tests.
A la IA le delegas “investigar y redactar el borrador”. La base de datos de producción, el cobro, el borrado y el botón de publicar los acciona una persona.

Por qué te tropiezas con la primera instrucción del primer día

Claude Code es rápido. Y justamente por ser rápido, si la información inicial es amplia, te genera con todas sus fuerzas hasta los diffs que dan igual.

Un compañero nuevo de carne y hueso preguntaría “¿esto lo puedo tocar?”. La IA no pregunta. Por amabilidad, ensancha el alcance. Si le dices “ordena”, ordena de verdad hasta el último rincón. Reformatear las migraciones, “optimizar” los reintentos de cobro… lo hace creyendo que te está ayudando.

Por eso lo que toca hacer el primer día no es leerse el código entero ni montar un plan de mejoras impecable. Es trazar los límites. Hasta dónde puede actuar solo y a partir de dónde tiene que preguntar. Si trazas esa línea de antemano, tu petición a Claude pasa de “piensa libremente” a “muévete dentro de este terreno y deja pruebas”. Para trazar la línea bastan 30 minutos. No hace falta entender todo el código.

La nota de una página del primer día, en 30 minutos

Sirve papel o un bloc de notas. Solo rellenas estos cuatro puntos. El orden también importa.

Decide un orden de lectura estrecho. Nada de leer todos los archivos de golpe: solo README y package.json. Con eso sabes qué lenguaje es, cómo se arranca y qué herramientas usa. Luego dos o tres pantallas o rutas principales. Con eso basta.
Escribe las zonas que no debe tocar. Cobros, autenticación de login, variables de entorno, migraciones de base de datos. Aquí dejas claro: “puedes leerlo, pero no lo reescribas”. Si no lo escribes, Claude las trata como un objeto de edición más.
Elige una primera tarea pequeña. Limítate a sitios fáciles de revertir: el texto al final de un artículo, la etiqueta de un botón, el nombre confuso de un test. Algo que, si sale mal, deshaces en un segundo.
Decide cómo confirmar que terminó. ¿Compila? ¿El diff cae dentro de lo previsto? ¿La pantalla no se ha roto? No decides por intuición, sino por el resultado de un comando.

Cuando rellenas estos cuatro, la mayor parte de la ansiedad del primer día se va. Porque dejas de preguntarte “¿qué barbaridad hará Claude?” y pasas a saber “hasta dónde le he delegado a Claude”.

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

Si pones la línea por escrito, no dudas cada vez. La división que yo uso es esta.

Tarea	Se delega a Claude	Lo decide una persona
Leer el código y resumir la estructura	Sí: que haga el borrador	La comprensión final la confirmas tú
Proponer zonas prohibidas	Sí: que liste candidatas	Cobros y autenticación los fija siempre una persona
Corregir textos y etiquetas	Sí: se puede delegar	Revisas el diff y apruebas
Escribir en la base de datos de producción	No	Lo ejecuta una persona a mano
Borrar, publicar, todo lo de cobros	No	Una persona pulsa el botón

La clave es colocar desde el principio todas las operaciones peligrosas en el lado de “preguntar a una persona”. Solo las operaciones que ya confirmaste seguras las asciendes después a automáticas. Al revés no. Permitir mucho al principio y apretar las tuercas después del accidente es el orden equivocado.

Si quieres entender este enfoque con más calma, leer también Claude Code: guía de los primeros pasos y la checklist de los primeros 30 minutos con Claude Code te ayuda a conectar bien los movimientos del primer día.

Plantilla de petición lista para copiar y pegar

El truco es no dejar que edite de entrada. Lo primero que le pides es “solo leer y resumir en una tabla”.

Es la primera vez que toco este repositorio. Todavía no edites nada.
Lee en este orden y devuélveme el resultado en una tabla.

1. Lee README y package.json: indica el lenguaje, el comando de arranque y las dependencias principales.
2. Lista las zonas peligrosas (cobros, autenticación, variables de entorno, migraciones de BD) con su ruta de archivo.
3. Propón 3 candidatas de "primera tarea pequeña" fáciles de revertir, con su motivo.
4. Para cada candidata, escribe el comando que confirma que está hecha (compilar, revisar diff, etc.).

Lo repito: en esta fase no edites ni un solo carácter.

Cuando vuelve la tabla, revisas con tus propios ojos que no falte ninguna “zona prohibida”. Si falta, la añades, y solo entonces le pides por fin una única tarea.

De las candidatas anteriores, avanza únicamente con OO (corregir el texto al final del artículo).
No toques nada de cobros, autenticación, variables de entorno ni migraciones.
Tras editar, ejecuta `npm run build` y muéstrame el diff con `git diff --stat`.
Si algo se rompe, explica en una línea la causa y la forma de arreglarlo, y detente.

Si escribes las “zonas prohibidas” en el CLAUDE.md desde el principio, te ahorras pegar este aviso cada vez. La forma de redactarlo la tienes en buenas prácticas para CLAUDE.md.

Un poco de código para que la máquina haga la comprobación

Si confías en tu memoria para “preparar bien antes de delegar”, un día con prisas se te escapa seguro. Así que dejas que la máquina juzgue si la nota de una página está al menos completa. El siguiente código corre tal cual en Node.js.

// Comprueba con la máquina si la nota del primer día está "lista para pasarle a Claude"
const repoMap = {
  goal: "elegir una primera tarea fácil de revertir",
  readFirst: ["README.md", "package.json", "src/routes/"],
  protectedAreas: [".env", "billing/", "migrations/", "wrangler.toml"],
  firstTask: "corregir el texto al final del artículo (no tocar el código de pagos)",
  proofCommands: ["npm run build", "git diff --stat"],
};

function isReady(map) {
  const reasons = [];
  if (map.readFirst.length < 2) reasons.push("orden de lectura demasiado estrecho o sin definir");
  if (map.protectedAreas.length === 0) reasons.push("zonas prohibidas vacías");
  if (!map.proofCommands.some((c) => c.includes("build"))) {
    reasons.push("falta el comando que confirma la compilación");
  }
  if (!map.firstTask) reasons.push("primera tarea sin elegir");
  return { ready: reasons.length === 0, reasons };
}

const result = isReady(repoMap);
console.log(result.ready ? "Listo para delegar" : "Aún no delegues: " + result.reasons.join(", "));

Al ejecutarlo, sale esto.

node check-repo-map.mjs
# => Listo para delegar

Si pruebas a dejar protectedAreas como array vacío, sale “Aún no delegues: zonas prohibidas vacías”. Es solo esto, pero te frena antes de delegar el accidente más típico: arrancar todo en automático con las zonas prohibidas sin escribir. Esta nota la puedes pegar tal cual en el CLAUDE.md o en una issue, y tanto tú al día siguiente como tus compañeros reutilizáis el mismo criterio.

Tres situaciones donde funcionó de verdad

1. En un blog, proteger los enlaces de los artículos que dan dinero Cuando solo quieres retocar el cierre de un artículo popular, si le pides a Claude “mejora el texto”, acaba tocando hasta la URL del enlace del producto. Por eso cierras el terreno: “puedes corregir el texto, pero no cambies ni un carácter de la URL de destino. Tras el cambio, muéstrame la compilación y el diff”. Así pules solo el texto sin romper el enlace que va directo a las ventas.

2. En un SaaS, no acercarse al procesamiento de facturación Cuando el texto explicativo de una pantalla de configuración es confuso, lo único a mejorar es el texto visible. La lógica de facturación o de cambio de plan no se toca. Si metes billing/ en las “zonas prohibidas” de la nota, evitas que Claude, por amabilidad, meta mano en la lógica de reintentos.

3. En una herramienta interna, corregir solo los nombres de las columnas de salida Me consultaron que los nombres de columna de una exportación a CSV eran confusos. Lo que se corrige es solo el texto del nombre de columna; la lógica de agregación es otra historia. Si pides “solo el texto visible de los nombres de columna. No toques las fórmulas de cálculo. Muéstrame la salida con datos de ejemplo”, la verificación se resuelve en un instante.

Lo común a las tres no es falta de capacidad de Claude, sino un único punto: si el límite es endeble, hay accidente. Cuanto más claro escribes el límite, más rápido y seguro se mueve la IA.

Trampas habituales y cómo arreglarlas

Trampa 1: hacerle leer todos los archivos desde el principio. Gasta tiempo y tokens en reformateos de poca importancia, y el cambio que de verdad importa queda flojo. Se arregla acotando la lectura a README, package.json y dos o tres rutas principales. La visión global la amplías poco a poco después de terminar la primera tarea.

Trampa 2: no escribir las zonas prohibidas. Claude trata cobros, autenticación y configuración de despliegue como objetos de edición normales. Se arregla escribiendo una lista de protección con la ruta de cada archivo y dejándola fija en el CLAUDE.md. Los avisos de palabra se olvidan; lo escrito permanece.

Trampa 3: creerse el “ya está” sin haber decidido un comando de verificación. Acabas adivinando cada vez si el informe de finalización es correcto. Se arregla incluyendo desde el inicio en la petición “compila y muéstrame el diff”. Un HTTP 200 o una respuesta que suena bien no son prueba de éxito. Solo te fías del resultado de haberlo ejecutado de verdad.

Preguntas frecuentes

P. ¿No es más seguro entender el código heredado entero antes de delegar? Lo ideal sí, pero el primer día no terminas de entenderlo todo. Si esperas a terminar, no avanzas nada, así que primero cierras las “zonas prohibidas” y empiezas por una tarea fácil de revertir. Entender el código va más rápido si lo amplías mientras trabajas.

P. ¿Cómo de pequeña debe ser la primera tarea? La medida es algo que se termine con un archivo, un texto y un comando. Si pides en grande, Claude amplía el alcance por amabilidad. Si avanzas a la siguiente tras confirmar compilación y captura de pantalla, no pierdes velocidad y reduces el tiempo de marcha atrás.

P. ¿Dónde conviene escribir las zonas prohibidas? Escribirlas en el CLAUDE.md es lo que más se mantiene. El método de pegarlas en el prompt cada vez se olvida un día de prisas. Si las dejas en un solo sitio como regla del proyecto, aplican automáticamente también en trabajos nuevos.

P. Le dije “no toques” y Claude lo tocó igualmente. Casi siempre es porque la protección se quedó en el nombre de archivo y no abarca el directorio entero. No escribas solo billing.js, sino el rango: billing/. Si aun así se sale, mete al inicio de la petición un paso extra: “antes de editar, declara los archivos objetivo y luego avanza”; así frena mejor.

P. ¿Hay que rehacer esta nota cada vez? La haces una vez por repositorio y luego la reutilizas. Si la pegas en el CLAUDE.md y en una issue, tanto tú al día siguiente como tus compañeros heredáis el mismo criterio. Cuando aparezca una nueva zona a proteger, solo la añades.

Lo que confirmé al probarlo de verdad

Después del incidente del código de pagos del principio, probé el mismo procedimiento en otro repositorio heredado. Primero, sin dejarle editar nada, hice que sacara solo la tabla con la petición de arriba, y propuso bien billing/ y migrations/ como candidatas a proteger. Eso sí, se le escapó el archivo de variables de entorno, así que añadí yo .env a mano. Volví a comprobar lo importante que es avanzar dando por hecho que una persona revisa este punto.

Limité la primera tarea a una sola corrección de texto al final de un artículo y la di por terminada tras confirmar con npm run build y git diff --stat. El diff eran solo 7 líneas y no tocó ni un carácter del código de pagos. También ejecuté el código de comprobación de verdad y confirmé que, al dejar protectedAreas vacío, se detiene con “Aún no delegues”. Más que buscar una IA inteligente, decide primero un terreno pequeño del que puedas levantarte enseguida si te caes. Eso fue lo que más funcionó el primer día con código ajeno.

Si estás en el punto de querer fijar en equipo un patrón para meter Claude Code en el código heredado de la empresa, en formación y consultoría podemos repasar un repositorio real juntos y ordenar cómo trazar los límites. Y para los requisitos oficiales, revisar la guía oficial de Anthropic para empezar con Claude Code deja todo más tranquilo.