Prompts para Entender Código que No Es Tuyo

Te toca un módulo que no has visto en tu vida. Ciento ochenta líneas de función sin nombre útil, tres efectos secundarios que no se intuyen, y un comentario de 2019 que dice // TODO: fix later. Nadie del equipo recuerda por qué está así. Tienes tres opciones: leerlo entero y perder una tarde, preguntar y hacer ruido, o usar una IA bien interrogada.

La tercera es la buena, con un matiz importante: la IA no ejecuta el código. Explica lo que ve y, cuando le faltan contexto, rellena huecos con lo que sería razonable. Ese matiz es exactamente la diferencia entre entender el código y CREER que lo entiendes. Por eso los prompts que verás aquí están diseñados para que la IA se equivoque en voz alta antes que en silencio.

Antes de nada, si tu problema real es que el código falla y no se ejecuta bien, empieza por los mejores prompts para depurar código con IA. Aquí vamos del caso contrario: el código funciona, y simplemente no sabes qué hace.

Cuatro cosas que conviene tener claras antes de empezar

1. Pide siempre líneas concretas. “Esta función hace lo mismo que la anterior” no es verificable. “Las líneas 42 a 58 recorren el array y_validation” sí lo es. Si no puede citar líneas, es que está suponiendo.

2. Pídele que diga “no está en el código” cuando no tenga respuesta. Sin esta instrucción, la IA siempre responde, y una respuesta segura e inventada es peor que un silencio.

3. Empieza por el mapa, no por las líneas. En un repositorio desconocido, lo primero que necesitas es saber dónde está el norte. Copiar 400 líneas de un archivo al principio es tirar tokens a la basura.

4. Pide también lo que el código NO hace. El código te dice lo que hace. Lo interesante casi siempre es lo que deja de hacer: validaciones que faltan, casos sin cubrir, efectos colaterales que nadie menciona.

Los prompts

1. Explicar un archivo entero

Voy a entrar en este repositorio y no conozco nada. Este es el primer
archivo que voy a leer:

[pegar el archivo completo, con la ruta arriba]

Dime:
1. Qué responsabilidad tiene este archivo, en una frase.
2. Qué expone (exports, clases, funciones públicas) y quién lo usa.
3. Qué dependencias tiene y de dónde vienen.
4. En qué parte del flujo del sistema ocurre esto (entrada,
   transformación, persistencia, salida...).
5. Qué parte me toca leer primero para entenderlo.

No me des tutoriales genéricos del lenguaje. Cita líneas concretas
del archivo en cada afirmación.

Si algo no se puede deducir del código, escribe "no está en el código".

Por qué funciona: separarlo en cinco preguntas cerradas impide que la IA se vaya por las ramas con una descripción vaga. La última instrucción (decir “no está en el código”) es lo que separa una explicación fiable de una con frases compuestas.

Ejemplo real de respuesta:

1. Es el punto de entrada HTTP del módulo de facturación. Todas las
   rutas cuelgan de `router` (línea 18).

2. Exporta `createRouter` y `registerBillingRoutes`. Lo consume
   `src/server/index.ts` al arrancar; lo importa también el test de
   integración `billing.integration.test.ts`.

3. Depende de `stripe` (línea 3), del repositorio de facturas
   (`../repositories/invoiceRepo`, línea 5) y de `authMiddleware`
   (línea 4).

4. Es la capa de transporte: valida entrada, llama al servicio y
   traduce errores a códigos HTTP. No toca la base de datos
   directamente.

5. Empieza por las rutas en las líneas 24-118; después mira
   `mapStripeError` en la línea 131, que es donde está toda la
   lógica no obvia.

Eso son 30 segundos de trabajo contra la hora que cuesta lo mismo a ojo.

2. Hacer un mapa de un módulo entero

No conozco este repositorio. Aquí tienes su estructura:

[pegar salida de `find . -type f -name "*.ts" -not -path "*/node_modules/*"`
 o el árbol de carpetas del módulo]

Y el contenido de los entry points:
[pegar los index o main de cada carpeta]

Hazme un mapa del módulo:
- Qué hace el sistema en conjunto, en 3 frases.
- Qué carpeta hace qué, en una línea por carpeta.
- Cuál es el recorrido típico de una petición o de un job, con las
  carpetas implicadas en orden.
- Dónde está la lógica de negocio y dónde está el pegamento (infra,
  config, serialización).
- Los tres archivos que leería primero y por qué.
- Los tres archivos que parecen sobrar y que probablemente estén
  muertos.

Sin suposiciones: si algo no se deduce de los nombres y los entry
points, márcalo como "no verificable con lo que te paso".

Por qué funciona: un modelo con el árbol de carpetas y dos entry points construye un mapa bastante bueno, porque los nombres de archivo y de directorio son señales muy fuertes. Y el aviso de “no verificable” te evita perseguir archivos que no existen.

3. Entender una función compleja paso a paso

Esta función hace más de lo que parece y no la entiendo.
No me hagas un resumen: quiero entender la EJECUCIÓN.

[pegar la función]

Explícamela así:
1. Qué firma tiene y qué devuelve en cada caso (incluye excepciones).
2. Qué variables son parámetros de entrada, cuáles son estado externo
   y cuáles son locales. Marca las mutables.
3. Recorre el flujo con un ejemplo concreto: entrada de ejemplo
   [ejemplo] y qué ocurre línea a línea hasta la salida.
4. Qué efectos secundarios tiene (BD, red, sistema de ficheros, logs)
   y en qué momento exacto se producen.
5. Qué casos borde NO cubre y qué pasa en ellos.
6. Qué parte del código es más difícil de leer y por qué.

Cita números de línea en cada paso.

Por qué funciona: la clave es el punto 3. Poner un ejemplo concreto de entrada y recorrer la ejecución obliga a la IA a simular el código real en lugar de describir la intención declarada. Ahí es donde aparecen los bugs escondidos: si la IA no puede seguir su propio ejemplo, el problema está en el código o le falta contexto.

4. Trazar el flujo de una petición de principio a fin

Necesito entender qué pasa desde que entra una petición hasta que se
devuelve la respuesta.

Punto de entrada: [ej: POST /api/orders].
Tecnología: [Node + Express / Next.js API routes / Fastify / Django].

Ya sé esto:
- Rutas registradas: [pegar el archivo de rutas]
- Middleware global: [lista]

No me expliques la teoría. Sigue ESTA petición concreta por el código
real y ve saltando de archivo en archivo.

Formato:
1. Lista ordenada de archivos que se tocan, con el motivo.
2. Para cada salto: función que se llama, archivo y línea.
3. Dónde se validan los datos y dónde se accede a la base de datos.
4. Dónde se puede cortar: todos los puntos donde puede lanzarse una
   excepción y qué devuelve el usuario en cada uno.
5. Dónde se registra el error o la petición (logging).

Si en algún salto no estoy seguro de qué hace el código, escribe
"revisar a mano" en lugar de inventar.

Por qué funciona: seguir un flujo real obliga a que cada afirmación esté anclada a un archivo, y los “revisar a mano” son tan útiles como el resto: te dicen dónde no fiarte. La lista de puntos de fallo es la parte que más valor tiene cuando estás heredando un sistema.

5. Detectar deuda técnica

Revisa este módulo buscando deuda técnica. No busques errores de
sintaxis: busca problemas de diseño que van a costar dinero dentro de
seis meses.

[pegar el código o la lista de archivos con contenido]

Analiza:
- Funciones que hacen más de una cosa. Di qué hace cada una.
- Acoplamiento: qué pasa si quiero cambiar X, cuántos archivos toco.
- Duplicación literal o casi literal, con los sitios.
- Estado global o singletons, y quién puede mutarlo.
- Manejo de errores genérico (catch vacío, catch que se traga todo).
- Dependencias en la capa equivocada (lógica de negocio en el
  controlador, acceso a BD en el cliente).
- Funciones sin tests: por el estilo del código, ¿cuáles dirías que no
  los tienen?

Para cada hallazgo: archivo, línea, problema, coste estimado de
arreglarlo (bajo/medio/alto) y qué romperías al arreglarlo.

Prioriza por coste/beneficio, no por gravedad.

Por qué funciona: el truco está en el formato de salida. Obligar a rellenar “qué romperías al arreglarlo” es lo que separa un análisis útil de una lista de deseos. Si reescribir algo rompe tres sitios, el coste sube, y la IA lo calcula.

6. Entender una regex

No sé leer esta regex. Explícamela con el mismo código de ejemplo.

Regex: [pegar]
Lenguaje: [JavaScript / Python / PCRE]
Cadenas con las que suelo comparar: [ejemplos reales, 3 o 4]

Dame:
1. Qué parte hace qué, desglosada token a token, en una tabla.
2. Qué cadena mínima hace match.
3. Qué cadenas NO hacen match y por qué. Al menos 3 casos, con
   los que casi seguro se cuelan.
4. Qué hace con los grupos de captura, si los hay.
5. Si es frágil o peligrosa, y cuál sería una versión equivalente
   más legible. Si es simple, dilo.
6. Cómo la reescribirías para que se entendiera de un vistazo.

Por qué funciona: la pregunta 3 es la importante. Saber lo que una regex acepta es fácil; saber lo que no acepta es lo que evita el bug de producción a las tres de la mañana. Y las cadenas reales del usuario son las que hacen útil el análisis.

7. Entender un bug leyendo el código

Este es el más útil de todos cuando heredaste algo.

Este código tiene un bug. No te voy a dar el error porque quiero
entenderlo leyendo, no que me lo parchees.

Comportamiento esperado: [qué debería pasar].
Comportamiento actual: [qué pasa].

Código:
[pegar el archivo entero, no solo el fragmento sospechoso]
[pegar si tienes los tipos o el esquema de datos]
[pegar si tienes un test que falla]

Método:
1. Lista las hipótesis, de más a menos probable.
2. Para cada hipótesis: qué línea del código la respalda y cómo la
   comprobarías con una prueba concreta.
3. No me des el arreglo todavía. Quiero entender la causa primero.

Por qué funciona: decir “todavía no” evita el reflejo de darte un parche sin explicación. Y pedir las hipótesis ordenadas por probabilidad es lo que te deja descartarlas una a una en lugar de aceptarlas todas. La diferencia entre entender un bug y parchearlo es justo esta.

Ejemplo real de salida:

1. El filtro por `tenantId` se aplica DESPUÉS del `find` en vez de
   antes. En invoiceRepo.ts:88 el where solo filtra por estado.

   Cómo comprobarlo: insertar dos facturas, una de cada tenant, con
   el mismo estado, y pedir el listado para un tenant. Salen las dos.

2. `parseInt` sin radix en la línea 112 devuelve NaN con fechas en
   formato "2026-10".

   Comprobación: pasar "2026-10" como periodo y ver si el filtro se
   queda sin resultados en lugar de dar error.

8. Hazme preguntas hasta que lo entienda

Este es el prompt que más subestima la gente y el que más rinde. Método socrático.

Voy a entender este código y no quiero que me lo expliques de una vez.
Quiero que me preguntes.

Código inicial: [pegar fragmento]

Método:
1. Empieza con una pregunta sobre lo que NO debería fallar aquí.
2. Espera mi respuesta. No avances hasta que responda.
3. Si mi respuesta es correcta, pasa a la siguiente pregunta.
   Si es incorrecta o incompleta, corrígela y vuelve a preguntar de
   otra forma.
4. Cuando creas que ya lo entiendo, hazme una pregunta de examen que
   no sea un "¿lo has entendido?".
5. Al final dame un resumen de lo que he confirmado que sé.

Nivel: [principiante / intermedio / avanzado en [lenguaje]].
Empieza por lo que determine el comportamiento observable de este
código, no por la sintaxis.

Por qué funciona: es socrático de manual. La IA solo avanza cuando confirmas, así que no te deja avanzar con una comprensión falsa. Y el punto 6 (pregunta de examen) revela huecos que tú no sabías que tenías. Es lento, y por eso funciona: es lo contrario del copiar y pegar.

9. Entender por qué el código está hecho así

Hay código en este archivo que parece innecesario y seguro que se
puede borrar. En vez de borrarlo, quiero entender por qué existe.

Código: [pegar]

Historial del archivo:
[pegar `git log --follow -p -- archivo` con los commits relevantes,
 o al menos `git log --oneline -- archivo` con mensajes]
[pegar issues, PRs o comentarios de review que los mencionen]

Pregúntame:
1. ¿Qué problema resolvería cada pieza que me parece innecesaria?
2. ¿Qué bug histórico hay detrás de cada patrón raro?
3. ¿Qué pasaría si la borro y qué test lo detectaría?
4. ¿Cuál es el cambio mínimo que la simplifica sin perder nada?

No asumas que es basura porque se ve rara. El código raro suele
existir por un motivo.

Por qué funciona: enlaza el código con git log y el modelo encuentra el commit que explica la rareza. Eso es algo que puedes hacer tú con git blame pero que tarda veinte minutos por archivo. La pregunta 3 (qué test lo detectaría) es la que te dice si es seguro borrarlo o no.

10. Verificar lo que la IA te ha explicado antes

Un meta-prompt que uso bastante. Cierra el círculo de cualquier workflow.

Te acabo de explicar este código. Voy a comprobar que lo has
entendido, porque no quiero quedarme con una explicación que suene
correcta pero sea falsa.

Explicación que me diste: [pegar]

Ahora:
1. Dame un caso de prueba concreto que distinga tu explicación de
   la alternativa más plausible. Si no puedes, tu explicación es vaga.
2. Dime qué parte de tu explicación es una inferencia y no un hecho
   verificable en el código.
3. ¿Qué información adicional te habría hecho falta para estar seguro?
4. Reescribe tu propia explicación marcando inferencias con un
   asterisco.

Por qué funciona: es el control de calidad del pensamiento automático. Si la IA puede construir un caso que la contradiga, es que su explicación era una descripción plausible pero no una explicación causal. Y listar las inferencias te dice dónde no debes confiar.

Catálogo: qué prompt usar según la situación

Situación	Prompt	Cuándo	Señal de que funcionó
Primer archivo de un repositorio nuevo	#1 Explicar archivo	Al heredar o al abrir un PR ajeno	Sabes qué responsabilidad tiene
No sé por dónde empezar	#2 Mapa del módulo	Primer día en un repositorio	Tienes una ruta de lectura
Función ilegible	#3 Paso a paso	Antes de tocar nada	Sigues un ejemplo de entrada
No sé qué toca una petición	#4 Flujo completo	Antes de tocar una API	Tienes la lista de archivos
Código viejo que huele mal	#5 Deuda técnica	Antes de refactorizar	Tienes coste/beneficio
Regex que no entiendo	#6 Regex	En el momento del bug	Sabes qué NO hace match
Bug sin traza de error	#7 Bug por lectura	Cuando el error no ayuda	Tienes hipótesis ordenadas
Quiero aprender de verdad	#8 Socrático	Estudiando un repositorio nuevo	Superas la pregunta de examen
Código raro heredado	#9 Por qué está así	Antes de borrar nada	Tienes el commit que lo explica
Sospecho de alucinación	#10 Verificar	Siempre, antes de actuar	Ves las inferencias marcadas

Anti-patrones

❌ Preguntar “explícame este código”

Explícame este código.

Te devuelve un resumen de cinco líneas que no sirve para nada. No hay estructura, no hay anclaje y no hay forma de saber qué se ha saltado.

✅ Preguntar con las cinco preguntas del prompt 1

Este archivo es [ruta]. Dime qué responsabilidad tiene, qué expone,
sus dependencias, en qué parte del flujo está y por dónde empiezo
a leerlo. Cita líneas.

❌ Aceptar la explicación y seguir sin comprobar

[pegar explicación de la IA]
Vale, ya lo entiendo.

Ese es el patrón que te cuesta tres días de depuración. La explicación puede ser verosímil y estar equivocada en el punto clave.

✅ Pedir el caso discriminante

Dame un caso de prueba que demuestre que tu explicación es correcta
y la alternativa no.

❌ Pegar el repositorio entero

[pegar 40 archivos]
Explícame cómo funciona esto.

Pierdes contexto, tardas una hora en preparar el prompt y la respuesta será igual de vaga. Si necesitas todo el repositorio, usa una herramienta que lo lea con acceso a ficheros en vez de copiar y pegar.

✅ Empezar por el mapa y bajar a detalle

[pegar el árbol de carpetas]
Hazme un mapa. Dime los tres archivos que leería primero.

Tres archivos, no cuarenta. Con eso ya tienes dirección.

❌ Pedir el arreglo antes que la explicación

Este código tiene un bug, arréglalo.

Te devuelve un parche que funciona en su cabeza. Y dentro de tres meses vuelves al mismo bug porque nadie entendió por qué pasaba.

✅ Pedir las hipótesis primero

Lista las hipótesis ordenadas por probabilidad, con las líneas que
las respaldan. No me des el arreglo todavía.

Errores frecuentes

“Me explica cosas que no están en el código”. Es el síntoma clásico de no haber pegado el contexto suficiente. Añade los tipos, el esquema y quién llama a la función. Y activa siempre la instrucción de “no está en el código”.

“Me da un resumen bonito y sigo sin entender nada”. Suele pasar con archivos largos. El prompt 3 (recorrido con ejemplo) está pensado justo para eso: si el resumen no te sirve, pide ejecución, no descripción.

“Se inventa imports o funciones”. Le pasa más con repositorios grandes. Solución: dile “si no estás seguro del nombre, márcalo con [?]” y luego compruebas con grep. Cinco segundos de comprobación.

“La explicación es demasiado formal para mi nivel”. Añade el nivel explícito al principio (“soy junior en Rust”) y pide analogías con algo que conozcas. Funciona mejor de lo que esperas.

“Me explica el qué y no el por qué”. Es el límite de lo que se puede deducir del código. Si necesitas el porqué, tienes que ir a git log, a los PRs o a preguntar a quien lo escribió. El prompt 9 cubre parte de eso.

“Cambia de opinión entre sesiones”. Pasa cuando el contexto no cabe entero. Guarda en un fichero las conclusiones importantes de cada análisis, así la siguiente sesión parte de ahí en vez de reconstruir todo. Y si lo que te frena de verdad es el coste de los prompts largos, mira cómo aprovechar el context window.

El flujo completo

   Repositorio que no conoces
          │
          ▼
   ┌─────────────┐
   │  Prompt #2  │  mapa del módulo
   └──────┬──────┘
          │ 3 archivos prioritarios
          ▼
   ┌─────────────┐
   │  Prompt #1  │  qué hace y qué expone
   └──────┬──────┘
          │
          ▼
   ┌─────────────┐   ¿necesitas entenderlo a fondo?
   │  Prompt #3  │◄────────────── sí
   └──────┬──────┘
          │ no
          ▼
   ┌─────────────┐
   │  Prompt #5  │  deuda técnica: ¿toco algo?
   └──────┬──────┘
          │ sí, hay que tocar
          ▼
   ┌─────────────┐
   │  Prompt #9  │  por qué está así (git log)
   └──────┬──────┘
          │
          ▼
   ┌─────────────┐
   │  Prompt #10 │  verificar la explicación
   └──────┬──────┘
          │
          ▼
   ┌─────────────┐
   │  Prompt #7  │  si hay bug: hipótesis
   └──────┬──────┘
          │
          ▼
      Refactorizar
          │
          ▼
   ┌─────────────┐
   │  Prompt #8  │ (test nuevos con IA)
   └─────────────┘

La diferencia entre leer código con IA y entenderlo está en una cosa: nadie escribe un módulo con IA sin un criterio claro, y eso se nota cuando te toca mantenerlo. Si quieres ver cómo se escribe el otro lado, en la guía para programar con IA sin arruinarte está el proceso de generación, y en testear el código generado cómo cubrirlo.

Cuando lo que entiendes ya es suficiente para escribir, el paso natural es documentar los cambios: los prompts para commits y mensajes de Git con IA te cubren esa parte.

Y si quieres que las preguntas salgan solas sin tener que pensar el prompt, la herramienta generadora de prompts te da una base para copiar y adaptar.