El README de un portafolio no tiene que contar toda la historia del proyecto. Tiene que permitir que otra persona entienda el problema, encuentre una decisión de ingeniería y vea cómo comprobar la afirmación principal. Una galería de pantallas puede llamar la atención, pero no explica qué elegiste, qué probaste o qué todavía desconoces.

Para escribir ese README, organiza la lectura en cinco pasadas: problema, contribución, decisiones, verificación y límites. La guía sobre lo que debe demostrar un portafolio de software engineer con IA cubre el conjunto de proyectos. Esta página se centra en el artefacto práctico: cómo convertir un repositorio en algo que sostenga una conversación técnica.

Diagrama que muestra un README de portafolio conectado con problema, decisiones, verificación y límites.

Respuesta breve

  • Explica qué problema resuelve el proyecto y para quién antes de enumerar la stack.
  • Muestra una decisión que podría haber sido distinta y el trade-off que aceptaste.
  • Ofrece un camino corto para instalar, ejecutar y verificar el comportamiento principal.
  • Separa lo que construiste, adaptaste, delegaste y reutilizaste.
  • Declara los límites, los casos no probados y lo que cambiarías después.

¿Qué debe demostrar un README de portafolio?

El README de un repositorio tiene una función más amplia que la marca personal. La documentación de GitHub sobre los archivos README describe el archivo como un lugar para explicar por qué un proyecto es útil, qué hace y cómo empezar. También recomienda indicar dónde pedir ayuda y quién mantiene el proyecto.

En un portafolio, añade la pregunta que probablemente hará un revisor: ¿qué tipo de ingeniería permite observar este proyecto? La respuesta no tiene que prometer seniority. Puede señalar una frontera concreta, como autenticación, procesamiento asíncrono, validación de entradas, recuperación de fallos o evaluación de la salida de un modelo.

Una apertura útil responde cuatro preguntas sin obligar al lector a abrir el código:

Pregunta Lo que debe mostrar el README
¿Qué es? una frase sobre el comportamiento principal
¿Por qué existe? el problema, el usuario u operador y el límite del alcance
¿Qué hiciste? tu contribución y las partes adaptadas o reutilizadas
¿Cómo se puede comprobar? un comando, una entrada, una salida esperada o una demo reproducible

El estudio Categorizing the Content of GitHub README Files analizó 4.226 secciones de 393 repositorios. Encontró con frecuencia información sobre lo que hace un proyecto y cómo usarlo, mientras que el propósito y el estado aparecían menos. La muestra es de 2018 y no mide contrataciones. Aun así, plantea una pregunta útil para el portafolio: ¿tu README explica solo cómo funciona el proyecto o también por qué existe y en qué estado está?

Empieza por el problema, no por la tecnología

Abre con dos o tres frases que definan el límite. "API en Node.js con PostgreSQL" nombra herramientas, pero no ofrece una decisión que revisar. "API que registra pedidos y rechaza una actualización cuando cambió la versión del recurso" nombra un comportamiento y un riesgo que se pueden discutir.

Un proyecto personal no necesita usuarios reales ni tráfico comercial. El README debe decir si el proyecto sirve para estudiar una técnica, demostrar un contrato o explorar una hipótesis. Así evitas que alguien atribuya al proyecto una promesa que nunca hiciste.

Usa una estructura sencilla al principio:

# Nombre del proyecto

Una frase sobre lo que hace el sistema y para quién.

Este proyecto explora [problema o técnica]. Cubre [alcance]
y no intenta resolver [fuera de alcance].

## Demo rápida

Comando o enlace que muestra el recorrido principal.

La guía de GitHub para preparar un repositorio para la colaboración también sitúa el propósito, el uso y el mantenimiento del proyecto en el README. En un portafolio, mantenimiento incluye decir si el repositorio está activo, congelado, experimental o limitado a una demostración.

Registra decisiones que el código no explica

Una lista de dependencias no demuestra criterio. Para cada decisión elegida, registra el riesgo que atiende, la alternativa que consideraste y el coste que aceptaste. No hace falta documentar cada decisión de sintaxis. Elige una o dos que cambien el comportamiento, la operación o la posibilidad de verificar el proyecto.

Decisión Pregunta que responde el README Evidencia útil
Almacenamiento ¿Por qué esta base o archivo encaja con el alcance? consulta, modelo de datos o límite declarado
Concurrencia ¿Qué ocurre cuando llegan dos acciones juntas? prueba, regla de conflicto o escenario no cubierto
Fallo ¿Cómo reacciona el sistema ante un timeout o una entrada inválida? fixture, estado de error o log redactado
Dependencia de IA ¿Qué se delegó y cómo se revisó la salida? diff, prueba, criterio o decisión rechazada

Un registro breve funciona mejor cuando conecta causa y consecuencia:

## Decisión: rechazar una actualización con una versión antigua

Comparo `version` antes de escribir porque dos solicitudes pueden editar el
mismo recurso. La alternativa era aceptar la última escritura, pero eso
ocultaría un cambio concurrente. `npm test -- conflict` muestra los casos
aceptado y rechazado.

El ejemplo es ilustrativo. Sustituye el comando, el riesgo y la decisión por elementos que existan en tu proyecto. Un README que describe una arquitectura que el código no tiene ofrece una evidencia más débil que un README corto y honesto.

Muestra un camino de verificación

Una demo ayuda, pero por sí sola no explica cómo se obtuvo el resultado. Escribe el camino más corto que otra persona pueda repetir:

  1. qué versiones, requisitos o variables hacen falta;
  2. qué comando instala y qué comando inicia el proyecto;
  3. qué entrada representa el caso principal;
  4. qué salida o efecto debe observarse;
  5. qué caso de fallo muestra el límite de la implementación.

Si la configuración requiere un secreto, un servicio de pago o una cuenta privada, dilo. Incluye un ejemplo seguro, un modo local o una descripción de lo que no se puede reproducir. La documentación de GitHub espera que el README ayude a empezar, pero eso no significa prometer una ejecución sin configuración cuando el proyecto no puede ofrecerla.

La prueba no tiene que ser grande. npm test, una fixture pequeña o un ejemplo de entrada y salida pueden bastar para la pregunta elegida. En un proyecto que usa un modelo, registra también el criterio de evaluación y una entrada que debería rechazarse. Una respuesta fluida no demuestra un comportamiento consistente.

No pongas en el README un resultado que no hayas ejecutado. Si un comando es solo un ejemplo, márcalo como "ilustrativo". Si comprobaste una fixture local, indica el entorno y lo que no cubre. Esa diferencia también forma parte de la evidencia.

Explica la autoría sin convertir el README en una defensa

El revisor necesita saber qué partes se te pueden atribuir. Esto importa en un proyecto en grupo, un fork, una base de tutorial o un proyecto asistido por IA.

Usa una sección breve:

## Límites de autoría y contribución

Implementé el contrato de la API, la validación y las pruebas de conflicto.
Adapté la configuración inicial de [fuente]. No medí carga de producción
y no afirmo que el proyecto cubra la recuperación de la base de datos.

No necesitas publicar una conversación completa con un agente. Si usaste Codex, Claude Code u otra herramienta, explica qué delegaste, qué revisaste y qué prueba ejecutaste después. Para sesiones largas, el autor usa RemoteCode para conservar el contexto entre sesiones. Eso describe el método de trabajo, no demuestra que el proyecto tenga calidad.

El checklist para evaluar un portafolio de software engineer lee desde el otro lado. Pregunta si la contribución, las decisiones, la verificación y los límites son visibles. Usa esas preguntas para revisar tu propio README antes de pedir que otra persona lo evalúe.

Declara lo que todavía no está probado

Un proyecto de portafolio resulta más fácil de confiar cuando separa tres estados:

  • No implementado: la función no existe.
  • No verificado: la función existe, pero la evidencia disponible no cubre el caso.
  • Fuera del alcance: el proyecto no intenta resolver esa situación.

Esta distinción evita dos exageraciones. La primera es llamar a una demo lista para producción. La segunda es esconder un proyecto útil porque no tiene la escala de un servicio comercial.

Relaciona los límites con las decisiones que mostraste. Si elegiste SQLite para simplificar la instalación, indica que esa elección no demuestra el comportamiento bajo carga distribuida. Si usas una API externa, indica que la fixture no verifica la disponibilidad del proveedor. Si un agente generó parte del código, explica qué revisión y qué pruebas siguen bajo tu responsabilidad.

Indica también el estado del repositorio: activo, congelado, experimental o archivado. El lector necesita saber si un problema abierto representa trabajo en curso o una decisión abandonada.

Separa el README de la documentación larga

El README debe llevar al lector al primer uso y a la prueba principal. No necesita contener la referencia completa de la API, el historial de cada commit ni un manual completo de operaciones. La documentación de GitHub sobre wikis distingue el README, que explica rápidamente qué puede hacer un proyecto, de la documentación más extensa.

Mueve los detalles largos a docs/ si eso mejora la lectura, pero deja claro el camino:

README.md                 problema, decisión principal y quickstart
docs/architecture.md      diseño y alternativas descartadas
docs/testing.md           fixtures, comandos y huecos de la prueba
docs/operations.md        configuración, recuperación y mantenimiento

No uses la separación para esconder la información importante. El README todavía debe contener el problema, el primer recorrido, la decisión que quieres discutir y un enlace directo a la evidencia complementaria.

Checklist antes de publicar

Lee el README como alguien que no conoce el proyecto. ¿Puedes responder estas preguntas sin abrir cinco archivos?

  • ¿El proyecto explica el problema y lo que queda fuera del alcance?
  • ¿El primer bloque dice qué hacer y qué observar?
  • ¿Hay una decisión de ingeniería ligada a un riesgo o requisito?
  • ¿Aparecen la alternativa descartada y el trade-off aceptado?
  • ¿Se comprobó el comando de instalación en un entorno limpio o está marcado como ilustrativo?
  • ¿Una prueba, fixture o ejemplo muestra el comportamiento principal?
  • ¿Hay un caso de fallo, un límite o un hueco de verificación?
  • ¿La autoría separa lo construido, adaptado, delegado y reutilizado?
  • ¿Está claro el estado del repositorio?
  • ¿Funcionan los enlaces a la documentación larga?

Si una respuesta es "no", eso no significa que el proyecto deba crecer. Significa que el README todavía no demuestra esa afirmación. Corrige la documentación, reduce la promesa o elimina la afirmación.

Conclusión

Un README de portafolio es un recorrido de revisión. Empieza con el problema, muestra una decisión con consecuencias, apunta a una forma de verificar el comportamiento y termina en los límites que siguen abiertos. La tecnología importa, pero no carga la prueba por sí sola.

Escribe para la conversación que el proyecto puede sostener. Si no puedes explicar por qué existe una elección o qué prueba podría contradecirla, el README no debe fabricar confianza. Una documentación breve, reproducible y honesta prepara una conversación técnica mejor que una página llena de badges y adjetivos.

Cómo se produjo este artículo

Samuel Fajreldines es el autor responsable de este artículo. La investigación comparó documentación actual de GitHub, un estudio académico sobre el contenido de los README y discusiones públicas recientes de desarrolladores brasileños. El checklist es una síntesis editorial. No es el resultado de una entrevista real, un proceso de selección medido ni un benchmark de portafolios.

La asistencia de IA apoyó la búsqueda de fuentes, la organización, el primer borrador, la localización, la ilustración SVG y la revisión de consistencia. No evaluó candidatos, no ejecutó el proyecto de portafolio de otra persona ni aportó experiencia profesional que el autor no haya demostrado.

Fuentes consultadas