---
title: "Notación"
description: "Una notación estándar en cada paso — requisitos EARS, escenarios Given/When/Then, etiquetas ZOMBIES, ids de escenario en los nombres de los tests."
canonical_url: "https://razcue-agent-kit.vercel.app/es/concepts/notation"
---
# Notación

> Una notación estándar en cada paso — requisitos EARS, escenarios Given/When/Then, etiquetas ZOMBIES, ids de escenario en los nombres de los tests.

<table>
<thead>
  <tr>
    <th>
      Paso
    </th>
    
    <th>
      Estándar
    </th>
    
    <th>
      Cómo se ve
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Por qué y alcance
    </td>
    
    <td>
      Propuesta
    </td>
    
    <td>
      <code>
        work/changes/004-invoices/proposal.md
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Requisito
    </td>
    
    <td>
      <strong>
        EARS
      </strong>
    </td>
    
    <td>
      <code>
        ### invoices.R2 — Totals
      </code>
      
       + <code>
        When an invoice is saved, the BFF shall round its total to 3 decimals.
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Aceptación
    </td>
    
    <td>
      <strong>
        BDD / ATDD
      </strong>
    </td>
    
    <td>
      <code>
        #### invoices.R2.S3 — Rounding edge @boundary
      </code>
      
       + Given / When / Then
    </td>
  </tr>
  
  <tr>
    <td>
      Elegir casos
    </td>
    
    <td>
      <strong>
        ZOMBIES
      </strong>
    </td>
    
    <td>
      una etiqueta por escenario
    </td>
  </tr>
  
  <tr>
    <td>
      Tests
    </td>
    
    <td>
      Trazabilidad
    </td>
    
    <td>
      <code>
        it("invoices.R2.S3 rounds 0.0005 up")
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Datos de prueba
    </td>
    
    <td>
      ZOMBIES en los datos
    </td>
    
    <td>
      <code>
        -- @fixture invoices.R2.S3 @boundary
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      QA
    </td>
    
    <td>
      Checklist
    </td>
    
    <td>
      un ítem por escenario
    </td>
  </tr>
</tbody>
</table>

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:

<table>
<thead>
  <tr>
    <th>
      Patrón
    </th>
    
    <th>
      Plantilla
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Ubicuo
    </td>
    
    <td>
      The <code>
        <system>
      </code>
      
       shall <code>
        <response>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      Evento
    </td>
    
    <td>
      When <code>
        <trigger>
      </code>
      
      , the <code>
        <system>
      </code>
      
       shall <code>
        <response>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      Estado
    </td>
    
    <td>
      While <code>
        <state>
      </code>
      
      , the <code>
        <system>
      </code>
      
       shall <code>
        <response>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      No deseado
    </td>
    
    <td>
      If <code>
        <condition>
      </code>
      
      , then the <code>
        <system>
      </code>
      
       shall <code>
        <response>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      Opcional
    </td>
    
    <td>
      Where <code>
        <feature>
      </code>
      
      , the <code>
        <system>
      </code>
      
       shall <code>
        <response>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      Complejo
    </td>
    
    <td>
      While <code>
        <state>
      </code>
      
      , when <code>
        <trigger>
      </code>
      
      , the <code>
        <system>
      </code>
      
       shall <code>
        <response>
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

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:

<table>
<thead>
  <tr>
    <th>
      Etiqueta
    </th>
    
    <th>
      Pregunta
    </th>
    
    <th>
      Ejemplo
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        @zero
      </code>
    </td>
    
    <td>
      nada / vacío
    </td>
    
    <td>
      sin facturas → estado vacío
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @one
      </code>
    </td>
    
    <td>
      el caso básico único
    </td>
    
    <td>
      una línea suma bien
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @many
      </code>
    </td>
    
    <td>
      varios, orden, duplicados
    </td>
    
    <td>
      tres líneas en dos monedas
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @boundary
      </code>
    </td>
    
    <td>
      límites y bordes
    </td>
    
    <td>
      el 5.º login fallido bloquea; último día de un período
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @interface
      </code>
    </td>
    
    <td>
      el contrato
    </td>
    
    <td>
      403 para otra provincia; forma de la API
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @exception
      </code>
    </td>
    
    <td>
      entrada mala, fallo
    </td>
    
    <td>
      código inválido → error claro, nada guardado
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @simple
      </code>
    </td>
    
    <td>
      el camino feliz
    </td>
    
    <td>
      crear y verlo en la lista
    </td>
  </tr>
</tbody>
</table>

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**:

```ts
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:

```markdown
| 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.


## Sitemap

See the full [sitemap](https://razcue-agent-kit.vercel.app/sitemap.md) for all pages.