SDD y OpenSpec: primero se acuerda, después se construye

SDD y OpenSpec: primero se acuerda, después se construye

El problema más caro de trabajar con una IA no es que escriba mal el código. Es que escriba código correcto para algo que tú no querías. El modelo no recuerda por qué le pediste aquello, cada conversación arranca de cero, y el resultado sale compilando, con pruebas en verde y con otra semántica. No hay error visible. Solo una función que no era la que querías.

La salida no es un prompt más largo. Es cambiar el orden: escribir primero qué tiene que hacer el sistema, aceptar que ese texto sea la referencia, y recién entonces dejar que la IA lo construya. A eso le llaman SDD. Y OpenSpec es una forma concreta y ligera de hacerlo, sin montar el proceso de una empresa.

El requisito que vive en el chat

El flujo habitual es invisible. Pides un cambio, el modelo responde con quince archivos, pruebas pasan, y cierras el día convencido de que salió bien. Semanas después aparece el efecto secundario y nadie recuerda qué se pidió realmente, porque la única fuente de verdad era una conversación que ya no existe.

Ahí está el punto. Mientras el requisito viva en el historial del chat no hay nada que revisar, nada que versionar y nada que comparar. Y el costo de un malentendido crece con el tamaño del cambio: arreglar un párrafo mal entendido es gratis, arreglar cuatrocientas líneas mal entendidas ya no lo es.

Qué es SDD

SDD es Spec-Driven Development, desarrollo dirigido por especificaciones. Toda la idea cabe en una frase que conviene memorizar: primero se acuerda, después se construye.

Un spec es un contrato de comportamiento. Dice qué hace el sistema, no cómo lo hace. Por eso se escribe con las palabras de RFC 2119, que arrastran un significado estándar de fuerza:

La separación entre el qué y el cómo es lo que hace útil el ejercicio. Hay una prueba rápida para decidir si algo pertenece a un spec: si puedes cambiar la implementación sin cambiar el comportamiento visible, probablemente no debería estar en el spec sino en el diseño. Los nombres de clases, la librería elegida y el orden de los pasos son decisiones técnicas, no requisitos.

Qué es OpenSpec

OpenSpec es una capa de acuerdo ligera entre tú y tu asistente. No es un framework, no es un IDE y no obliga a ningún proceso. Es una carpeta en tu repositorio con dos subcarpetas, y la diferencia entre las dos explica casi todo lo demás:

openspec/
├── specs/      la verdad: cómo se comporta el sistema hoy
└── changes/    lo que estás proponiendo cambiar

specs/ es la fuente de verdad y describe el comportamiento actual. changes/ contiene las propuestas, cada una en su propia carpeta. Mientras un cambio no se archiva no toca la verdad, y eso permite trabajar en dos cambios en paralelo, revisar la propuesta antes de que toque nada y tener un historial limpio de por qué se hizo cada cosa.

La otra mitad de la herramienta son los comandos. Tú escribes /opsx:propose y la IA redacta los documentos del cambio para que tú los revises. La instalación va en la terminal y los comandos van en el chat del asistente. Esa separación de lugares es lo que más confunde al principio.

Los cuatro documentos de un cambio

Esta es la parte que más valor tiene, porque es una plantilla que ya viene pensada. Cada cambio se empaqueta en una carpeta con cuatro documentos que se alimentan entre sí:

proposal → specs → design → tasks → implementar
  por qué     qué      cómo     pasos      hacerlo

Una consecuencia práctica sale sola: el alcance se acuerda antes de que exista código. Si al leer la propuesta descubres que el cambio es el doble de lo que pensabas, ese es el momento barato de recortarlo. Un mes después, con el código ya escrito, ese mismo recorte es un proyecto entero.

Delta specs: la idea que lo hace útil

Si OpenSpec te obligara a reescribir el spec completo del sistema en cada cambio no serviría para nada. Un sistema real tiene cientos de requisitos, y documentarlo entero antes de tocarlo es un trabajo que nunca se termina.

La solución son los delta specs. En lugar de describir el destino completo, describes la diferencia respecto a la verdad actual:

El formato es Markdown pelado, sin sintaxis nueva que aprender. Esto es un delta spec completo:

## MODIFIED Requirements

### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 15 minutes pass without activity
- THEN the session is invalidated

Esa es la diferencia entre una herramienta que se usa en proyectos nuevos y una que se usa en el código que ya tienes. Un delta se escribe sin haber documentado nunca el resto del sistema, y por eso funciona igual de bien sobre un proyecto con seis meses de historia que sobre uno de la semana pasada.

El día a día

El ciclo completo son cuatro pasos, y ninguno es un ritual: son preguntas que ya te ibas a hacer, escritas en un sitio donde quedan guardadas.

npm install -g @fission-ai/openspec@latest
openspec init

Y después, en el chat del asistente:

/opsx:propose add-dark-mode    la IA redacta propuesta, specs, diseño y tareas
/opsx:apply                    implementa la lista de tareas y la va marcando
/opsx:archive                 fusiona los deltas en los specs y guarda el cambio

Entre el segundo y el tercero hay un paso opcional que la propia documentación recomienda cuando la idea todavía está difusa: /opsx:explore. No escribe código, lee el repositorio, compara opciones y convierte una idea vaga en un plan. Es el antídoto contra la IA que construye algo, con total confianza, a partir de un pedido impreciso.

Habilitadores, no puertas

La frase que más aparece en la documentación de OpenSpec es enablers, not gates, y vale la pena entenderla bien porque define el carácter de la herramienta.

Un proceso clásico es una cascada: se planifica, luego se implementa, y volver atrás tiene castigo. En OpenSpec las dependencias entre documentos muestran qué se puede crear a continuación, no qué estás obligado a crear. Si a mitad de la implementación descubres que el diseño estaba mal, editas design.md y sigues. Si el alcance se infló, ajustas la propuesta. Nada te bloquea.

La contrapartida honesta es disciplina: como nadie te empuja hacia adelante, mantener un cambio acotado es trabajo tuyo. La ventaja es que la herramienta es ligera; el costo es que no es gratis.

Cuándo no usarlo

Vale la pena decirlo, porque un proceso que se aplica siempre termina ignorándose. Para un arreglo de una línea, o para un cambio de texto, la ceremonia no se paga. El gasto es real: escribir el plan, revisarlo y mantenerlo al día.

El criterio es sencillo. Úsalo cuando el malentendido sería caro, es decir, cuando el cambio toca comportamiento del que alguien va a depender o cuando hay más de una persona leyendo lo que construyes. Déjalo pasar cuando el resultado se ve en la pantalla y se deshace igual de fácil.

La idea en una frase

SDD es poner el acuerdo antes del código. OpenSpec es la versión de ese acuerdo que cabe en una carpeta de Markdown y se escribe con el mismo asistente que después implementa. Aprende solo tres cosas y tienes casi todo: specs es la verdad, changes son propuestas, y el archivado es el momento en que una propuesta se convierte en verdad. Todo lo demás son detalles de la herramienta.

© Arturo Juárez Monroy