guiar-tdd
(Repo back · desarrollo) Gobernar el ciclo TDD Red-Green-Refactor sobre la lista "Tests a escribir PRIMERO" que dejó la Tarea del tablero: primero el test que falla (rojo), después el código mínimo qu
SKILL.mdback/.claude/skills/guiar-tdd/SKILL.md
GitHubGuiar TDD (backend)
Hace cumplir el orden test-first sobre la lista de tests que la Tarea del tablero ya trae cerrada. No escribe la solución: es el árbitro del ciclo.
Regla de oro
- Rojo antes que verde, siempre. No se escribe código de producción sin un test que falle primero, y que falle por la razón correcta.
- Código sin test = revertir. Si aparece implementación sin su test previo, se vuelve al último estado en rojo.
- Un test por ítem de la lista "Tests a escribir PRIMERO" de la Tarea; no se
inventan casos fuera de esa lista (si falta uno, no se inventa: se anota como pendiente a
confirmar en el resumen final, para la tarjeta). Si un ítem enumera dos comportamientos del mismo
contrato, van como dos aserciones en el mismo test (un solo
test(rojo): <n>), no se parte el ítem ni se inventa un segundo número; si son de contratos distintos, se anota como pendiente («el ítem n son dos»). Un caso que los «Modos de falla» atribuyen al ítem n sin que el ítem lo enumere no se agrega: se anota. - Un ítem «Esquema» (la misma condición con varias filas de datos) se escribe como un
test parametrizado con una fila por cada fila del ítem, ni una más ni una menos, cada una
con su resultado esperado; su
test(rojo)es uno solo. Cada ítem se lee junto con el párrafo «Datos base» de la lista, si lo hay. - No inventar comportamiento. El qué probar sale del contrato OpenAPI y los
[RN-…]de la Tarea, no del criterio del que codea. - Modo de pruebas declarado. Si la Tarea declara
test-despuésosin testscon motivo (esqueleto, configuración, migración, UI puramente visual, spike), el árbitro no exige el rojo por ítem pero sí la red mínima que ese modo pide (vertdd-ciclo-y-evidencia.md§«Cuándo TDD»). Sin motivo escrito, es TDD. - Español (Argentina).
Flujo (por cada ítem de la lista de la Tarea)
- Red: escribir el test (con el runner de tests del repo); correrlo y verificar que FALLA por la razón esperada.
- Green: el código mínimo que lo hace pasar. Nada de más.
- Refactor: limpiar con los tests en verde.
- Repetir hasta agotar la lista. Al terminar, cada test de la Tarea tiene su caso.
Evidencia del rojo (obligatoria)
El ciclo no vale por declaración: hay que dejar prueba de que el test falló antes de que existiera la solución.
- Al cerrar el paso Red, se guarda la salida del runner mostrando el test fallando: las 1 a 3 líneas de la aserción, en el
cuerpo del commit
test(rojo)(no en un archivo: ahí viaja con la evidencia y no se puede fabricar después). - Un rojo válido falla en su aserción. Si falla por error de compilación, import roto o configuración, NO cuenta como rojo: hay que llegar a la aserción y fallar ahí.
- Recién con esa evidencia se escribe el código del paso Green.
- Cada evidencia queda asociada a su ítem de la lista "Tests a escribir PRIMERO".
- Quien escribe el código NO aprueba su propia evidencia. Esa auditoría la hace
verificar-tdd, en una pasada separada.
Test de integración (si la Tarea lo pide)
La Tarea declara "Requiere test de integración: sí/no". Si dice sí (toca una dependencia externa: un sistema externo, una base de datos, una cola), además del ciclo unitario va un test de integración que ejercita esa dependencia real o su doble controlado. El orden no cambia: primero el test de integración en rojo, después el código.
Entrada / Salida
- Entrada: la Tarea del tablero: contrato OpenAPI + tabla de «Especificación cerrada (SDD)»
(qué Escenarios de la Historia padre cubre esta Tarea y qué test verifica cada uno) +
el cuerpo del Gherkin de esos Escenarios (los
Dado/Cuando/Entonces/Y, no solo el título: un Escenario suele tener varios pasos observables y la tabla solo trae uno por fila — sin el cuerpo no se puede saber si el test cubre el Escenario entero o un pedazo) + lista numerada de tests test-first. - Salida: tests + código, con trazabilidad 1:1 contra la lista de la Tarea, y cada test nombrado de forma que se vea a qué Escenario responde (el número de test que la tabla SDD le asignó). Así el que audita puede ir del Escenario al test sin adivinar.
Para qué sirve la tabla SDD mientras codeás. La lista de tests dice qué probar; la tabla dice para qué — qué comportamiento de negocio, escrito en el Gherkin de la Historia, queda cubierto cuando ese test se pone verde. Cuando un ítem de la lista es ambiguo, la respuesta está en el Escenario al que la tabla lo asocia. Si la tabla dice que esta Tarea cubre solo parte de un Escenario, no implementes la otra parte: es de la Tarea complementaria que la tabla nombra. Si la Tarea no trae la tabla, avisá: no pasó el DoR y vas a estar adivinando el porqué.
Cómo se deja la evidencia del rojo (obligatorio)
Un commit por paso rojo, antes del código que lo pone en verde:
test(rojo): 3 recurso ya no disponible -> 409 RECURSO_NO_DISPONIBLE
Ese commit lleva solo el test, nada de producción. Después va el commit de la
implementación. verificar-tdd lo audita con git log: si el test no precede a su
implementación, el rojo no existió.
Por qué así y no pegando la salida del runner en un archivo: un texto pegado es indistinguible de uno fabricado. Comentar la implementación, correr el runner, pegar el rojo y descomentar produce exactamente el mismo artefacto que hacer TDD de verdad. El orden de los commits, en cambio, es un dato del repo que no se escribe desde el chat.
Los tests declarados guardarraíl no llevan commit de rojo — nacen verdes a propósito.
Dos casos que el método blanquea (si no, el agente improvisa): (a) cuando la clase o la función todavía no
existe, el rojo falla por import y no en la aserción; entonces va antes un commit chore(firma): … con sólo
las firmas vacías (sin comportamiento), y recién después el test(rojo); verificar-tdd.py lo reconoce y no lo
cuenta como producción antes del rojo. (b) Si un ítem nace verde porque el verde mínimo de otro ya lo cubre, no
se rompe el otro a propósito: se commitea test(verde-de-entrada): <n> … con sólo el test y se anota como
pendiente a confirmar (¿la Tarea debía declararlo guardarraíl?); el verificador lo da por cumplido sin rojo.
- Si una firma nueva rompe la compilación de un test que ya existía (un tipo que ganó un campo obligatorio, una
función que cambió de forma), su ajuste mínimo va en el mismo
chore(firma): es la consecuencia del cambio de forma, no un test nuevo. Cualquier otro cambio a un test existente es un rojo propio, con su committest(rojo).
Van en su propio commit test(guardarrail): … para que se vea que la excepción es
deliberada y no un rojo que faltó.
Estos commits son de trabajo y no van al Merge Request: no los pushees vos. Después de la
verificación, y con la aprobación del humano, la rama se reorganiza por importancia, uno
por cambio lógico (alrededor de 10 commits, como guía), y el historial de trabajo queda en la
rama evidencia/<ID>, que se sube a origin como respaldo, sin Merge Request (orquestador-desarrollo §«Commits: de trabajo, y pocos en el Merge
Request»).
Barreras
- No genera la solución "de una"; sin test en rojo no hay código de producción.
- Si la Tarea no trae contrato o lista de tests, se frena: no pasó el DoR. Si están pero
les falta algo puntual (un dato, un caso, una decisión
⚠), no se inventa ni se frena: se hace lo que no depende de eso y se devuelve como pendiente a confirmar, que queda en la tarjeta. Si hace falta contexto de negocio, se usaconsultar-cerebro.