Las specs son el nuevo código fuente en la era de agentes AI

Los agentes de AI coding generan implementación más rápido de lo que la mayoría de equipos puede clarificar qué quieren construir. El cuello de botella se movió. Ya no es velocidad de tipeo, conocimiento de frameworks, ni expertise algorítmica. Es la capacidad de expresar intent con suficiente precisión para que una máquina produzca comportamiento correcto en el primer intento — y comportamiento predecible en cada intento subsiguiente. El código ya no es el recurso escaso. La claridad sí. Las specs son el nuevo código fuente porque son el artefacto que determina lo que el sistema realmente hace, mientras que el código generado es cada vez más una representación derivada y descartable de ese intent.

Este cambio no es incremental. Redefine cómo los product managers definen requerimientos, cómo los ingenieros invierten su tiempo, cómo los equipos miden calidad, y dónde vive la accountability cuando algo se rompe. Las organizaciones que tratan las specs como contratos vivos y enforceables están entregando más rápido y regresionando menos que las que todavía las tratan como artefactos de coordinación escritos para humanos y olvidados por máquinas.

AI hace que las specs débiles sean más caras, no más baratas

Cada requerimiento ambiguo que antes producía un pull request confuso ahora produce cinco implementaciones confiadas y contradictorias en el tiempo que tomaba escribir el ticket. Un agente no se detiene a hacer preguntas de clarificación. Llena vacíos con suposiciones plausibles, genera código que compila y pasa los tests que escribió para sí mismo, y sigue adelante. La ambigüedad no emerge hasta la integración, la review, o producción — cuando el costo de corrección es más alto.

Una spec vaga como "construí un dashboard de billing" genera un sistema con suposiciones incrustadas en cada capa: qué rol de usuario ve qué datos, si los montos son brutos o netos, cómo aparecen las suscripciones eliminadas en los agregados, qué pasa cuando la fuente de datos no está disponible, si el componente hace streaming o polling. Cada suposición es un defecto potencial. Cada defecto es invisible hasta que un humano con conocimiento de dominio inspecciona la salida — lo cual derrota el propósito de usar un agente para ahorrar tiempo.

La economía se invirtió. Cuando la implementación era cara, una spec imprecisa costaba horas extra de ingeniería para interpretar. Ahora que la implementación es barata, una spec imprecisa cuesta el retrabajo de descartar código generado que satisface la letra del requerimiento pero viola su intent. Cuanto más barata se vuelve la generación de código, más cara crece la ambigüedad.

El viejo PRD era un artefacto de coordinación — la nueva spec es un contrato de ejecución

Los documentos de requerimiento de producto tradicionales servían un propósito humano: alinear stakeholders, registrar decisiones, y darle a los ingenieros suficiente contexto para tomar decisiones durante la implementación. Se leían una vez, parcialmente, y luego eran superados por conversaciones en Slack, comentarios en Figma, y decisiones hechas mid-sprint que nunca volvieron al documento.

Ese workflow no sobrevive el desarrollo agentic. Un agente lee la spec literalmente. No tiene acceso al hilo de Slack donde el PM clarificó que "usuarios activos" significa "logueados en los últimos 30 días, excluyendo cuentas internas." No tiene memoria del standup donde el diseñador dijo que el empty state debería mostrar un prompt de onboarding en vez de una pantalla en blanco. Genera lo que la spec dice, no lo que el equipo quiso decir.

La nueva spec es un contrato de ejecución — un artefacto versionado y enforceable que el agente trata como autoritativo. Define:

• Intent: qué outcome debe producir el sistema, para quién, bajo qué condiciones.
• Constraints: presupuestos de performance, fronteras de seguridad, requerimientos de compliance, estándares de accesibilidad.
• Interfaces: formas de input, formatos de output, respuestas de error, contratos de API.
• Invariantes: reglas que nunca deben violarse sin importar el path de implementación (e.g., "el total de una factura nunca es negativo," "los datos de un usuario eliminado nunca se retornan en la sesión de otro usuario").
• Ejemplos: pares concretos de input-output que sirven como documentación y como test cases.
• Modos de fallo: qué sucede cuando las dependencias no están disponibles, los datos son malformados, o los rate limits se alcanzan.

Cuando alguno de estos elementos falta, el agente llena el vacío con su propio juicio — que es estadísticamente plausible pero no necesariamente correcto para el dominio específico.

Los criterios de aceptación deben convertirse en tests ejecutables

La forma más fuerte de una spec es aquella donde los criterios de aceptación no son descripciones en prosa que un humano interpreta — son assertions ejecutables que el sistema valida continuamente. Esto no es nuevo en principio. Behavior-Driven Development (BDD) intentó esto hace dos décadas. Lo que cambió es que los agentes de AI ahora pueden consumir criterios de aceptación estructurados y generar tanto la implementación como la verificación en un solo paso.

El cambio práctico:

• Antes: PM escribe "el dashboard debería cargar en menos de 2 segundos." El ingeniero interpreta esto como un target p95 medido en el cliente, o tal vez en la API, o tal vez solo en desarrollo. Nadie verifica después del lanzamiento.
• Después: la spec establece latency_p95_ms: 2000, measurement_point: client_first_contentful_paint, environment: production. El agente genera la implementación, el test de performance, y la alerta de monitoreo. El constraint es enforceable desde el primer deployment.

Este patrón se extiende a todo tipo de requerimiento. Los modelos de permisos se convierten en matrices de acceso por rol que el agente implementa como políticas RLS y testea como assertions de integración. Las reglas de validación de datos se convierten en constraints de schema que el agente genera junto con los componentes de formulario. Los empty states se convierten en variantes de UI enumeradas que el agente renderiza para cada combinación de disponibilidad de datos.

Los eval rubrics que los product managers escriben para sistemas de AI siguen el mismo principio: la definición de "comportamiento correcto" es la especificación, y la especificación es ejecutable. La distinción entre requerimiento y test se disuelve.

Los constraints importan más que las instrucciones

Las instrucciones le dicen al agente qué construir. Los constraints le dicen qué nunca debe romperse. En un mundo de código generado, los constraints son más durables que las instrucciones porque sobreviven la regeneración — el agente puede reescribir la implementación entera, pero los invariantes se mantienen.

Una spec construida alrededor de instrucciones:

"Construí un workflow de reembolso que envía un email de confirmación y actualiza el ledger."

Una spec construida alrededor de constraints:

"El workflow de reembolso debe: (1) nunca procesar un reembolso que exceda el monto del cargo original, (2) producir una entrada de ledger idempotente keyed en refund_id, (3) emitir un evento de auditoría antes de cualquier mutación de estado, (4) completar en menos de 5 segundos en p99, (5) degradar gracefully si el servicio de email no está disponible — el reembolso procede, el email se reintenta asincrónicamente."

La spec basada en instrucciones le da al agente libertad para construir un sistema que funciona en el happy path. La spec basada en constraints le da al agente un contrato que funciona en producción — incluyendo los failure cases, race conditions, y edge states que las instrucciones rutinariamente omiten.

Por eso refactorizar antes de la automatización con AI importa como prerrequisito: los constraints deben existir como reglas enforceables en el sistema antes de que el agente pueda respetarlos. Un constraint que solo vive en conocimiento tribal es invisible para el agente y será violado.

El checklist de specs: qué incluye una especificación agent-ready

No toda spec necesita verificación formal. Pero toda spec que impulsa código generado por agentes necesita estos siete elementos para producir output confiable:

1. Intent — una oración describiendo el outcome que el sistema produce para el usuario final. No la implementación, no el approach técnico — el outcome.
2. Constraints — requerimientos no funcionales codificados como umbrales medibles: presupuestos de latencia, techos de error rate, topes de costo, fronteras de seguridad.
3. Interfaces — contratos de input y output tipados. Request schemas, response shapes, event payloads. El agente no puede generar código de integración correcto sin saber qué habla el sistema.
4. Invariantes — reglas de dominio que deben mantenerse bajo todas las circunstancias. Sobreviven reescrituras de implementación y sirven como anchors de regresión.
5. Ejemplos — escenarios concretos con inputs específicos y outputs esperados. Funcionan como test cases y desambiguación para edge conditions.
6. Modos de fallo — qué hace el sistema cuando las dependencias fallan, los datos son inválidos, o los recursos se agotan. Si la spec no define comportamiento de degradación, el agente no lo implementará.
7. Expectativas de test — la estrategia de verificación. Unit, integración, performance, seguridad. Qué se testea, cómo, y qué umbrales constituyen un pass.

Una spec que no incluye alguno de estos elementos está incompleta para desarrollo impulsado por agentes. El agente igual generará código — generará código que se ve correcto pero se comporta impredeciblemente en las fronteras que la spec no cubrió.

¿Qué tan detallada debe ser una spec AI-ready?

El nivel de rigor de la spec depende del radio de explosión de la feature y la complejidad del dominio involucrado.

¿Toda feature necesita una spec completa antes de que AI genere código?

Features de bajo riesgo y bien entendidas — un filtro nuevo en una vista de lista, un cambio de copy, un endpoint CRUD para una herramienta interna — necesitan especificación mínima. El dominio es estrecho, los modos de fallo son obvios, y el costo de regeneración es bajo. Features de alto riesgo — cualquier cosa que toque billing, permisos, integridad de datos, u orquestación cross-service — necesitan specs completas basadas en constraints porque el costo de una suposición incorrecta se compone con cada dependencia downstream.

¿Qué formato debería usar una spec agent-ready?

Markdown en el repositorio, versionado junto al código. El formato importa menos que la estructura: intent, constraints, interfaces, invariantes, ejemplos, modos de fallo, expectativas de test. Algunos equipos usan YAML o JSON schemas estructurados para campos machine-readable (presupuestos de latencia, matrices de roles). Otros mantienen todo en prosa con test cases ejecutables en archivos companion. El constraint clave es que la spec debe ser verificable — un humano o una máquina puede confirmar si la implementación la satisface.

¿Quién escribe la spec — el PM o el ingeniero?

Ambos. El PM define intent, constraints e invariantes — qué debe hacer el sistema y qué nunca debe hacer. El ingeniero agrega interfaces, modos de fallo y expectativas de test — cómo se integra el sistema y cómo se verifica la correctitud. La spec es un artefacto de colaboración, no un documento de handoff. Cuando ambas perspectivas faltan, el agente opera con un ojo cerrado.

Una visión opuesta

Un argumento reconocido en el campo sostiene que requerir specs completas antes de la implementación reintroduce demoras tipo waterfall en un workflow ágil. Los agentes modernos pueden generar implementaciones exploratorias, surfear edge cases que el equipo no había considerado, y refinar iterativamente tanto la spec como el código en un feedback loop ajustado. Exigir specs completas upfront asume que el equipo conoce todos los requerimientos de antemano — lo cual rara vez es cierto para features nuevas.

Esta visión es correcta sobre el descubrimiento. Los agentes son excelentes para exponer las implicaciones de un requerimiento generando una implementación candidata que revela vacíos. El error está en confundir exploración con producción. Una implementación exploratoria generada sin constraints es un prototipo — útil para aprender, peligroso si se shipea. La spec no necesita estar completa antes de que el agente comience; necesita estar enforced antes de que el output del agente entre al sistema. Descubrimiento y enforcement son fases distintas, no filosofías competidoras.

Lo que importa recordar

• Cuando la implementación se vuelve barata, la ambigüedad se convierte en la parte más costosa del software. El cuello de botella se movió de tipear código a especificar intent.
• Las specs ya no son documentos de coordinación para humanos. Son contratos de ejecución para agentes — el artefacto que determina lo que el sistema realmente hace.
• Los constraints son más durables que las instrucciones. Un agente puede reescribir toda la implementación; los invariantes deben mantenerse sin importar qué.
• Una spec agent-ready completa incluye intent, constraints, interfaces, invariantes, ejemplos, modos de fallo y expectativas de test.
• La spec es una colaboración entre PM (intent, constraints, invariantes) e ingeniería (interfaces, modos de fallo, expectativas de test). Ninguna perspectiva sola es suficiente.
• Descubrimiento y enforcement son fases distintas. Los agentes pueden explorar sin specs; no pueden shippear sin ellas.

Conclusión

Las organizaciones que entregan más rápido con agentes de AI no son las que tienen los mejores prompts. Son aquellas cuyas especificaciones son lo suficientemente precisas para que el código generado satisfaga el intent en el primer paso y mantenga la correctitud a través de ciclos de regeneración. La spec se movió de un artefacto de coordinación que los humanos ojean durante el kickoff al entorno de ejecución que los agentes tratan como autoritativo. Esto cambia quién hace qué en un equipo de producto: los product managers se convierten en autores de specs cuyo output determina directamente el comportamiento del sistema, y los ingenieros se convierten en arquitectos de constraints cuyo trabajo es hacer esas specs enforceables. La pregunta para todo equipo adoptando desarrollo agentic no es "qué modelo de AI debería generar el código" — es "quién es dueño de la spec, y es lo suficientemente precisa para producir el sistema correcto?"