Spec-driven development: uso OpenSpec a diario y chirría

Respuesta corta: spec-driven development (SDD) es escribir en Markdown qué tiene que hacer un cambio (requisitos y escenarios de aceptación) antes de que el agente toque código, y que el agente implemente a partir de ese documento. OpenSpec, Spec Kit y Kiro son las herramientas más conocidas. En 2026, en los flujos que he leído, ya no es el centro: el esfuerzo va a que el agente pueda comprobar su trabajo con algo que acabe en verde o en rojo, y la spec, cuando la hay, es corta (Anthropic propone sacarla de una entrevista).

Desconectas dos o tres semanas de la IA y al volver parece que han pasado años. Todo el mundo habla de SDD, harness engineering, grilling y software factories, y tú no sabes si te has perdido una revolución o unas cuantas palabras nuevas para lo mismo.

A mí me pasó con el SDD. Me puse a investigar qué era eso del spec-driven development y resultó que lo llevaba haciendo meses. Uso OpenSpec a diario en esta web y en Rydger. No sabía que tenía nombre.

Una advertencia antes de seguir: OpenSpec es la única herramienta de SDD que uso a diario. Spec Kit, Kiro y BMAD los he leído, no los he sufrido. Y la gente que cito más abajo es mi selección de flujos que merecen la pena, no una encuesta.

Y para que no te pierdas con el resto del vocabulario, tres palabras que vas a oír esta semana:

• Harness engineering: todo lo que guía y comprueba al agente; la spec es una de sus guías. Lo expliqué en este post.
• Grilling: que el agente te entreviste sin piedad antes de escribir nada.
• Software factory: entra la spec, sale el software, y nadie lo revisa. El extremo opuesto a lo que defiendo aquí.

Llevaba meses haciendo SDD sin saber que se llamaba así

La idea la popularizó GitHub con Spec Kit en septiembre de 2025: la spec como «un contrato de cómo debe comportarse tu código». Birgitta Böckeler, en martinfowler.com, la ordenó en tres niveles que sirven para no perderse:

• Spec-first: escribes la spec, el agente implementa, y no hace falta conservarla al terminar.
• Spec-anchored: la spec se queda en el repo y evoluciona con el código.
• Spec-as-source: la spec es la fuente de verdad y el código se genera desde ella.

OpenSpec es spec-anchored. Cada cambio vive en openspec/changes/<nombre>/ con cuatro piezas: proposal.md (por qué y qué cambia), unas specs delta con requisitos y escenarios WHEN … THEN …, design.md (cómo) y tasks.md (la checklist). Cuando terminas, archivas el cambio y sus deltas se integran en las specs vivas del proyecto.

El resto del mapa, en una línea cada una:

La tabla es mi lectura de sus docs, no una recomendación de ninguna de ellas.

Dónde chirría OpenSpec cuando lo usas todos los días

Las fricciones no salen en una demo. Salen cuando llevas meses con la herramienta, y son cuatro.

explore se queda en la superficie. Debería ser la fase de pensar e investigar antes de proponer. En la práctica lee lo que tiene a mano y da la tarea por terminada enseguida. La investigación que haría yo, ir a la documentación y mirar cómo lo han resuelto otros, no la hace.

propose no pregunta todo lo que debería. Donde hay un hueco, mete una suposición razonable y sigue. El problema es que esas suposiciones quedan escritas con la misma seguridad que lo que sí decidiste, y luego toca cazarlas. No es algo que haya contado, es lo que veo a menudo.

El Markdown es largo, y una revisión larga se degrada. Cuatro ficheros por cambio es mucho texto que leer con atención antes de escribir una sola línea de código. El problema es el volumen, no quien lee. Böckeler lo dijo en octubre de 2025, probando Kiro y Spec Kit: “I’d rather review code than all these markdown files”. Y el Radar de Thoughtworks avisó en noviembre de 2025 de que algunas herramientas generan specs largas y difíciles de revisar.

Cerrar un cambio es pura ceremonia. Al archivar, primero te pide sincronizar las specs delta con las vivas y luego archiva: otro punto de control, que ni escribe código ni lo comprueba. Es el precio de mantener la spec viva, y se paga en cada cambio, también en los pequeños. Con un fix pequeño, Böckeler lo comparó con matar moscas a cañonazos.

La parte honesta: la spec viva sí aporta algo

En esta web tengo un cambio de OpenSpec, improve-seo-ai-visibility, propuesto el 6 de octubre. Todas las tareas están cerradas menos una: volver a medir 28 días después del deploy. Esa tarea sigue ahí, en tasks.md, esperando, y ninguna sesión de chat la habría recordado por mí. Todo hay que decirlo: una issue de GitHub también habría guardado el recordatorio. Lo que la issue no guarda es el requisito al lado, con sus escenarios, en el mismo repo que el código que describe. Ese es el valor que promete spec-anchored: que dentro de un año alguien pueda leer por qué el código es así. En un cambio de tres semanas todavía es más promesa que resultado.

También me gusta que cada tarea termine en un “verify …” concreto: el agente sabe qué tiene que comprobar antes de marcar la casilla.

Y el SDD no está muerto. Spec Kit sacó cuatro versiones entre el 16 y el 27 de octubre de 2026, y el Radar de abril de 2026 puso OpenSpec en Assess, que en su idioma significa “merece la pena explorarlo”.

Lo que hacen ahora: una spec corta y un check que el agente pueda ejecutar

Leí cómo describen su propio flujo cuatro personas a las que sigo, más la guía de Anthropic. Coinciden más de lo que parece.

• La guía de Claude Code de Anthropic propone, cuando no sabes bien lo que quieres, pedirle a Claude que te entreviste hasta poder escribir la spec en un SPEC.md, y luego construir desde una sesión nueva. Y la frase que lo resume todo: “Give Claude something it can run that comes back pass or fail.”
• Boris Cherny, responsable de Claude Code, en un hilo de enero: cinco Claudes en paralelo, casi todas las sesiones empiezan en plan mode, y lo que considera más importante para sacarle buenos resultados: darle a Claude una forma de verificar su trabajo. Lo de que ahora escribe loops en vez de prompts lo conté en otro post.
• Simon Willison, en su guía de agentic engineering: TDD red/green (el test primero, comprobar que falla, luego el código) y ejecutar los tests antes de empezar.
• Mitchell Hashimoto, en febrero: si le das al agente una forma de verificar su trabajo, la mayoría de las veces se corrige solo. Y cada error repetido del agente gana una línea en AGENTS.md o un script para que no vuelva.
• Böckeler, en abril, con harness engineering: guías antes de que el agente actúe (reglas, specs) y sensores después (tests, linters, tipos). La spec pasa a ser una guía más.

En parte esto es SDD con otro nombre: la entrevista y el SPEC.md son spec-first de manual. La diferencia está en dónde va el esfuerzo. En el SDD clásico lo pones en escribir y revisar Markdown, así que la garantía depende de una lectura humana. Aquí lo pones en un escenario que se convierte en un test que falla, y que después se pone en rojo sin que nadie esté mirando. Tampoco es gratis. Un test que escribe el mismo agente que escribe el código puede pasar comprobando lo que no era, así que la revisión no desaparece: se muda al test. Y un comando en verde no dice nada de una decisión de diseño que ningún comando puede comprobar.

Tres fricciones tienen arreglo; la cuarta no

Esto es lo que probaría yo con cada una, a partir de lo anterior:

La última fila no tiene arreglo limpio. Si quieres que la spec sobreviva, alguien tiene que pasar por la ceremonia. Lo que puedes elegir es en qué cambios compensa.

Qué aprender después, de lo más barato a lo más caro

1. Un comando que dé verde o rojo en cada proyecto. Tests, tipos, linter, lo que tengas, detrás de un solo comando que el agente pueda ejecutar. Es el punto en el que coinciden las cinco fuentes.
2. Que los escenarios se conviertan en tests. El WHEN … THEN … de tu spec ya es un test escrito en prosa. Pídele al agente que lo escriba primero y que compruebe que falla.
3. Un AGENTS.md corto que crece error a error. Cada vez que el agente repite una equivocación, una línea o un script. Y quita lo que sobre: el Radar de abril pone las instrucciones infladas en Caution porque acaban largos y con reglas que se contradicen.
4. Entrevista antes de la spec. Esto ataca directamente la fricción de propose. Ya conté cómo lo hago con grill-with-docs.
5. Un revisor con el contexto limpio. Una sesión o un subagente que revisa el diff contra la spec sin haber visto tu conversación. La guía de Anthropic lo deja claro: pasarle la misma tarea a un subagente no mejora la respuesta; uno que no haya visto tu razonamiento sí aporta.
6. Paralelo con worktrees, y loops. Lo último. Un worktree es barato de probar y un loop pequeño también; la cautela del Radar es por los enjambres de muchos agentes a la vez, que es lo que más ruido mete.

En esta web ya tengo el 1, el 3 y el 4: un hook de pre-push que pasa astro check, el lint y los tests antes de cada push, un AGENTS.md corto y grill-with-docs. El 5 lo monté como un verificador.

El paso dos es en el que más insisten Willison y Pocock. Con un ejemplo de reservas inventado:

// spec: WHEN la sala R1 está reservada de 10:00 a 11:00
//       y alguien reserva R1 de 10:30 a 11:30
//       THEN la API devuelve 409 y no guarda nada
it("rechaza una reserva que se solapa", async () => {
  await book({ room: "R1", from: "10:00", to: "11:00" });
  const res = await book({ room: "R1", from: "10:30", to: "11:30" });
  expect(res.status).toBe(409);
  expect(await countBookings("R1")).toBe(1);
});

Antes de tu próximo propose

No hace falta que dejes OpenSpec. Un “verify …” en prosa lo interpreta el agente; un comando con código de salida, no. Así que haz una cosa: revisa el tasks.md del próximo cambio y asegúrate de que cada tarea termine en un comando que el agente pueda ejecutar y que salga en verde o en rojo. Si una tarea no tiene comando, como una decisión de diseño o un documento, apunta qué verías al terminarla (un fichero que existe, una URL que responde) o márcala a propósito como revisión humana. Las que ningún comando puede confirmar por ti son las que merecen tu atención.

Lectura relacionada: el paso que añadí antes de OpenSpec para decidir qué merece una spec está en el post de los subagentes de Rydger.

Fuentes

• GitHub, lanzamiento de Spec Kit (2 de septiembre de 2025).
• Birgitta Böckeler, Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl (15 de octubre de 2025) y Harness engineering (2 de abril de 2026).
• Thoughtworks Technology Radar: spec-driven development (noviembre de 2025), OpenSpec y agent instruction bloat (vol. 34, abril de 2026).
• Anthropic, buenas prácticas de Claude Code (leído el 28 de octubre de 2026).
• Boris Cherny, hilo sobre su flujo con Claude Code (2 de enero de 2026).
• Simon Willison, Agentic Engineering Patterns.
• Mitchell Hashimoto, My AI Adoption Journey (5 de febrero de 2026).
• Matt Pocock, skills, incluida grill-me.
• Mi experiencia con OpenSpec es de uso diario; el cambio improve-seo-ai-visibility está en el repo de esta web.

P.D. ¿Tú también usas SDD a diario? Me interesa sobre todo qué parte has dejado de hacer y no has echado de menos. Cuéntamelo en LinkedIn.