Qué busca quien abre tu GitHub
El lector no siempre es quien imaginas. Un reclutador mira primero si los repositorios son legibles y recientes. Un hiring manager quiere saber en qué tipo de problema te mueves con soltura. Un responsable técnico abre uno o dos ficheros y se pregunta si las decisiones se sostienen. Ninguno de los tres lee todo el código.
Tres preguntas deben resolverse en menos de dos minutos: qué problema resuelve el proyecto, qué decisiones se tomaron y por qué, y cómo se sabe que el resultado era aceptable. Un repositorio que responde a las tres vale más que un perfil lleno de contribuciones.
El objetivo de esta guía no es que produzcas diez proyectos, sino que sea demostrable lo que ya sabes hacer.
Elegir qué proyectos mostrar
Fija dos o tres repositorios, no más. El criterio no es la dificultad técnica aparente, sino que el proyecto ilustre una competencia que reivindicas en tu perfil y en tus candidaturas.
- Un proyecto que se solape con el puesto objetivo: un tema tratado con rigor pesa más que uno espectacular fuera de foco.
- Un proyecto del que puedas hablar veinte minutos en entrevista sin releer el código.
- Un proyecto donde una restricción real te obligó a decidir: volumen, coste, calidad de datos, plazo.
- Opcionalmente uno más corto pero muy bien documentado, que sirva de demostración de método.
El resto de repositorios no hace falta borrarlos. Basta con no destacarlos y con que ninguno contradiga lo que afirmas saber hacer.
Proyecto de tutorial frente a proyecto que demuestra una competencia
Un repositorio salido de un curso o un tutorial no descalifica por sí mismo. Lo hace cuando nada indica qué aportaste. Un lector técnico reconoce al instante la estructura de un tutorial: mismos ficheros, mismo conjunto de datos, misma conclusión.
Presentación débil
«Chatbot RAG sobre documentos PDF. Stack: Python, LangChain, base vectorial, Streamlit. Ejecuta `app.py` para arrancar.»
Presentación creíble
«Asistente de búsqueda sobre 400 actas de reunión, construido porque la búsqueda por palabras clave fallaba con el vocabulario interno. Troceado por sección en vez de tamaño fijo, tras ver que las respuestas partían las decisiones por la mitad. Búsqueda híbrida en lugar de solo vectorial: las referencias de proyecto son códigos que el vectorial recuperaba mal. Evaluado con 40 preguntas escritas a partir de peticiones reales; el punto débil siguen siendo las preguntas que abarcan varias reuniones.»
La segunda versión no describe un proyecto más complejo. Describe un proyecto cuyas decisiones se entienden.
El README es el entregable principal
En un perfil de IA, el README hace el trabajo que el código no puede hacer en dos minutos. Se lee de arriba abajo, del contexto al detalle, y no al revés. Una estructura que funciona con cualquier tema:
- Problema y contexto: qué no funcionaba antes y para quién.
- Qué hace el proyecto, en una frase, más una captura o un ejemplo de entrada/salida.
- Arquitectura: los componentes y, sobre todo, la razón de cada uno.
- Decisiones y alternativas descartadas: dos o tres bastan, si están justificadas.
- Datos: origen, volumen, licencia, sesgos o límites conocidos.
- Evaluación: método, conjunto de prueba, resultados, incluido lo que falla.
- Límites y posibles continuaciones.
- Ejecución: dependencias, variables de entorno y comando de arranque.
Un ejemplo de uso concreto —una consulta con su respuesta real, una captura de la interfaz, un fragmento breve de log— sustituye párrafos de descripción y evita que el lector tenga que instalar nada para hacerse una idea.
Calidad del repositorio y reproducibilidad
La reproducibilidad no tiene que ser industrial: tiene que ser honesta. O el proyecto arranca, o el README dice con claridad qué falta y por qué, por ejemplo una fuente de datos que no se puede redistribuir.
- Dependencias fijadas e instrucciones de instalación probadas en una máquina limpia.
- Configuración por variables de entorno, con un fichero de ejemplo sin secretos.
- Un conjunto de datos de muestra, reducido o sintético, cuando los datos reales no se pueden publicar.
- Algunas pruebas sobre las partes deterministas: parsing, transformaciones, formatos de salida.
- Un historial de commits legible, sin ficheros pesados ni datos sensibles.
Un repositorio que no arranca y no lo advierte consigue el efecto contrario al buscado: el lector supone que nunca funcionó.
Decir qué hiciste realmente
En un proyecto de equipo, académico o de empresa, la contribución individual debe ser explícita. Basta una frase: qué parte diseñaste, cuál retomaste y qué existía antes de ti. Esa precisión nunca debilita una candidatura; su ausencia, en cambio, se vuelve en contra en cuanto la entrevista técnica profundiza en un detalle.
La misma regla vale para el código asistido. Usar herramientas de generación es hoy corriente; presentar como diseño propio algo que no puedes defender línea a línea, no.
Proyectos GenAI, RAG y agentes, o ML más clásico
Las dos familias se demuestran de forma distinta, y confundirlas sale caro en entrevista.
- GenAI, RAG, agentes: la parte visible es fácil de producir; lo que distingue es el tratamiento de los documentos, la estrategia de búsqueda, el protocolo de evaluación, la gestión de respuestas sin fuente y el comportamiento ante fallos.
- ML más clásico: el valor está en la construcción del conjunto de datos, la validación adecuada al problema, el tratamiento de las fugas de información, la comparación con una referencia simple y la estabilidad en el tiempo.
- En ambos casos: una métrica elegida por la razón correcta y comparada con una baseline vale más que una cifra aislada.
Una demo en línea ayuda cuando es estable y no te cuesta nada. Un vídeo corto o dos capturas bastan cuando mantener un alojamiento permanente no es razonable.
Qué es mejor no publicar
El portfolio también es una prueba de criterio. Publicar lo que debía quedar fuera descalifica más rápido que un repositorio vacío.
- Datos de clientes, extractos de producción o documentos internos, aunque estén anonimizados a mano.
- Claves de API y credenciales, incluso en el historial de commits de un repositorio que luego se hizo público.
- Código de un empleador o cliente sin autorización escrita, aunque esté «limpiado».
- Datos personales o conjuntos cuya licencia prohíbe la redistribución.
- Proyectos abandonados en el primer commit y destacados como si estuvieran acabados.
Cuando el trabajo más significativo está bajo cláusula de confidencialidad, la solución no es publicarlo a medias: descríbelo en tu perfil y en la entrevista a través del problema, las restricciones y las decisiones, sin exponer código ni datos.
Errores frecuentes
- Destacar diez repositorios, siete de ellos sin README.
- Describir el stack y nunca el problema.
- Anunciar una cifra de rendimiento sin decir sobre qué conjunto ni frente a qué.
- Dejar un único notebook de 900 líneas como toda huella del proyecto.
- Hacer público un ejercicio técnico de empresa.
- Destacar un proyecto que ya no sabes explicar seis meses después.
Un portfolio creíble no es una acumulación: es un conjunto pequeño, coherente con lo que dices saber hacer y defendible. Su continuación natural es la entrevista, donde el mismo proyecto habrá que contarlo como una cadena de decisiones y no como una lista de herramientas.
Antes de compartir tu GitHub
Siete comprobaciones. Cada una lleva minutos en el repositorio que destacas.
- El README dice en tres frases qué problema resuelve y para quién.
- Al menos una decisión de arquitectura está justificada, con la opción descartada.
- Se indica el origen de los datos y sus límites.
- Se describe un método de evaluación, aunque sea modesto, con resultados honestos.
- Alguien de fuera puede ejecutarlo, o al menos entender cómo se ejecuta, sin escribirte.
- Lo que hiciste tú se distingue de lo que hizo el equipo.
- No hay material confidencial, ni claves, ni datos reales de clientes en el historial.
Para retener
- Quien revisa busca una prueba de razonamiento, no una colección de repositorios.
- El README es el entregable principal: se lee antes que el código y a menudo en su lugar.
- Un proyecto de tutorial no descalifica, siempre que expliques qué aportaste tú.
- La evaluación es la señal de seriedad más rara y más eficaz.
- En proyectos GenAI, la dificultad se demuestra en el retrieval, la evaluación y la gestión de fallos.
- Dos repositorios asumidos y un perfil honesto valen más que diez escaparates vacíos.
- AI Engineering
- Evaluación