Claude Code para onboarding de codebases: usa prompts de preguntas y respuestas para mapear módulos, flujos clave y riesgos, y convierte las notas en un breve documento de onboarding.
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:
Un onboarding "suficientemente bueno" en 1–2 días no es “Puedo explicar cada clase.” Es más parecido a esto:
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.
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:
Si falta algo, regístralo como una pregunta para un compañero. No "eludas" el contexto faltante con suposiciones.
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:
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.
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:
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.
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:
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.
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.
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.
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.”
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.
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.
Mantén el doc predecible para que la gente encuentre cosas rápido. Una buena estructura es:
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:
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.
Usa una regla simple en tus notas: cada afirmación debe etiquetarse como una de estas:
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.
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.
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:
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.
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:
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:
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.
Apunta a un mapa mental útil, no a un entendimiento total.
Un resultado sólido en 1–2 días es:
Entrégale artefactos concretos para que pueda señalar código real en vez de adivinar:
Elige una porción estrecha con límites claros.
Un alcance por defecto bueno es:
Anota explícitamente qué queda fuera de alcance (otros servicios, módulos legacy, características raramente usadas) para que el asistente no se distraiga.
Empieza desde triggers conocidos y avanza hacia adelante:
Pide rutas de archivos y nombres de función en orden, y termina con: “¿Cómo probaría esto rápido?”
Busca donde el sistema toma decisiones o cambia estado:
Usa un sistema simple de etiquetas y adjunta un paso de verificación.
Formato de ejemplo:
Obliga al asistente a separar evidencia de inferencia.
Pídele que etiquete cada afirmación como:
Cuando algo sea desconocido, conviértelo en una pregunta para un compañero (“¿Dónde se define el rol X?”) en vez de dejar que lo complete con una conjetura.
Mantén una nota ligera con cinco secciones:
Haz una comprobación rápida y real:
Esto valida que mapeaste la ruta que la app usa.
Usa las funciones de la plataforma para reducir el blast radius y mantener revisiones claras.
Valores prácticos:
Luego pregunta: “¿Qué puede fallar silenciosamente y cómo lo notaríamos?”
Sé breve para que lo actualices conforme aprendes.
Añade una línea a cada flujo: “¿Cómo lo probaría?” para convertirlo en checklist.
Funciona especialmente bien para tareas de onboarding como “añadir un guardrail”, “endurecer validación” o “mejorar un mensaje de error”.