Qué es una spec: partes, ejemplos y cómo se escribe para la IA

Tabla de contenidos

Una spec es un documento corto que dice qué tiene que hacer un cambio de software, de forma que se pueda comprobar si lo hace. No dice cómo programarlo ni en qué orden. Dice qué comportamiento esperas, en qué casos y cómo sabrás que está bien.

Con un agente de IA al otro lado, esa diferencia lo cambia todo.

Le pides “añade exportar a CSV” y el agente rellena todo lo que no dijiste: qué columnas, qué pasa con un proyecto vacío, si avisa por email cuando termina. La spec es el sitio donde decides tú esas cosas antes de que las decida él.

En este artículo vas a encontrar:

  • Una definición de spec que puedes usar para saber si lo que tienes delante lo es.
  • En qué se diferencia de un plan, una lista de tareas, un PRD, un ticket, un ADR o un AGENTS.md.
  • Sus partes, ordenadas en seis familias de bloques, y cuáles necesitas según el tamaño del cambio.
  • Las tres notaciones para escribir escenarios y la trampa de las cuatro almohadillas.
  • Cómo reparten la spec en ficheros OpenSpec, Spec Kit, PAUL, GSD y las skills de Matt Pocock.
  • Qué pasa con la spec cuando el cambio termina, y las señales de que tu spec ya no es una spec.

Si lo que buscas es el método completo (especificar, planificar, implementar y verificar), está en la guía de Spec Driven Development. Aquí vamos a mirar la pieza central de ese método con lupa.

¿Qué es una spec y qué no es?

Una spec es el contrato de comportamiento de un cambio: describe lo que el sistema tiene que hacer y lo deja escrito de forma verificable, en un fichero que vive en el repo junto al código.

Tres rasgos la distinguen de cualquier otro documento:

  1. Habla de comportamiento, no de implementación. “El usuario puede exportar sus tareas a CSV” es spec. “Usa la librería csv-stringify en el servicio de exportación” no lo es.
  2. Se puede comprobar. Cada cosa que afirma se puede convertir en un test o en una revisión con respuesta de sí o no. Si no hay forma de comprobarla, es un deseo.
  3. Está versionada. Vive en el repositorio, en Markdown, y cambia con el código. No en un Notion que nadie abre ni en el historial de un chat.

OpenSpec lo resume en una prueba que puedes aplicar a cualquier frase de tu documento: si la implementación puede cambiar sin que cambie el comportamiento visible, esa frase no va en la spec. Va en el diseño, en el plan o en ningún sitio (OpenSpec, writing-specs).

¿Por qué importa tanto con un agente?

Porque el agente no pregunta. Rellena. Un modelo con un hueco delante no se queda quieto esperando a que vuelvas del café: escoge la opción más probable según lo que ha visto en millones de repos, que rara vez es la que tú tenías en la cabeza.

🔑 Una spec no sirve para que el agente sepa más. Sirve para que improvise menos.

¿En qué se diferencia una spec de un plan, un PRD o un ticket?

Cada documento del desarrollo responde a una pregunta distinta, y la spec responde a una sola: qué tiene que pasar. El resto de documentos se le parecen, pero contestan otra cosa.

La confusión más habitual es mezclar spec y plan en el mismo fichero. El plan dice cómo vas a construirlo: qué módulos tocas, qué librería usas, en qué orden. Es útil, pero cambia en cuanto empiezas a programar. La spec, en cambio, debería sobrevivir a que cambies de librería.

Matriz de dos ejes con siete documentos del desarrollo. En horizontal, si hablan del producto o del código; en vertical, si viven con el proyecto o mueren con el cambio. La spec queda en la zona del producto y del cambio; el PRD, en producto y proyecto; el plan, las tareas y el ticket, en código y cambio; el ADR y el AGENTS.md, en código y proyecto

Esta tabla pone cada documento frente a la pregunta que contesta:

Documento Pregunta que responde Quién lo lee Cuánto vive
Spec ¿Qué tiene que pasar y cómo lo compruebo? Tú, tu equipo y el agente Lo que dura el cambio (y, si es viva, lo que dura la funcionalidad)
Plan / diseño ¿Cómo lo vamos a construir? El agente y quien revisa Hasta que se implementa
Tareas ¿En qué orden y en qué pasos? El agente Hasta que se completa cada una
PRD ¿Qué producto queremos y por qué? Producto y negocio Lo que dura la iniciativa
Ticket / issue ¿Qué hay que hacer ahora? Quien lo coge Hasta que se cierra
ADR ¿Por qué decidimos esto y no lo otro? Quien venga después Lo que dure la decisión
AGENTS.md ¿Cómo se trabaja siempre en este repo? El agente, en cada sesión Lo que dure el proyecto

Fíjate en las dos últimas filas.

El AGENTS.md (o CLAUDE.md) también es un documento para el agente, pero lleva reglas permanentes: cómo se ejecutan los tests, qué convenciones sigue el código. La spec lleva reglas de un cambio concreto. Si pones en el AGENTS.md que “el CSV tiene que incluir la fecha de creación”, lo estás convirtiendo en una spec eterna que el agente cargará en cada sesión, aunque estés arreglando el login. Tenemos una guía para escribir un buen AGENTS.md si quieres ver dónde está esa frontera.

El ADR es el otro primo cercano. Matt Pocock solo escribe uno cuando la decisión cumple tres condiciones a la vez: es difícil de revertir, sorprende a quien no tiene contexto y sale de un compromiso real entre alternativas (mattpocock/skills). Lo que no cumple las tres se queda en la spec, en el bloque de decisiones.

¿Qué partes tiene una spec?

Una spec completa se puede descomponer en seis familias de bloques: por qué, qué, cómo, tareas, verificación y gobierno. Ninguna spec lleva todos los bloques. Pero conocer el mapa entero te ayuda a elegir los que necesitas y a detectar el que te falta.

Este mapa no es un invento nuestro. Sale de leer las plantillas reales de cinco sistemas de Spec Driven Development en noviembre de 2026: OpenSpec 2.0, Spec Kit 1.4, PAUL 1.4, GSD Core 1.21 y las skills de Matt Pocock. Cada uno pone el énfasis en un sitio distinto, y juntos cubren unos cuarenta bloques diferentes.

Un fichero spec.md abierto en un editor, dividido en seis franjas de colores: por qué, con problema y objetivo; qué, con requisitos, escenarios y fuera de alcance; cómo, con decisiones y riesgos; tareas, con su verificación; verificación, con criterios de aceptación y comandos; y gobierno, con ficheros que no se tocan y estado. A la derecha, una nota por familia explica qué pregunta responde

Vamos familia por familia.

Por qué: el problema antes que la solución

La primera familia explica qué duele, a quién y por qué ahora. Parece obvia, pero es la que más se salta cuando escribes deprisa, y es la que el agente necesita para resolver las ambigüedades que la spec no cubre.

Los bloques típicos son:

  • Problema: una a tres frases contadas desde el usuario, sin solución dentro.
  • Objetivo: el resultado en una frase comprobable, del estilo “X pasa de A a B”. PAUL y GSD lo exigen medible.
  • Contexto: cómo está el código hoy y qué restricciones hay.
  • Criterios de éxito: cómo sabrás que mereció la pena, con números y sin nombrar tecnología. Spec Kit los llama Success Criteria y los numera (SC-001).

El truco del objetivo comprobable es más útil de lo que parece. “Mejorar la exportación” no se puede verificar. “Un proyecto de 10.000 tareas se exporta en menos de 5 segundos” sí.

Qué: el comportamiento que esperas

Es el corazón de la spec y la familia más grande. Aquí escribes lo que el sistema hará cuando esté hecho, y también lo que no hará.

Los bloques que más pesan:

  • Requisitos: un comportamiento por requisito, con MUST o SHALL. OpenSpec pone un tope de 500 caracteres por requisito y obliga a que cada uno tenga al menos un escenario.
  • Escenarios: ejemplos concretos que se convierten en test, uno por comportamiento e incluido el camino de error.
  • Casos límite: permisos, errores, estados vacíos, límites, reglas de negocio y concurrencia.
  • Fuera de alcance: lo que no vas a hacer, con su motivo. Es lo que frena al agente entusiasta.
  • Prohibiciones: lo que el sistema no debe hacer nunca. GSD las escribe como MUST NOT y cada línea se convierte en un test en negativo.
  • Por aclarar: lo que aún no está decidido. Spec Kit lo marca con [NEEDS CLARIFICATION] y no deja más de tres.

Hay más bloques en esta familia: historias de usuario con prioridad (Spec Kit), entidades de datos, supuestos, restricciones, capacidades con nombre estable (OpenSpec). Pero si solo escribes requisitos, escenarios y fuera de alcance, ya tienes el 80 % del valor.

💡 El bloque “por aclarar” es el más infravalorado. Una duda escrita es una duda que el agente no puede resolver a su manera sin que lo veas.

Las preguntas que conviene hacerse para rellenar los casos límite las tienes desarrolladas en la guía de SDD, en la sección de preguntas incómodas.

Cómo: las decisiones que no son implementación

Esta familia vive en la frontera. No es código, pero tampoco es comportamiento: son las decisiones técnicas que condicionan el resultado y que no quieres que el agente tome por su cuenta.

  • Decisiones: qué eliges, por qué y qué descartaste. Sin rutas ni código.
  • Riesgos: qué puede salir mal y cómo lo frenas.
  • Migración y vuelta atrás: cómo se despliega y cómo se deshace.
  • Lee primero: los ficheros que son la fuente de verdad. GSD lo llama <read_first> y el agente los lee antes de tocar nada.
  • Margen del agente: dónde puede decidir sin preguntarte. Es un bloque de GSD y es de los más sensatos: no todo merece una decisión tuya.
  • Cómo se prueba: dónde se prueba y qué no se prueba. Matt Pocock insiste en pactarlo antes de escribir, con un único punto de prueba si se puede.

En OpenSpec este bloque sale de la spec y se va a un fichero aparte, design.md, que además es opcional. Tiene sentido: la parte de “qué” es la que debe durar, y la de “cómo” caduca antes.

Tareas: el orden de trabajo

Las tareas son los pasos para llegar al comportamiento descrito, en orden de dependencia. Muchos sistemas las sacan a otro fichero (tasks.md), pero forman parte del paquete que le das al agente.

La regla de oro la formula PAUL: si no puedes decir qué ficheros toca la tarea, qué hace, cómo se verifica y cuándo está hecha, la tarea es demasiado vaga (PAUL, plantilla PLAN.md). PAUL limita cada plan a dos o tres tareas para que quepan en la mitad del contexto del modelo.

El otro bloque de esta familia son las dependencias: qué bloquea a qué y qué puede ir en paralelo. Es lo que permite a GSD lanzar varias tareas a la vez en oleadas, cada una con su contexto limpio.

Verificación: cuándo está hecho

La familia que separa “compila” de “funciona”. Aquí escribes cómo vas a comprobar que el cambio cumple la spec.

  • Criterios de aceptación: hecho o no hecho, sin término medio. En PAUL cada tarea apunta a uno (AC-1, AC-2…).
  • Lo que tiene que ser verdad: el bloque más ingenioso de GSD. En vez de comprobar que las tareas se completaron, comprueba hacia atrás desde el objetivo: qué tiene que ser verdad, qué ficheros tienen que existir y qué piezas tienen que estar conectadas. Así detecta funciones vacías que “completan” una tarea sin hacer nada.
  • Cómo se comprueba: los comandos que tienen que pasar antes de dar el cambio por cerrado (tests, lint, una comprobación manual).

GSD lo resume con una frase que conviene tatuarse: task completion ≠ goal achievement. Que el agente haya marcado todas las casillas no significa que el objetivo se cumpla.

Gobierno: la spec como documento vivo

La última familia no habla del software, sino de la spec misma: en qué estado está, qué no se puede tocar y qué queda pendiente.

  • Ficha: estado, fecha y rama, para saber si la spec sigue viva.
  • No tocar: ficheros y zonas que el agente no puede modificar. PAUL lo llama DO NOT CHANGE y es, probablemente, el bloque más útil cuando trabajas con un agente.
  • Notas: lo que no encaja en otro sitio. Si crece, es que sobra spec.

¿Por qué “No tocar” es tan valioso? Porque es la forma más barata de evitar el clásico “ya que estaba, he refactorizado el módulo de pagos”. Una línea en la spec y te ahorras una revisión de cuarenta ficheros.

¿Cuántos bloques necesita tu spec?

Los bloques que necesitas dependen del tamaño y del riesgo del cambio, no de la herramienta que uses. Un arreglo pequeño con cinco familias completas es burocracia. Una migración de base de datos con dos bloques es una apuesta.

Esta tabla es un punto de partida razonable:

Tipo de cambio Bloques mínimos Lo que añadirías
Bug acotado Problema, escenarios (el que falla y el que debe pasar), cómo se comprueba No tocar, si el arreglo está cerca de código delicado
Feature pequeña Objetivo, requisitos, escenarios, casos límite, fuera de alcance, criterios de aceptación Por aclarar, si quedan dudas
Feature grande Lo anterior más contexto, decisiones, tareas con dependencias Historias con prioridad, criterios de éxito medibles
Migración o refactor amplio Objetivo, decisiones, riesgos, migración y vuelta atrás, no tocar, cómo se comprueba Lo que tiene que ser verdad, para detectar piezas sin conectar

La versión más corta posible, la de cinco bloques que cabe en una pantalla, está explicada con plantilla en la guía de SDD. Si quieres partir de ahí y añadir lo que te falte, el constructor te lo deja montado.

Herramienta · Constructor

Elige tus bloques y llévate la plantilla

Parte de la plantilla de un sistema o de la mínima, añade y ordena los bloques de las seis familias y cópiala en Markdown para tu agente.

Le das

Los bloques que quieres en tu spec

Te devuelve

La plantilla en Markdown, lista para tu agente

Montar mi spec

¿Cómo se escriben los escenarios de una spec?

Los escenarios se escriben con la estructura Given / When / Then: un estado de partida, una acción y un resultado observable. Es la notación que viene de BDD, y casi todos los sistemas de SDD la adoptan porque un escenario así se traduce a un test casi palabra por palabra. Si te interesa de dónde sale, lo contamos en TDD vs BDD vs SDD.

Lo que cambia entre sistemas es cómo se escribe en Markdown. Hay tres formas.

Gherkin, la que usan PAUL y GSD, en un bloque de código:

Scenario: Proyecto vacío
  Given un proyecto sin tareas
  When el usuario exporta a CSV
  Then se descarga un fichero solo con la fila de cabeceras

El formato de OpenSpec, con viñetas y palabras clave en mayúsculas:

#### Scenario: Proyecto vacío
- **GIVEN** un proyecto sin tareas
- **WHEN** el usuario exporta a CSV
- **THEN** se descarga un fichero solo con la fila de cabeceras

En una línea, el de Spec Kit, numerado dentro de cada historia de usuario:

1. **Given** un proyecto sin tareas, **When** el usuario exporta a CSV, **Then** se descarga un fichero solo con la fila de cabeceras

Las tres dicen lo mismo. Elige la que entienda tu herramienta.

⚠️ En OpenSpec, los escenarios llevan exactamente cuatro almohadillas (####). Con tres, o escritos como viñetas sueltas, OpenSpec los ignora sin avisar: tu requisito se queda sin escenario y nadie te lo dice.

Un detalle más: aunque escribas la spec en español, deja las palabras clave (Given, When, Then, GIVEN, WHEN, THEN) en inglés. Son las que reconocen las herramientas y los validadores.

¿Dónde vive una spec en cada sistema de SDD?

Cada sistema reparte las mismas familias de bloques en ficheros distintos. Ninguno lo hace mal: responden a ideas diferentes sobre qué parte de la spec debe durar y cuál se tira al terminar.

Cinco árboles de carpetas, uno por sistema. OpenSpec separa specs vivas por capacidad y una carpeta por cambio con proposal, design, tasks y el delta de la spec. Spec Kit guarda la constitución aparte y una carpeta por feature con spec, plan y tasks. PAUL lo mete todo en un PLAN.md por fase con un SUMMARY al cerrar. GSD reparte cada fase en SPEC, CONTEXT, PLAN y VERIFICATION. Matt Pocock publica la spec como un issue y la trocea en tickets

Así lo resuelve cada uno:

  • OpenSpec separa la spec viva (openspec/specs/<capacidad>/spec.md), que describe cómo funciona el sistema hoy, de los cambios (openspec/changes/<cambio>/), que llevan proposal.md, un design.md opcional, tasks.md y un delta de la spec. Lo tienes paso a paso en nuestra guía de OpenSpec.
  • Spec Kit guarda los principios del proyecto en una constitución (.specify/memory/constitution.md) y crea una carpeta por feature (specs/001-nombre/) con spec.md, plan.md y tasks.md. Más detalles en la guía de Spec Kit.
  • PAUL lo junta casi todo en un PLAN.md por fase, escrito en bloques XML (objetivo, contexto, criterios de aceptación, tareas, límites), y al cerrar escribe un SUMMARY.md que compara lo planeado con lo hecho. Lo comparamos con GSD en PAUL vs GSD.
  • GSD reparte cada fase en varios ficheros dentro de .planning/phases/: SPEC.md, CONTEXT.md, PLAN.md y un VERIFICATION.md que comprueba el objetivo, no las tareas. Lo tienes en la guía de GSD.
  • Matt Pocock no usa ficheros de spec en el repo: la skill to-spec publica la spec como un issue con la etiqueta ready-for-agent, y to-tickets la trocea en tickets que atraviesan todas las capas (mattpocock/skills).

Si dudas entre ellos, el comparador de sistemas SDD te los pone uno al lado del otro.

Lo interesante es lo que tienen en común. Los cinco separan, de una forma u otra, lo que hay que construir de cómo se va a construir. Y los cinco tienen un sitio para la verificación. Esa es la columna vertebral de una spec, la escribas donde la escribas.

¿Qué pasa con la spec cuando termina el cambio?

Aquí está la diferencia que más confunde a quien empieza: hay specs de cambio y specs vivas. Una spec de cambio describe una modificación concreta y se archiva al terminar. Una spec viva describe cómo funciona hoy una parte del sistema y se actualiza con cada cambio.

La mayoría de sistemas solo trabajan con specs de cambio. Escribes la spec de la feature, la implementas y la spec se queda en una carpeta como registro histórico. Funciona, pero con los meses tienes cuarenta specs de exportación y ninguna dice cómo se exporta hoy.

OpenSpec resuelve eso con el delta. Cada cambio no reescribe la spec viva: lleva un fichero que solo dice qué requisitos se añaden, se modifican, se eliminan o se renombran.

## ADDED Requirements

### Requirement: Exportar con fecha de creación
El CSV MUST incluir la fecha de creación de cada tarea.

#### Scenario: Tarea con fecha
- **GIVEN** una tarea creada el 3 de noviembre
- **WHEN** el usuario exporta el proyecto
- **THEN** la fila de esa tarea incluye 2026-11-03

## REMOVED Requirements

### Requirement: Exportar a Excel
**Reason**: Nadie lo usaba y duplicaba el código del CSV.
**Migration**: Los usuarios exportan a CSV y lo abren con Excel.

Al archivar el cambio, OpenSpec aplica el delta sobre la spec viva. La carpeta del cambio se guarda como historia y la spec viva queda al día, como un git merge pero de requisitos.

Mapa de metro con dos líneas. La línea de la spec viva recorre el tiempo con la versión de cada momento de la capacidad de exportar. De ella sale una línea de cambio que pasa por proponer, aclarar, implementar y verificar, y vuelve a la línea principal en la estación archivar, donde el delta se funde con la spec viva

Los otros sistemas tienen su propia forma de cerrar el círculo:

  • Spec Kit 1.4 añadió /converge, que compara el código con la spec, el plan y las tareas y anota lo que falta.
  • PAUL obliga a cerrar cada plan con UNIFY: escribe un SUMMARY.md con los criterios de aceptación cumplidos, las decisiones tomadas y las desviaciones respecto al plan.
  • GSD termina cada fase con un VERIFICATION.md que marca cada verdad como verificada, fallida o dudosa, con evidencia.

En todos los casos la idea es la misma: una spec que no se contrasta con el código al final se convierte en ficción. Y una spec que se contrasta es la mejor documentación que vas a tener del proyecto.

De la teoría a tu repo

Specs vivas y deltas, sobre un proyecto real

El ciclo completo con OpenSpec (proponer, aplicar, verificar y archivar) sobre código que ya existe, con un paso de verificación que OpenSpec no trae de serie y un esquema para documentar código heredado antes de tocarlo.

Abrir la guía →

Guía a fondo con OpenSpec

¿Cómo sabes que tu spec ya no es una spec?

Hay síntomas fáciles de detectar que indican que el documento se ha convertido en otra cosa. Varios sistemas los convierten en reglas que se pueden comprobar con una máquina, y sirven aunque no uses ninguno.

Tiene rutas de fichero o código. Matt Pocock no permite ni una ruta en la spec. Si aparece src/services/export.ts, lo que tienes es un plan disfrazado.

Un requisito ocupa un párrafo entero. OpenSpec corta en 500 caracteres. Un requisito más largo suele llevar dos o tres comportamientos mezclados, y cada uno merece su escenario.

Tiene más de tres dudas abiertas. Spec Kit no deja pasar de tres [NEEDS CLARIFICATION]. Con más, la spec no está lista para el agente: está lista para una conversación con quien sepa las respuestas.

Las tareas no dicen cómo se verifican. Es la regla de PAUL: sin ficheros, acción, verificación y criterio de hecho, la tarea es un deseo.

El bloque de notas crece. Cuando las notas ocupan más que los requisitos, la spec está guardando cosas que pertenecen a otro sitio: un ADR, el AGENTS.md o la papelera.

Nadie la ha leído después de implementar. Es el síntoma más común y el más caro. La spec que no se contrasta al final no se diferencia de un prompt largo.

Si quieres ver estos fallos en acción, con ejemplos, los repasamos en los errores más comunes al hacer SDD.

Curso · paso a paso

Escribe tu primera spec con un agente al lado

Ya sabes qué partes tiene. En este curso escribes una spec con OpenSpec sobre un proyecto real, en modo asistido, y ves cómo el agente la convierte en código y la verifica.

Empezar el curso →

Para terminar

Una spec no es un documento largo ni un requisito de proceso. Es la respuesta escrita a la pregunta que el agente no te va a hacer: qué tiene que pasar, exactamente, y cómo sabrás que ha pasado.

Conocer las seis familias de bloques no significa usarlas todas. Significa saber cuál te falta cuando el agente vuelve con algo que no esperabas. Si se inventó una funcionalidad, faltaba fuera de alcance. Si tocó lo que no debía, faltaba no tocar. Si dijo que estaba hecho y no lo estaba, faltaba verificación.

Empieza con la versión mínima, añade bloques cuando un fallo te diga cuál y deja que la spec crezca con el proyecto.

Y la próxima vez que escribas “añade exportar a CSV”, acuérdate del proyecto vacío.

TL;DR

  • 📄 Una spec es el contrato de comportamiento de un cambio: dice qué tiene que pasar y cómo se comprueba, no cómo se programa.
  • 🧭 No es un plan, un PRD, un ticket ni un AGENTS.md: cada uno responde a otra pregunta y vive un tiempo distinto.
  • 🧩 Sus bloques se agrupan en seis familias (por qué, qué, cómo, tareas, verificación y gobierno), y cuántos usas depende del tamaño y el riesgo del cambio.
  • ✍️ Los escenarios siguen Given/When/Then; en OpenSpec, con cuatro almohadillas o se ignoran.
  • 🔁 Hay specs de cambio, que se archivan, y specs vivas, que se actualizan con deltas; las dos solo sirven si se contrastan con el código al terminar.

Preguntas frecuentes

¿Qué es una spec en programación?

Una spec (de specification, especificación) es un documento que describe qué debe hacer un cambio de software de forma que se pueda comprobar. Habla de comportamiento, no de implementación, y vive versionada en el repositorio junto al código.

¿Qué diferencia hay entre una spec y un PRD?

El PRD describe un producto o una iniciativa desde el negocio: qué se quiere conseguir y por qué. La spec baja a un cambio concreto y dice qué comportamiento exacto debe tener y cómo se verifica. Un PRD puede dar lugar a varias specs.

¿Qué diferencia hay entre una spec y un plan?

La spec dice qué tiene que pasar; el plan, cómo se va a construir. Una forma rápida de distinguirlos: si cambias de librería y la frase sigue siendo cierta, es spec; si deja de serlo, es plan.

¿Qué partes debe tener una spec?

Las partes se agrupan en seis familias: por qué (problema y objetivo), qué (requisitos, escenarios, casos límite, fuera de alcance), cómo (decisiones y riesgos), tareas, verificación (criterios de aceptación y comandos) y gobierno (estado y ficheros que no se tocan). No hace falta usarlas todas.

¿Cuánto debe ocupar una spec?

Lo justo para que no queden huecos importantes. Una feature pequeña cabe en una pantalla; una migración necesita más bloques, como riesgos y vuelta atrás. Si las notas crecen más que los requisitos, la spec está guardando cosas que van en otro sitio.

¿Qué es un escenario Given/When/Then?

Es un ejemplo concreto de comportamiento con tres partes: un estado inicial (Given), una acción (When) y un resultado observable (Then). Se usa en las specs porque cada escenario se traduce casi directamente a un test.

¿Qué es una spec delta?

Es un fichero que describe solo lo que un cambio añade, modifica, elimina o renombra respecto a la spec viva de una funcionalidad. OpenSpec lo usa para que, al archivar el cambio, la spec viva quede actualizada sin reescribirla entera.

¿Qué diferencia hay entre una spec viva y una spec de cambio?

La spec de cambio describe una modificación concreta y se archiva al terminar. La spec viva describe cómo funciona hoy una parte del sistema y se actualiza con cada cambio. La mayoría de herramientas solo usan la primera; OpenSpec combina las dos.

¿Se puede usar una spec sin OpenSpec ni Spec Kit?

Sí. Una spec es un fichero Markdown con una estructura clara, y cualquier agente de IA puede leerla. Las herramientas añaden comandos, validación y un flujo, pero el valor está en el contenido del documento.

¿En qué idioma escribo la spec?

En el que piense tu equipo. Lo único que conviene dejar en inglés son las palabras clave que reconocen las herramientas, como Given, When, Then o MUST, y los nombres de sección que exija tu sistema.

Fuentes

Imagen de Daniel Primo
Claude, IA de Anthropic

Escrito con la ayuda de la IA generativa de Claude, fuentes fidedignas y con un human in the loop:
Dani Primo.

CEO en pantuflas de Web Reactiva. Programador y formador en tecnologías que cambian el mundo y a las personas. Activo en linkedin, en substack y canal @webreactiva en telegram

12 recursos para developers cada domingo en tu bandeja de entrada

Además de una skill práctica bien explicada, trucos para mejorar tu futuro profesional y una pizquita de humor útil para el resto de la semana. Gratis.