Resumen ejecutivo

• El README es lo primero (y a veces lo único) que lee un recruiter en tu repositorio: tiene que explicar en dos minutos qué resuelve el proyecto y por qué es bueno.

• Una estructura que funciona: qué resuelve, demo, capturas o GIF, stack, cómo correrlo, decisiones técnicas y próximos pasos.

• Abajo tenés una plantilla lista para copiar y ejemplos para proyectos de desarrollo web, datos e IA.

• Los errores que más restan: README vacío, demo caída, sin capturas y claves de API expuestas.

Ya hablamos de qué proyectos subir en Proyectos de GitHub que te consiguen trabajo. Pero un buen proyecto mal presentado pasa desapercibido: un recruiter revisa decenas de perfiles y no va a clonar tu repo para entender qué hiciste. El README es tu vidriera. La propia documentación de GitHub sobre READMEs lo define como el archivo que cuenta qué hace el proyecto, por qué es útil, cómo empezar a usarlo y quién lo mantiene.

Qué mira un recruiter en dos minutos

• Primeras tres líneas: ¿se entiende qué es y para quién?

• Una imagen: captura o GIF del producto funcionando.

• Link a demo: si funciona, el proyecto gana muchísima credibilidad.

• Stack: para ver si coincide con la búsqueda.

• Señales de criterio: decisiones técnicas, tests, próximos pasos.

El perfil técnico que te entreviste después va a leer más (estructura, commits, código), pero el filtro inicial pasa por ahí.

La estructura de un buen README

1. Título y descripción en una línea

“TurnoFácil: app web para que consultorios chicos gestionen turnos y recordatorios por WhatsApp.” Evitá “Proyecto final del curso”.

2. Qué problema resuelve

Dos o tres oraciones: el problema, para quién y cómo lo resuelve tu proyecto.

3. Demo y capturas

Link a la demo en vivo (Vercel, Netlify, Render, Streamlit Cloud) y 2–3 capturas o un GIF corto. Usá rutas relativas para las imágenes del repo, como recomienda GitHub.

4. Stack

Una lista corta: React, Node.js, PostgreSQL, Tailwind. Si usaste IA (una API de LLM, por ejemplo), aclaralo.

5. Cómo correrlo localmente

Pasos exactos: clonar, instalar dependencias, variables de entorno (con un .env.example, nunca con tus claves reales) y comando de inicio.

6. Decisiones técnicas

Es la sección que más diferencia a un junior: por qué elegiste esa base de datos, cómo resolviste la autenticación, qué descartaste y por qué.

7. Próximos pasos

Qué mejorarías con más tiempo. Muestra autocrítica y visión de producto.

Plantilla lista para copiar

• # Nombre del proyecto: una línea con qué es y para quién.

• ## Demo: link + captura o GIF.

• ## El problema: 2–3 oraciones.

• ## Funcionalidades: 3–5 bullets.

• ## Stack: lista corta.

• ## Cómo correrlo: pasos numerados + archivo .env.example.

• ## Decisiones técnicas: 3 decisiones con su porqué.

• ## Próximos pasos: 3 mejoras.

• ## Autor: nombre, LinkedIn y email.

Para escribirlo, la guía de sintaxis Markdown de GitHub cubre títulos, listas, tablas, bloques de código e imágenes.

Ejemplos según el tipo de proyecto

Desarrollo web

Priorizá la demo y el GIF del flujo principal (registro → acción → resultado). En decisiones técnicas, contá cómo manejaste estado, autenticación y deploy.

Datos

Empezá por la pregunta de negocio y la conclusión principal (“las ventas caen 18% los martes por…”). Mostrá un gráfico, la fuente del dataset y cómo reproducir el notebook. Para ordenar todo el perfil, mirá tu perfil de GitHub como portfolio de datos.

Inteligencia artificial

Explicá qué modelo o API usás, cómo evaluaste la calidad de las respuestas, qué límites tiene y cuánto cuesta correrlo. Mostrá ejemplos de entrada y salida. Más ideas en cómo armar un portafolio de proyectos de IA.

Errores que restan puntos

• README vacío o con la plantilla por defecto del framework.

• Demo caída o con datos de prueba rotos.

• Claves de API o contraseñas subidas al repo.

• Textos larguísimos sin títulos ni imágenes.

• Instrucciones que no funcionan en una máquina limpia (probalo vos mismo).

Checklist de 10 minutos antes de aplicar

1. ¿Las primeras tres líneas explican qué es?

2. ¿Hay captura o GIF visible sin clonar?

3. ¿La demo abre y funciona?

4. ¿El .env.example existe y no hay secretos en el repo?

5. ¿Los pasos de instalación funcionan en una carpeta limpia?

6. ¿Hay al menos una decisión técnica escrita?

7. ¿El README menciona tu rol (qué hiciste vos si fue en equipo)?

Si fallás en dos o más, arreglalo antes de mandar el link en una postulación. Un README flojo descuenta proyectos buenos.

Curso recomendado de Coderhouse

Si todavía no tenés proyectos web para presentar, el Curso de JavaScript de Coderhouse te lleva a construir proyectos reales con entregas, ideales para estrenar esta plantilla.

CTA: elegí tu mejor repositorio, aplicale la plantilla hoy y pedile a alguien fuera de tech que te diga qué hace el proyecto después de leerlo dos minutos. Si necesitás más proyectos, arrancá JavaScript en Coderhouse.

Preguntas frecuentes

¿El README va en inglés o en español? Si apuntás a empresas del exterior, en inglés. Si buscás en Argentina, cualquiera sirve; algunos ponen ambos.

¿Qué largo debería tener? Lo suficiente para entender y correr el proyecto. Si se hace muy largo, mové detalles a una carpeta /docs.

¿Es lo mismo que el README de perfil? No. El de perfil es un repo con tu nombre de usuario que se muestra en tu página de GitHub; el de proyecto explica un repositorio puntual.

¿Puedo usar IA para escribirlo? Sí, como borrador. Revisá que los pasos funcionen y que las decisiones técnicas sean realmente las tuyas: te las van a preguntar en la entrevista.