Saltar al contenido

Entiende un repositorio heredado con Claude Code antes de tocarlo

En la práctica/ 13 min de lectura

Antes de cambiar un repositorio heredado, haz que Claude Code lo lea en plan mode y arme un mapa en cuatro capas con evidencia, guardado en ARCHITECTURE.md.

  • IA
  • Claude Code
En este artículo (8)
  1. No cambies nada todavía: lee el repositorio heredado en plan mode
  2. El mapa en cuatro capas
  3. Los prompts exactos para Claude Code
  4. Guárdalo en un archivo de arquitectura
  5. El primer cambio seguro
  6. Errores comunes
  7. Preguntas frecuentes
  8. Checklist

Para entender un repositorio heredado con Claude Code, no le pidas cambios el primer día. Ábrelo en plan mode, que lee y explora sin editar, y pídele un mapa en cuatro capas: carpetas, entradas y datos, dependencias y zonas de riesgo, cada dato con el archivo que lo prueba. Guarda el mapa en ARCHITECTURE.md antes del primer cambio.

Aquí tienes los comandos para empezar, los cinco prompts exactos, cómo guardar el mapa sin inflar tu CLAUDE.md, un script en Node que comprueba que el mapa no cita archivos inventados y los criterios para elegir el primer cambio.

No cambies nada todavía: lee el repositorio heredado en plan mode

Un repositorio que no escribiste tiene decisiones que no ves: un cron que nadie documentó, un archivo que parece muerto pero se importa desde un script de despliegue, una función de pagos sin tests. Si le pides a un agente un cambio antes de saber eso, el agente tampoco lo sabe, y vas a revisar un diff sin poder juzgarlo.

Por eso la primera sesión solo lee. La tabla de modos de la documentación de permisos recomienda plan justo para esto: explorar un código antes de cambiarlo. En plan mode Claude lee archivos, corre comandos para explorar y escribe un plan, pero no edita tu código; las ediciones quedan bloqueadas hasta que apruebas el plan. Si no conoces el flujo de aprobación, está explicado en plan mode en Claude Code; aquí lo usamos como herramienta de lectura.

cd ruta/al/repositorio
git status
git switch -c docs/mapa-arquitectura
claude --permission-mode plan
  1. cd a la raíz del proyecto: la receta de la documentación para un proyecto nuevo empieza ahí, y desde la raíz Claude Code carga el CLAUDE.md del proyecto si existe.
  2. git status debe salir limpio. Así, cualquier cambio que aparezca después vino de la sesión y no de antes.
  3. git switch -c abre una rama para el mapa. El único archivo que va a escribir esta sesión queda en su propio commit; el flujo completo está en git para trabajar con agentes de IA.
  4. claude --permission-mode plan arranca la sesión ya en plan mode. Si ya estás dentro, Shift+Tab recorre los modos hasta que la barra de estado diga ⏸ plan mode on.

Dos detalles de la documentación que importan en código viejo. Los comandos de solo lectura (ls, cat, grep, find, wc y las formas de git que solo leen) corren sin pedir permiso; otros comandos pasan por el clasificador o te piden aprobación. Y las búsquedas respetan .gitignore, pero si el repositorio tiene código generado o una librería copiada dentro y versionada, conviene bloquear su lectura con reglas deny de Read, como explica la guía de repositorios grandes. Las reglas en sí están en permisos de Claude Code en settings.json.

El mapa en cuatro capas

Pedir "explícame este repositorio" devuelve un resumen amable y poco útil. Un mapa por capas obliga a contestar preguntas concretas, en un orden que va de lo seguro a lo delicado: primero qué hay, después por dónde pasa el trabajo, después de qué depende y al final dónde duele tocar.

CapaQué respondeDónde mira ClaudeQué anotas
1. CarpetasQué es cada cosa y cómo se arrancaÁrbol de carpetas, manifiesto, scripts, Dockerfile, CIUna línea por carpeta; comandos para instalar, arrancar, probar y construir
2. Entradas y datosPor dónde entra el trabajo y dónde terminaRutas, webhooks, cron, colas, esquema y migracionesEntradas con archivo y línea; un flujo seguido de punta a punta
3. DependenciasDe qué depende y qué está viejo o sin usoManifiesto, lockfile, imports, variables de entorno (solo nombres)Framework y runtime con versión; librerías críticas; servicios externos
4. Zonas de riesgoDónde un cambio puede romper algo caroHistorial de git, tests, tamaño de archivos, TODO y FIXMETabla archivo, señal, evidencia, riesgo; preguntas para el equipo
el mapa en cuatro capas, de lo seguro a lo delicado01carpetas¿qué es cada cosa y cómo se arranca?árbol, manifiesto, scripts, CI02entradas y datos¿por dónde entra el trabajo y dónde acaba?rutas, webhooks, cron, esquema03dependencias¿de qué depende y qué sobra?manifiesto, lockfile, imports04zonas de riesgo¿dónde un cambio sale caro?git log, tests, TODO, tamañouna capa por mensaje, cada dato con su archivolas capas 1 a 3 describen; la capa 4 decide dónde tocar

Desliza la figura para verla completa

El orden importa por una razón práctica: cada capa usa la anterior. No puedes seguir un flujo (capa 2) sin saber qué carpeta es código propio y cuál generado (capa 1), y no puedes juzgar un riesgo (capa 4) sin saber qué archivos tocan dinero o datos (capas 2 y 3). Pide una capa por mensaje, lee la respuesta y corrige antes de pasar a la siguiente.

Los prompts exactos para Claude Code

La sección "Understand new codebases" de los flujos comunes empieza con preguntas amplias, como "give me an overview of this codebase", y después baja a modelos de datos y a seguir un flujo de punta a punta. Estos prompts hacen lo mismo con una exigencia más: cada dato con su archivo, y "sin confirmar" cuando no hay prueba.

1 · Carpetas
Estoy heredando este repositorio y todavía no voy a cambiar nada. Dame la capa 1
del mapa: qué hay en cada carpeta de primer nivel, en una línea; cuáles son código
propio, generado, copiado de terceros o configuración; y los comandos para
instalar, arrancar, probar y construir, sacados de los archivos. Cita el archivo
de cada dato. Si no lo puedes confirmar leyendo, escribe "sin confirmar".

2 · Entradas y datos
Capa 2: lista las entradas del sistema (rutas HTTP, webhooks, cron, colas, CLI)
con archivo:línea. Sigue el flujo más importante desde la entrada hasta donde se
guarda o se envía, paso a paso. Dime dónde están el esquema y las migraciones.

3 · Dependencias
Capa 3: del manifiesto y el lockfile, dame framework y runtime con versión, las
librerías que tocan dinero, autenticación o datos, y las que parecen sin uso
(compruébalo con grep antes de decirlo). Lista servicios externos y variables de
entorno que lee el código: solo nombres, nunca valores.

4 · Zonas de riesgo
Capa 4: ejecuta
git log --since="12 months ago" --format= --name-only | sort | uniq -c | sort -rn | head -20
y cruza esos archivos con los que no tienen tests, los más largos, los que tocan
pagos, auth o datos, y los que tienen TODO o FIXME. Dame una tabla: archivo,
señal, evidencia, riesgo (alto, medio, bajo). Termina con las preguntas que solo
alguien del equipo puede responder.

5 · El plan
Escribe como plan el contenido de docs/ARCHITECTURE.md con las cuatro capas, cada
dato con su archivo, y una sección de preguntas abiertas. No propongas cambios
de código.
  1. Carpetas. "Todavía no voy a cambiar nada" fija la intención aunque el modo ya lo impida. Separar código propio de generado evita que el resto del mapa se base en archivos que nadie edita a mano. Los comandos salen de los archivos (manifiesto, Makefile, CI), no de lo que el modelo supone.
  2. Entradas y datos. archivo:línea convierte cada afirmación en algo que puedes abrir. Seguir un solo flujo completo enseña más que listar todos a medias.
  3. Dependencias. "Compruébalo con grep" evita el error clásico de declarar sin uso una librería que se carga por configuración. "Solo nombres, nunca valores" mantiene los secretos fuera de la conversación.
  4. Zonas de riesgo. El comando cuenta cuántas veces cambió cada archivo en el último año. Lo corrimos en un repositorio real con Git Bash. git log está en el conjunto de solo lectura; sort y uniq no aparecen en la lista que da la documentación, así que según tu modo te puede pedir permiso: solo leen, apruébalo. En PowerShell no existe uniq; corre ese paso en Git Bash o WSL.
  5. El plan. En plan mode Claude no edita tu código, pero sí escribe un plan. Pedir que el plan sea el contenido del mapa hace que la única edición pendiente sea ese archivo.

Si quieres darle un archivo concreto, usa @: @package.json incluye el contenido si cabe en el límite de lectura (25,000 tokens por defecto; un archivo de texto de más de 256 KB no se incluye) y @src/ muestra el listado de la carpeta, no su contenido. En un repositorio grande, la documentación sugiere delegar la exploración en un subagente para que solo vuelvan los hallazgos.

Guárdalo en un archivo de arquitectura

Cuando el plan te convenza, apruébalo con «Yes, manually approve edits»: Claude sale de plan mode y te pide confirmar cada edición, y la única debería ser docs/ARCHITECTURE.md. Si ves otra, recházala.

del prompt al archivo: una sola ediciónprompts 1 a 4una capa por mensaje, en plan modeninguna ediciónprompt 5el plan es el contenido del mapacada dato con su archivoapruebas el plan«Yes, manually approve edits»Claude sale de plan modedocs/ARCHITECTURE.mdla única edición; check-map.mjs la revisacommit en su ramael mapa vive en docs/, no dentro de CLAUDE.mdlo citas con @docs/ARCHITECTURE.md cuando hace falta

Desliza la figura para verla completa

¿Por qué un archivo aparte y no CLAUDE.md? Las buenas prácticas ponen "describe tu arquitectura y tu estructura de carpetas en CLAUDE.md" en la lista de consejos que ya puedes dejar, porque Claude lee el repositorio por su cuenta. Y según la documentación de memoria, un @docs/ARCHITECTURE.md dentro de CLAUDE.md se carga en cada sesión: importar no reduce el contexto. El mapa es para ti, para la próxima persona y para las tareas que lo necesitan: lo citas con @docs/ARCHITECTURE.md cuando el cambio toca una zona de riesgo. Si quieres nombrarlo en CLAUDE.md, escribe la ruta entre comillas invertidas, que no se importa.

Para el CLAUDE.md en sí, /init genera una primera versión con comandos de build, de tests y convenciones; si ya hay uno, sugiere mejoras en vez de sobrescribirlo. Córrelo después del mapa y recórtalo: lo que debe quedar y lo que va en skills o hooks está en un CLAUDE.md corto con skills y hooks.

Un mapa escrito por un modelo puede citar un archivo que no existe. Este script lo detecta: busca cada ruta entre comillas invertidas y comprueba que esté en el repositorio.

// check-map.mjs: every file path the map cites must exist in the repo.
import { readFileSync, existsSync } from "node:fs";

const map = process.argv[2] ?? "docs/ARCHITECTURE.md";
const lines = readFileSync(map, "utf8").split(/\r?\n/);
const EXT = /\.(json|md|ts|tsx|js|jsx|mjs|cjs|py|rb|go|php|sql|ya?ml|toml|prisma|liquid|css|html|sh)$/i;
const isPath = (s) =>
  !/\s|\*|^\/|^\$|^[a-z]+:/i.test(s) && (s.includes("/") || s.startsWith(".") || EXT.test(s));

let checked = 0;
const missing = [];
lines.forEach((line, i) => {
  for (const [, span] of line.matchAll(/`([^`]+)`/g)) {
    const path = span.replace(/#.*$/, "").replace(/:\d+(-\d+)?$/, "");
    if (!isPath(path)) continue;
    checked++;
    if (!existsSync(path)) missing.push(`line ${i + 1}: ${path}`);
  }
});

for (const m of missing) console.log(`MISSING ${m}`);
console.log(`${missing.length ? "FAIL" : "OK"}: ${checked} paths checked, ${missing.length} missing`);
process.exit(missing.length ? 1 : 0);
  1. Lee el mapa que le pases, o docs/ARCHITECTURE.md por defecto, y lo parte en líneas (sirve con finales CRLF de Windows).
  2. EXT y isPath deciden qué es una ruta: algo sin espacios ni comodines que tenga una barra, empiece con punto o termine en una extensión de código. Descarta rutas HTTP como /api/orders, variables como $DATABASE_URL, node:fs, comandos y globs.
  3. Por cada texto entre comillas invertidas quita el ancla (#scripts) y el número de línea (:40 o :40-88), y comprueba que la ruta exista.
  4. Imprime cada ruta que falta con su línea y termina con código 1 si falta alguna.

Córrelo desde la raíz con node check-map.mjs. Lo probamos en un repositorio de prueba (8 rutas, pasa; quitando dos archivos, falla con las dos) y en un mapa de nuestro propio sitio con una ruta inventada, que marcó. Un .env ignorado por git saldrá como faltante en un clon nuevo: es esperado. El script prueba que los archivos existen, no que la descripción sea correcta; eso lo revisas tú abriendo las citas de la capa 4.

El primer cambio seguro

Con el mapa en la rama, el primer cambio de código se elige con la capa 4 delante. Busca algo que cumpla todo esto: está en una zona de riesgo bajo, tiene tests cerca o puedes escribir uno antes, cabe en un diff que lees en minutos y se revierte con un solo commit. Arreglar un texto, completar un test que falta o borrar una dependencia que el grep confirmó sin uso son buenos candidatos. Una refactorización del archivo que más cambia no lo es.

señales de riesgo en un repositorio heredadoseñalcómo verlaqué hacercambia muchogit log --name-onlytest antes de tocarsin testsningún *.test cercafijar comportamientodinero o authpagos, sesión, rolessolo con revisiónarchivo enormewc -lno refactorizar aúnTODO / FIXMEgrep -rn TODOpreguntar al equipoel primer cambio va donde no aparece ninguna señalcapa 4 del mapa: zonas de riesgoseñales ilustrativas; ajústalas a tu repositorio

Desliza la figura para verla completa

Para hacerlo, empieza una sesión nueva: el contexto de la exploración ya cumplió su función, y la documentación recomienda construir desde un contexto limpio con una definición escrita de terminado. Escribe esa definición como en la especificación para agentes de IA, cita @docs/ARCHITECTURE.md si el cambio toca una zona marcada y revisa el diff con tests como en revisar los cambios de un agente. Por qué la sesión nueva rinde más está en el contexto de un agente de IA.

Si el archivo de riesgo alto no tiene tests y tienes que tocarlo, el primer cambio es un test que fije su comportamiento actual, aunque ese comportamiento parezca raro. Ese test es lo que te deja cambiarlo después sin adivinar.

Errores comunes

  • Pedir un cambio en la primera sesión. El agente no sabe más que tú del repositorio; los dos descubren los riesgos en el diff.
  • Aceptar el resumen sin evidencia. Sin archivo:línea, no puedes distinguir lo que el modelo leyó de lo que supuso.
  • Pedir todo en un mensaje. Las cuatro capas en un prompt dan una respuesta superficial en cada una. Una capa por mensaje, y corrige antes de seguir.
  • Meter el mapa en CLAUDE.md. Se carga en cada sesión y la documentación lo desaconseja. Va en docs/ARCHITECTURE.md y lo citas cuando hace falta.
  • Pegar valores de variables de entorno. El mapa lleva nombres de variables, nunca valores. Revísalo antes del commit.
  • Empezar por el archivo que más cambia. Es donde más duele un error. El primer cambio va donde el riesgo es bajo y el diff es corto.

Preguntas frecuentes

¿Existe un modo de solo lectura en Claude Code?

No con ese nombre. Plan mode es el modo que la documentación recomienda para explorar antes de cambiar: lee, explora y bloquea las ediciones hasta que apruebas. El modo Manual (default) solo ejecuta lecturas sin preguntarte. Si necesitas que algo no se edite nunca, usa una regla deny en los permisos.

¿Por qué no basta con correr /init?

/init genera un CLAUDE.md inicial con comandos y convenciones, que es lo que Claude necesita en cada sesión. No te dice qué flujo guarda dinero, qué archivo no tiene tests ni qué preguntas tienes que hacerle al equipo. Haz el mapa primero y corre /init después.

¿Y si el repositorio es enorme o un monorepo?

Haz un mapa por paquete y arranca Claude en la carpeta de ese paquete. Bloquea la lectura del código generado con reglas deny de Read y delega la exploración amplia en un subagente, como sugiere la guía de repositorios grandes. El plan de plan mode se guarda en un archivo y se vuelve a cargar después de una compactación.

¿Cómo sé que el mapa no se inventó nada?

Tres filtros: cada dato con su archivo, "sin confirmar" cuando no hay prueba, y el script que comprueba que las rutas existen. Después abre tú las citas de la capa 4, que son las que deciden dónde vas a tocar. Lo que el equipo confirme, anótalo en la sección de preguntas abiertas.

Checklist

  • Árbol de git limpio y una rama para el mapa.
  • Sesión en plan mode; ninguna edición antes de aprobar el plan.
  • Una capa por mensaje: carpetas, entradas y datos, dependencias, zonas de riesgo.
  • Cada dato con archivo:línea o marcado "sin confirmar".
  • Variables de entorno por nombre, nunca con su valor.
  • El mapa en docs/ARCHITECTURE.md, no importado en CLAUDE.md.
  • node check-map.mjs pasa sin rutas faltantes.
  • /init después del mapa, y el CLAUDE.md recortado.
  • El primer cambio: riesgo bajo, con test, diff corto, en una sesión nueva.

¿Viste esto en Instagram? Todas las guías de los Reels están en ecomlabs.dev/guias.

Escrito por

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

Publicado el 19 de noviembre de 2026 · actualizado el 20 de noviembre de 2026

← Blog