Entender código con Claude Code: el mapa antes de tocar nada
DominicodeLunes, primer día en el proyecto. Te dan acceso a un repo con ocho años de commits, tres autores que ya no están y un ticket para el miércoles.
Haces lo que haría cualquiera para entender código con Claude Code: escribes "explícame este repo". En un minuto tienes un resumen impecable, con capas, servicios y un flujo de autenticación bien contado.
El martes buscas el AuthMiddleware del resumen. No existe. Hay un guard con otro nombre en otra carpeta, y media validación vive en un trigger de base de datos que el resumen no menciona. El agente sabía leer. Tú no le pediste pruebas.
En corto: para entender código con Claude Code, trabaja en plan mode para que no edite nada y sigue cuatro pasos: mapa de alto nivel, flujo de una petición de punta a punta, dónde viven las reglas de negocio y preguntas trampa. Exige ruta:línea en cada afirmación y abre los archivos tú. Delega la exploración pesada a un subagente para no llenar el contexto.
¿Qué es entender código con Claude Code?
Entender código con Claude Code es usar el agente para construir un mapa verificable de un repositorio (estructura, flujo de una petición y reglas de negocio) en modo solo lectura, comprobando cada afirmación contra rutas y líneas reales antes de cambiar nada.
La palabra que importa es verificable. Un mapa que no puedes comprobar es una opinión bien redactada.
Este post va de leer, no de cambiar. Para migrar después, sigue con refactorizar código legacy con el método SDD.
Por qué "explícame este repo" no basta
Aparte de tu CLAUDE.md, Claude Code no conoce el repo de antemano: construye el contexto buscando y abriendo archivos. En Hacker News, themanmaran lo describió en octubre de 2025 como "putting grep in a for loop", el mismo proceso que él seguiría en un código desconocido (comentario en HN).
Si la búsqueda no llega a un archivo, el resumen rellena el hueco con lo que suele haber en un proyecto así: suena bien y falla en los detalles.
El otro riesgo es tuyo. En junio de 2026, overgard contaba en HN que estaba aprendiendo el código de un trabajo nuevo y que la IA era "a really double edged sword": útil para preguntar, pero si deja que aplique el fix antes de investigar, no aprende el código. Añadía que, a ese tamaño, incluso los modelos frontera tienen problemas (comentario en HN).
El agente acelera la lectura. El entendimiento tiene que acabar en tu cabeza, no en el chat.
Explorar un repositorio con Claude Code sin que edite nada
Para explorar un repositorio con Claude Code, empieza en plan mode: Claude lee archivos, ejecuta comandos de exploración y escribe un plan, pero no edita tu código hasta que lo apruebes (permission modes, consultado en octubre de 2026).
claude --permission-mode plan
Dentro de una sesión, pulsa Shift+Tab hasta que la barra muestre ⏸ plan mode on, o empieza un prompt con /plan. Si el repo es solo para estudiarlo, fija permissions.defaultMode a "plan" en .claude/settings.json (las sesiones que abre la extensión de VS Code no leen ese ajuste del proyecto).
El modo completo lo cuento en plan mode en Claude Code. Aquí es un cinturón de seguridad: desde Claude Code v2.1.283 la terminal arranca en auto mode, donde un clasificador aprueba las acciones por ti. En un repo ajeno no quieres un "ya que estoy, lo arreglo".
El método para entender código con Claude Code en cuatro pasos
La guía de workflows de Anthropic arranca con "give me an overview of this codebase" y aconseja ir de lo amplio a lo concreto. Mantengo ese orden, pero cada pregunta exige ruta:línea.
1. Mapa de alto nivel
Pide estructura, no explicación, y que separe lo leído de lo deducido.
Dame un mapa del repo: puntos de entrada, módulos principales,
dependencias externas y cómo se arranca en local.
Cada afirmación con ruta:línea. Separa lo que has leído de lo que deduces.
2. Flujo de una petición de punta a punta
Elige la petición más común del producto y pide que la siga hasta la base de datos.
Sigue POST /orders desde el router hasta la escritura en base de datos.
Cada salto como ruta:línea con la función que se ejecuta.
Si un salto depende de configuración o inyección de dependencias, dilo.
Un flujo trazado vale más que diez resúmenes de módulos: da nombres reales y orden de llamada.
3. Dónde viven las reglas de negocio
Las reglas casi nunca están en un solo sitio: validaciones, servicios, triggers, jobs nocturnos.
¿Dónde se decide si un pedido puede cancelarse? Busca en todas las capas,
incluidas migraciones, triggers y jobs. Cada regla con ruta:línea.
Si no encuentras alguna capa, dilo.
4. Preguntas trampa
Pregunta por algo que sabes que no existe.
¿Qué hace la función calculateLegacyDiscountV2 y quién la llama?
La respuesta correcta es "no la encuentro". Si te la explica, desconfía del resto.
Preguntas útiles vs preguntas que generan alucinación
La diferencia no es el tema. Es si la respuesta se puede comprobar.
| Pregunta | Tipo | Por qué | Cómo verificar |
|---|---|---|---|
| "Sigue POST /orders con ruta:línea en cada salto" | Útil | Obliga a leer archivos concretos | Abre cada ruta y comprueba que llama a la siguiente |
| "¿Dónde se valida el email? Lístalas todas" | Útil | Pide búsqueda, no recuerdo | Busca el campo tú con grep y compara |
| "¿Qué tests cubren el cálculo de impuestos?" | Útil | La respuesta son archivos | Rompe la función y mira qué tests fallan |
| "Explícame la arquitectura" | Alucinación | Invita a narrar patrones típicos | Pide las rutas de cada capa; sin rutas, descártalo |
| "¿Por qué se hizo así?" | Alucinación | La intención no está en el código | git blame sobre esas líneas y el PR asociado |
| "¿Es seguro cambiar X?" | Alucinación | Sin tests nadie lo sabe leyendo | Busca llamadores y tests; si no hay, "no se sabe" |
Las tres de abajo no están prohibidas. Trátalas como hipótesis, no como hechos.
Cómo verificar lo que te dice Claude Code
Verificar es abrir el archivo. Pide siempre ruta:línea y abre al menos las rutas que sostienen tus conclusiones. Si una no existe o la línea dice otra cosa, vuelve a preguntar citando el error.
Mi regla: una afirmación sin ruta:línea no entra en las notas de onboarding. Si el agente no puede señalarla, no la sé.
Segundo filtro: ejecuta. Si el mapa dice que un test cubre un caso, rómpelo y míralo fallar.
Subagentes de exploración para no llenar el contexto
Explorar un repo grande llena el contexto de lecturas que no vas a volver a usar. La documentación propone delegar la exploración para que solo vuelvan las conclusiones (common workflows).
Usa un subagente para investigar cómo gestiona el sistema de auth
el refresco de tokens. Devuélveme el flujo con ruta:línea.
Claude Code trae un subagente integrado, Explore, de solo lectura (Write y Edit denegados), con niveles quick, medium y very thorough que elige Claude (subagentes, octubre de 2026). Ojo: Explore no carga tus CLAUDE.md para ir más rápido, así que no verá las convenciones que tengas ahí.
Mi regla: un subagente por pregunta, nunca "explora todo el repo". Cuanto más acotado el encargo, más fácil verificar lo que devuelve. Para coordinar varios, tienes cómo orquestar subagentes.
Cuándo no fiarte del mapa que te da la IA
El método reduce errores, no los elimina. Hay zonas donde lo que buscas no está escrito en el código que el agente lee.
Código generado. Clientes OpenAPI, tipos de Prisma o GraphQL, salidas de build. Si no están en el repo, el agente razona sobre algo que no ha visto; si están, puede tomarlos por código escrito a mano.
Metaprogramación e inyección de dependencias. Decoradores, reflection, registros dinámicos, rutas construidas con strings. Un grep no encuentra quién llama a algo que se resuelve en runtime. Ahí el paso 2 necesita debugger o logs.
Configuración en runtime. Feature flags, variables por entorno, reglas guardadas en base de datos. El código dice "si el flag está activo"; qué pasa en producción lo dice un panel que el agente no ve.
Repos enormes. El agente lee una muestra. Aparte, un @archivo solo entra si cabe en el límite del Read tool (25.000 tokens por defecto) y un texto de más de 256 KB no entra; ese límite es de las referencias @, no de cómo explora el agente (common workflows, octubre de 2026). En monorepos, acota antes con smart context slicing.
Plan mode no es una jaula. Ejecuta comandos de exploración, y en sesiones de terminal con bypass permissions disponible no aplica sus bloqueos (permission modes). Si hay scripts que tocan datos reales, mira qué lanza.
Del mapa verificado a CLAUDE.md
Lo verificado (rutas clave, flujo principal, reglas y trampas) no debería morir en tus notas: es lo que necesita el siguiente agente o compañero.
Conviértelo en CLAUDE.md. Cómo estructurarlo está en CLAUDE.md: el system prompt de tu proyecto. Una sola condición: que entre lo verificado, no lo deducido.
Qué hacer con tu próximo repo ajeno
No pidas "explícame esto". Arranca con claude --permission-mode plan, haz las cuatro preguntas en orden y abre cada ruta:línea que sostenga una conclusión. Saldrás con un mapa en el que apoyarte el miércoles, cuando toque cambiar código.
En el curso Construye con IA trabajamos ese flujo completo con Claude Code, de la idea al producto. Y si el siguiente paso es cambiar el código, escribir la especificación antes que el prompt es lo que defiendo en el libro Spec-Driven Development.
Preguntas frecuentes
¿Puede Claude Code entender un repositorio entero de una vez?
No en un repo grande: lee archivos bajo demanda y trabaja con una muestra. Pregunta por flujos concretos y delega las búsquedas amplias a subagentes.
¿Plan mode impide que Claude Code modifique archivos?
Bloquea las ediciones hasta que apruebes el plan, pero puede ejecutar comandos para explorar. En sesiones de terminal con bypass permissions disponible no aplica sus bloqueos.
¿Cómo sé si Claude Code se está inventando una respuesta?
Pide ruta:línea en cada afirmación y abre los archivos. Añade una pregunta trampa sobre algo que no existe: si lo explica en vez de decir que no lo encuentra, desconfía del resto.
¿Sirve este método para el onboarding de un codebase con IA en equipo?
Sí. El mapa verificado sirve de documento de onboarding y, pasado a CLAUDE.md, orienta a los agentes que vengan después.
Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.
¿Te resultó útil este artículo?
Compártelo con tu comunidad y ayuda a otros desarrolladores.