Notación
| Paso | Estándar | Cómo se ve |
|---|---|---|
| Por qué y alcance | Propuesta | work/changes/004-invoices/proposal.md |
| Requisito | EARS | ### invoices.R2 — Totals + When an invoice is saved, the BFF shall round its total to 3 decimals. |
| Aceptación | BDD / ATDD | #### invoices.R2.S3 — Rounding edge @boundary + Given / When / Then |
| Elegir casos | ZOMBIES | una etiqueta por escenario |
| Tests | Trazabilidad | it("invoices.R2.S3 rounds 0.0005 up") |
| Datos de prueba | ZOMBIES en los datos | -- @fixture invoices.R2.S3 @boundary |
| QA | Checklist | un ítem por escenario |
Los requisitos y escenarios se escriben en inglés: son la notación que revisa agent-kit specs lint.
Requisitos EARS
EARS (Easy Approach to Requirements Syntax) limita cada requisito a una frase con una de estas formas:
| Patrón | Plantilla |
|---|---|
| Ubicuo | The <system> shall <response>. |
| Evento | When <trigger>, the <system> shall <response>. |
| Estado | While <state>, the <system> shall <response>. |
| No deseado | If <condition>, then the <system> shall <response>. |
| Opcional | Where <feature>, the <system> shall <response>. |
| Complejo | While <state>, when <trigger>, the <system> shall <response>. |
Nombra un sistema concreto ("the BFF", "the invoices page"), un comportamiento por requisito y resultados medibles (within 15 minutes, answers 409). agent-kit specs lint rechaza cualquier otra forma.
Escenarios (BDD / ATDD)
Cada requisito tiene escenarios escritos como ejemplos: Given un contexto, When una acción, Then un resultado observable (And / But amplían un paso). Se acuerdan antes del código y son los tests de aceptación.
ZOMBIES
Elige los escenarios (y los casos de test) con ZOMBIES y etiqueta cada escenario con la categoría que cubre:
| Etiqueta | Pregunta | Ejemplo |
|---|---|---|
@zero | nada / vacío | sin facturas → estado vacío |
@one | el caso básico único | una línea suma bien |
@many | varios, orden, duplicados | tres líneas en dos monedas |
@boundary | límites y bordes | el 5.º login fallido bloquea; último día de un período |
@interface | el contrato | 403 para otra provincia; forma de la API |
@exception | entrada mala, fallo | código inválido → error claro, nada guardado |
@simple | el camino feliz | crear y verlo en la lista |
Lint avisa cuando un requisito no tiene escenarios @exception ni @boundary. Las reglas de dinero, permisos y datos siempre los llevan.
Trazabilidad
Un test que prueba un escenario empieza su nombre con el id del escenario:
it("auth.R2.S2 shows the login page for an expired session", () => { /* … */ })
Un escenario probado sin test (una revisión visual, un flujo manual, una consulta SQL) lleva una fila ✅ en el tasks.md del cambio:
| auth.R2.S2 | manual: reloaded with an expired token, login shown | ✅ |
agent-kit specs trace y agent-kit work trace NNN listan los escenarios ✗ not covered; preflight bloquea un cambio terminado que tenga alguno.