Cómo armar un portafolio de proyectos backend que demuestre arquitectura real

1. Introducción: trascender los proyectos de juguete

Un repositorio de GitHub lleno de proyectos que replican tutoriales —una API de tareas pendientes, un CRUD de usuarios sin autenticación, un blog sin pruebas— dice muy poco sobre la capacidad real de un candidato para operar en un entorno de producción. Los reclutadores técnicos y los ingenieros que revisan portafolios en procesos de selección para roles backend no buscan demostraciones de sintaxis: buscan evidencia de que la persona entiende cómo se sostiene un sistema en el tiempo, cómo se comunica con otros servicios y cómo se documenta el criterio detrás de cada decisión. Este artículo complementa la ruta de aprendizaje descrita en qué hace un desarrollador backend y se enfoca en un problema distinto: cómo seleccionar y construir los proyectos que compondrán ese portafolio.

La diferencia entre código de tutorial y arquitectura lista para producción no está en la cantidad de líneas ni en la elegancia del algoritmo, sino en cuatro pilares que rara vez aparecen juntos en un proyecto de aprendizaje: contratos de API bien especificados, una estrategia de pruebas automatizadas estructurada, un flujo de entrega continua verificable y un registro documentado de las decisiones técnicas que se tomaron y por qué. Un portafolio que exhibe estos cuatro elementos comunica, sin necesidad de una entrevista extensa, que quien lo construyó ya piensa como un ingeniero de sistemas y no como alguien que solo sabe hacer funcionar código en su máquina local.

2. Diseño y especificación de contratos de API

2.1 Estandarización agnóstica al lenguaje mediante OpenAPI

La OpenAPI Specification (OAS) es una especificación de interfaz para APIs HTTP, independiente del lenguaje de programación, mantenida como proyecto colaborativo de la Linux Foundation dentro de la OpenAPI Initiative. Su propósito central es que tanto humanos como máquinas puedan descubrir y entender las capacidades de un servicio sin necesidad de acceder al código fuente, revisar documentación adicional o inspeccionar el tráfico de red. Cuando un servicio está correctamente definido mediante OpenAPI, quien lo consume puede interactuar con él con una cantidad mínima de lógica de implementación, de la misma forma en que las interfaces de bajo nivel eliminaron la incertidumbre en la programación clásica.

Para un portafolio de proyectos backend, incluir un contrato OpenAPI no es un accesorio estético: es la prueba de que el proyecto fue diseñado pensando en quien lo va a consumir, sea un frontend, otro microservicio o un equipo externo. Esto conecta directamente con los fundamentos técnicos descritos en la comparativa de lenguajes de programación backend, donde la elección del stack condiciona, pero no sustituye, la necesidad de un contrato explícito.

2.2 Definición estructurada y desacoplamiento del código

Los documentos OpenAPI se representan en formato YAML o JSON y pueden producirse de forma estática o generarse dinámicamente desde la propia aplicación. La especificación no exige reescribir APIs existentes ni ligar ningún software a un servicio concreto: únicamente requiere que las capacidades del servicio queden descritas siguiendo la estructura de OAS, ya sea que el equipo trabaje bajo un enfoque de diseño primero (design-first) o de código primero (code-first). Este desacoplamiento es justamente lo que permite que un evaluador externo entienda la superficie de un proyecto sin tener que leer controladores o rutas dispersas en el código.

2.3 Casos de uso prácticos en un proyecto de portafolio

Entre los usos documentados de un archivo OpenAPI destacan la generación de documentación interactiva, la generación de código —tanto de clientes como de stubs de servidor— y la automatización de casos de prueba. Un proyecto de portafolio que incluye un archivo openapi.yaml versionado junto al código, del cual se derivan la documentación interactiva y las pruebas de contrato, demuestra en un solo artefacto tres competencias simultáneas: diseño de interfaces, disciplina de documentación y comprensión de cómo se automatiza la verificación de esa interfaz frente a cambios futuros.

3. Estrategia de pruebas automatizadas y calidad de código

3.1 La pirámide de testing como estructura de referencia

La pirámide de testing, desarrollada por Mike Cohn en su libro Succeeding with Agile, ilustra la cantidad y el tipo óptimo de pruebas a usar durante el desarrollo de un programa. Su estructura típica contempla tres capas: pruebas unitarias, pruebas de integración y pruebas end-to-end (E2E), aunque algunas variantes agregan el análisis estático como base adicional. Estas capas no son compartimentos estancos: es habitual que se solapen, especialmente cuando las pruebas de integración cubren funcionalidad que también podría validarse en pruebas end-to-end, por lo que definir límites claros para cada capa ayuda a evitar duplicación de esfuerzo y mantiene la suite eficiente.

3.2 Pruebas unitarias para validación granular

Las pruebas unitarias son las más específicas: verifican si una unidad particular del código base funciona correctamente. Son escritas y ejecutadas típicamente por quienes desarrollan el código, ya que son responsables de verificar que cada pieza funcione antes de integrarse con el resto de la aplicación. Buenas prácticas incluyen probar la interfaz pública de la clase o función, cubrir tanto el camino esperado como los casos límite, y mantener una organización que asocie una clase de prueba por cada módulo de producción. En un proyecto de portafolio, la ausencia de pruebas unitarias sobre la lógica de negocio —no solo sobre funciones triviales— suele ser la primera señal de alerta para quien revisa el repositorio.

3.3 Abandonar la regresión manual en favor de ciclos rápidos

La investigación de DORA (DevOps Research and Assessment) señala que el enfoque tradicional de testing manual y revisión de código en una fase separada tras el llamado "dev complete" presenta varios problemas: las pruebas de regresión manual consumen tiempo y son costosas, lo que las convierte en un cuello de botella que impide desplegar software con frecuencia; además, las personas son poco fiables ejecutando tareas repetitivas como esas regresiones. Frente a esto, DORA recomienda ejecutar todo tipo de pruebas de forma continua a lo largo del ciclo de vida del software y curar suites de pruebas automatizadas rápidas y confiables que corran como parte de los pipelines de entrega continua. Un elemento concreto y medible de esta recomendación es que los equipos deben poder obtener retroalimentación de las pruebas automatizadas en menos de diez minutos, tanto en las máquinas de desarrollo local como desde el sistema de integración continua. Este umbral de diez minutos es un criterio verificable que un portafolio puede exhibir documentando el tiempo de ejecución de su suite de pruebas en el pipeline.

3.4 Test-Driven Development (TDD) como disciplina

Dentro de las prácticas organizacionales que DORA asocia con mejor desempeño está que los equipos practiquen desarrollo guiado por pruebas, escribiendo pruebas unitarias antes que el código de producción para todos los cambios en la base de código. Esta técnica, conocida como TDD, garantiza que el código resultante sea comprobable por diseño y no como una capa añadida después. Adoptar TDD en al menos uno de los proyectos del portafolio —y dejar constancia de ello en el historial de commits— es una forma tangible de mostrar esta disciplina sin necesidad de explicarla en una entrevista.

4. Arquitectura de aplicaciones y patrones nativos

4.1 Principios de Twelve-Factor App vigentes

La metodología Twelve-Factor App, publicada originalmente por Adam Wiggins en Heroku en 2011, fue escrita para un mundo específico de plataformas PaaS y despliegue mediante slugs de Git, antes de la existencia de Docker, Kubernetes o el cómputo serverless. Sin embargo, un análisis retrospectivo publicado quince años después concluye que, aunque no todos los doce factores conservan la misma relevancia, hay principios que importan hoy más que nunca, entre ellos la configuración externalizada mediante variables de entorno y el diseño de procesos sin estado (stateless) capaces de escalar horizontalmente. Estos dos factores en particular siguen siendo un criterio de evaluación directo sobre la madurez arquitectónica de un proyecto: un servicio que guarda credenciales en el código fuente o que mantiene estado de sesión en memoria de proceso revela una comprensión incompleta de cómo se opera software en entornos distribuidos.

4.2 Contenerización y consistencia entre entornos

Diseñar procesos stateless con configuración externa es, además, el requisito previo para que la contenerización cumpla su promesa: un contenedor solo garantiza paridad entre el entorno local y el de despliegue si la aplicación no depende de estado retenido en el sistema de archivos o en la memoria del proceso que lo ejecuta. Un proyecto de portafolio que incluye un Dockerfile funcional, junto con variables de entorno correctamente externalizadas y sin secretos hardcodeados, demuestra que quien lo construyó entiende la contenerización no como un empaquetado cosmético, sino como una consecuencia directa de un diseño de aplicación correcto.

5. Flujo de entrega continua y cultura operativa

5.1 Trunk-Based Development y lotes pequeños

Existen dos patrones principales para que los equipos de desarrollo trabajen con control de versiones. El primero son las ramas de funcionalidad (feature branches), donde un desarrollador o grupo trabaja de forma aislada hasta completar una funcionalidad y luego fusiona su rama a la rama principal. El segundo, conocido como trunk-based development, consiste en que cada persona divide su trabajo en lotes pequeños y los integra a la rama principal al menos una vez al día, o incluso varias veces. La diferencia clave entre ambos enfoques es el alcance: las ramas de funcionalidad suelen involucrar a varios desarrolladores durante días o semanas, mientras que las ramas en trunk-based development duran típicamente no más de unas horas. El análisis de datos de DORA muestra que los equipos alcanzan niveles más altos de desempeño en entrega y operación de software cuando mantienen tres o menos ramas activas en el repositorio, fusionan a la rama principal al menos una vez al día y evitan los congelamientos de código y las fases de integración prolongadas.

5.2 Pipelines de integración continua fiables

La integración continua se define, precisamente, como la combinación de practicar trunk-based development y mantener una suite de pruebas automatizadas rápidas que se ejecutan después de cada commit para verificar que el sistema sigue funcionando. En este paradigma, quienes desarrollan son responsables de mantener el proceso de build "en verde": si el pipeline falla, deben detener su trabajo para corregir el problema de inmediato o revertir el cambio si no puede resolverse en pocos minutos. Un portafolio que muestra un pipeline de CI configurado —con ejecución de pruebas, análisis estático y, cuando aplica, escaneo de vulnerabilidades tras cada push— es la evidencia más directa de que el candidato entiende la integración continua como disciplina operativa y no como una insignia decorativa en el README.

5.3 Métricas DORA: throughput y estabilidad

Las métricas DORA constituyen un conjunto estandarizado de indicadores de desempeño en la entrega de software, desarrollado por el equipo de investigación DevOps de Google, y se agrupan en dos dimensiones: throughput —qué tan rápido un equipo puede llevar cambios a producción— y estabilidad —qué tan confiable y segura es esa entrega—. Las métricas de throughput incluyen la frecuencia de despliegue, el lead time for changes y el tiempo de recuperación ante fallos de despliegue; las métricas de estabilidad incluyen la tasa de fallos por cambio y, desde 2024, la tasa de retrabajo en despliegues. Estas métricas permiten a los equipos evidencia empírica y reproducible en lugar de indicadores subjetivos o de vanidad como las líneas de código escritas. Aunque un proyecto personal de portafolio no puede simular todas estas métricas a la escala de una organización, documentar el historial de despliegues, el tiempo entre commit y despliegue, y la frecuencia de integración a main permite argumentar frente a un reclutador con el mismo vocabulario que usa la industria para medir madurez operativa.

6. Registro de criterio técnico: Architecture Decision Records (ADR)

6.1 Preservar el contexto y la justificación

Michael Nygard planteó en 2011 un problema que sigue vigente: una persona nueva en un proyecto puede sentirse desconcertada, encantada o indignada por alguna decisión pasada, y sin entender su razón de ser (rationale) o sus consecuencias, solo tiene dos opciones —aceptarla ciegamente o cambiarla ciegamente—, ambas riesgosas si el contexto original ya no aplica o si la decisión sigue siendo válida pero se revierte sin comprenderla. Los ADR nacen para evitar ese escenario, registrando decisiones "arquitectónicamente significativas": aquellas que afectan la estructura, las características no funcionales, las dependencias, las interfaces o las técnicas de construcción de un sistema. La guía de arquitectura del servicio digital del Reino Unido (GDS) refuerza esta idea señalando que preservar el razonamiento permite al equipo actual entender si una decisión se tomó por conveniencia —y por tanto puede cambiarse con poco impacto— o si respondía a restricciones externas que siguen siendo relevantes.

6.2 La estructura estándar de Nygard

El formato propuesto por Nygard consta de partes deliberadamente breves: Título, como una frase nominal corta que describe la decisión, no el problema; Contexto, que describe las fuerzas en juego —tecnológicas, políticas, sociales o locales del proyecto— en lenguaje neutral, limitándose a describir hechos; Decisión, redactada en oraciones completas y voz activa ("Haremos..."); Estado, que puede ser "propuesta" hasta que los interesados del proyecto la acuerden, "aceptada" una vez acordada, o "desaprobada"/"reemplazada" si una ADR posterior la revierte; y Consecuencias, que debe listar todos los efectos resultantes, tanto positivos como negativos, porque todos ellos afectan al equipo y al proyecto en el futuro. El documento completo debería ocupar una o dos páginas, escrito como si fuera una conversación con un futuro desarrollador. Incluir una carpeta docs/adr con al menos tres o cuatro registros de decisiones reales —por ejemplo, la elección de una base de datos, un patrón de autenticación o una estrategia de particionamiento— convierte al portafolio en un artefacto que responde por sí solo a la pregunta que todo entrevistador técnico hace tarde o temprano: "¿por qué decidiste hacerlo así?".

6.3 Visibilidad mediante control de versiones

Tanto la guía del GDS como el análisis operativo sobre ADR coinciden en un punto práctico: las decisiones arquitectónicas deben almacenarse en control de versiones, dentro del mismo repositorio de la aplicación a la que afectan, para que exista un registro de qué cambió, quién lo hizo y cuándo, y para que ese registro permanezca sincronizado con el código real. Guardar los ADR en herramientas externas al repositorio —una wiki separada, un espacio de documentación que nadie abre— es, según la experiencia documentada en la práctica de varias organizaciones, la causa más común de que el proceso se abandone silenciosamente. Que un ADR viva en main, visible junto al código, evita también la aceptación ciega o la reversión no informada que Nygard identificó como el riesgo original a resolver: cualquier persona que revise el repositorio puede leer, en cuestión de minutos, por qué el sistema es como es, sin depender de que quien tomó la decisión original siga en el equipo.

7. Conclusión: la anatomía del repositorio backend ideal para reclutadores técnicos

Un portafolio backend que efectivamente compite en procesos de selección exigentes no se distingue por la cantidad de repositorios ni por la complejidad superficial del dominio elegido, sino por la presencia simultánea de cuatro señales verificables: un contrato de API especificado en OpenAPI que desacopla el consumo del servicio de su implementación interna; una suite de pruebas organizada según la pirámide de testing, con feedback rápido y, idealmente, evidencia de TDD; un flujo de trabajo basado en trunk-based development e integración continua, documentado en la configuración del pipeline; y una carpeta de ADR que deja constancia escrita del criterio detrás de cada decisión relevante. Estos cuatro elementos son exactamente los que un reclutador técnico o un ingeniero senior busca cuando revisa un repositorio antes de una entrevista, porque son los mismos que definen si un sistema puede sostenerse en producción o si simplemente funciona en la máquina de quien lo escribió.

Construir este tipo de portafolio no reemplaza otros elementos del proceso de búsqueda de empleo: sigue siendo necesario saber comunicar estas decisiones en una entrevista —para lo cual conviene revisar el método STAR para preguntas conductuales— y presentar esa experiencia de forma clara en el currículum, como se explica en la guía para redactar un currículum técnico y en cómo optimizar ese currículum frente a los filtros ATS. Pero ningún párrafo bien escrito sustituye la evidencia directa de un repositorio que, al abrirse, demuestra por sí mismo que quien lo construyó ya piensa en términos de contratos, pruebas, entrega continua y decisiones documentadas.

Fuentes Oficiales y Referencias Consultadas

• github.com - github.com
• cognitect.com - cognitect.com