Desarrollo guiado por specs: escribir especificaciones, no codigo

El codigo se escribe solo. La spec no.

Un equipo en Amazon envio una funcionalidad en tres dias usando desarrollo guiado por specs. No escribieron ni una linea de codigo de aplicacion a mano. Escribieron una spec: 47 lineas de requisitos estructurados, criterios de aceptacion, casos limite e integraciones. Un agente leyo la spec y produjo 2,300 lineas de codigo funcional. Los tests pasaron. El deployment se puso en verde. La funcionalidad llego a produccion.

Segun la guia de product.engineer, esto es desarrollo guiado por specs: la practica de definir especificaciones estructuradas y legibles por maquinas que agentes de IA interpretan y ejecutan como software funcional. En lugar de escribir codigo directamente, los ingenieros escriben el documento de requisitos que un agente usa para generar, probar e iterar sobre codigo de forma autonoma. La spec se convierte en la fuente de verdad. El codigo se convierte en un artefacto.

El framework de product.engineer para desarrollo guiado por specs invierte el flujo de trabajo tradicional de ingenieria. Dejas de ser la persona que escribe codigo. Te conviertes en la persona que define que debe hacer el codigo, como debe comportarse y que restricciones debe satisfacer. El agente se encarga de la implementacion. Tu eres dueno de la intencion.

Esto importa porque el rol de un product engineer siempre se ha tratado de resultados, no de outputs. Envias software funcional que resuelve problemas reales para usuarios reales. El desarrollo guiado por specs elimina la parte de menor valor de ese ciclo (traducir intencion a sintaxis) y la reemplaza con la parte de mayor valor (definir la intencion con suficiente precision para que una maquina la ejecute). Esa traduccion de deseo humano difuso a requisito tecnico preciso siempre ha sido la parte mas dificil de construir software. Ahora es la unica parte que importa.

Amazon Kiro, presentado en el AI Engineer Summit en 2025 (la charla ha acumulado desde entonces mas de 48,000 vistas), formalizo este enfoque para uso en produccion. Su sistema ingiere specs estructuradas y produce implementaciones completas incluyendo tests, manejo de errores y configuraciones de deployment. Los datos de adopcion interna fueron notables: los equipos usando flujos de trabajo guiados por specs enviaron 2.7x mas funcionalidades por sprint con 40% menos incidentes en produccion comparados con equipos haciendo desarrollo tradicional. Las specs detectaron ambiguedades y casos limite que los humanos tipicamente pasan por alto durante la implementacion, porque escribir la spec forzo al ingeniero a pensar completamente el problema antes de que existiera cualquier codigo.

Por que el codigo es la abstraccion equivocada

Durante sesenta anos, la industria del software asumio que el codigo era el artefacto principal. Contrataban ingenieros para escribir codigo. Median la productividad en lineas de codigo, commits o pull requests. Los code reviews eran la puerta de calidad. El codigo era la cosa.

Esa suposicion se esta disolviendo.

El codigo no es la intencion. El codigo es una posible expresion de la intencion. Cuando escribes if (user.subscription.tier === 'enterprise' && user.seats > 100), estas expresando una regla de negocio. Pero el codigo oculta la regla dentro de sintaxis, flujo de control y detalle de implementacion. La regla de negocio es: "Las cuentas enterprise con mas de 100 asientos obtienen precios por volumen." Esa oracion es la spec. El codigo es un artefacto derivado.

Esta distincion importaba menos cuando los humanos eran los unicos que podian traducir specs a codigo. Necesitabas el codigo porque la computadora necesitaba el codigo. Pero cuando un agente de IA puede traducir confiablemente requisitos estructurados a implementaciones correctas, el codigo deja de ser el artefacto creativo. La spec lo es.

El reporte Octoverse 2025 de GitHub encontro que el 47% del codigo committeado en repositorios con herramientas de IA habilitadas fue generado por IA. En Shopify, metricas internas mostraron que el 68% de los pull requests mergeados en Q3 2025 contenian codigo generado por IA. La contribucion humana se estaba moviendo hacia arriba: hacia la definicion de problemas, especificacion de requisitos y revision.

El product engineer que entiende este cambio deja de optimizar su velocidad de escritura y empieza a optimizar su velocidad de pensamiento. Invierte en escribir mejores specs, no codigo mas rapido. Desarrolla la habilidad de context engineering para asegurar que los agentes reciban suficiente informacion estructurada para actuar correctamente. Y reconoce que los 25 minutos invertidos en escribir una spec precisa a menudo ahorran 4 horas de implementacion manual y debugging.

La anatomia de una spec ejecutable

No todas las specs son iguales. Un Google Doc con puntos no es una spec ejecutable. Un ticket de Jira con criterios de aceptacion esta mas cerca pero sigue siendo insuficiente. Una spec ejecutable tiene propiedades estructurales especificas que la hacen interpretable por un agente.

Despues de estudiar como Amazon Kiro, v0 de Vercel y las herramientas internas de OpenAI manejan entradas de especificacion, emerge una estructura comun:

Los cinco componentes de una spec ejecutable

Cada componente sirve una funcion distinta en el ciclo de ejecucion del agente. La declaracion de intencion guia el enfoque general. Los criterios de aceptacion se convierten en aserciones de tests. Los casos limite previenen los modos de falla mas comunes. Las restricciones de integracion previenen que el agente reinvente infraestructura existente. Los no-requisitos previenen la expansion de alcance.

Esta estructura no es arbitraria. Mapea directamente a como los ingenieros experimentados piensan los problemas antes de escribir codigo. La diferencia es que la mayoria de los ingenieros hacen este pensamiento implicitamente, en su cabeza, mientras escriben simultaneamente. El desarrollo guiado por specs hace ese pensamiento explicito y externo. Terminas de pensar antes de que el agente comience a trabajar.

Que hace a una spec legible por maquinas

Tres propiedades distinguen una spec que los agentes pueden ejecutar de una spec que es solo documentacion:

Criterios de aceptacion deterministicos. "La UI deberia sentirse rapida" no es ejecutable. "La carga de pagina se completa en menos de 200ms para el percentil 95 de usuarios" es ejecutable. Cada criterio debe ser verificable por un test automatizado.

Limites explicitos. Los agentes que encuentran ambiguedad la llenan con suposiciones. Malas suposiciones producen bugs. Una buena spec elimina la ambiguedad siendo explicita sobre restricciones: "Usar React Server Components, no client-side rendering." "Almacenar estado en la URL, no en estado local." "Llamar al servicio de pagos existente en /api/v2/charges, no crear un nuevo servicio."

Prioridad ordenada. Cuando los requisitos entran en conflicto (y siempre lo hacen en los bordes), la spec debe decirle al agente cual requisito gana. "Si la generacion de PDF toma mas de 30 segundos, retornar un resultado parcial con una advertencia en lugar de hacer timeout." El ordenamiento de prioridad previene que el agente se quede en bucles infinitos intentando satisfacer requisitos contradictorios simultaneamente.

El framework Kiro: como Amazon lo operacionalizo

El sistema Kiro de Amazon, revelado en el AI Engineer Summit, representa la implementacion en produccion mas madura del desarrollo guiado por specs a escala. No es un prototipo de investigacion. Corre en produccion en multiples equipos de Amazon.

El flujo de trabajo tiene cuatro fases:

Fase 1: Creacion de la spec. El ingeniero escribe una especificacion estructurada siguiendo un schema predefinido. Kiro proporciona plantillas, pero la spec es escrita por humanos. Este es el trabajo creativo. Aqui es donde vive el juicio de producto.

Fase 2: Validacion de la spec. Antes de que comience la ejecucion, el sistema analiza la spec buscando completitud, ambiguedad y contradicciones internas. Hace preguntas de clarificacion. Esto es critico porque una conversacion de cinco minutos en la etapa de spec previene cinco horas de debugging despues de la implementacion. El paso de validacion de Kiro detecto un promedio de 3.2 ambiguedades por spec en pruebas internas, cada una un bug potencial que habria sido descubierto mucho mas tarde en desarrollo tradicional.

Fase 3: Implementacion. El agente genera codigo, tests, documentacion y configuracion de deployment a partir de la spec validada. Corre tests iterativamente. Si un test falla, debuggea y reintenta. El ingeniero observa pero no escribe codigo. Solo interviene cuando el agente esta atorado o yendo en una direccion equivocada.

Fase 4: Revision y refinamiento. El ingeniero revisa la implementacion generada contra la spec original. No linea por linea (ese es el trabajo del agente) sino resultado por resultado. ?Se ve bien el PDF? ?La exportacion se completa en menos de 30 segundos? ?El manejo de errores coincide con lo que la spec requeria? Esta es la puerta de calidad.

Metricas internas de equipos de Amazon usando Kiro mostraron:

• Tiempo promedio de spec a PR mergeado: 3.4 horas (comparado con 14.2 horas para funcionalidades de complejidad similar)
• Cobertura de tests en codigo generado: 87% promedio (comparado con 64% para codigo escrito manualmente en los mismos equipos)
• Tasa de incidentes en produccion: 0.3 por 100 deployments (comparado con 0.8 por 100 para implementaciones manuales)

El numero de cobertura de tests es particularmente revelador. Los humanos toman atajos en los tests. Los agentes no. Cuando la spec dice "testear estos casos limite," el agente escribe esos tests. Siempre.

Que demanda el desarrollo guiado por specs de los ingenieros

Esta no es una historia sobre ingenieros volviendose obsoletos. Es una historia sobre el trabajo cambiando de forma. El desarrollo guiado por specs eleva el estandar para las habilidades que realmente importan y baja el estandar para las habilidades que siempre fueron commoditizadas.

Habilidades que se vuelven mas valiosas

Pensamiento preciso. Escribir una spec ejecutable es mas dificil que escribir codigo. El codigo te permite ser vago porque puedes navegar la ambiguedad durante la implementacion. Una spec te forza a resolver cada ambiguedad por adelantado. No puedes escribir "manejar errores apropiadamente" en una spec. Debes especificar exactamente cuales errores pueden ocurrir y exactamente que sucede para cada uno.

Diseno de sistemas. Cuando no estas escribiendo codigo, estas disenando sistemas. Estas decidiendo cuales son los componentes, como interactuan, que contratos mantienen. Este es el pensamiento arquitectonico que siempre fue la parte mas valiosa de la ingenieria senior. El desarrollo guiado por specs simplemente elimina el ruido de implementacion y lo convierte en el output principal.

Expertise de dominio. Un agente no puede decirte cual es el comportamiento correcto del producto. No puede entrevistar usuarios. No puede interpretar requisitos de negocio ambiguos de stakeholders. El product engineer que entiende el dominio profundamente escribe mejores specs, que producen mejor software. El conocimiento de dominio se convierte en la ventaja competitiva, no la velocidad de escritura.

Comunicacion escrita. Hay una conexion directa entre el desarrollo guiado por specs y la habilidad de comunicarse con precision por escrito. Las specs son artefactos escritos. Su calidad depende enteramente de la habilidad del autor para expresar ideas complejas con precision y completitud. Los ingenieros que escriben bien hacen buenas specs.

Habilidades que se deprecian

La velocidad pura de codificacion ya no diferencia. Memorizar superficies de API importa menos cuando el agente las conoce todas. Debuggear errores de sintaxis no es una habilidad cuando el agente produce codigo sintacticamente correcto por defecto. Estas nunca fueron las habilidades de alto valor, pero eran las visibles. Las habilidades que diferencian en un mundo guiado por specs estan todas antes del codigo.

Mi experiencia con flujos de trabajo guiados por specs

Comence a experimentar con enfoques guiados por specs en AWS a principios de 2025, inicialmente con herramientas internas y luego con funcionalidades orientadas al cliente. Lo primero que note fue lo mal que la mayoria de los ingenieros (incluyendome) especificamos requisitos cuando nos fuerzan a hacerlos explicitos.

Creemos que sabemos lo que queremos. Luego intentamos escribirlo como una spec deterministica, y descubrimos seis ambiguedades en lo que parecia una funcionalidad simple. "Agregar una barra de busqueda al dashboard." ?Buscar que? ?Por cuales campos? ?Que pasa con cero resultados? ?Es sensible a mayusculas? ?Filtra en tiempo real o al enviar? ?Cual es la longitud maxima de consulta? Estas son decisiones que normalmente tomamos inconscientemente durante la implementacion. El desarrollo guiado por specs las fuerza a salir a la luz.

Habiendo capacitado a mas de 12,000 ingenieros y contratado mas de 600, les puedo decir que la habilidad de pensar con precision sobre requisitos antes de escribir codigo es el predictor mas fuerte de efectividad en ingenieria que he observado. Correlaciona mas fuertemente con la calidad del output que los anos de experiencia, expertise en lenguajes o conocimiento algoritmico. El desarrollo guiado por specs formaliza esta habilidad y la convierte en el trabajo principal.

Los equipos con los que trabajo que han adoptado flujos guiados por specs reportan el mismo patron: las primeras dos semanas se sienten mas lentas. Estas escribiendo specs en lugar de codigo, y se siente como que no estas "construyendo." Para la semana tres, la diferencia de velocidad se vuelve innegable. Las funcionalidades llegan mas rapido, con menos bugs y con mejor cobertura de tests. Para la semana seis, nadie quiere volver atras.

Desarrollo guiado por specs e ingenieria agentica

El desarrollo guiado por specs es una pieza de un cambio mas grande hacia la ingenieria agentica. Responde una pregunta especifica: ?que hace el humano cuando el agente escribe el codigo? El humano escribe la spec.

Pero se conecta con otros patrones:

• Context engineering proporciona al agente la informacion que necesita para ejecutar la spec correctamente. Una spec sin contexto (?cual codebase? ?cuales patrones existentes? ?cuales convenciones de estilo?) produce codigo generico que no encaja en el sistema.
• Ingenieria de revision es lo que sucede despues de que el agente genera codigo. El product engineer revisa resultados contra la spec, no detalles de implementacion contra sus preferencias.
• Ciclos de iteracion manejan los casos donde la primera generacion no satisface completamente la spec. El ingeniero actualiza la spec o proporciona restricciones adicionales, y el agente itera.

Juntos, estos patrones forman el flujo de trabajo del product engineer moderno: especificar, proporcionar contexto, revisar resultados, iterar. Ninguno de estos pasos requiere escribir codigo a mano. Todos requieren juicio profundo de producto y tecnico.

Comenzando con desarrollo guiado por specs

No necesitas Amazon Kiro para empezar a practicar desarrollo guiado por specs. Los principios aplican con cualquier herramienta de codificacion con IA.

Un framework practico para comenzar

1. Antes de abrir un editor, escribe la spec. Usa la estructura de cinco componentes: intencion, criterios de aceptacion, casos limite, restricciones de integracion y no-requisitos. Mantenla en un archivo markdown en la raiz del feature branch.

2. Alimenta la spec a tu agente. Ya sea que uses Claude Code, Cursor o GitHub Copilot Workspace, pega la spec completa como el prompt inicial. Deja que el agente haga preguntas de clarificacion. Respondelas, luego agrega esas respuestas a la spec.

3. Revisa contra criterios, no contra codigo. Cuando el agente produce una implementacion, no leas cada linea buscando problemas de estilo. Ejecuta los criterios de aceptacion. ?Pasan los tests? ?Los casos limite se comportan correctamente? ?Se integra con los sistemas existentes como se especifico?

4. Itera sobre la spec, no sobre el codigo. Si algo esta mal, no corrijas manualmente el codigo. Actualiza la spec para ser mas precisa, y deja que el agente regenere. Esto mantiene la spec como la fuente de verdad y previene la divergencia entre lo que especificaste y lo que existe.

5. Versiona la spec con el codigo. El archivo de spec se envia con el PR. Ingenieros futuros (y agentes futuros) pueden leer la spec para entender la intencion, no solo la implementacion. Esta es documentacion que se escribe sola porque fue escrita primero.

Errores comunes

Sub-especificar casos limite. El happy path es facil de especificar. Los modos de falla son donde viven los bugs. Fuerzate a enumerar al menos cinco casos limite para cada funcionalidad, incluso las simples.

Sobre-especificar implementacion. La spec debe decir que, no como. "Ordenar la lista alfabeticamente" es una spec. "Usar Array.prototype.sort con un comparador sensible a locale" es un detalle de implementacion. Deja que el agente elija el como a menos que tengas una restriccion especifica.

Omitir los no-requisitos. Sin no-requisitos explicitos, los agentes construiran de mas. Agregaran funcionalidades que no pediste porque parecian logicas. "No soporta exportacion masiva" previene que el agente pase tres horas construyendo exportacion masiva cuando todo lo que necesitabas era descarga de un solo item.

La economia del desarrollo guiado por specs

El argumento economico es directo. En desarrollo tradicional, el cuello de botella es la implementacion. Un ingeniero senior cuesta $200-400 por hora con carga completa. Pasan 60-70% de ese tiempo escribiendo y debuggeando codigo. El desarrollo guiado por specs mueve su tiempo al 30-40% que siempre fue el trabajo de alto valor: entender problemas, disenar soluciones y validar resultados.

La investigacion interna de productividad de Stripe (compartida en su offsite de ingenieria 2025, luego referenciada en su blog de ingenieria) encontro que sus ingenieros de mayor impacto pasaban menos del 40% de su tiempo escribiendo codigo incluso antes de las herramientas de IA. Pasaban la mayoria en especificacion, revision y coordinacion entre equipos. El desarrollo guiado por specs no es un cambio radical para estos ingenieros. Es una formalizacion de lo que ya estaban haciendo.

Para equipos adoptando este enfoque, la matematica es clara. Una funcionalidad que tomaba a un ingeniero cinco dias ahora toma dos dias (un dia especificando, un dia revisando e iterando). Los tres dias ahorrados se componen a traves de docenas de funcionalidades por trimestre. A escala, esto no es una mejora marginal. Es un cambio estructural en la economia de la ingenieria.

Puntos clave

• El desarrollo guiado por specs trata la especificacion como el artefacto creativo principal y el codigo como un output derivado.
• Los ingenieros definen intencion, criterios de aceptacion, casos limite y restricciones; los agentes generan la implementacion.
• Una funcionalidad que tomaba cinco dias ahora toma dos (un dia especificando, un dia revisando e iterando).
• La spec debe ser legible por maquinas, estructurada y lo suficientemente precisa para que los agentes la ejecuten sin ambiguedad.
• Este enfoque se compone a escala, creando un cambio estructural en la economia de la ingenieria a traves de docenas de funcionalidades por trimestre.

FAQ

?Que es el desarrollo guiado por specs?

El desarrollo guiado por specs es la practica de escribir especificaciones estructuradas y legibles por maquinas que agentes de IA interpretan y ejecutan como software funcional. Los ingenieros definen que debe hacer el software (intencion, criterios de aceptacion, casos limite, restricciones) y los agentes generan la implementacion. La spec es el artefacto creativo principal; el codigo es un output derivado.

?El desarrollo guiado por specs reemplaza a los ingenieros de software?

No. Cambia lo que hacen los ingenieros, no si son necesarios. El desarrollo guiado por specs requiere pensamiento de producto mas profundo, habilidad de diseno de sistemas y expertise de dominio. Elimina la traduccion manual de intencion a sintaxis. El juicio de ingenieria requerido para escribir una buena spec es el mismo juicio que hacia a alguien un buen ingeniero antes de que existieran las herramientas de IA.

?Que herramientas soportan desarrollo guiado por specs hoy?

Amazon Kiro es la implementacion mas formalizada. Sin embargo, los principios funcionan con Claude Code, Cursor, GitHub Copilot Workspace, v0 de Vercel y cualquier asistente de codificacion con IA que acepte entrada estructurada. La clave es proporcionar al agente una spec completa en lugar de instrucciones ad-hoc. La herramienta importa menos que la disciplina de especificar antes de generar.

?Como se diferencia el desarrollo guiado por specs de escribir buenos tickets?

Los buenos tickets describen intencion para humanos. Las specs ejecutables describen intencion para maquinas. La diferencia es precision: los tickets pueden contener ambiguedad porque un implementador humano hara preguntas o asumira cosas razonables. Las specs deben ser inequivocas porque los agentes llenaran vacios con suposiciones potencialmente erroneas. Una buena spec elimina cada ambiguedad que un ticket dejaria abierta.

?Pueden los ingenieros junior hacer desarrollo guiado por specs?

Los ingenieros junior pueden empezar pero produciran specs mas debiles inicialmente porque tienen menos intuicion sobre casos limite, restricciones del sistema y modos de falla. El desarrollo guiado por specs eleva el piso de calidad del output (el agente escribe buen codigo sin importar la habilidad de codificacion del autor de la spec) pero el techo sigue siendo determinado por la habilidad del ingeniero para pensar completamente los problemas. La habilidad se desarrolla con practica y mentoria.

Lectura relacionada

• ?Que es un Product Engineer?
• Context Engineering: La habilidad que reemplazo al Prompt Engineering
• Ingenieria agentica: como los Product Engineers construyen con IA
• Comunicacion escrita para Product Engineers
• No construyas agentes, construye habilidades