Proyectos guiados — Índice y método

🎯 Por qué esta sección existe. Los capítulos te enseñan piezas. Un proyecto te obliga a decidir: qué usar, en qué orden, qué dejar fuera y cómo saber si has terminado. Es donde el conocimiento pasa de "me suena" a "sé hacerlo".

🧠 La regla que más importa de todo el libro: un proyecto pequeño terminado enseña más que diez tutoriales a medias. Terminado significa: desplegado, con README, con tests y con alguien que no seas tú capaz de arrancarlo siguiendo tus instrucciones.

Mapa de proyectos

#	Proyecto	Después de	Duración	Qué demuestra
P1	Kit de herramientas DevOps	Parte 0 (T1-T3)	1 semana	Terminal, Bash, automatización, cron
P2	API de tareas multi-stack	Caps. 0-11	2-4 semanas	REST, SQL, auth, tests, arquitectura
P3	Plataforma de cursos	Caps. 12-22	4-6 semanas	Fullstack, Docker, CI/CD, despliegue real
P4	Diseño sin código	Caps. 23-26	1 semana	Pensamiento arquitectónico, ADRs, trade-offs
P5	Producto propio	Todo	2-3 meses	Todo junto, con usuarios reales

mermaid

graph LR
    T["Parte 0<br/>Terminal y Bash"] --> P1["P1 · Kit DevOps"]
    P1 --> F["Caps. 0-11<br/>Backend y calidad"]
    F --> P2["P2 · API de tareas"]
    P2 --> D["Caps. 12-22<br/>DevOps y frontend"]
    D --> P3["P3 · Plataforma"]
    P3 --> I["Caps. 23-26<br/>Ingeniería"]
    I --> P4["P4 · Diseño"]
    P4 --> P5["P5 · Producto propio"]

Cómo trabajar un proyecto (el método)

Es el método del capítulo 23, aplicado:

1. LEE LA ESPECIFICACIÓN ENTERA antes de escribir nada.
   Apunta lo que no entiendes. Esas dudas son requisitos ocultos.

2. ESCRIBE TU PROPIA LISTA DE TAREAS, en trozos de 1-2 horas.
   Si una tarea es "hacer la autenticación", no la has descompuesto.

3. EMPIEZA POR UNA REBANADA VERTICAL.
   Un caso de uso completo: de la petición HTTP a la base de datos y vuelta.
   NO empieces creando todas las tablas.

4. COMMITEA A MENUDO, con mensajes que expliquen el porqué.
   Tu historial de Git es parte de la entrega.

5. CUANDO TE ATASQUES MÁS DE 30 MINUTOS: escribe el problema en un papel
   como si se lo explicaras a alguien. La mitad de las veces lo resuelves ahí.

6. AL TERMINAR CADA FASE, PREGÚNTATE: ¿podría desplegar esto hoy?
   Si la respuesta es no, no has terminado la fase.

⚠️ El error nº1 al hacer proyectos: empezar por lo bonito. El instinto lleva a diseñar la interfaz o a montar el sistema de plugins. El método correcto es empezar por lo que no sabes si va a funcionar. Si el proyecto depende de una integración externa que nunca has usado, pruébala el primer día con un script de 20 líneas, antes de construir nada alrededor.

Rúbrica de evaluación

Úsala para autoevaluarte al terminar. Es también, más o menos, lo que mira alguien que revisa tu portfolio.

Área	🔴 Insuficiente	🟡 Correcto	🟢 Nivel profesional
Funciona	Falla en casos normales	Cumple los requisitos	Cumple, y los casos límite están cubiertos
Errores	Se cae con un stack trace	Devuelve códigos HTTP correctos	Errores tipados, mensajes útiles, nada sensible expuesto
Datos	Todo en una tabla, sin claves	Normalizado con FK	Índices justificados, restricciones que garantizan invariantes
Seguridad	SQL concatenado, contraseñas en claro	Consultas parametrizadas, hash de contraseñas	Autorización por recurso, rate limiting, validación de entrada, secretos fuera del repo
Tests	Ninguno	Tests de los casos principales	Unitarios + integración, casos límite, corren en CI
Estructura	Todo en un archivo	Separado en capas	Dependencias hacia el dominio, fácil de cambiar
Git	3 commits: "cambios", "más cambios"	Commits pequeños y descriptivos	Ramas, mensajes que explican el porqué, historial legible
README	No hay	Cómo instalar y arrancar	Además: decisiones, arquitectura, limitaciones conocidas
Despliegue	Solo funciona en tu portátil	Dockerfile que funciona	Desplegado y accesible por URL, con CI/CD
Observabilidad	`print()` por todas partes	Logs estructurados	Logs + healthcheck + métricas básicas

💡 Objetivo realista: todo en 🟡 y dos o tres columnas en 🟢. Nadie llega a 🟢 en todo en un proyecto de aprendizaje, y perseguirlo es la mejor forma de no terminar nunca.

Qué debe tener la entrega, siempre

mi-proyecto/
├── README.md              ← 📌 el archivo más importante del repositorio
├── docs/
│   ├── adr/               ← decisiones (capítulo 25)
│   └── api.md             ← endpoints, o un OpenAPI
├── src/
├── tests/
├── .env.example           ← ⚠️ el .env REAL nunca se sube
├── .gitignore
├── docker-compose.yml
├── Dockerfile
└── Makefile               ← make dev · make test · make deploy

El README que separa un proyecto serio de un ejercicio

markdown

# Nombre del proyecto
Una frase: qué problema resuelve y para quién.

## Demo
URL desplegada + credenciales de prueba. (Si no hay demo, una captura o un gif.)

## Arranque rápido
    git clone … && cd …
    cp .env.example .env
    docker compose up
Abre http://localhost:3000. Debe funcionar con ESTOS comandos, sin más pasos.

## Stack y por qué
No una lista de logos: una frase por decisión importante.
"PostgreSQL porque los datos son relacionales y necesitamos transacciones para X."

## Arquitectura
Un diagrama y tres párrafos. Cómo fluye una petición de principio a fin.

## Decisiones destacadas
Enlace a los ADRs, o un resumen de las 3 decisiones que más condicionaron el proyecto.

## Limitaciones conocidas
📌 La sección que más credibilidad da. "No hay paginación en X; con más de 10.000
registros se degradaría. Se resolvería con Y." Demuestra que conoces tu propio sistema.

## Tests
    make test
Qué está cubierto y qué no.

🧠 Por qué "Limitaciones conocidas" impresiona tanto: cualquiera puede listar lo que su proyecto hace. Saber exactamente dónde se rompe, por qué, y qué haría falta para arreglarlo es justo lo que distingue a alguien que entiende su sistema de alguien que solo consiguió que funcionara.

Cómo saber que has terminado

Una lista de comprobación final, común a todos los proyectos:

□ Alguien que no eres tú clona el repo y lo arranca siguiendo el README, sin preguntarte nada.
□ Los tests pasan en limpio (borra node_modules / .venv y vuelve a instalar).
□ No hay secretos en el historial de Git.  → git log -p | grep -iE "password|secret|api[_-]key"
□ Los errores devuelven el código HTTP correcto, no un 500 genérico.
□ Funciona con la base de datos vacía (probaste desde cero, no solo con tus datos).
□ Funciona con datos "sucios": campos vacíos, textos larguísimos, emojis, comillas.
□ Hay un healthcheck y unos logs que sirven para depurar en producción.
□ El README explica el porqué de al menos tres decisiones.
□ Está desplegado en algún sitio con una URL pública.

Empieza por: 01-kit-devops-bash.md

Mapa de proyectos ​

Cómo trabajar un proyecto (el método) ​

Rúbrica de evaluación ​

Qué debe tener la entrega, siempre ​