Versión: 1.0
Fecha: 2026-06-10
Clasificación: Interno — Apoyo al equipo de desarrollo
Naturaleza: Guía de acompañamiento. No es una evaluación, no es un control, no es una camisa de fuerza.
Cómo leer este documento. No tienes que memorizarlo. Tenlo abierto al lado mientras trabajas una HT y úsalo como un mapa: te dice dónde estás, qué sigue, y cuándo puedes avanzar tranquilo. Si solo te llevas una idea de aquí, que sea esta: no tienes que resolver todo a la vez; solo el siguiente paso.
Si estás leyendo esto, probablemente has sentido en algún momento que la cantidad de cosas por hacer es más grande que tú. Que cada HT trae reglas, validaciones, contratos, casos de prueba, y que es fácil perder el hilo y terminar sintiendo que no avanzas o que generas más problemas de los que resuelves.
Queremos decirte tres cosas, con honestidad:
Este documento no existe para vigilarte. Existe para que dejes de cargar solo el peso de "no saber por dónde empezar". A partir de aquí, siempre vas a saber por dónde empezar.
El error más común no es escribir mal el código. Es empezar a codificar antes de entender, y entregar antes de verificar. Entre esos dos extremos se cuela casi todo el reproceso.
La ruta parte la HT en 6 hitos (pasos). Cada hito tiene:
La regla de oro de toda la ruta:
┌───────────────────────────────────────────────────────────┐
│ Si una puerta no cierra, NO se salta. │
│ O la resuelves tú, o la ESCALAS con contexto. │
│ Nunca se deja "en el aire" ni se pasa cruda a otra persona.│
└───────────────────────────────────────────────────────────┘
¿Por qué puertas y no una lista gigante? Porque una lista de 40 cosas abruma. Seis puertas, no. Cada vez que cierras una, tu cabeza descansa: ese pedazo ya está, no tienes que volver a pensarlo. Eso es lo que reduce la ansiedad y, de paso, los errores.
Este es el camino completo de principio a fin. Imprímelo mentalmente: siempre estás en uno de estos seis puntos.
┌──────────────────────────────────────────────────────────────────────────┐
│ HT recibida (10 archivos) │
└──────────────────────────────────────────────────────────────────────────┘
│
┌────▼────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ H0 │─▶│ H1 │─▶│ H2 │─▶│ H3 │─▶│ H4 │─▶│ H5 │
│ENTENDER │ │PREPARAR │ │CONSTRUIR│ │ PROBAR │ │AUTO- │ │ENTREGAR │
│ │ │ │ │ │ │ │ │REVISIÓN │ │ │
│análisis │ │ el │ │desarrollo│ │funcional│ │integral │ │PR + doc │
│ │ │ terreno │ │ por capas│ │ │ │ │ │ │
└────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘
│ │ │ │ │ │
┌───▼───┐ ┌───▼───┐ ┌───▼───┐ ┌───▼───┐ ┌───▼───┐ ┌───▼───┐
│PUERTA │ │PUERTA │ │PUERTA │ │PUERTA │ │PUERTA │ │PUERTA │
│"lo sé │ │"la base│ │"compila│ │"todos │ │"yo │ │"un │
│ expli-│ │ está │ │ y │ │ los CP │ │ mismo │ │ tercero│
│ car" │ │ lista" │ │ arranca"│ │ pasan" │ │ lo │ │ lo │
│ │ │ │ │ │ │ │ │ rompí"│ │ entiende"│
└───────┘ └───────┘ └───────┘ └───────┘ └───────┘ └───────┘
Tiempo emocional aproximado de cada hito:
H0 calma y curiosidad · H2 concentración · H3-H4 donde aparece la
tentación de "ya casi, lo entrego" — JUSTO AHÍ es donde se gana la calidad.
La HT no es un PDF que se lee de corrido. Es un kit de 10 piezas, y cada pieza tiene un momento. Esta tabla es tu "traductor": cuando estés en un hito, sabes exactamente qué abrir.
LA HT (10 archivos) ¿EN QUÉ HITO LO USAS?
──────────────────────── ──────────────────────
README.md ............................ H0 (visión general)
01_Model.md .......................... H0 + H2 (qué construir)
02_Data.md ........................... H1 (base de datos / migración)
03_Rules.md .......................... H0 + H4 (reglas a cumplir y revisar)
04_References.md ..................... H0 (qué se reusa, decisiones)
05_Checklist.md ...................... referencia (calidad de la HT)
06_Delivery.md ....................... H1 + H2 + H5 (orden, precondiciones, handoff)
07_TestCases.md ...................... H3 (los casos de prueba)
08_Contracts.md ...................... H0 + H4 (los endpoints exactos)
09_Simulator.md ...................... H3 (escenarios de apoyo)
10_TraceMatrix.md .................... H4 (trazabilidad: nada se quedó por fuera)
Nota tranquilizadora: no tienes que entender los 10 archivos el primer día. En H0 lees cinco. El resto los abres cuando el hito te lo pide. Pieza por pieza.
Cada hito trae tres cosas: qué haces (lo técnico), la puerta (cuándo avanzas) y una nota de apoyo (qué vas a sentir y cómo manejarlo). Léelas todas; la nota de apoyo no es relleno, es parte del método.
Qué haces
README.md → 01_Model.md → 03_Rules.md → 07_TestCases.md → 08_Contracts.md.ERR-XXX) y las reglas (RN-ALC...) que vas a tener que cumplir. Esa lista es tu "lista de cosas que no se me pueden olvidar".La puerta
┌─────────────────────────────────────────────────────────┐
│ ¿Podría explicarle esta HT a un compañero en 2 minutos │
│ sin volver a abrir el documento? │
│ │
│ SÍ → avanza a H1. NO → reléela. No es perder tiempo.│
└─────────────────────────────────────────────────────────┘
Nota de apoyo. Aquí vas a sentir la tentación de "ya entendí más o menos, arranco a codificar". Es la trampa más cara de todas. Cada minuto que inviertes entendiendo aquí te ahorra horas de reproceso después. Entender no es la antesala del trabajo: es trabajo, y del más importante.
Qué haces
02_Data.md y aplica la migración (recuerda SET SQLBLANKLINES ON antes del script).06_Delivery.md, sección de precondiciones de despliegue. Verifica: ¿existen ya las tablas que vas a reusar? ¿están mergeadas las ramas de las que depende esta HT?La puerta
┌─────────────────────────────────────────────────────────┐
│ ¿La migración corrió sin error y todo lo que voy a │
│ reusar ya existe y está disponible? │
│ │
│ SÍ → avanza a H2. │
│ NO → ESCALA. Construir encima de algo ausente es │
│ garantía de reproceso. │
└─────────────────────────────────────────────────────────┘
Nota de apoyo. Detectar a tiempo que "falta una dependencia" y avisarlo no es un problema tuyo: es un acierto tuyo. Es exactamente el tipo de cosa que un buen desarrollador ve antes que los demás. Escalar aquí te hace ver más profesional, no menos.
Qué haces
06_Delivery.md, sección "Orden de implementación", y síguelo literal. Normalmente es: migración → entity/repository → DTOs/records → validators → component → service → controller.01_Model.md para las firmas exactas (entities, records, métodos).La puerta
┌─────────────────────────────────────────────────────────┐
│ ¿El proyecto compila y el servicio arranca sin tronar? │
│ │
│ SÍ → avanza a H3. │
│ NO → no apiles más código encima del error. Resuélvelo │
│ ahora, mientras es pequeño. │
└─────────────────────────────────────────────────────────┘
Nota de apoyo. Construir por capas se siente más lento al principio. No lo es. Lo que se siente rápido —escribir todo de un tirón y "después lo pruebo"— es lo que termina costando el doble. Ir capa por capa es como subir una escalera con pasamanos: más seguro, y al final, más rápido.
Qué haces
07_TestCases.md. Ejecuta cada caso de prueba (CP), uno por uno. No una muestra, no "los principales". Todos. Ve marcando cada uno como pasa o falla.ERR-XXX debe dispararse cuando corresponde. Provoca el error a propósito y confirma que el sistema responde como dice la regla.09_Simulator.md, úsalo para los escenarios complejos (lote, atomicidad, concurrencia).La puerta
┌─────────────────────────────────────────────────────────┐
│ ¿Pasan TODOS los CP, incluidos los de error y los de │
│ atomicidad/concurrencia? │
│ │
│ SÍ → avanza a H4. │
│ NO → un solo CP en rojo significa que el hito NO está │
│ cerrado. Todavía no es momento de entregar. │
└─────────────────────────────────────────────────────────┘
Nota de apoyo. Este es, con cariño y con honestidad, el hito donde más se ha perdido terreno históricamente. Probar solo el camino feliz da una falsa sensación de "ya quedó", y los errores aparecen después, en manos de otra persona — y ahí es donde nace la sensación de "yo soy la fuente de los problemas". No es que produzcas más errores que los demás: es que llegan a probarlos otros en vez de ti. Cambiar eso está 100% en tus manos, y es el cambio que más rápido va a transformar cómo te ven y cómo te sientes.
Este es el hito que separa a un desarrollador que "termina código" de uno en quien se confía. Antes de pedirle revisión a nadie, te pones el sombrero de la persona más exigente y tratas de tumbar tu propio trabajo.
Qué haces — recórrelo como una lista, sin saltarte líneas
03_Rules.md y ve regla por regla: ¿está implementada? ¿está probada? Las dos cosas, no una.08_Contracts.md y compara: ¿el endpoint real (ruta, verbo, request, response) coincide exactamente con el contrato? Sin diferencias "menores".10_TraceMatrix.md: ¿cada funcionalidad/regla/caso tiene su pieza técnica correspondiente? ¿Nada se quedó por fuera?La puerta
┌─────────────────────────────────────────────────────────┐
│ ¿Yo mismo intenté romper esto por todos lados y no │
│ encontré nada abierto? │
│ │
│ SÍ → avanza a H5 y pide revisión humana con la frente │
│ en alto. │
│ NO → arréglalo. Lo que encuentres aquí, nadie más lo │
│ sufrirá después. │
└─────────────────────────────────────────────────────────┘
Nota de apoyo. Cada cosa que tú encuentras aquí es una cosa que nadie tendrá que devolverte. Y cada vez que entregas algo que ya revisaste a fondo, construyes algo invisible pero valiosísimo: reputación de confiabilidad. Esa reputación es la que hace que, con el tiempo, te dejen de revisar tan de cerca y ganes la autonomía que quieres. La autonomía no se pide: se gana entregando cosas que no rebotan.
Qué haces
06_Delivery.md (vistas, endpoints, comportamiento esperado).La puerta
┌─────────────────────────────────────────────────────────┐
│ ¿Alguien que no conoce esta HT entendería mi PR solo │
│ leyéndolo? │
│ │
│ SÍ → entregado. Permítete reconocer que lo lograste. │
│ NO → mejora la descripción. Tu trabajo merece │
│ entenderse. │
└─────────────────────────────────────────────────────────┘
Nota de apoyo. Cierra el ciclo de verdad. Tómate cinco segundos para registrar que completaste algo de principio a fin, bien hecho. Ese pequeño reconocimiento no es vanidad: es lo que reconstruye la confianza, hito a hito. Lo lograste. El siguiente será más fácil.
Esto es lo que "te obliga" — pero de la forma amable: no es alguien vigilándote, eres tú dándote la tranquilidad de saber que no se te quedó nada. Copia este bloque a un archivo nuevo por cada HT que trabajes y ve marcando.
La única regla del checklist: una casilla que no puedas marcar no se borra y no se ignora. Se convierte en una pregunta concreta para quien te acompaña. Un checklist con un bloqueo escalado a tiempo vale más que uno todo marcado a la fuerza.
# Checklist de ejecución — HT_____________ (sprint: ____)
## H0 · ENTENDER [ ] CERRADO
- [ ] Leí README, 01_Model, 03_Rules, 07_TestCases, 08_Contracts
- [ ] Escribí el resumen de 3-5 frases con mis palabras
- [ ] Listé los ERR-XXX y las RN-ALC que debo cumplir
- [ ] Identifiqué qué reuso (no reinvento) de sprints previos
## H1 · PREPARAR [ ] CERRADO
- [ ] Migración aplicada sin error
- [ ] Precondiciones de 06_Delivery verificadas
- [ ] Bloqueos detectados y escalados: ________________________
## H2 · CONSTRUIR [ ] CERRADO
- [ ] Seguí el orden de implementación de 06_Delivery (capa por capa)
- [ ] Compila y el servicio arranca
## H3 · PROBAR [ ] CERRADO
- [ ] Ejecuté TODOS los CP de 07_TestCases (no una muestra)
- [ ] Probé cada camino de error (cada ERR-XXX dispara cuando toca)
- [ ] CP fallidos: ____ de ____ (debe ser 0 para cerrar)
## H4 · AUTO-REVISIÓN INTEGRAL [ ] CERRADO
- [ ] Recorrí 03_Rules una por una: todas implementadas Y probadas
- [ ] El endpoint real == 08_Contracts (ruta, verbo, request, response)
- [ ] i18n en español E inglés para toda clave nueva
- [ ] Revisé 10_TraceMatrix: nada se quedó por fuera
- [ ] Intenté ROMPERLO yo mismo (dos veces / vacío / nulo / concurrente)
## H5 · ENTREGAR [ ] CERRADO
- [ ] PR apunta a la HT y a los CP probados
- [ ] Handoff frontend dejado (si aplica)
- [ ] Cumple el Definition of Done del nivel
- [ ] Un tercero entendería mi PR sin contexto adicional
────────────────────────────────────────────────────────────────
Una frase sobre cómo me sentí en esta HT (para mí, opcional):
________________________________________________________________
Tu meta es ganar autonomía sin quedarte atascado en silencio, y sin pasarle a otra persona un problema crudo. Este semáforo te dice qué hacer en cada momento. No es para que sufras solo: es para que cuando pidas ayuda, la pidas bien.
┌────────────────────────────────────────────────────────────────┐
│ │
│ ● VERDE — Resuélvelo tú │
│ Lo entiendes, tienes por dónde, hay un patrón previo que │
│ puedes seguir. Adelante, confía. Esto es tuyo. │
│ │
│ ● AMARILLO — Intenta primero, luego escala con contexto │
│ No lo ves claro. Dale 30 minutos honestos. Anota qué │
│ probaste. Si sigue trabado, escala — pero ya con material. │
│ │
│ ● ROJO — Escala de inmediato (y está perfecto hacerlo) │
│ Es un bloqueo externo: falta una dependencia, una rama no │
│ está, una decisión no te corresponde a ti. No pierdas horas.│
│ Avisar a tiempo aquí es lo correcto, no lo débil. │
│ │
└────────────────────────────────────────────────────────────────┘
Cómo se escala bien (la fórmula que te hace ver profesional):
En vez de: "No me sale esto, ¿me ayudas?"
Di: "Estoy en [HT / hito]. Quiero lograr [X].
Intenté [A] y [B]. Pasó [C].
Mi hipótesis es [D]. ¿Voy por buen camino?"
La diferencia entre las dos frases es enorme. La primera traslada el problema entero a otra persona. La segunda muestra que ya trabajaste, que pensaste, y solo necesitas una validación o un empujón. Esa segunda frase es autonomía. Y se aprende practicándola, no naciendo con ella.
Aprender un método nuevo no es una línea recta hacia arriba. Tiene una bajada en el medio. Conocerla de antemano evita que la confundas con un fracaso.
Confianza
▲
│ "¡qué "ya confío
│ fácil, en mi
│ ya entendí!" método"
│ ● ___●
│ / \ ___/
│ / \ ___/
│ / \ ___/
│ / \ ___/
│ / \ ___/
│/ ●_______________ /
│ "uy, esto "ok, paso a paso
│ es más sí avanza"
│ de lo que
│ creía"
│ (EL VALLE — aquí NO te rindas)
└──────────────────────────────────────────────────────────▶ tiempo
semana 1 semanas 2-3 semana 4 en adelante
El valle del medio es obligatorio, no opcional. Todo el que aprende algo serio lo cruza. La sensación de "esto es más difícil de lo que pensé" no es la señal de que no puedes: es la señal de que estás aprendiendo de verdad y dejando atrás la etapa fácil. Quien se rinde, se rinde justo ahí, a un paso de la subida. Tú ya lo sabes ahora, así que no te va a sorprender.
El acompañamiento no es vigilancia. Es alguien caminando a tu lado mirando el mismo mapa que tú. Así lo hacemos:
| Ritual | Cada | Para qué | Quién lo lleva |
|---|---|---|---|
| Revisar el checklist de la HT en curso | En el 1:1 | Ver qué hitos cerraste y dónde hubo bloqueos | Tú lo muestras |
| Celebrar los hitos cerrados | Cada vez que cierras uno | Tu cabeza necesita el "esto ya está" | Tú mismo |
| Mini-retro personal (1 frase) | Al cerrar cada HT | ¿Qué me costó? ¿Qué hice mejor que la anterior? | Tú |
| Ajustar el método si algo no funciona | Cuando haga falta | Esta guía es viva: se adapta a ti, no al revés | Juntos |
Lo que medimos no es "cuántos errores tuviste". Es cuántos hitos cierras por ti mismo y con qué calidad llegas a la auto-revisión. Esa curva subiendo, sprint a sprint, es la única evidencia que importa. No buscamos perfección de un día para otro: buscamos una mejora visible y sostenida.
Cuando sientas que no avanzas, vuelve aquí.
1. No tengo que resolver todo. Solo el siguiente hito.
2. Entender no es perder tiempo. Es el trabajo más importante.
3. Probar a fondo hoy = no avergonzarme mañana.
4. Escalar con contexto es fortaleza, no debilidad.
5. El valle es parte del camino. No me rindo a un paso de la subida.
Y uno más, el más importante: no eres un lastre. Eres alguien que pidió ayuda para mejorar, y eso —en cualquier equipo, en cualquier empresa— es exactamente lo que hace la gente que termina creciendo. El solo hecho de querer un método ya te pone en el camino correcto. El resto es practicarlo, una HT a la vez.
| Versión | Fecha | Autor | Descripción |
|---|---|---|---|
| 1.0.0 | 2026-06-10 | Carlos Torres | Creación de la guía de acompañamiento técnico y personal — ruta de 6 hitos para trabajar una HT |