Claude Code para onboarding de codebases: prompts que mapean tu app

Qué intentas aprender (y qué puede esperar)

Leer archivos al azar es lento porque la mayoría de los codebases no están organizados como una historia. Abres una carpeta, ves diez nombres que parecen importantes, haces clic en uno y acabas en helpers, configs y casos límite. Tras una hora, tienes muchos detalles pero aún no puedes explicar cómo funciona la app.

Un objetivo mejor para Claude Code durante el onboarding es construir un mapa mental simple. Ese mapa debería responder tres preguntas:

• ¿Cuáles son los módulos principales?
• ¿Cuáles son los flujos clave que los usuarios disparan?
• ¿Dónde están las áreas riesgosas que pueden romper producción o causar bugs?

Un onboarding "suficientemente bueno" en 1–2 días no es “Puedo explicar cada clase.” Es más parecido a esto:

• Puedes nombrar los 5–8 módulos que importan y qué posee cada uno.
• Puedes trazar 2–3 flujos reales de usuario de extremo a extremo (desde la entrada UI o API hasta la base de datos y de vuelta).
• Conoces los riesgos principales (pagos, auth, escrituras de datos, jobs en background) y dónde están.
• Puedes hacer un pequeño cambio con seguridad porque sabes qué probar y a quién preguntar.

Algunas cosas pueden esperar. Refactors profundos, entender perfectamente cada abstracción y leer código antiguo que nadie toca rara vez te consigue el mayor valor más rápido.

Piensa en el onboarding como construir un mapa, no en memorizar calles. Tus prompts deben devolverte constantemente a: “¿Dónde estoy en el sistema, qué pasa después y qué podría fallar aquí?” Una vez tengas eso, los detalles son más fáciles de aprender bajo demanda.

Trabajo previo: obtener contexto sin hervir el océano

Antes de empezar a preguntar, recoge lo básico que normalmente necesitas el primer día. Claude Code funciona mejor cuando puede reaccionar a archivos reales, configuración real y comportamiento que puedas reproducir.

Empieza con acceso y una ejecución funcional. Asegúrate de poder clonar el repo, instalar dependencias y ejecutar la app (o al menos una porción pequeña) localmente. Si el setup local es difícil, consigue acceso a un entorno de staging y a donde vivan los logs, para que puedas verificar lo que el código realmente hace.

A continuación, busca los docs "fuente de la verdad". Buscas lo que el equipo realmente actualiza cuando cambian las cosas: un README, una nota corta de arquitectura, una carpeta de ADR, un runbook o una nota de despliegue. Aunque estén desordenados, te dan nombres de módulos y flujos, lo que hace las preguntas y respuestas mucho más precisas.

Decide el alcance temprano. Muchos repos contienen múltiples apps, servicios y paquetes compartidos. Elige límites como “solo la API y el worker de facturación” o “solo la web app y su flujo de auth.” Un alcance claro evita desvíos interminables.

Escribe las suposiciones que no quieres que el asistente infiera. Esto parece pequeño, pero evita modelos mentales equivocados que hagan perder horas más adelante.

Aquí hay una simple checklist de preparación:

• Confirma acceso al repo, permisos requeridos y cómo ejecutar tests.
• Recopila notas de setup de entorno (env vars, seeds, feature flags) y dónde se consultan logs y métricas.
• Identifica los archivos de verdad actuales (README, notas de arquitectura, ADRs, runbooks).
• Define qué está en scope y qué está explícitamente fuera de scope para esta pasada de onboarding.
• Establece reglas de seguridad: nunca pegar secretos, API keys, tokens, datos privados de clientes o logs de producción con detalles sensibles.

Si falta algo, regístralo como una pregunta para un compañero. No "eludas" el contexto faltante con suposiciones.

El mapa mental: qué capturar mientras exploras

Un mapa mental es un pequeño conjunto de notas que responde: cuáles son las partes principales de esta app, cómo se comunican entre sí y dónde pueden fallar las cosas. Hecho bien, el onboarding deja de ser navegar archivos y se convierte en construir una imagen reutilizable.

Empieza definiendo tus outputs. Quieres una lista de módulos que sea práctica, no perfecta. Para cada módulo, captura qué hace, quién lo posee (equipo o persona si lo sabes) y sus dependencias clave (otros módulos, servicios, bases de datos, APIs externas). También anota puntos de entrada principales: rutas UI, endpoints API, jobs en background y tareas programadas.

Luego, elige algunas jornadas de usuario que importen. Tres a cinco son suficientes. Escoge flujos que toquen dinero, permisos o cambios de datos. Ejemplos: signup y verificación por email, crear un plan de pago o compra, una acción de admin que cambia el acceso de un usuario, y un flujo crítico de uso diario que la mayoría de usuarios usa.

Decide cómo vas a etiquetar riesgo antes de empezar a recopilar notas. Mantén categorías simples para poder escanearlas luego. Un conjunto útil es seguridad, integridad de datos, disponibilidad y costo. Cuando marques algo como riesgoso, añade una frase explicando por qué, además de qué probaría que está seguro (un test, un log, una comprobación de permisos).

Usa un formato consistente para poder convertir las notas en un doc de onboarding sin reescribir todo:

• Módulos: propósito, puntos de entrada, dependencias, owner
• Flujos clave: trigger, pasos, datos escritos, puntos de fallo
• Datos: tablas o colecciones tocadas, campos importantes, constraints
• Riesgos: categoría, impacto peor, cómo monitorizar, cómo revertir
• Preguntas abiertas: lo que aún no sabes, a quién preguntar

Ejemplo: si Checkout llama a Billing que escribe en payments e invoices, márcalo como integridad de datos y costo. Luego anota dónde ocurren los reintentos y qué previene cargos dobles.

Prompts paso a paso para explorar un codebase

Cuando entras a un repo nuevo, quieres orientación rápida, no entendimiento perfecto. Estos prompts te ayudan a construir un mapa mental en pasos pequeños y seguros.

Empieza dando al asistente el árbol del repo (o un subconjunto pegado) y pide un tour. Mantén cada ronda enfocada, y termina con una pregunta que te diga qué leer a continuación.

1) Repo tour
"Aquí está la lista de carpetas top-level: <pegar>. Explica qué contiene probablemente cada carpeta y cuáles son relevantes para el comportamiento central del producto."

2) Puntos de entrada
"Encuentra los puntos de entrada de la app y el proceso de arranque. ¿Qué archivos inician la app, configuran routing, config env/DI y arrancan jobs en background? Nombra los archivos exactos y qué hacen."

3) Índice de módulos
"Crea un índice de módulos: nombre del módulo, propósito, archivos clave y dependencias externas importantes. Manténlo para los módulos que afectan el comportamiento visible al usuario."

4) Pistas del modelo de datos
"Basado en migrations/models, lista las tablas/entidades clave, campos críticos y relaciones. Señala campos que parezcan sensibles en seguridad o usados para facturación/permisos."

5) Rastro de flujo
"Traza este flujo de extremo a extremo: <flow>. ¿Dónde empieza la request/evento, dónde termina y qué se llama en medio? Lista las funciones/archivos principales en orden."

6) Próxima inspección
"¿Qué debería inspeccionar a continuación y por qué? Dame 3 opciones: claridad más rápida, área más riesgosa y mejor beneficio a largo plazo."

Un ejemplo concreto: si estás mapeando “el usuario se registra y crea su primer proyecto”, pide el handler de la ruta API, la validación, la escritura en BD y cualquier job asíncrono que envíe emails o provisione recursos. Luego vuelve a ejecutar el rastro para “usuario elimina proyecto” para encontrar gaps de limpieza.

Para mantener las respuestas accionables, pide artefactos específicos, no solo resúmenes:

• Rutas de archivos y nombres de funciones
• Suposiciones y desconocidos claramente señalados
• Dependencias redactadas como “Si cambio X, ¿qué se rompe?”
• Una pequeña tarea de lectura que puedas hacer en 10 minutos

Cómo capturar respuestas para que sigan siendo útiles

La mayor victoria en onboarding es convertir Q&A dispersa en notas que otro desarrollador pueda reutilizar. Si las notas solo te sirven a ti, volverás a hacer la misma investigación más tarde.

Una estructura simple vence a páginas largas. Tras cada sesión de exploración, guarda las respuestas en cinco artefactos pequeños (un archivo o doc está bien): una tabla de módulos, un glosario, flujos clave, desconocidos y un registro de riesgos.

Aquí tienes una plantilla compacta que puedes pegar en tus notas y completar sobre la marcha:

Module table
- Module:
  Owns:
  Touches:
  Entry points:

Glossary
- Term:
  Meaning:
  Code name(s):

Key flow (name)
1.
2.
3.

Unknowns
- Question:
  Best person to ask:
  Where to look next:

Risk register
- Risk:
  Location:
  Why it matters:
  How to verify:

Mantén los flujos clave cortos a propósito. Ejemplo: 1) usuario inicia sesión, 2) backend crea una sesión, 3) cliente carga el dashboard, 4) API obtiene datos, 5) UI renderiza y maneja errores. Si no puedes ajustar un flujo en cinco pasos, sepáralo (login vs carga de dashboard).

Al usar Claude Code, añade una línea a cada respuesta: “¿Cómo probaría esto?” Esa sola línea convierte notas pasivas en una checklist que puedes ejecutar después, especialmente cuando unknowns y riesgos se solapan.

Si construyes en una plataforma tipo Koder.ai, este tipo de toma de notas también te ayuda a ver dónde los cambios generados pueden tener efectos laterales. Los módulos con muchos puntos de contacto tienden a atraer cambios.

Encontrar áreas riesgosas rápido (sin leer cada archivo)

El riesgo en un codebase rara vez es aleatorio. Se agrupa donde la app decide quién eres, cambia datos, habla con otros sistemas o ejecuta trabajo en background. Puedes encontrar la mayor parte con preguntas dirigidas y búsquedas focalizadas.

Empieza por identidad. Pregunta dónde ocurre la autenticación (login, sesión, tokens) y dónde viven las decisiones de autorización (chequeos de rol, feature flags, reglas de ownership). Una trampa común es tener checks esparcidos por UI, handlers API y consultas a BD sin una única fuente de verdad.

Luego, mapea las rutas de escritura. Encuentra endpoints o funciones que crean, actualizan o eliminan registros, además de las migraciones que cambian datos con el tiempo. Incluye jobs en background también. Muchos bugs misteriosos provienen de workers asíncronos que escriben valores inesperados mucho después de que la request terminó.

Prompts que sacan riesgo rápidamente:

• "Lista cada lugar que aplica permisos para [recurso X]. ¿Cuál es la puerta final?"
• "Muestra la ruta completa para escribir [tabla/entidad X]: handler API -> servicio -> llamada DB. ¿Dónde están las validaciones?"
• "¿Qué integraciones externas existen (pagos, email, webhooks, APIs de terceros)? ¿Dónde están los retries y timeouts?"
• "¿Dónde puede ejecutarse trabajo dos veces (colas, goroutines, cron)? ¿Qué lo hace idempotente?"
• "¿Qué puede romperse silenciosamente y cómo lo notaríamos (logs, métricas, alertas, dashboards)?"

Luego revisa configuración y manejo de secretos. Busca variables de entorno, archivos de config en runtime y fallbacks por defecto. Los defaults son útiles, pero arriesgados cuando ocultan malconfiguraciones (por ejemplo, usar una key de dev en producción porque faltó un valor).

Un ejemplo rápido: en un backend Go con PostgreSQL, podrías encontrar un job “send email” que reintenta en fallo. Si reintenta sin una clave de idempotencia, los usuarios pueden recibir emails duplicados. Si los fallos solo registran una advertencia y no existe ninguna alerta, falla silenciosamente. Eso es un área de alto riesgo que vale la pena documentar y probar temprano.

Ejemplo walkthrough: mapear un flujo real de usuario

Usa un flujo real para construir tu primer hilo de extremo a extremo por el sistema. Login es un buen inicio porque toca routing, validación, sesiones o tokens y lecturas de BD.

Escenario: una app React llama a una API en Go, y la API lee y escribe en PostgreSQL. Tu objetivo no es entender cada archivo. Es responder: “Cuando un usuario hace clic en Login, ¿qué código se ejecuta a continuación, qué datos se mueven y qué puede fallar?” Así el onboarding se mantiene concreto.

Mapea el flujo desde el navegador hasta la base de datos

Empieza en la UI y camina hacia adelante, un salto a la vez. Pide nombres de archivos específicos, funciones y shapes de request/response.

• "Encuentra la ruta/página React para la pantalla de login. ¿Qué componente la renderiza y qué acción se dispara al enviar?"
• "¿Dónde se hace la llamada del cliente a la API (fetch/axios/etc.)? ¿Qué URL exacta, método, headers y body envía?"
• "En el lado Go, ¿dónde está registrado el handler para ese path? Muestra el setup del router y la función handler."
• "Dentro del handler, ¿dónde ocurre la validación de input (frontend, backend, ambos)? ¿Qué reglas existen y dónde se formatean los errores?"
• "¿Qué consulta a la base de datos se ejecuta para el login? Señala el repositorio/archivo SQL, lista las tablas/columnas tocadas y anota transacciones o locks."

Después de cada respuesta, escribe una línea corta en tu mapa mental: "Componente UI -> endpoint API -> handler -> servicio -> consulta DB -> response." Incluye los nombres, no solo “alguna función.”

Confirma con una ejecución rápida

Una vez tengas la ruta, verifícala con una pequeña ejecución. Estás comprobando que la ruta de código que mapeaste es la que la app realmente usa.

Observa las peticiones de red en dev tools (path, código de estado, cuerpo de respuesta). Añade o habilita logs del servidor alrededor del handler y la llamada a la DB (request ID si está disponible). Consulta PostgreSQL por cambios esperados (para login, quizá last_login_at, sesiones o filas de auditoría). Fuerza un fallo (contraseña errónea, campo faltante) y anota dónde se crea el mensaje de error y dónde se muestra. Registra respuestas esperadas para éxito y fallo (códigos de estado y campos clave), para que el siguiente desarrollador pueda hacer una comprobación rápida.

Este único flujo suele exponer límites de ownership: qué confía la UI, qué hace cumplir la API y dónde los errores desaparecen o se manejen doblemente.

Convierte el mapa mental en un documento corto de onboarding

Una vez tengas un mapa mental decente, fíltralo a una nota de 1–2 páginas. El objetivo no es ser completo. Es ayudar al siguiente desarrollador a responder: ¿qué es esta app, dónde miro primero y qué es lo que más puede fallar?

Si usas Claude Code, trata el doc como el output de tu Q&A: claro, concreto y fácil de escanear.

Estructura simple de 1–2 páginas

Mantén el doc predecible para que la gente encuentre cosas rápido. Una buena estructura es:

• Propósito: qué hace la app, quién la usa y qué significa “done”
• Resumen de arquitectura: servicios principales, almacenes de datos y cómo se mueven las requests por el sistema
• Cómo ejecutar: prerequisitos, el comando único para arrancar y el comando único para ejecutar tests
• Dónde viven las cosas: las carpetas que importan, más los 5–10 archivos que actúan como puntos de entrada
• Flujos clave y riesgos: trazas cortas de jornadas importantes, más qué validar después de cambios

Hazlo accionable, no académico

Para “Dónde viven las cosas”, incluye punteros como “Auth empieza en X, lógica de sesión en Y, rutas UI en Z.” Evita volcar todo el árbol. Elige solo lo que la gente tocará.

Para “Flujos clave”, escribe 4–7 pasos por flujo: trigger, controller o handler, módulo central, llamada a BD y efecto externo (email enviado, estado actualizado, job en cola). Añade nombres de archivos en cada paso.

Para “Áreas riesgosas”, nombra el modo de fallo y la comprobación de seguridad más rápida (un test específico, una ejecución de humo o un log a vigilar).

Termina con una pequeña lista de primeras tareas para que alguien pueda contribuir con seguridad:

• Actualizar una copia o validación en una pantalla bien contenida
• Añadir una pequeña unit test sobre un helper complicado que identificaste
• Arreglar un bug de bajo riesgo con un repro y resultado esperado claro
• Añadir un guardrail: mejor mensaje de error, chequeo de input o timeout
• Preguntar quién posee deploys a producción y a quién pinguear por dudas del dominio

Errores comunes y cómo evitarlos

La forma más rápida de desperdiciar un asistente es pedir “una explicación completa de todo el repo.” Obtienes un resumen largo que suena seguro pero se mantiene vago. En su lugar, elige una porción pequeña que importe (un módulo más un flujo de usuario), luego expande hacia afuera.

Un segundo error cercano es no nombrar qué jornadas importan. Si no dices “checkout”, “login” o “admin edit”, las respuestas se convierten en charla arquitectónica genérica. Empieza cada sesión con un objetivo concreto: “Ayúdame a entender el flujo de signup de extremo a extremo, incluyendo validación, estados de error y dónde se almacena la data.”

Otra trampa es dejar que el asistente adivine. Cuando algo no esté claro, haz que lo etiquete como incertidumbre. Pídele que separe lo que puede probar en el código de lo que infiere.

Mantén los desconocidos visibles (para resolverlos)

Usa una regla simple en tus notas: cada afirmación debe etiquetarse como una de estas:

• Confirmado en código
• Confirmado ejecutando la app
• Suposición (necesita verificación)
• Desconocido (falta contexto)

Las notas se deshacen cuando se recopilan sin estructura. Un montón de fragmentos de chat es difícil de convertir en un mapa mental. Mantén una plantilla consistente: módulos involucrados, punto de entrada, funciones y archivos clave, datos tocados, efectos secundarios, rutas de error y tests a ejecutar.

No trates las salidas como hechos

Incluso con Claude Code, trata los outputs como un borrador. Verifica flujos clave en la app en ejecución, especialmente partes que pueden romper producción: auth, pagos, permisos, jobs en background y migraciones.

Un ejemplo práctico: si el asistente dice “password reset envía un email vía X”, confírmalo disparando un reset en un entorno dev y comprobando logs o el sandbox de email. Ese chequeo de realidad evita que te subas a una historia que no es cierta.

Checklist rápido antes de decir “estoy onboarded”

No necesitas memorizar el repo. Necesitas suficiente confianza para hacer un cambio seguro, depurar un issue real y explicar el sistema al siguiente.

Antes de declararte onboarded, asegúrate de poder responder sin adivinar:

• ¿Puedes explicar las cinco áreas más importantes del código y qué posee cada una (por ejemplo: UI, capa API, jobs en background, acceso a datos, integraciones)?
• ¿Puedes recorrer dos jornadas de alto valor de extremo a extremo y señalar el primer archivo o función que inicia cada jornada?
• ¿Puedes señalar dónde se aplica la autenticación y dónde se definen y revisan roles o permisos?
• ¿Puedes nombrar las escrituras a BD más riesgosas (dinero, permisos, borrados, transiciones de estado) y describir cómo probarías cada cambio con seguridad?
• ¿Puedes darle a un nuevo desarrollador una nota de onboarding corta que lea en menos de 10 minutos y luego sepa dónde empezar?

Si falta un ítem, haz una pasada pequeña y enfocada en vez de una búsqueda amplia. Elige un flujo, síguelo hasta la frontera de la BD y para. Cuando algo no esté claro, captúralo como una pregunta, no como un párrafo. “¿Dónde se crea el rol X?” es más útil que “auth es confuso.”

Una buena prueba final: imagina que te piden añadir una pequeña feature detrás de un flag. Si puedes nombrar los archivos que tocarías, los tests que ejecutarías y los modos de fallo a vigilar, estás lo suficientemente onboarded para contribuir de forma responsable.

Próximos pasos: mantener el mapa actualizado y facilitar handoffs

Un mapa mental solo es útil mientras coincide con la realidad. Trátalo como un artefacto vivo, no una tarea de una sola vez. La forma más fácil de mantenerlo honesto es actualizarlo justo después de cambios que afectan el comportamiento.

Una rutina ligera vence a grandes reescrituras. Ata las actualizaciones al trabajo que ya estás haciendo:

• Después de cada feature: actualiza la lista de módulos y los flujos principales que tocó
• Después de cada incidente: agrega el trigger, impacto y la ubicación exacta del fix
• Después de cada refactor riesgoso: anota qué cambió y qué se mantuvo compatible
• Antes de un release: vuelve a chequear las 3 áreas más riesgosas y las rutas de prueba
• Una vez al mes: borra notas obsoletas y confirma owners para módulos clave

Mantén el doc de onboarding cerca del código y versionado con la misma disciplina que el codebase. Los diffs pequeños se leen. Las reescrituras grandes suelen saltarse.

Cuando los despliegues son riesgosos, escribe qué ayudaría al siguiente a recuperar rápido: qué cambió, qué vigilar y cómo revertir. Si tu plataforma soporta snapshots y rollback, añade el nombre del snapshot, la razón y cómo se ve “bien” después del fix.

Si construyes con Koder.ai (koder.ai), el modo de planificación puede ayudarte a redactar un mapa de módulos y una nota de onboarding consistente desde tu Q&A, y la exportación de código da a los revisores una forma limpia de validar el resultado.

Finalmente, define una checklist de handoff que el siguiente desarrollador pueda seguir sin adivinar:

• Qué leer primero (2–3 archivos o docs) y por qué
• Qué ejecutar localmente (comandos, env vars, seed data)
• Qué verificar (un happy path y un caso de fallo)
• Dónde están las aristas (módulos riesgosos, tests inestables, configs complicadas)
• A quién preguntar por qué (owners de flujos clave)

Hecho bien, Claude Code para onboarding de codebases se vuelve un hábito: cada cambio deja un mapa más claro para la siguiente persona.