Una historia te dice la dirección.
Una especificación te dice exactamente a dónde vas, qué queda fuera de límites, y qué hacer cuando las cosas no salen como se esperaba. Esa diferencia hoy decide la velocidad de entrega.
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
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
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
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
Antes de entregar una especificación, cinco preguntas. Un sí en cualquiera es una brecha, y la especificación vuelve atrás.
- ¿Hay algún requerimiento que el agente tendría que buscar en otra parte para entender?
- ¿Hay algún comportamiento que se sobreentiende pero no está escrito?
- ¿Podrían dos personas razonables leer esto y construir cosas distintas?
- ¿Los casos donde algo NO debe pasar están tan explícitos como los casos donde sí?
- 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.
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.
Por qué esto es el cuello de botella ahora
La velocidad de implementación era la restricción. Ya no lo es. Un agente produce en horas lo que tomaba días, y eso mueve la restricción hacia arriba: a qué tan bien se describió el trabajo.
Los errores se multiplican en esa dirección. Un error en la especificación no produce un comportamiento equivocado. Produce una implementación equivocada, pruebas equivocadas escritas contra ella, y un modelo mental equivocado que carga todo el que toque el trabajo después.
- Una línea de código mala es una línea de código mala
- Un plan malo son cien líneas malas
- Una especificación mala son mil
- Retrabajo a velocidad de IA sigue siendo retrabajo
Tráenos el backlog.
En 30 minutos te mostramos qué entregaría primero un Pod y cómo lo cotizaríamos.