# Estándar de Especificación

> La diferencia entre una historia y una especificación, las secciones que necesita, y la prueba de cinco preguntas que dice si un agente puede construir desde ella sin adivinar.

Fuente: https://www.koombea.com/es/ai-pods/standards/specification/

---

## Una historia no es una especificación

Al tablero llegan dos tipos de ítem. Una historia de usuario describe qué quiere
alguien y por qué. Una historia técnica describe trabajo cuyo beneficiario es el
sistema y no una persona: una migración, un umbral de rendimiento, un cambio de
esquema.

Las dos necesitan especificación, y la estructura es la misma. Lo que cambia es
el lenguaje de los criterios de aceptación.

En ambos casos, la historia captura requerimientos. Es un punto de partida. Una
especificación toma esos requerimientos y resuelve toda ambigüedad antes de
empezar.

Esa es toda la distinción, y no se trata de contar secciones. Una historia deja
espacio para interpretar, y un desarrollador senior llena ese espacio con
experiencia, conversación y criterio. Un agente lo llena con una suposición.
Cada brecha en la especificación se vuelve una suposición en el resultado.

Una especificación responde toda pregunta que necesitaría el implementador para
construir bien la primera vez:

- ¿Cómo se ve terminado?
- ¿Qué pasa en los límites?
- ¿Qué queda explícitamente afuera?
- ¿Cómo sabremos que está correcto?
- ¿Con qué se conecta?

## Las secciones que necesita una especificación {#core-sections}

Cinco secciones centrales son siempre obligatorias. Para historias de usuario se
escriben a nivel de negocio, legibles por el cliente. Para historias técnicas
describen resultados a nivel de sistema en lenguaje claro, específicos y
medibles.

| Sección central | Qué contiene | Por qué es obligatoria |
| --- | --- | --- |
| Objetivo | Una frase: qué logra y para quién | Ancla toda decisión posterior. Sin él, el agente optimiza para el resultado equivocado |
| Audiencia | Para quién es | Define alcance, lenguaje y formato |
| Criterios de aceptación | Enunciados numerados y verificables de qué es terminado | La definición de terminado del agente. Cada uno se mapea a al menos una prueba |
| Fuera de alcance | Exclusiones explícitas | Evita construir de más. La ambigüedad de alcance se vuelve funcionalidad extra |
| Definición de terminado | Un checklist explícito | El agente sabe dónde parar |

### Secciones de contexto, cuando aplican {#context-sections}

Le dan al agente el material de referencia que necesita sin saturar las
secciones centrales. No cambian qué debe hacer el producto. Definen cómo se
conecta con todo lo que lo rodea.

| Sección de contexto | Cuándo incluirla |
| --- | --- |
| Referencia de diseño | Cualquier trabajo con componente visual. Enlaza el frame o nodo específico, no el archivo. Sin eso el agente lee el frame equivocado o adivina |
| Flujo de usuario | Recorridos de varios pasos donde los criterios solos no transmiten la secuencia. Se omite para una sola acción |
| Contratos técnicos | Cuando el trabajo debe cumplir una interfaz o restricción externa. Una especificación de API, un esquema, un formato de payload, un umbral de rendimiento. Si el contrato no existe todavía, la implementación está bloqueada hasta que exista |
| Problema | Historias técnicas donde el objetivo solo no aclara qué existe hoy y qué debe cambiar |
| Dependencias | Cuando el trabajo no puede empezar hasta que otro ítem, endpoint o sistema esté listo |
| Fuentes de datos | Reportes, tableros, y todo lo que consuma datos externos |

**Sobre la fragmentación.** La información de una especificación tiende a
repartirse entre un tracker, un repositorio, archivos de diseño y una
herramienta de pruebas. Cada uno tiene una parte y ninguno el todo. Un agente
parte del ítem de trabajo. Si la información no está ahí ni enlazada desde ahí,
el agente no la tiene, y llena la brecha con su mejor suposición, no con la tuya.

## Escribir criterios de aceptación {#acceptance-criteria}

Los criterios de historias de usuario son a nivel de negocio. Describen qué
puede hacer una persona y qué experimenta, no cómo lo implementa el sistema.

| Escribe esto | No esto |
| --- | --- |
| El usuario puede ordenar la lista de hoteles para ver primero los más baratos | El orden devuelve hoteles ascendente cuando se pasa `sort_by=price_asc` a la API |
| Compartir un viaje por enlace permite ver el viaje a invitados sin cuenta | El token de compartir se agrega a la URL y se valida en el servidor contra un vencimiento de 24 horas |

El detalle técnico no está equivocado. Está en la sección equivocada. Endpoints,
parámetros y lógica de vencimiento van en el contrato técnico.

Los criterios de historias técnicas son a nivel de sistema, y siguen siendo
específicos y verificables.

| Escribe esto | No esto |
| --- | --- |
| El endpoint de lista responde en menos de 200ms para payloads de hasta 100 ítems bajo carga normal | El rendimiento debería ser aceptable |
| La migración de esquema termina sin pérdida de datos en un volumen equivalente a producción | La migración debería funcionar bien |

## Tres niveles, y qué trabajo necesita cada uno

Los niveles describen cuánta ambigüedad queda, no qué secciones existen. Son
pisos, no metas.

| Nivel | Qué tiene | Quién puede construir desde ahí |
| --- | --- | --- |
| Trabajable por humano | Título, descripción, criterios aproximados | Un desarrollador senior que conoce el código y puede preguntar. No un agente, y no alguien nuevo en el código |
| Asistible por agente | Secciones centrales completas, criterios estructurados | Un agente con supervisión y revisión humana |
| Listo para IA | Todo lo anterior más casos borde, exclusiones, definición de terminado, y cada sección de contexto que aplique | Un agente con supervisión mínima. Sin ambigüedad que tenga que resolver solo |

No todo ítem necesita el nivel más alto. Ajústalo al riesgo.

| Tipo de trabajo | Nivel mínimo |
| --- | --- |
| Arreglo de una línea, cambio de texto | Trabajable por humano |
| Cambio simple de interfaz, funcionalidad menor | Asistible por agente |
| Funcionalidad nueva, integración, trabajo de datos | Listo para IA |
| Autenticación, permisos, facturación, seguridad | Listo para IA, sin excepciones |

Escribir una especificación lista para IA cuesta una hora. Retrabajar una
implementación ambigua cuesta un sprint.

## La prueba de completitud {#completeness-test}

Antes de entregar una especificación, cinco preguntas. Un sí en cualquiera es
una brecha, y la especificación vuelve atrás.

1. ¿Hay algún requerimiento que el agente tendría que buscar en otra parte para entender?
2. ¿Hay algún comportamiento que se sobreentiende pero no está escrito?
3. ¿Podrían dos personas razonables leer esto y construir cosas distintas?
4. ¿Los casos donde algo NO debe pasar están tan explícitos como los casos donde sí?
5. Si el agente encuentra un caso borde, ¿está escrito el comportamiento esperado?

Una especificación que pasa está lista. Una que no, es una fábrica de
suposiciones.

## Quién es dueño de qué, y cuándo

Cada artefacto tiene un dueño y un momento. La especificación la escribe y la
posee producto. Diseño aporta la referencia de diseño cuando el frame se marca
listo. Ingeniería aporta el contrato técnico antes de que empiece el desarrollo.
Nada está listo para construir hasta que todas las secciones obligatorias estén
presentes y cada contribuyente haya firmado la suya.

Calidad deriva el plan de validación desde la especificación. Es un artefacto
aparte, escrito desde la especificación antes de que empiece el build y no
después, y esa secuencia es el tema del
[estándar de validación](https://www.koombea.com/es/ai-pods/standards/validation/).

## Trazabilidad

Para que el trabajo sea auditable, cada funcionalidad se rastrea de
especificación a prueba. El trabajo de la especificación es asegurar que cada
criterio exista antes del build. El trabajo del plan de validación es mapear
cada criterio a una prueba que lo demuestre. Un criterio sin prueba no está
terminado, y una prueba sin criterio no es evidencia de nada.