Tu proyecto está desplegado, probado, medido y vigilado. Y sin embargo hay un hecho incómodo que conviene decir sin rodeos: nadie lo sabe, nadie entiende qué decisiones hay detrás, y tú todavía no has practicado cómo contarlo. Un trabajo que no se puede enseñar ni defender vale mucho menos de lo que es — y no por injusticia, sino porque quien lo evalúa tiene diez minutos y ninguna forma de adivinar lo que hiciste bien. Esta lección convierte lo construido en algo que se puede enseñar, defender y mejorar. Verás cómo escribir un README que haga que alguien entienda el proyecto en dos minutos, con plantilla completa y comentada; cómo documentar las decisiones de arquitectura con registros breves (ADR), y por qué documentar el porqué vale mucho más que documentar el qué; cómo preparar una demostración de cinco minutos con su guion, su orden narrativo, sus datos preparados y su plan B; cómo hablar del proyecto en una entrevista técnica —incluida la pregunta que te van a hacer seguro, «¿por qué no usaste React?»—, cómo reconocer una limitación sin sonar inseguro y cómo contar un bug difícil; cómo autoevaluarte con una rúbrica completa por dimensiones; cómo revisarte el código a ti mismo y buscar revisión externa sin hundirte con la crítica; cómo publicar el proyecto con un repositorio ordenado, un historial limpio y una licencia; y cómo iterar después de la entrega, que es lo que distingue un ejercicio terminado de un producto vivo.

1. Por qué presentar es parte del trabajo
2. El README que se entiende en dos minutos
3. La plantilla completa, comentada
4. Capturas, GIF y demo
5. Documentar decisiones: los ADR
6. La plantilla de ADR y cinco ejemplos reales
7. Por qué el porqué vale más que el qué
8. La demostración de cinco minutos
9. El guion y el orden de la narración
10. Datos de ejemplo preparados y plan B
11. Hablar del proyecto en una entrevista técnica
12. «¿Por qué no usaste React?»
13. Reconocer una limitación sin sonar inseguro
14. Contar un bug difícil
15. La autoevaluación con rúbrica por dimensiones
16. La revisión de código a uno mismo
17. Buscar revisión externa y recibir crítica
18. Publicar: repositorio, historial y licencia
19. El portafolio
20. Iterar después de la entrega
21. Errores Comunes y Consejos
22. Ejercicios
23. Conclusión

Hay una creencia extendida y falsa: que el buen trabajo habla por sí solo. No lo hace. Lo que ocurre en la realidad es esto:

Ninguno de los cuatro va a leer 4.000 líneas de código para descubrir que tu detección de ciclos en el árbol cubre los tres casos. Eso hay que contarlo.

Y hay un argumento que va más allá del portafolio: explicar es una habilidad profesional de primer orden. En el trabajo real pasarás una parte considerable del tiempo justificando decisiones, escribiendo documentación, explicando a alguien por qué algo tardará más de lo que parece, y defendiendo un enfoque frente a otro. Quien construye bien pero no sabe explicarlo tiene un techo profesional muy concreto, y no es técnico.

La buena noticia es que esta lección no pide inventar nada: todo lo que hay que contar ya lo has hecho. Se trata de ordenarlo.

El README.md es la portada de tu proyecto. Se lee más que cualquier otra cosa que hayas escrito, incluido el código.

La prueba de los dos minutos: dáselo a alguien que no sepa nada del proyecto y cronometra. A los dos minutos debería poder responder:

1. ¿Qué es esto y para quién?
2. ¿Funciona? ¿Puedo verlo?
3. ¿Qué tiene de interesante técnicamente?
4. ¿Cómo lo ejecuto?

Si no puede, el README falla — por muy bien escrito que esté.

Los cuatro errores que hacen fallar la prueba:

La estructura que funciona, en orden estricto de interés decreciente:

Los tres bloques destacados son los que más peso tienen: la frase inicial decide si siguen leyendo, las decisiones técnicas son lo que diferencia tu proyecto de otros diez iguales, y las limitaciones son lo que demuestra madurez.

git clone https://github.com/usuario/orbita.git cd orbita npm install npm run dev # http://localhost:5173

npm test # 251 pruebas unitarias y de integración npm run test:cov # con informe de cobertura npm run e2e # 3 recorridos de extremo a extremo (Cypress) npm run verificar # lint + formato + pruebas + build

src/dominio/ Entidades y reglas R1-R15. Sin dependencias. Se prueba en Node. src/datos/ Persistencia y red. Un contrato, tres implementaciones. src/vista/ DOM, eventos y accesibilidad. No sabe de dónde vienen los datos. src/aplicacion/ Casos de uso y estado. Une las tres anteriores.

Las insignias del principio no son decoración: comunican en un vistazo que hay CI, que hay pruebas y que hay licencia. Son de las pocas cosas que un reclutador técnico interpreta en dos segundos.

La tabla de rendimiento con su metodología es un detalle poco común y muy valorado: demuestra que mediste con método, no que ejecutaste Lighthouse una vez con suerte.

La imagen es lo que más se mira y lo que menos cuidado suele recibir.

Las siete reglas del GIF del README:

1. Muestra el flujo principal completo, no un clic suelto.
2. Datos realistas. Nada de «tarea 1», «prueba», «asdf». Usa los tuyos ficticios pero verosímiles.
3. Movimiento del ratón lento y deliberado. Los movimientos rápidos marean.
4. Sin barras de herramientas ni pestañas del navegador: solo la aplicación.
5. Menos de 3 MB, o GitHub tardará en cargarlo y muchos verán un hueco.
6. Empieza y termina en un estado limpio, para que el bucle no dé saltos.
7. 10–15 segundos. Más largo, nadie lo termina.

La demo en vivo necesita datos preparados. Una aplicación vacía no demuestra nada, y pedirle a quien la visita que cree seis tareas para entender el producto es pedirle demasiado. Dos opciones:

• Semilla automática la primera vez, con un botón «Empezar de cero».
• Modo demostración por URL (?demo=1) que carga un conjunto de ejemplo.

Y en cualquiera de los dos casos, un aviso claro: «Datos de ejemplo. Todo se guarda solo en tu navegador».

Un ADR (Architecture Decision Record, registro de decisión de arquitectura) es un documento corto que registra una decisión importante, su contexto y sus consecuencias. Nace de una observación simple: el código dice qué se hizo, pero nunca por qué, ni qué alternativas se descartaron, ni qué habría que revisar si cambiara el contexto.

Cuándo escribir uno. No para cada decisión: solo para las que cumplen alguna de estas condiciones:

Para un proyecto de este tamaño, entre 5 y 10 ADR es el número correcto. Menos de 3 sugiere que no hubo decisiones —lo cual es improbable— y más de 20 sugiere que estás documentando detalles de implementación.

Dónde viven: en docs/adr/, numerados, en el repositorio, versionados con el código. Nunca en un servicio externo: se desincronizan.

Las cinco secciones son obligatorias y ninguna sobra:

Los cinco ADR mínimos de este proyecto:

Y dos opcionales que quedan muy bien si tu proyecto los tiene: actualización optimista con reversión y historial inmutable append-only con anonimización en lugar de borrado.

Compara estas dos formas de documentar exactamente lo mismo:

El primer comentario es ruido: dice lo que ya se lee. El segundo contiene información que no existe en ningún otro sitio y que evita que alguien —tú— borre esa línea dentro de seis meses pensando que sobra.

La regla general:

Esa última fila merece énfasis. Las alternativas descartadas son la información más valiosa y la que más rápido se pierde. Sin ella, quien llegue después propondrá exactamente lo que tú ya evaluaste y rechazaste, gastará una semana descubriéndolo, y llegará a tu misma conclusión.

Vas a tener que enseñar tu proyecto: en una entrevista, a un compañero, en una presentación. Cinco minutos es la duración típica, y hay que prepararlos y ensayarlos.

Por qué cinco minutos son difíciles. Porque conoces el proyecto entero y quieres contarlo entero. La disciplina de la demostración consiste en elegir qué no contar.

El error más común, con nombre: el recorrido guiado por la interfaz. «Aquí está el tablero, aquí el botón de filtro, si pulso aquí sale esto, y aquí tenemos otro botón…». Es aburrido, no tiene tensión narrativa, y no dice nada de ti. Nadie recuerda un recorrido por botones.

El orden que funciona tiene estructura de historia:

Un guion literal para Órbita, cronometrado. Adáptalo palabra por palabra a tu proyecto:

Cinco reglas de ejecución de la demostración:

1. Ensáyala en voz alta al menos tres veces, con cronómetro. Se tarda entre un 30 % y un 50 % más de lo que uno cree.
2. No leas el guion. Apréndete la estructura, improvisa las palabras.
3. No enseñes código salvo que lo pidan, y si lo pides tú, que sea un fragmento corto y preparado.
4. No pidas perdón por nada. «Esto está un poco feo», «no me dio tiempo a…» resta sin aportar. Las limitaciones van en el paso 5, dichas con seguridad.
5. Termina con lo siguiente, no con «y ya está». Deja la sensación de proyecto vivo.

Los datos son la mitad de la demostración. Con «tarea 1», «tarea 2» y «prueba asdf», tu producto parece un ejercicio. Con datos verosímiles, parece un producto.

Qué debe contener tu conjunto de demostración, y por qué cada elemento:

Todos los datos ficticios, siempre. Nunca uses nombres reales de compañeros, clientes o conocidos en una demostración pública o en un repositorio. Es una cuestión de respeto y, si el proyecto se publica, de protección de datos. Taller Nómada y su equipo son ficticios; los tuyos también deben serlo.

El plan B, que hay que tener preparado antes y no improvisado:

Una precaución técnica que ha salvado muchas demostraciones: ten una grabación de vídeo de 90 segundos del flujo principal. Si todo falla —red, portátil, proyector—, sigues teniendo algo que enseñar. Cuesta media hora grabarla y es un seguro barato.

En una entrevista, tu proyecto es la mejor herramienta que tienes: es lo único de lo que sabes más que quien te entrevista.

Lo que se evalúa cuando hablas de él no es lo que la mayoría piensa:

La estructura de respuesta que funciona para «háblame de un proyecto tuyo», en unos 90 segundos:

El paso 5 es el que convierte un monólogo en una conversación: das a elegir, y quien entrevista pregunta por lo que le interesa. Eso siempre va mejor que seguir hablando.

Las preguntas que te van a hacer, con la clave de cada una:

Y la respuesta a «¿cómo escalaría?» merece un apunte, porque casi todo el mundo la contesta mal improvisando optimizaciones. La respuesta buena empieza por medir:

«Primero mediría. Mi línea base está con 500 tareas: render() en 44 ms y 1.380 nodos. Con 10.000, lo primero que se rompería es el DOM, así que virtualizaría la lista, que ya está preparada porque el render y la actualización están separados. Lo segundo sería localStorage, que a ese volumen se queda corto: pasaría a IndexedDB, y eso solo toca un fichero porque el repositorio es una frontera con contrato probado. Lo tercero sería el informe, que hoy recalcula entero; ahí memorizaría el selector.»

Esa respuesta demuestra tres cosas de una vez: que mides antes de optimizar, que conoces tus propios números, y que tu arquitectura estaba pensada para eso.

Te la van a hacer. Es la pregunta más probable de todas si tu proyecto es JavaScript puro, y no es una trampa: quieren ver si elegiste o si simplemente no sabes React.

Las tres peores respuestas:

La respuesta buena tiene tres partes: criterio, honestidad y conocimiento del otro lado.

«Fue una decisión, y tengo los números. El producto es una única aplicación con mucha lógica de dominio —quince reglas de negocio— y poca superficie de interfaz: siete pantallas. El equipo soy yo. Con ese contexto, la infraestructura propia que necesito son unas doscientas líneas: un almacén con suscripciones, reconciliación por data-id y delegación de eventos. Eso es menos que el coste de aprender y mantener las convenciones de un framework para este caso concreto.

Y la cifra que más me convenció: en la comparación que hice, el fichero de reglas del dominio era idéntico en JavaScript puro, React, Vue y Angular. Lo único que cambiaba era la vista. Como el valor de este proyecto está en el dominio, el framework aportaba poco aquí.

Ahora bien, sé perfectamente cuándo cambiaría de opinión: con tres o más personas en el equipo, o con más de quince o veinte pantallas, esas doscientas líneas propias pasan a ser un problema, porque nadie más las conoce y no hay documentación ni comunidad detrás. Ahí React o Vue compensan claramente. De hecho reescribí la pantalla principal en los cuatro enfoques para poder comparar: 210 líneas y 18 kB en JavaScript puro, 130 líneas y 63 kB en React.»

Por qué esta respuesta funciona:

1. Empieza afirmando que fue una decisión, no una limitación.
2. Da el contexto concreto que la justifica: producto, equipo, superficie.
3. Aporta un dato, no una opinión.
4. Declara cuándo cambiaría de opinión, que es la marca del criterio frente al dogma.
5. Demuestra que conoces la alternativa con números propios.

Y la variante honesta si no has hecho esa comparación: no la inventes. Di lo que sí puedes defender: «Fue una decisión por el contexto —un producto con mucha lógica de dominio y una persona—, y conozco React lo suficiente para saber que con un equipo de tres o con quince pantallas la balanza se invertiría. Lo que no puedo darte son números propios de la comparación; me quedé en el razonamiento.» Eso es infinitamente mejor que fingir.

El mismo esquema sirve para cualquier «¿por qué no X?»: TypeScript, Tailwind, una base de datos concreta. Contexto → decisión → dato → cuándo cambiaría.

Hay tres formas de hablar de un defecto de tu proyecto, y solo una funciona:

La fórmula de tres partes, que funciona siempre:

Tres ejemplos aplicados:

Limitación por decisión de alcance:

«No hay vista de calendario. La descarté del MVP porque la lista ordenada por fecha cubría la necesidad principal y el calendario eran doce horas para algo secundario. Está en la hoja de ruta como v1.1, y el modelo ya lo soporta: solo falta la vista.»

Limitación técnica reconocida:

«Con más de dos mil tareas el rendimiento se degradaría: mi línea base está medida con quinientas. Lo sé porque medí, no porque lo suponga. La solución sería virtualizar la lista, y la vista ya separa render de actualización precisamente para poder hacerlo sin reescribir nada.»

Algo que harías distinto:

«Empecé a escribir la vista antes de tener el dominio cerrado y perdí dos días rehaciendo. En cuanto lo reordené —dominio primero, luego una rebanada vertical— el ritmo cambió completamente. Es lo primero que haría distinto.»

Los tres ejemplos comparten lo mismo: son concretos, tienen dato o razón, y terminan en una acción. Ninguno pide perdón, y ninguno oculta nada.

Un matiz sobre las limitaciones del README, porque suele preocupar: declararlas no hace tu proyecto peor a ojos de quien lo evalúa. Hace lo contrario. Un proyecto sin limitaciones declaradas transmite una de dos cosas: o no las has buscado, o las escondes. Las dos son peores que tener limitaciones.

Es una de las preguntas más frecuentes en entrevistas técnicas, y la mejor oportunidad que tienes para demostrar cómo piensas en lugar de qué sabes.

El formato SAR —situación, acción, resultado— estructura la respuesta:

El error clásico es dedicar el 80 % a la situación («era muy raro, no había forma de…») y el 20 % a la acción. Justo al revés: la acción es lo que evalúan.

Un ejemplo completo, con el fallo de la condición de carrera de 11-04:

Situación. «Con la red lenta, a veces —no siempre— al marcar una tarea como hecha, volvía a aparecer como pendiente un segundo después. En mi máquina no pasaba nunca, y no había ningún error en consola.»

Acción. «Lo primero fue no tocar nada hasta poder reproducirlo a voluntad, porque un fallo intermitente no se puede depurar. Estrangulé la red y salía una de cada tres veces, que seguía sin bastar, así que envolví fetch para retrasar tres segundos solo las peticiones PUT. Con eso pasaba siempre.

Con la secuencia delante vi que había dos operaciones asíncronas: el PUT optimista, que tardaba tres segundos, y un refresco de la lista que se lanzaba medio segundo después y llegaba antes. El refresco sustituía la lista entera con datos que el servidor había generado antes de mi cambio.

Escribí primero la prueba que fallaba, con temporizadores falsos para controlar el orden exacto, y solo entonces toqué el código. Evalué tres soluciones: bloquear los refrescos mientras hubiera envíos en vuelo —frágil—, versionar cada tarea y descartar lo antiguo —lo más robusto pero dependía de la API—, y fusionar respetando los identificadores pendientes. Elegí la tercera.»

Resultado. «El fallo desapareció y la prueba se quedó en la suite como regresión. Lo que aprendí y aplico desde entonces son dos cosas: que un fallo intermitente casi siempre es una carrera entre dos operaciones asíncronas, y que cualquier código que sustituye un estado entero es sospechoso, porque descarta información que puede ser más reciente. Revisé el resto de la aplicación buscando ese patrón y encontré otro sitio igual.»

Los seis elementos que hacen buena esta respuesta:

1. Síntoma concreto, con el detalle de que era intermitente.
2. Reproducir primero, dicho explícitamente como principio.
3. Una técnica concreta: retrasar solo un tipo de petición.
4. La prueba antes de la corrección.
5. Alternativas evaluadas, con el criterio de elección.
6. Un aprendizaje generalizable, aplicado después. Este es el que más peso tiene.

Prepara dos historias antes de cualquier entrevista: una de un fallo técnico difícil y otra de una decisión de diseño complicada. Escríbelas, crónometralas en dos minutos, y ensáyalas en voz alta. No es hacer trampa: es no depender de la memoria bajo presión.

Antes de enseñar el proyecto, evalúate tú. Con honestidad, porque el objetivo no es la nota: es saber qué dirás cuando te pregunten por lo peor.

Ocho dimensiones, 0 a 4 puntos cada una. Máximo 32.

La regla del equilibrio, que importa más que el total: es mejor un 3 en las ocho dimensiones (24) que un 4 en cuatro y un 0 en otras cuatro (16… o incluso 32 mal repartido). Un proyecto brillante sin pruebas ni accesibilidad transmite un perfil desequilibrado; un proyecto sólido en todo transmite alguien con quien se puede trabajar.

La pregunta obligatoria de la autoevaluación, y la más útil de todas:

¿Cuál es tu dimensión más baja, y qué dirías si te preguntan por ella?

Prepara esa respuesta con la fórmula del apartado 13. Te la van a pedir, y tenerla lista es la diferencia entre parecer consciente y parecer pillado.

Antes de publicar, revisa tu propio código como si fuera de otra persona. Es incómodo y encuentra cosas.

El procedimiento que hace posible el cambio de perspectiva:

1. Deja pasar tiempo. Un día como mínimo. Tu cerebro rellena huecos en el código reciente.
2. Lee el diff completo del proyecto en la interfaz web de GitHub, no en tu editor. El cambio de contexto visual funciona sorprendentemente bien.
3. Ve fichero por fichero, de abajo hacia arriba de la arquitectura: dominio, datos, aplicación, vista.
4. Anota, no arregles. Primero la lista completa; después las correcciones. Si arreglas mientras lees, pierdes el hilo y la perspectiva.
5. Clasifica lo anotado en tres cajas: arreglar ahora, arreglar después (a la hoja de ruta), y aceptar (con su porqué anotado).

La lista de comprobación completa:

Los puntos 12 y 13 se comprueban siempre antes de publicar un repositorio, sin excepción.

Tu revisión tiene un límite infranqueable: no puedes ver lo que no sabes que existe. Para eso hacen falta otros ojos.

Dónde pedirla, con expectativas realistas:

Cómo pedir una revisión que sirva. Las peticiones vagas obtienen respuestas vagas:

Añade siempre: qué es el proyecto en una frase, qué has intentado, y qué pregunta concreta tienes. Y enlaza a un fichero, no al repositorio entero.

Cómo recibir la crítica, que es la parte difícil:

Y la regla que más ayuda: una crítica a tu código no es una crítica a ti. Es difícil de sentir así al principio, y se aprende con la práctica. El atajo mental que funciona: la persona que señala un fallo en tu código te está regalando información que no tenías. Es la reacción de gratitud, no la de defensa, la que hace que te vuelvan a revisar.

Y no todas las críticas se aceptan. «Deberías usar React» sin conocer tu contexto no es una crítica accionable. Escucha, valora, y si no aplica, agradece y sigue. Aceptar todo lo que te dicen es tan malo como no aceptar nada.

Antes de hacer público el repositorio, una revisión final:

El punto 1 tiene un matiz que sorprende a mucha gente: borrar un secreto en un commit posterior no lo elimina del historial. Sigue ahí, accesible con git log -p. Si alguna vez confirmaste uno, la única respuesta correcta es rotarlo (cambiar la clave en el servicio); reescribir el historial es opcional y no basta por sí solo.

El historial limpio. Un git log legible es una señal de profesionalidad que quien revisa mira más de lo que crees:

Si tu historial es un desastre, tienes tres opciones honestas: dejarlo y aprender para el siguiente (perfectamente aceptable), limpiar solo lo más reciente, o empezar un repositorio nuevo con un historial cuidado si estás al principio. Lo que no hay que hacer es reescribir el historial de una rama compartida.

La licencia, con lo que hay que saber:

Ese último punto sorprende a mucha gente: un repositorio público sin licencia no es de dominio público. Por defecto, se aplican todos los derechos de autor, y nadie puede copiarlo, modificarlo ni usarlo legalmente. Si quieres que tu proyecto sirva de portafolio y que alguien pueda inspirarse en él, añade una licencia.

Y dos avisos:

• Comprueba las licencias de tus dependencias. La mayoría son MIT o similares y no dan problema, pero conviene mirarlo (npx license-checker --summary).
• Nada de esto es asesoramiento legal. Para un proyecto personal de portafolio, MIT es una elección segura y habitual. Para un producto comercial, consulta.

Tu proyecto tiene que aparecer donde la gente lo busque:

En el currículum, el formato que funciona:

Qué hace bueno ese bloque: hay números concretos (15 reglas, 251 pruebas, 96 %), hay conceptos que demuestran nivel (arquitectura por capas, presupuesto en CI, idempotencia), y hay enlaces. No hay adjetivos vacíos: ni «robusto», ni «escalable», ni «moderno».

Un proyecto bien contado vale más que tres a medias. Si tienes varios, elige el mejor, cuéntalo entero, y menciona los demás en una línea.

Aquí está la diferencia entre un ejercicio y un producto: el ejercicio se entrega y se acaba; el producto tiene una versión siguiente.

Cómo conseguir comentarios reales, que es lo más valioso y lo que menos se hace:

La técnica de observar a alguien usarlo merece detalle porque es brutalmente eficaz y casi nadie la aplica: le das una tarea («crea una tarea con dos subtareas y averigua quién está más cargado esta semana»), te callas, y observas. La regla es no ayudar nunca. Cada vez que sientas el impulso de decir «tienes que pulsar ahí», eso es un fallo de diseño que acabas de encontrar. Con tres personas descubres el 80 % de los problemas de usabilidad.

Cómo priorizar lo que llega. No todo se hace, y decidir es la habilidad:

Con un filtro previo de tres preguntas para cada petición:

1. ¿Cuántas personas lo han pedido? Una petición apasionada de una persona no es una tendencia.
2. ¿Encaja con la frase del producto (11-01)? Si no, probablemente sea otro producto.
3. ¿Qué se rompe si lo hago? Toda funcionalidad nueva añade superficie que mantener.

Planificar la versión siguiente es repetir el ciclo de 11-01 en pequeño: escoge tres o cuatro cosas, escríbelas como historias con criterios, estima con tu factor de corrección ya calibrado por el proyecto anterior —que ahora es real y no una suposición—, y ponte una fecha.

Y una nota sobre cuándo parar. No todos los proyectos deben continuar eternamente. Un proyecto puede estar terminado en el sentido de que cumple lo que prometía. Si decides no seguir, dilo en el README:

Eso es mucho más honesto que un repositorio con la última actividad hace dos años y una hoja de ruta llena de casillas sin marcar.

Un README que empieza por la instalación. A quien llega no le interesa instalar nada hasta que sepa qué es y para qué sirve. Nombre, frase, imagen, demo, problema — y luego lo demás.

No poner ninguna imagen. Es el fallo más caro del README, porque el 90 % de la gente que lo abre mira si hay imagen antes de leer una palabra. Un GIF de doce segundos vale más que tres párrafos.

Listar tecnologías en lugar de decir qué hace el producto. «React, Redux, Tailwind, Vite» no dice si es un gestor de tareas o un juego. Las tecnologías van en la sección de decisiones, con su porqué.

Ocultar las limitaciones. Se descubren solas, y entonces parece que ocultabas. Declararlas es lo que más credibilidad da, y es lo que casi nadie hace.

Documentar el qué en lugar del porqué. Un comentario que repite lo que el código dice es ruido que además se desactualiza. El porqué, las alternativas descartadas y el contexto son lo único que el código no puede contarte.

Una demostración que es un recorrido por botones. Sin problema al principio, no hay tensión narrativa y nadie recuerda nada. Problema, solución, un flujo completo, un detalle técnico, limitaciones.

Demostrar con datos de prueba. «Tarea 1», «asdf», «prueba prueba» hacen que tu producto parezca un ejercicio de clase. Prepara un conjunto verosímil y ficticio.

No ensayar la demostración. Se tarda un 30–50 % más de lo que uno cree, y sin ensayo se llega al minuto cinco por la mitad. Tres pasadas en voz alta con cronómetro.

Responder «no sé React» a «¿por qué no usaste React?». Convierte una decisión en una limitación. Contexto, decisión, dato, y cuándo cambiarías de opinión.

Pedir perdón por tu proyecto. «Está un poco feo», «no me dio tiempo». Resta, no aporta, e invita a mirar justo donde no quieres. Las limitaciones van enmarcadas, no disculpadas.

Publicar sin revisar el historial. Un secreto confirmado hace tres meses sigue accesible con git log -p. Si ocurrió, la respuesta es rotar la clave, no solo borrarla.

Publicar sin licencia. Un repositorio público sin licencia no puede ser usado legalmente por nadie. Si es portafolio, MIT y listo.

Consejo · Escribe el README como si fuera para alguien con prisa y sin contexto. Porque lo es. Frases cortas, tablas, listas, y lo importante arriba.

Consejo · Guarda el GIF y las capturas en el repositorio, en docs/imagenes/. Los servicios externos de imágenes caducan y dejan huecos en tu README dentro de dos años.

Consejo · Escribe los ADR el mismo día que tomas la decisión. Reconstruir el razonamiento un mes después es imposible: recordarás la conclusión, no las alternativas ni el porqué.

Consejo · Ensaya la demostración grabándote. Es incómodo verse, y es la forma más rápida de detectar muletillas, prisas y las partes donde te pierdes.

Consejo · Ten preparadas dos historias, un bug difícil y una decisión de diseño, escritas y cronometradas en dos minutos. Te las van a pedir, y no querrás improvisarlas.

Estos ejercicios cierran el hito H6 de tu proyecto: README, ADR, guion de demostración y autoevaluación cumplimentada.

Ejercicio 1 — El README y los ADR.

1. Escribe el README.md completo con la plantilla del apartado 3, adaptada a tu proyecto: identidad con insignias, imagen, demo, problema, funcionalidades, tabla de decisiones técnicas con enlaces a ADR, ejecución, pruebas con números reales, arquitectura, limitaciones conocidas, tabla de rendimiento con metodología, hoja de ruta y licencia.
2. Graba un GIF de 10–15 segundos del flujo principal cumpliendo las siete reglas del apartado 4, guardado en el repositorio, de menos de 3 MB.
3. Prepara los datos de demostración con los siete elementos de la tabla del apartado 10, todos ficticios, y añade el modo demo o la semilla automática.
4. Escribe al menos cinco ADR con la plantilla completa del apartado 6, con sus cinco secciones —incluidas las consecuencias negativas y el «cuándo revisar»— y con al menos dos alternativas evaluadas en cada uno.
5. Haz la prueba de los dos minutos: dale el README a alguien que no conozca el proyecto, cronometra, y pídele que responda las cuatro preguntas. Anota qué no supo contestar y corrige el README.

Ejercicio 2 — La demostración y las respuestas de entrevista.

1. Escribe el guion de cinco minutos con la estructura de cinco pasos, con los tiempos anotados y lo que dirás en cada uno.
2. Ensáyalo tres veces en voz alta con cronómetro y ajústalo hasta caber en cinco minutos con margen.
3. Grábate haciéndolo y revísalo. Anota tres cosas a mejorar.
4. Prepara el plan B completo: la tabla de seis situaciones adaptada a tu contexto, más una grabación de 90 segundos del flujo principal como último recurso.
5. Escribe y ensaya las respuestas a estas seis preguntas, cada una en menos de dos minutos:
   • «Háblame de este proyecto» (estructura de cinco pasos del apartado 11).
   • «¿Por qué no usaste React?» (o el framework que corresponda), con contexto, decisión, dato y cuándo cambiarías de opinión.
   • «¿Qué es lo peor de tu proyecto?» (fórmula de tres partes del apartado 13).
   • «Cuéntame un bug difícil» (formato SAR, con aprendizaje generalizable).
   • «¿Cómo escalaría a 10.000 elementos?» (empezando por medir).
   • «¿Qué harías distinto?» (concreto y técnico).

Ejercicio 3 — Autoevaluación, revisión y publicación.

1. Cumplimenta la rúbrica de ocho dimensiones del apartado 15, con una justificación de una frase por cada puntuación. Nada de puntuarte de memoria: abre el proyecto y compruébalo.
2. Identifica tus dos dimensiones más bajas y escribe un plan concreto para subirlas, con el esfuerzo estimado.
3. Prepara la respuesta a «¿cuál es tu punto más débil?» con la fórmula de tres partes.
4. Haz la revisión de código a ti mismo con las 16 comprobaciones del apartado 16, dejando pasar al menos un día. Documenta los hallazgos clasificados en las tres cajas: arreglar ahora, después, y aceptar con su porqué.
5. Pide una revisión externa con una pregunta concreta sobre una parte concreta. Documenta qué te dijeron, qué aceptaste y qué descartaste con su razón.
6. Haz que al menos una persona use tu aplicación mientras la observas, sin ayudar. Anota cada momento de duda: cada uno es un fallo de diseño.
7. Ejecuta las 10 comprobaciones previas a la publicación del apartado 18, incluida la del historial de Git. Añade licencia, descripción, temas y enlace a la demo.
8. Añádelo a tu portafolio: repositorio fijado, README del perfil, y el bloque de currículum con números concretos.
9. Planifica la versión siguiente: tres o cuatro mejoras priorizadas con la matriz impacto/esfuerzo, escritas como historias con criterios, y con fecha.

Rúbrica del ejercicio 1 — README y ADR (24 puntos)

Umbral: 17/24, con obligatoriamente ≥ 2 en «Prueba de los dos minutos» y en «ADR: calidad».

Criterios de aceptación del ejercicio 1

Criterios de aceptación del ejercicio 2 — Demostración

Rúbrica del ejercicio 3 — Revisión y publicación (21 puntos)

Umbral: 14/21. Con una condición que no se compensa: cero secretos y cero datos personales reales, ni en el código ni en el historial ni en las capturas.

La autoevaluación final del proyecto. Antes de dar el hito por cerrado:

Has convertido un proyecto que funcionaba en un proyecto que se puede enseñar, defender y mejorar — y esa diferencia vale tanto como el código.

Sabes por qué presentar es parte del trabajo: porque nadie va a leer 4.000 líneas para descubrir lo que hiciste bien, porque quien te evalúa tiene entre 90 segundos y 15 minutos, y porque explicar decisiones es una habilidad profesional de primer orden con la que se topa cualquiera que construya bien y no sepa contarlo.

Tienes un README que pasa la prueba de los dos minutos, con el orden de interés decreciente que funciona: identidad, imagen, demo, problema, funcionalidades, decisiones técnicas —la sección que te diferencia de otros diez proyectos iguales— y limitaciones conocidas, que es la sección que más credibilidad da y que casi nadie escribe. Con insignias que comunican en dos segundos, con la tabla de rendimiento acompañada de su metodología, y con instrucciones que funcionan copiadas y pegadas. Y con un GIF que cumple las siete reglas, porque la imagen es lo primero que se mira y lo que menos cuidado suele recibir.

Tienes ADR para las cinco decisiones que lo merecen, con las cinco secciones obligatorias —contexto, alternativas evaluadas, decisión, consecuencias incluidas las negativas, y cuándo revisarla— y sabes por qué el porqué vale más que el qué: el código dice qué se hizo, los nombres y las pruebas dicen cómo, pero solo un ADR dice por qué no se hizo de la otra forma. Esa es la información más valiosa y la que más rápido se pierde, y sin ella quien llegue después gastará una semana en llegar a tu misma conclusión.

Tienes una demostración de cinco minutos con estructura de historia en lugar de recorrido por botones: problema, solución, un flujo completo, un detalle técnico contado bien, y limitaciones con hoja de ruta. Con las cinco reglas de ejecución —ensayar tres veces con cronómetro, no leer, no enseñar código salvo que lo pidan, no pedir perdón por nada, y terminar con lo siguiente—, con datos ficticios y verosímiles que contienen los siete elementos que hacen que el producto se explique solo, y con un plan B para seis situaciones más una grabación de 90 segundos que es el seguro más barato que existe.

Sabes hablar del proyecto en una entrevista entendiendo qué se evalúa de verdad: no cuántas tecnologías usaste sino por qué; no si es grande sino si está terminado; no si es perfecto sino si conoces sus defectos. Tienes la estructura de cinco pasos que termina en un gancho —«si quieres te enseño…»— que convierte un monólogo en conversación. Y tienes preparada la pregunta que te van a hacer seguro, «¿por qué no usaste React?», con las tres peores respuestas identificadas y una buena construida sobre contexto, decisión, un dato propio y —lo que separa el criterio del dogma— cuándo cambiarías de opinión. Con la variante honesta para cuando no tienes el dato, porque inventarlo siempre sale peor.

Sabes reconocer una limitación sin sonar inseguro con la fórmula de tres partes —qué falta, por qué está así, qué harías— que convierte un defecto en una demostración de criterio. Y sabes contar un bug difícil con el formato SAR dedicando la mitad a la acción y no a lo raro que era, con los seis elementos que la hacen buena y, sobre todo, con un aprendizaje generalizable que aplicaste después.

Te has autoevaluado con una rúbrica de ocho dimensiones y 32 puntos, sabiendo que el equilibrio importa más que el total —un 3 en las ocho vale más que un 4 en cuatro y un 0 en el resto— y con la pregunta obligatoria contestada: cuál es tu dimensión más baja y qué dirás cuando te pregunten por ella.

Sabes revisarte el código a ti mismo con distancia, en la interfaz web, de abajo hacia arriba de la arquitectura, anotando antes de arreglar y clasificando en tres cajas. Y sabes buscar revisión externa con peticiones concretas en lugar de vagas, y recibir la crítica con la regla que lo cambia todo: quien señala un fallo en tu código te está regalando información que no tenías. Con el matiz de que no todas las críticas se aceptan, y que aceptar todo es tan malo como no aceptar nada.

Sabes publicar con las diez comprobaciones previas, incluida la que sorprende —que borrar un secreto no lo quita del historial, y que la única respuesta correcta es rotar la clave—, con un historial legible, y con licencia, porque un repositorio público sin licencia no lo puede usar nadie legalmente. Y sabes ponerlo en el portafolio con números concretos y sin adjetivos vacíos.

Y sabes iterar después de la entrega, que es la diferencia entre un ejercicio y un producto: observar a alguien usarlo sin ayudar nunca —cada impulso de ayudar es un fallo de diseño encontrado—, priorizar con la matriz de impacto y esfuerzo y las tres preguntas de filtro, y planificar la versión siguiente repitiendo el ciclo de 11-01 con un factor de estimación que ya no es una suposición sino un dato de tu propio proyecto. O declarar honestamente que está terminado, que también es una respuesta válida y mucho mejor que una hoja de ruta abandonada.

El hito H6 está cerrado, y con él el proyecto: planificado, construido, persistido, probado, desplegado, documentado y defendible. Queda una sola lección, y no es de proyecto: es el balance de todo lo que sabes ahora, el mapa de lo que viene después —TypeScript, Node.js, un framework en profundidad, la plataforma web, la carrera— y cómo se sigue aprendiendo cuando ya no hay un curso que te diga qué toca. Es Siguientes Pasos: TypeScript, Node.js y tu Carrera.