Cómo hacer un buen README de GitHub para tus proyectos: estructura, ejemplos y errores que restan puntos

Resumen ejecutivo

• El README es la portada de tu repositorio: quien evalúa tu perfil lo lee antes que el código, y suele decidir en menos de un minuto si sigue mirando.

• Una estructura probada: qué problema resuelve, captura o demo, stack, cómo correrlo, decisiones técnicas y próximos pasos.

• Incluimos un ejemplo antes y después y una plantilla en Markdown que puedes copiar.

• Para perfiles junior, un README claro puede diferenciar dos proyectos de código similar; también se enlaza desde el CV y LinkedIn.

Muchas personas que buscan su primer trabajo en programación suben proyectos a GitHub y se olvidan del README. El resultado: repositorios con buen código que nadie entiende. Quien recluta o entrevista no tiene tiempo de clonar cada proyecto; mira la portada, ve si se entiende qué hace y si parece cuidado. Esta guía baja a lo concreto: una estructura para que tu README muestre el proyecto en 60 segundos, un ejemplo antes y después y los errores que más restan puntos. Complementa las guías generales de GitHub como portfolio y de documentación de proyectos para recruiters; aquí nos enfocamos en el archivo README en sí.

Qué es un README y dónde se ve

Es un archivo de texto en formato Markdown, llamado README.md, que GitHub muestra automáticamente en la página principal del repositorio. Según la documentación de GitHub, un README suele explicar qué hace el proyecto, por qué es útil, cómo empezar a usarlo, dónde obtener ayuda y quién lo mantiene. Piensa en él como la ficha técnica y la presentación comercial de tu trabajo a la vez.

La estructura que muestra el proyecto en 60 segundos

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

Nombre claro y una frase que diga qué hace y para quién. Ejemplo: "Gastos Claros: app web para registrar gastos del hogar y ver en qué se va el dinero cada mes".

2. Captura o demo

Una imagen o un GIF corto de la aplicación funcionando, y si puedes, un enlace a la demo desplegada. Es lo primero que mira la mayoría. Si el proyecto no tiene interfaz, muestra un ejemplo de uso o de salida.

3. Qué problema resuelve

Dos o tres líneas: el problema, la solución y el público al que apunta. Esto demuestra criterio de producto, no solo de código.

4. Stack utilizado

Una lista corta con las tecnologías principales y para qué se usó cada una, por ejemplo: React (interfaz), Node.js y Express (API), PostgreSQL (datos).

5. Cómo correrlo

Pasos numerados y probados: requisitos, clonar el repositorio, instalar dependencias, configurar variables de entorno y ejecutar. Si alguien puede levantar tu proyecto con cinco comandos, ya ganaste confianza. Pruébalo tú mismo en una carpeta limpia.

6. Decisiones técnicas

Esta sección distingue a un perfil junior que piensa. Explica en pocas líneas por qué elegiste cierta tecnología, qué problema difícil resolviste y qué harías distinto. Es material directo para la entrevista.

7. Próximos pasos y limitaciones

Una lista de mejoras pendientes muestra honestidad y visión. Reconocer límites suma más de lo que resta.

8. Contacto y licencia

Tu nombre, enlace a LinkedIn o portfolio y, si corresponde, la licencia del proyecto.

Plantilla en Markdown para copiar

# Nombre del proyecto

Una frase que explique qué hace y para quién.

![Captura de la app](docs/captura.png)

**Demo:** https://tu-demo.com

## Problema que resuelve
Describe el problema y cómo lo resuelve tu proyecto.

## Stack
- Frontend: React
- Backend: Node.js + Express
- Base de datos: PostgreSQL

## Cómo correrlo
1. Clona el repositorio: `git clone https://github.com/usuario/proyecto.git`
2. Instala dependencias: `npm install`
3. Copia `.env.example` a `.env` y completa los valores
4. Ejecuta: `npm run dev`

## Decisiones técnicas
- Elegí X porque...
- El mayor desafío fue... y lo resolví con...

## Próximos pasos
- [ ] Agregar tests
- [ ] Mejorar accesibilidad

## Autor
Tu Nombre - [LinkedIn](https://linkedin.com/in/tu-perfil)

# Nombre del proyecto

Una frase que explique qué hace y para quién.

![Captura de la app](docs/captura.png)

**Demo:** https://tu-demo.com

## Problema que resuelve
Describe el problema y cómo lo resuelve tu proyecto.

## Stack
- Frontend: React
- Backend: Node.js + Express
- Base de datos: PostgreSQL

## Cómo correrlo
1. Clona el repositorio: `git clone https://github.com/usuario/proyecto.git`
2. Instala dependencias: `npm install`
3. Copia `.env.example` a `.env` y completa los valores
4. Ejecuta: `npm run dev`

## Decisiones técnicas
- Elegí X porque...
- El mayor desafío fue... y lo resolví con...

## Próximos pasos
- [ ] Agregar tests
- [ ] Mejorar accesibilidad

## Autor
Tu Nombre - [LinkedIn](https://linkedin.com/in/tu-perfil)

# Nombre del proyecto

Una frase que explique qué hace y para quién.

![Captura de la app](docs/captura.png)

**Demo:** https://tu-demo.com

## Problema que resuelve
Describe el problema y cómo lo resuelve tu proyecto.

## Stack
- Frontend: React
- Backend: Node.js + Express
- Base de datos: PostgreSQL

## Cómo correrlo
1. Clona el repositorio: `git clone https://github.com/usuario/proyecto.git`
2. Instala dependencias: `npm install`
3. Copia `.env.example` a `.env` y completa los valores
4. Ejecuta: `npm run dev`

## Decisiones técnicas
- Elegí X porque...
- El mayor desafío fue... y lo resolví con...

## Próximos pasos
- [ ] Agregar tests
- [ ] Mejorar accesibilidad

## Autor
Tu Nombre - [LinkedIn](https://linkedin.com/in/tu-perfil)

# Nombre del proyecto

Una frase que explique qué hace y para quién.

![Captura de la app](docs/captura.png)

**Demo:** https://tu-demo.com

## Problema que resuelve
Describe el problema y cómo lo resuelve tu proyecto.

## Stack
- Frontend: React
- Backend: Node.js + Express
- Base de datos: PostgreSQL

## Cómo correrlo
1. Clona el repositorio: `git clone https://github.com/usuario/proyecto.git`
2. Instala dependencias: `npm install`
3. Copia `.env.example` a `.env` y completa los valores
4. Ejecuta: `npm run dev`

## Decisiones técnicas
- Elegí X porque...
- El mayor desafío fue... y lo resolví con...

## Próximos pasos
- [ ] Agregar tests
- [ ] Mejorar accesibilidad

## Autor
Tu Nombre - [LinkedIn](https://linkedin.com/in/tu-perfil)

Ejemplo antes y después

Antes:

# gastos-app
App de gastos hecha con React.
npm start

# gastos-app
App de gastos hecha con React.
npm start

# gastos-app
App de gastos hecha con React.
npm start

# gastos-app
App de gastos hecha con React.
npm start

Qué falla: no dice qué problema resuelve, no tiene captura, no explica cómo configurarla ni qué decisiones hay detrás. Quien lee no sabe si vale la pena abrir el código.

Después:

# Gastos Claros
App web para registrar gastos del hogar y ver en qué se va el dinero cada mes.

![Panel principal](docs/panel.png)
**Demo:** https://gastos-claros.example.com

## Problema que resuelve
Las planillas de gastos se abandonan porque cargar datos es tedioso.
Gastos Claros permite registrar un gasto en dos toques y muestra un resumen por categoría.

## Stack
React (interfaz), Node.js + Express (API), PostgreSQL (datos), Jest (tests)

## Cómo correrlo
1. `git clone ...` e `npm install`
2. Copia `.env.example` a `.env`
3. `npm run dev` y abre http://localhost:3000

## Decisiones técnicas
- Elegí PostgreSQL por las consultas agregadas por categoría.
- Validé los datos en el servidor para no depender del navegador.

## Próximos pasos
- Exportar a CSV
- Modo oscuro

# Gastos Claros
App web para registrar gastos del hogar y ver en qué se va el dinero cada mes.

![Panel principal](docs/panel.png)
**Demo:** https://gastos-claros.example.com

## Problema que resuelve
Las planillas de gastos se abandonan porque cargar datos es tedioso.
Gastos Claros permite registrar un gasto en dos toques y muestra un resumen por categoría.

## Stack
React (interfaz), Node.js + Express (API), PostgreSQL (datos), Jest (tests)

## Cómo correrlo
1. `git clone ...` e `npm install`
2. Copia `.env.example` a `.env`
3. `npm run dev` y abre http://localhost:3000

## Decisiones técnicas
- Elegí PostgreSQL por las consultas agregadas por categoría.
- Validé los datos en el servidor para no depender del navegador.

## Próximos pasos
- Exportar a CSV
- Modo oscuro

# Gastos Claros
App web para registrar gastos del hogar y ver en qué se va el dinero cada mes.

![Panel principal](docs/panel.png)
**Demo:** https://gastos-claros.example.com

## Problema que resuelve
Las planillas de gastos se abandonan porque cargar datos es tedioso.
Gastos Claros permite registrar un gasto en dos toques y muestra un resumen por categoría.

## Stack
React (interfaz), Node.js + Express (API), PostgreSQL (datos), Jest (tests)

## Cómo correrlo
1. `git clone ...` e `npm install`
2. Copia `.env.example` a `.env`
3. `npm run dev` y abre http://localhost:3000

## Decisiones técnicas
- Elegí PostgreSQL por las consultas agregadas por categoría.
- Validé los datos en el servidor para no depender del navegador.

## Próximos pasos
- Exportar a CSV
- Modo oscuro

# Gastos Claros
App web para registrar gastos del hogar y ver en qué se va el dinero cada mes.

![Panel principal](docs/panel.png)
**Demo:** https://gastos-claros.example.com

## Problema que resuelve
Las planillas de gastos se abandonan porque cargar datos es tedioso.
Gastos Claros permite registrar un gasto en dos toques y muestra un resumen por categoría.

## Stack
React (interfaz), Node.js + Express (API), PostgreSQL (datos), Jest (tests)

## Cómo correrlo
1. `git clone ...` e `npm install`
2. Copia `.env.example` a `.env`
3. `npm run dev` y abre http://localhost:3000

## Decisiones técnicas
- Elegí PostgreSQL por las consultas agregadas por categoría.
- Validé los datos en el servidor para no depender del navegador.

## Próximos pasos
- Exportar a CSV
- Modo oscuro

Con apenas unos minutos más, el mismo proyecto pasa de ser un archivo más a ser una pieza que cuenta una historia.

Errores que restan puntos

1. README vacío o de una línea. Es la señal más clara de descuido.

2. Instrucciones que no funcionan. Si el proyecto no se levanta, la imagen del perfil se deteriora.

3. Nada visual. Sin captura ni demo, el lector tiene que imaginar qué hace.

4. Texto copiado de un tutorial sin explicar qué agregaste tú.

5. Claves o contraseñas subidas al repositorio. Nunca publiques credenciales; usa variables de entorno y un archivo .env.example.

6. Stack inflado. Listar tecnologías que no usaste se nota en la entrevista.

7. Enlaces rotos a la demo o al portfolio.

8. Mucho texto sin formato. Usa títulos, listas y bloques de código para que se lea rápido.

Cómo enlazar tu README desde el CV y LinkedIn

• En el CV: para cada proyecto, incluye una línea de resultado y el enlace al repositorio o a la demo. Mira cómo estructurarlo en plantillas de CV para tecnología.

• En LinkedIn: usa la sección "Destacados" o "Proyectos" para enlazar tus dos o tres mejores repositorios con una descripción clara.

• Fija repositorios en tu perfil de GitHub: GitHub permite fijar hasta seis repositorios destacados; elige los que tengan el README más cuidado.

• Agrega un README de perfil: un repositorio con el nombre de tu usuario permite mostrar una presentación breve con enlaces a tus mejores proyectos.

Si todavía estás armando tus primeros proyectos, usa esta guía para armar un portfolio de tecnología desde cero y la guía de portfolio de programador junior.

Usa IA para mejorar el README, no para inventarlo

Puedes pedirle a un asistente que revise la estructura o que corrija la redacción. Pega tu borrador y pregunta: "Revisa este README como lo haría un recruiter con un minuto: ¿qué falta para entender el proyecto?". Verifica siempre que los comandos y las descripciones coincidan con lo que realmente hace tu proyecto; un README generado sin revisar puede incluir pasos que no existen.

Checklist final antes de publicar

• ¿Se entiende qué hace en la primera línea?

• ¿Hay una captura o demo?

• ¿Los pasos para correrlo funcionan en una carpeta limpia?

• ¿Explicas al menos una decisión técnica?

• ¿Sin credenciales ni datos privados?

• ¿Los enlaces funcionan?

Curso recomendado de Coderhouse

Si quieres construir proyectos completos para tu portfolio con acompañamiento y feedback, la Carrera de Desarrollo Full Stack de Coderhouse trabaja React, JavaScript y Node.js para que termines con aplicaciones listas para mostrar.

Preguntas frecuentes

¿Qué debe incluir un README de GitHub? Qué hace el proyecto, una captura o demo, el stack, cómo ejecutarlo, decisiones técnicas y próximos pasos, además de tus datos de contacto.

¿En qué idioma conviene escribirlo? Depende del público: en español si postulas a empresas locales; en inglés si apuntas a empresas del exterior. Puedes incluir ambos.

¿Cuánto debe durar un README? Lo suficiente para entender el proyecto en un minuto: no es un manual completo. Si necesitas más detalle, enlaza a una carpeta de documentación.

¿Importa más el README o el código? Los dos. El README es la puerta de entrada: si no se entiende, es probable que nadie llegue a leer el código.