Las especificaciones de software deberían ser portables. La descripción de un cambio debería poder entrar por el flujo de un agente, convertirse en trabajo estructurado, código, tests y evidencia de ejecución, y salir después de forma que otra persona u otra herramienta puedan entenderla.
Parece obvio. No es como funciona la mayor parte del desarrollo asistido por IA.
Hoy las partes importantes de un cambio suelen estar partidas entre un chat, una carpeta de Markdown, un gestor de tareas, una pull request y la memoria de quien lo hizo. Cambias de agente, de editor o vuelves tres semanas después, y la intención ya empieza a degradarse. El código puede seguir ahí. La razón por la que existe, el comportamiento que prometía y la prueba de que funcionó son mucho más fáciles de perder.
No es un argumento contra las especificaciones. Es un argumento contra tratarlas como archivos que pertenecen a una herramienta concreta.
Una especificación es un contrato, no un destino
Una buena especificación de software explica qué tiene que cambiar, qué no puede cambiar y cómo reconocer un resultado correcto. Es el contrato entre la intención de producto y la implementación.
Ese contrato no debería quedarse encerrado en la herramienta que lo escribió primero.
Debería poder importarse una propuesta, unos requisitos, decisiones de diseño y tareas desde un flujo de trabajo orientado a agentes. Debería poder conectarse ese material con un modelo de producto, un repositorio, el trabajo que sigue y la evidencia que vuelve. Y debería poder exportarse de nuevo sin obligar a la siguiente herramienta a reconstruir su significado desde un montón de prosa.
La distinción importante es esta:
Una especificación portable conserva la intención. Una especificación verificada demuestra el comportamiento.
Hacen falta las dos. La portabilidad mantiene vivo el contrato entre herramientas. La verificación decide si el contrato se ha cumplido de verdad. Como explicamos en qué es el desarrollo guiado por especificaciones, un build verde no basta: los criterios de aceptación deben ejecutarse contra el resultado real.
El fallo: contexto bloqueado dentro de un workflow
Las herramientas de código con IA son muy buenas creando un bucle local:
- Describes un cambio.
- Un agente prepara un plan.
- El agente aplica el plan.
- Sigues adelante.
El bucle se rompe cuando el contexto tiene que salir de su casa original. Un nuevo agente no ve las decisiones que había detrás del plan. Un compañero ve tareas terminadas, pero no el contrato de aceptación. Un mantenedor futuro ve un diff, pero no por qué se descartó otra alternativa. El repositorio puede seguir correcto por piezas mientras el producto se vuelve cada vez más difícil de razonar como un todo.
Es el mismo problema del software localmente correcto, globalmente incoherente: cada cambio aislado puede tener sentido y, aun así, el sistema perder dirección compartida.
Markdown no es el problema. Markdown es un buen formato de intercambio. El problema empieza cuando una carpeta de Markdown es la única representación del cambio.
Mover el cambio sin aplanarlo
PAELLADOC trata ahora un workflow externo de especificaciones como un sobre interoperable, no como un destino rival.
OpenSpec es un formato práctico que ya puede entrar y salir de PAELLADOC. Sus archivos conocidos de propuesta, specs, diseño y tareas sirven porque hacen legible un cambio fuera de un único chat. La idea no es sustituir ese formato por otro silo. La idea es llevarlo a través de la implementación y devolverlo con el contexto que ha adquirido.
Puedes traer un paquete de cambio: propuesta, requisitos, diseño y tareas. PAELLADOC convierte ese material en un modelo local vivo del trabajo: artefactos de producto, relaciones, contexto de ejecución y expectativas de validación. El cambio puede recorrer después la fábrica, desde discovery y planificación hasta agentes, código, revisión y evidencia.
Cuando toca salir, ese mismo cambio se puede exportar otra vez. El siguiente agente o herramienta recibe un contrato legible, no solo un diff final.
No es una importación de una sola dirección a propósito. Una importación de una sola dirección convierte las otras herramientas en una ruta de migración. Un formato bidireccional las convierte en participantes de un workflow más amplio.
Qué debe sobrevivir al viaje
Una especificación portable es más que un título y una checklist. Como mínimo necesita llevar cinco cosas.
1. Intención
¿Qué comportamiento de usuario o de negocio debe cambiar? Sin eso, una lista de tareas se puede ejecutar perfectamente y seguir creando una feature factory: un registro de output sin una explicación del comportamiento que buscaba instalar. Hacer producto es instalar un comportamiento, no acumular superficie.
2. Límites
¿Qué queda explícitamente fuera? ¿Qué tiene que seguir siendo cierto después del cambio? Las restricciones suelen valer más que el camino feliz, sobre todo cuando un agente es capaz de generar mucho código plausible a gran velocidad.
3. Decisiones
¿Por qué este diseño y no otro? Las decisiones de arquitectura, los trade-offs y los riesgos conocidos deben seguir unidos al cambio. No son ceremonia; son el camino más corto para entender un diff futuro.
4. Trabajo y procedencia
¿Qué tareas, archivos, componentes, servicios y tests pertenecen al contrato? Una especificación portable debe poder adquirir referencias al código que la implementa, no limitarse a señalar un repositorio vago.
5. Evidencia
¿Qué se ejecutó? ¿Qué pasó? ¿Contra qué versión del contrato? Una casilla marcada es estado útil. No es evidencia. La diferencia importa más cuando la implementación la ha producido un agente de IA y nadie ha revisado cada línea.
Por eso importa un grafo de conocimiento de producto: da a la especificación un lugar donde enganchar intención, código, decisiones y prueba sin reducirlos todos a un documento indiferenciado.
Interoperabilidad no es vendor lock-in con un botón de importación más bonito
Hay una trampa habitual en las herramientas para developers: llamar interoperable a algo porque acepta una importación y, después, hacer que toda acción valiosa dependa de una representación interna propietaria.
La prueba es más sencilla: ¿puede salir el trabajo con su significado intacto?
Si cambias de agente mañana, ¿puede el siguiente entender la propuesta, los límites, las decisiones, las tareas y el resultado? Si el equipo decide trabajar con otro editor, ¿puede conservar sus contratos aceptados? Si el producto cambia, ¿puedes encontrar la evidencia que ya está obsoleta en vez de confiar en un verde antiguo?
Las especificaciones portables responden a esa prueba. Permiten que cambie el workflow sin obligar a que se reinicie la memoria del producto.
Por qué importa más con agentes de IA
Cuanto más rápido escribe código un agente, más caro resulta perder el rastro de decisiones que rodea a ese código.
La IA ha abaratado producir un diff. No ha abaratado decidir qué construir, proteger las restricciones ni demostrar el comportamiento. De hecho, eleva el listón: cuando la implementación abunda, la intención duradera y la verificación se convierten en las partes escasas.
Por eso la unidad útil no es el prompt, el chat ni siquiera la tarea. Es el contrato portable que puede sobrevivir a los tres.
La visión de la fábrica local de software
PAELLADOC no intenta poseer el lugar donde se escribe cada especificación. Está construyendo la fábrica local donde una especificación puede convertirse en software mantenible.
Entra el contrato. Se conecta con el producto y el código. Se ejecuta el trabajo. Se captura la evidencia. Vuelve a salir.
Los agentes cambiarán. Los editores cambiarán. Los frameworks cambiarán.
La intención, las decisiones y la prueba deberían sobrevivirles.
Preguntas frecuentes
¿Las especificaciones de software portables son lo mismo que el desarrollo guiado por especificaciones? No exactamente. El desarrollo guiado por especificaciones define el contrato de aceptación antes de implementar. La portabilidad hace que ese contrato pueda moverse entre herramientas y conserve su vínculo con el código y la verificación posteriores.
¿Una especificación portable garantiza que la implementación sea correcta? No. Conserva el contrato; la validación en runtime y la evidencia de aceptación siguen siendo las que demuestran que es correcto.
¿Para qué exportar una especificación después de implementar? Para que otro agente, compañero o mantenedor futuro reciba la intención, decisiones, tareas y contexto de verificación que hay detrás del código, en lugar de tener que deducirlo de un diff.