Claude Code en un repo heredado: dibuja el mapa antes de tocar nada

Mi primer día en un proyecto heredado, abrí el repositorio de una herramienta interna que dejó la persona anterior. El README tenía tres líneas y la última actualización era de hace ocho meses. Sin pensarlo mucho, le pedí a Claude Code: «entiende este proyecto y corrige el texto de la pantalla de login». Cinco minutos después, no solo había tocado eso: también había «aprovechado para ordenar» los archivos de configuración de autenticación y un script de despliegue a producción que nadie había tocado en mucho tiempo.

Por suerte me di cuenta con git status y revertí todo. Pero todavía se me hiela la sangre al pensar qué habría pasado si hubiera hecho git commit sin mirar. El problema no era la inteligencia del modelo. El problema era que le delegué el trabajo sin saber yo mismo qué se podía tocar y qué no.

La primera hora dentro del código de otra persona no es para arreglar. Es para dibujar un mapa. En este artículo te muestro cómo dibujar ese mapa, como un procedimiento que no provoca accidentes ni siquiera en un repositorio que ves por primera vez.

Puntos clave

• La primera hora no es para «arreglar», sino para «dibujar el mapa». Separa de antemano lo que se puede tocar de lo que no.
• A Claude Code le delegas «leer y listar», nada más. Qué declarar zona protegida lo decides tú.
• Antes de tocar nada, fija siempre un comando de verificación (build o tests). Esa es la prueba de que «ya quedó arreglado».
• El primer cambio se limita a algo pequeño, reversible con un solo comando de git.
• Anota lo que entendiste en una sola nota. Así la próxima persona que entre al repo (incluido tu yo futuro) no repite la misma investigación.

Por qué los accidentes ocurren en la primera hora

Cuando tropiezas en un repositorio nuevo, casi nunca es por la dificultad del código. Es porque no ves la forma del repositorio.

Qué carpeta es la pantalla, dónde está la lógica de fondo, qué archivo es la configuración de producción. Si pides «arréglalo bien» sin tener esto claro, Claude Code reescribe un rango amplio con buena intención. La IA, salvo que le digas «esto no lo toques», asume que es un lugar donde puede escribir.

Los proyectos heredados son especialmente peligrosos. Las reglas no escritas de quien estuvo antes, sus manías al nombrar, ese comentario que sigue ahí sin que se sepa por qué. Ese contexto no está escrito en ninguna parte del código. Ni siquiera un humano lo entiende todo el primer día. Justo por eso, lo primero no es editar, sino hacer el mapa.

Cuatro pasos para dibujar el mapa

El orden importa. Define qué leer, define las zonas protegidas, define el comando de verificación y, solo al final, arregla una cosa pequeña. Avanza en ese orden.

Paso 1: escribe la meta de hoy en una sola frase

«Entender este proyecto» es demasiado amplio. Tanto Claude Code como tú perdéis el punto donde parar cuando la meta es vaga.

En su lugar, escribe esto: «corregir el texto de la pantalla de login en un único punto y confirmar que el build pasa». Una meta que cabe en una frase deja claro de un vistazo si ya terminaste.

Paso 2: separa lo que se lee de lo que no se toca

Aquí está el centro del mapa. Antes de entregarle a Claude Code un «puedes leerlo todo», pon en palabras de antemano lo que no se debe tocar.

Lo que yo meto siempre en la zona protegida es: autenticación, facturación, los archivos de variables de entorno (.env) y los scripts de despliegue a producción. Un error ahí causa un daño grande y, encima, es difícil de revertir. Por eso, al principio dejo explícito: «leer está bien, escribir no».

Paso 3: define el comando de verificación antes de tocar

Aunque te digan «ya está arreglado», ¿con qué pruebas que de verdad lo está? Eso se decide antes.

En la mayoría de los proyectos, la verificación es un comando de build o de tests. Que npm run build pase, que npm test salga en verde. Si fijas ese único comando antes de editar, no te tragas el «ya quedó» de Claude Code: juzgas con el aprobado o suspenso de la máquina.

Paso 4: un solo cambio pequeño y reversible

Una vez tengas el mapa, el primer cambio es no querer abarcar de más. Elige una sola cosa que se revierta con un git checkout: corregir un texto, añadir un comentario, arreglar una errata evidente.

Aguanta las ganas de «ya que estoy, también aquello». Un diff grande nadie lo puede revisar, y revertirlo cuando algo sale mal se vuelve un dolor.

Qué delegar a Claude Code y qué decides tú

En el mapeo, qué delegas y qué te reservas. Si mezclas las dos cosas, ocurre el accidente del principio.

Tarea	Responsable	Razón
Captar la lista de archivos y la estructura de carpetas	Claude Code	La lectura mecánica es rápida y precisa
Investigar «¿dónde está esta función?»	Claude Code	Buscar y resumir es lo suyo
Qué declarar zona protegida	Tú	La gravedad del daño depende del contexto. La IA no lo sabe
Decisión final del comando de verificación	Tú	Quien conoce las particularidades del proyecto eres tú
Cambios en producción, facturación o autenticación	Tú	Las operaciones difíciles de revertir las aprueba una persona

El principio es simple. Leer y listar se delega. Las decisiones difíciles de revertir las controlas tú. Solo las operaciones que ya confirmaste como seguras las vas «ascendiendo» después a Claude Code.

El diseño fino de permisos lo tengo en otro artículo. Si dudas qué frenar al principio, mira la guía de permisos.

Prompt de mapeo para copiar y pegar

Este es el prompt que de verdad lanzo en la primera hora. Pégalo tal cual y cambia solo el nombre del repositorio por el tuyo.

Es la primera vez que toco este repositorio. Todavía no edites nada.
Investiga lo siguiente en orden y reporta el resultado en viñetas.

1. La estructura de carpetas de nivel superior y el rol de cada una
   (puede ser una suposición, pero indícalo como tal).
2. Los comandos de build, test y arranque (de package.json o del README).
3. La ubicación de los archivos relacionados con autenticación, facturación,
   variables de entorno y despliegue a producción.
4. En qué archivo está «el texto de la pantalla de login».

Tras el reporte, el grupo de archivos del punto 3 queda esta vez
como «solo lectura, prohibido editar».
Lo único que puedes editar es el único archivo que encontraste en el punto 4.

La clave está en clavar en la primera línea un «todavía no edites». Sin eso, hay IA que empieza a arreglar de paso mientras investiga.

Script de verificación que funciona al copiarlo

Una vez tengas el mapa, conviene poder pasar la misma comprobación antes y después del cambio. El siguiente script verifica si el build pasa antes y después, y si el diff no se ensanchó demasiado. Funciona con Node.js.

// verify-edit.mjs
// Comprueba si el build pasa antes y después del cambio,
// y si el diff no es mayor de lo previsto.
import { execSync } from "node:child_process";

// Decide de antemano el tope de archivos cambiados (rango reversible con un comando).
const MAX_CHANGED_FILES = 3;

function run(cmd) {
  return execSync(cmd, { encoding: "utf8" }).trim();
}

try {
  // Cuenta el número de archivos modificados.
  const changed = run("git diff --name-only")
    .split("\n")
    .filter(Boolean);

  console.log(`Archivos modificados: ${changed.length}`);
  changed.forEach((f) => console.log(`  - ${f}`));

  if (changed.length > MAX_CHANGED_FILES) {
    console.error(
      `El diff es demasiado amplio (${changed.length} > ${MAX_CHANGED_FILES}).`,
    );
    console.error("Revierte con git checkout y divide el cambio en partes más pequeñas.");
    process.exit(1);
  }

  // Comprueba que no se tocó la zona protegida.
  const protectedHits = changed.filter((f) =>
    /(^|\/)\.env|auth|billing|deploy/i.test(f),
  );
  if (protectedHits.length > 0) {
    console.error("Hay cambios en la zona protegida:");
    protectedHits.forEach((f) => console.error(`  - ${f}`));
    process.exit(1);
  }

  // Comprueba que el build pasa (sustituye según tu proyecto).
  console.log("Verificando el build...");
  run("npm run build");
  console.log("Build OK. El cambio se mantiene en el rango seguro.");
} catch (err) {
  console.error("La verificación falló:", err.message);
  process.exit(1);
}

Se ejecuta con node verify-edit.mjs. Si hay demasiados archivos modificados o se tocó la zona protegida, se detiene ahí mismo. El accidente del principio —que «ordenara» hasta los archivos de autenticación— se habría frenado solo si lo hubiera pasado por este script.

Tres escenarios donde funciona

Para concretar en qué tipo de repositorios sirve, te dejo tres patrones que probé yo mismo.

1. Herramienta interna heredada Cuando entras a un codebase sin documentación. Primero haz que liste la estructura de carpetas y los comandos de arranque, y fija como zona protegida la autenticación y los archivos de configuración. Que el primer cambio sea algo cuyo resultado se vea a simple vista, como cambiar una etiqueta del panel de administración.

2. Primera contribución a un repositorio público Cuando envías por primera vez un Pull Request a un proyecto de código abierto ajeno. Haz que identifique antes el comando de tests y envía un único cambio pequeño manteniendo npm test en verde. Una corrección de un solo archivo reversible se acepta más fácil que una propuesta de mejora amplia.

3. Reactivar un proyecto antiguo Cuando retomas código abandonado durante medio año. Haz que Claude Code investigue «hasta dónde funciona» y mapea las entradas que están rotas. Arregla empezando por el punto más fácil de revertir.

Errores comunes y cómo corregirlos

Error 1: querer arreglarlo todo de una vez Si con el «ya que estoy, refactorizo» el diff se hincha a 50 archivos, nadie lo puede revisar. La corrección: poner un tope al número de archivos cambiados con el script de verificación de arriba. Si se supera, revierte y divídelo.

Error 2: dar por terminado solo porque el build pasa Que el build pase en local no significa que la pantalla quede como esperabas. Si corriges un texto, no terminas hasta abrir esa pantalla y confirmar el texto con tus propios ojos.

Error 3: comunicar la zona protegida solo de palabra Aunque digas «no toques la autenticación» en el prompt, a mitad de un trabajo largo se puede olvidar. La corrección: rechazar mecánicamente los cambios en la zona protegida con el script de verificación. Protege con un comando, no con la memoria de una persona.

Error 4: no dejar registro del mapa que investigaste Por mucho que dediques una hora a entenderlo, si no dejas una nota la próxima vez repites la misma investigación. Si anotas en una sola nota la estructura de carpetas, el comando de verificación y la zona protegida, tu yo futuro te lo agradece.

Esa nota del mapa funciona aún mejor si la escribes en el CLAUDE.md como reglas del proyecto. Cómo escribirlo lo recopilé en buenas prácticas de CLAUDE.md.

Preguntas frecuentes

P. ¿De verdad no hace falta arreglar nada en la primera hora? R. Puedes arreglar, pero limítate a «un único punto pequeño y reversible». Usar el resto del tiempo en el mapeo reduce los accidentes y, al final, es más rápido.

P. ¿Es peligroso entregarle a Claude Code un «puedes leerlo todo»? R. Si es solo lectura, no es peligroso. Lo peligroso es el permiso de «escribir». Lectura amplia, escritura estrecha. Esa es la división básica.

P. ¿Qué hago con un proyecto donde no sé cuál es el comando de verificación? R. Primero haz que Claude Code proponga candidatos a partir de package.json o del README. Si aun así no queda claro, usa como verificación mínima que git status no muestre diferencias.

P. ¿Se puede hacer lo mismo en PowerShell? R. Sí. La lógica de contar el resultado de git diff --name-only y compararlo con un tope se escribe igual en PowerShell. Adapta el script de verificación al entorno que uses.

P. ¿Este procedimiento lo puede seguir un principiante? R. Sí. Es más, cuanto más principiante, más sirve. Aunque no entiendas el código por completo, si decides antes «qué se puede tocar», evitas los grandes accidentes. Si quieres asentar primero las bases, lee antes la guía de introducción y todo irá más fluido.

Lo que comprobé al probarlo de verdad

Este procedimiento lo armé para mí después del accidente del principio. Lo que más me sirvió al probarlo fue meter en el script de verificación el «tope de archivos cambiados» y la «comprobación automática de la zona protegida».

De hecho, al pasarlo unas tres veces en el repositorio heredado, una vez se detuvo porque el número de archivos cambiados superó el tope. Al mirar dentro, Claude Code había reescrito de paso hasta un componente compartido mientras corregía un texto, y si lo hubiera dejado pasar habría sido un diff con un alcance imposible de prever. Gracias a que se detuvo, pude enviar la corrección dividida en dos.

No es «si lo dejas en manos de una IA lista, todo bien», sino «delega solo dentro del rango que puedes revertir si te caes». Con solo dibujar el mapa primero, el tacto de la primera hora cambia por completo. Si no eres una persona técnica y quieres compartir esta división en tu equipo, también te sirve la puerta de entrada para no técnicos.

El uso oficial de Claude Code lo puedes consultar también en la documentación oficial de Anthropic. Si quieres asentar tus reglas de operación y dejarlas en un formato que tu equipo pueda reproducir, en las sesiones de formación y consultoría mapeamos juntos un repositorio concreto.