Google Maps para codebases: pegué la URL de mi propio repo y me asusté un poco

Gitingest, Repomix, CodeViz — la semana pasada cayeron en mi radar varias herramientas que prometen lo mismo: pegás una URL de GitHub y podés conversar con el código, mapearlo, entender su arquitectura en segundos. La comunidad las está descubriendo con el entusiasmo habitual. Yo también las probé. Y el experimento más interesante no fue analizar el repo de algún framework famoso.

Fue analizar el mío.

Hay algo levemente narcisista en pegar la URL de tu propio proyecto en una herramienta de análisis. Y algo levemente aterrador en lo que te devuelve.

Codebase visualization con GitHub AI análisis: de qué hablamos exactamente

Antes de entrar en lo que encontré, vale la pena aclarar de qué hablamos cuando hablamos de "visualización de codebases con AI".

No es simplemente un grafo de dependencias. Eso existía hace años y nadie lo usaba porque los grafos de dependencias de Node.js parecen el mapa del subte de Tokio después de un terremoto.

Lo que cambió es la capa de lenguaje natural encima. Herramientas como Gitingest convierten el repo entero en un formato que puede ingerir un LLM. Después podés hacer preguntas en lenguaje natural: "¿dónde están los cuellos de botella de performance?", "¿qué componentes tienen más acoplamiento?", "¿hay patrones inconsistentes en el manejo de errores?"

Repomix hace algo similar pero más enfocado en generar un archivo de contexto comprimido. La idea es que ese archivo se lo pasás a Claude o GPT-4 como contexto y preguntás lo que quieras.

Lo que obtienen estas herramientas no es magia — es contexto masivo entregado de forma eficiente. El análisis lo hace el LLM. La herramienta es el preprocesador.

# Instalación básica de Repomix
npx repomix

# O apuntando a un repo remoto directamente
npx repomix --remote juanchi-dev/juanchi.dev

# Genera un archivo repomix-output.xml con todo el código
# comprimido y listo para pasarle a un LLM

Hasta acá, nada nuevo. La novedad es qué pasa cuando el código analizado es tuyo y lo conocés de memoria — o eso creías.

Lo que un LLM encontró en juanchi.dev que yo no veía

juanchi.dev es mi proyecto público. Lo construí con Next.js 15, React 19, Tailwind v4, desplegado en Railway. Ya escribí sobre el stack en detalle. Creía que lo conocía bien.

Pasé el repo por Repomix, generé el archivo de contexto, y lo cargué en Claude con un prompt simple: "Analizá este codebase como si fueras un senior developer haciendo code review. Sé honesto. No me des palmaditas en la espalda."

Lo que salió me hizo abrir tres archivos que no tocaba hace semanas.

Hallazgo 1: Inconsistencia en el manejo de errores

Mis Server Components y mis Route Handlers manejaban los errores de forma distinta. En algunos lugares usaba try/catch con logging explícito. En otros, dejaba que Next.js manejara el error silenciosamente. No había una estrategia unificada.

// Cómo manejaba errores en algunos Server Components
async function getBlogPost(slug: string) {
  try {
    const post = await db.query(/* ... */)
    return post
  } catch (error) {
    // Logging explícito, re-throw controlado
    console.error(`Error fetching post ${slug}:`, error)
    throw new Error('Post no encontrado')
  }
}

// Cómo manejaba errores en OTROS lugares (el problema)
async function getProjects() {
  // Sin try/catch. Si falla, falla en silencio o explota arriba
  const projects = await db.query(/* ... */)
  return projects
}

El LLM lo identificó como "falta de estrategia de error handling consistente". Tenía razón. No era un bug — era deuda técnica acumulada de haber construido el proyecto en múltiples sesiones sin un estándar definido.

Hallazgo 2: Componentes con demasiadas responsabilidades

Había un componente que el análisis identificó como un "God Component" — hacía fetching, formateo de datos Y renderizado, todo junto. Yo lo había construido así porque en el momento era más rápido. Funcionaba. Pero no era correcto.

// El componente problemático (simplificado)
// Hace demasiado: fetch + transform + render
export async function BlogPostCard({ slug }: { slug: string }) {
  // Lógica de fetching que debería estar separada
  const post = await fetch(`/api/posts/${slug}`).then(r => r.json())
  
  // Transformación que debería estar en una utility
  const formattedDate = new Intl.DateTimeFormat('es-AR', {
    year: 'numeric',
    month: 'long',
    day: 'numeric'
  }).format(new Date(post.date))
  
  // Solo esto debería estar acá
  return (
    <article>
      <h2>{post.title}</h2>
      <time>{formattedDate}</time>
    </article>
  )
}

Hallazgo 3: El que más me dolió

Tenía lógica de negocio duplicada en dos lugares distintos. La misma transformación de datos escrita dos veces, ligeramente diferente cada vez. El tipo de cosa que en una code review rechazarías en el primer comentario.

No lo había visto porque cuando estás dentro del código, navegás por él de forma funcional — abrís el archivo que necesitás, hacés el cambio, cerrás. No tenés la vista panorámica.

Eso es exactamente lo que hice cuando optimicé el performance del sitio a 300ms: fui archivo por archivo, función por función. Eficiente para ese objetivo. Ciego para el panorama general.

Los antipatrones que no ves porque sos vos quien los escribió

Hay un problema epistemológico en revisar tu propio código: sabés demasiado.

Sabés por qué tomaste cada decisión. Sabés el contexto. Sabés qué quisiste hacer. Y ese conocimiento actúa como una capa de racionalización que filtra los problemas antes de que los veas.

Cuando un externo (humano o LLM) mira el código, no tiene ese contexto. Ve solo lo que está escrito. Y a veces lo que está escrito no refleja lo que tenías en mente.

Esto me recuerda algo que aprendí mucho antes de escribir TypeScript. Cuando estudiaba para el CCNA en 2009, practicaba configuraciones de red en Packet Tracer hasta memorizarlas. Pero cuando me sentaba a hacer los simulacros de examen, me equivocaba en exactamente las cosas que "sabía". El conocimiento implícito no siempre sobrevive el cambio de contexto.

El LLM operando sobre mi código es ese cambio de contexto forzado.

Dicho esto — no es magia y tiene límites claros.

Lo que el análisis NO vio:

• Por qué algunas decisiones de arquitectura son intencionales (tradeoffs que yo conozco)
• El contexto de evolución del proyecto (code que parece legacy pero tiene razón de ser)
• Problemas de performance que solo se ven en runtime — para eso tuve que instrumentar manualmente
• Integraciones específicas con servicios externos donde la "inconsistencia" es necesaria

Combinado con lo que sí encontró, el mapa es útil. Solo. No suficiente.

Errores comunes cuando usás estas herramientas

Error 1: Tomar todo como verdad absoluta

El LLM no sabe si esa "inconsistencia" en el manejo de errores es deuda técnica o una decisión deliberada. Vos sí. Filtrá.

Error 2: Usarlo sobre repos gigantes sin acotar el contexto

Repomix sobre un monorepo de 500k líneas va a generar un archivo de contexto que ningún LLM puede procesar bien. El análisis se degrada. Mejor acotar: pasá solo los directorios relevantes.

# Mejor acotar el análisis a lo que importa
npx repomix --include "src/components/**,src/lib/**"

# En vez de pasar todo el repo con node_modules y ruido
npx repomix  # sin filtros = mucho ruido

Error 3: Esperar que reemplace el code review humano

El análisis AI encontró tres problemas reales en mi código. Un senior developer con contexto de negocio hubiera encontrado esos tres más cinco que el LLM racionalizó o no pudo evaluar. Esto es lo mismo que aprendí con los coding agents: el AI acelera, no reemplaza el criterio.

Error 4: No iterar el prompt

El primer análisis que pedí fue genérico. El útil vino cuando refiné: "Enfocate específicamente en patrones de fetching de datos y cómo se propagan los errores hasta el cliente. Ignorá styling y configuración." La especificidad importa.

Error 5: Usarlo solo una vez

El valor real es usarlo como checkpoint periódico. Un snapshot del estado del código cada mes, con las mismas preguntas, te muestra si tu deuda técnica está creciendo o achicándose.

Esto conecta con algo que vi cuando metí un LLM chico en una app Next.js: la calidad del output depende brutalmente de la calidad del contexto que le das. Garbage in, garbage out — pero también ruido in, análisis diluido out.

FAQ: Preguntas frecuentes sobre codebase visualization con AI

¿Cuál es la mejor herramienta para analizar un repo de GitHub con AI?

Depende del objetivo. Para conversación libre sobre el código, Gitingest (gitingest.com) es el más directo — pegás la URL y podés preguntar en lenguaje natural. Para generar contexto que pasarle a tu LLM preferido, Repomix es más flexible y configurable. Para visualización gráfica de dependencias, CodeViz o Mermaid generado por el LLM funcionan bien. No hay una bala de plata.

¿Es seguro pegar la URL de un repo privado en estas herramientas?

Depende de la herramienta y tu modelo de amenaza. Repomix instalado localmente nunca sale de tu máquina — el código no va a ningún servidor externo. Herramientas web como Gitingest procesan el código en sus servidores. Para repos privados con código sensible, la opción local siempre es más segura. Para repos públicos, no hay diferencia.

¿Qué tan precisos son los análisis que devuelve el LLM?

En mi experiencia: precisos en detectar inconsistencias de patrones, imprecisos en evaluar decisiones de arquitectura sin contexto. El LLM ve el código tal como está escrito. No ve por qué está así. Los falsos positivos existen — te va a señalar como problema algo que es una decisión intencional. El filtro humano es obligatorio.

¿Funciona bien con repos grandes (más de 100k líneas)?

Mal, en general. Los LLMs tienen ventanas de contexto finitas. Repomix comprime el código para maximizar lo que entra, pero con repos muy grandes hay que acotar el análisis a subdirectorios o módulos específicos. Mejor análisis focalizado que análisis superficial de todo.

¿Puede reemplazar a un code review humano?

No. Complementarlo, sí. El análisis AI es rápido, sin ego, y no tiene contexto — esas tres cosas son simultáneamente su fortaleza y su límite. Encuentra lo que un humano podría pasar por alto por cansancio o familiaridad. No puede evaluar si una decisión es correcta para el negocio, el equipo, o la historia del proyecto. Son herramientas distintas para capas distintas del problema.

¿Vale la pena usarlo sobre código propio si ya lo conocés bien?

Especialmente sobre código propio. Esa es la paradoja. Cuanto más conocés el código, más necesitás la perspectiva externa. El conocimiento implícito que tenés actúa como filtro — te impide ver los problemas porque ya los racionalizaste. Un LLM sin contexto ve solo lo que está escrito. A veces eso es exactamente lo que necesitás.

¿Mapa útil o ansiolítico digital?

La pregunta que me hice antes de escribir esto: ¿cambié algo después del análisis?

Sí. Unifiqué el manejo de errores. Rompí el God Component en tres piezas. Eliminé la duplicación de lógica. Tres cambios concretos en código que funciona en producción hoy.

Pero también me pregunté si el ejercicio no era en parte ansiolítico — la sensación de que "auditaste" tu código sin haber realmente enfrentado el problema más profundo, que es tener más disciplina desde el principio.

La respuesta honesta es: probablemente ambas cosas. Y está bien.

Lo que aprendí en 30 años con tecnología — desde diagnosticar cortes de red a las 11pm en un cyber hasta deployar en Railway — es que las herramientas que te dan perspectiva son valiosas aunque sean imperfectas. El CCNA no me enseñó a administrar redes reales. Me dio el vocabulario para entender qué estaba mirando. Claude Code no escribe el código por mí. Acelera el tiempo que paso en lo que ya sé hacer.

Estas herramientas de visualización hacen algo similar: te devuelven tu propio código con ojos nuevos. Lo que hacés con eso depende de vos.

Pegá la URL de tu repo. Date un susto productivo.