Desarrollo impulsado por especificación con IA: OpenSpec y Spec Kit

El desarrollo impulsado por especificación invierte el bucle usual de prompt-y-reza: escribes una especificación precisa — requisitos, historias de usuario, criterios de aceptación — y el agente de codificación genera el plan, las tareas y el código de ese documento. La especificación, no el historial de chat, es lo que revisas, y permanece en el repo después de que se envía el código. OpenSpec y GitHub Spec Kit son los dos toolkits de código abierto que conectan este flujo de trabajo en Claude Code, Cursor y otros agentes a través de comandos slash, y este laboratorio recorre ambos de extremo a extremo en una pequeña característica: límite de velocidad en un endpoint de API.

Lo que el desarrollo impulsado por especificación realmente cambia

En una sesión de agente normal escribes una instrucción, el agente edita archivos y revisas el diff resultante. Todo lo que asumió sobre alcance, casos límite y manejo de errores se mantuvo implícito en el prompt, y solo descubres que estaba mal leyendo el código.

El desarrollo impulsado por especificación (SDD) inserta un documento entre la instrucción y el código: una especificación que establece lo que hace la característica y una lista de escenarios que deben ser verdaderos (criterios de aceptación). Revisas ese documento primero; solo entonces el agente lo convierte en un plan, una lista de tareas y código. La puerta de revisión se mueve de «¿es correcto este diff?» a «¿es correcta esta especificación?», y una especificación es mucho más corta de verificar que un diff tocando una docena de archivos.

Ambos toolkits a continuación implementan esta forma — proponer/especificar, planificar, implementar, verificar — como comandos slash que el agente ejecuta en su propio chat. La CLI solo instala la herramienta y los archivos de comando; el agente ejecuta cada otro paso.

OpenSpec: instalar y el bucle proponer → aplicar → archivar

OpenSpec se envía como un único binario sin dependencia de Node.js. Elige una ruta de instalación:

# macOS and Linux
curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh

# Windows PowerShell
irm https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.ps1 | iex

# Alternative: npm (needs Node.js 20.19.0+) or Homebrew
npm install -g @fission-ai/openspec@latest
brew install openspec

Inicializa dentro de tu proyecto:

cd your-project
openspec init                        # interactive tool picker
openspec init --tools claude,cursor  # set up specific tools, no prompts

openspec init escribe una carpeta openspec/ e imprime qué spelling de comando slash usan tus herramientas elegidas — el nombre canónico es /opsx:propose, pero Cursor y Copilot lo leen como /opsx-propose, Amazon Q como @opsx-propose, Codex como $openspec-propose. El perfil predeterminado proporciona tres comandos: /opsx:explore (una pasada de pensamiento sin apuestas antes de comprometerse con un plan), /opsx:propose <nombre-cambio> (crea openspec/changes/<nombre-cambio>/ con proposal.md, una carpeta specs/, design.md y tasks.md), /opsx:apply (implementa las tareas) y /opsx:archive (mueve la carpeta a openspec/changes/archive/<fecha>-<nombre-cambio>/ y fusiona sus deltas de especificación en la carpeta openspec/specs/ del proyecto).

Un perfil expandido agrega /opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive y /opsx:onboard vía openspec config profile más openspec update, que también actualiza los archivos de comando instalados después de una actualización de CLI.

Las mismas acciones existen como comandos de terminal, útiles para escribir scripts o verificar un cambio sin abrir el agente:

openspec list                    # active changes
openspec list --specs            # specs with requirement counts
openspec show add-rate-limit --diff   # requirement diffs for one change
openspec validate add-rate-limit      # check one change's artifacts
openspec validate --all               # check everything
openspec archive add-rate-limit -y    # CLI equivalent of /opsx:archive

GitHub Spec Kit: constitución, especificar, planificar, tareas, implementar, converger

Spec Kit es una CLI de Python, instalada con uv:

uv tool install specify-cli
specify init my-project --integration claude
cd my-project

--integration claude apunta a Claude Code; cámbialo por copilot u otra clave de agente soportada. Para Claude Code, la instalación escribe un archivo de habilidad por comando bajo .claude/skills/speckit-<nombre>/SKILL.md, invocado como /speckit-specify, /speckit-plan y así — la forma con guiones, no la /speckit.specify con puntos que los docs de Spec Kit usan como notación neutral. Codex usa $speckit-specify; Kimi usa /skill:speckit-specify.

Ejecuta estos uno a la vez en el chat del agente, leyendo cada resultado antes del siguiente:

/speckit-constitution Create principles focused on code quality, testing, and maintainability.
/speckit-specify Limit requests on POST /api/orders to protect the order service from bursts.
/speckit-plan Node.js with an in-memory token bucket per API key, no new infrastructure.
/speckit-tasks
/speckit-implement
/speckit-converge

/speckit-constitution se ejecuta una vez por proyecto y registra los principios contra los que se verifica cada paso posterior. /speckit-specify convierte una descripción de lenguaje natural en spec.md — requisitos e historias de usuario, no stack técnico. /speckit-plan genera plan.md, donde pertenece el stack técnico. /speckit-tasks genera un tasks.md ordenado por dependencia, dividido en Configuración, Fundamental, una fase por historia de usuario, luego Pulido. /speckit-implement ejecuta tasks.md en orden y es el único comando que escribe código de aplicación. /speckit-converge verifica el resultado contra los tres artefactos; es solo apéndice, su única escritura posible es agregar tareas bajo una sección «Convergencia» si encuentra brechas, e informa Converged cuando no queda nada.

Tres puertas de calidad opcionales se insertan en la secuencia completa (constitución → especificar → aclarar → planificar → lista de verificación → tareas → analizar → implementar → converger): /speckit-clarify hace hasta cinco preguntas dirigidas sobre áreas subespecificadas y escribe las respuestas de vuelta en spec.md; /speckit-checklist genera una lista de verificación de propiedad del revisor probando la especificación en sí por completitud; /speckit-analyze es una pasada de solo lectura reportando conflictos a través de los tres artefactos antes de que implementes nada.

Spec Kit rastrea la característica «activa» a través de .specify/feature.json, no tu rama de git. Dos extensiones incluidas siguen el mismo estilo: specify extension add bug agrega /speckit-bug-assess, /speckit-bug-fix y /speckit-bug-test, con reportes bajo .specify/bugs/<slug>/; specify extension add assess agrega un flujo de evaluación de ideas de cinco pasos bajo .specify/assessments/<slug>/.

OpenSpec vs Spec Kit de un vistazo

Elige OpenSpec para un bucle ligero con la libertad de saltar de vuelta a una propuesta a mitad de la implementación. Elige Spec Kit para una secuencia más estricta y verificada con una constitución escrita y una verificación de consistencia automatizada antes de que se escriba código.

Laboratorio: especificar un límite de velocidad, generar el plan, implementar, revisar

La característica: limitar POST /api/orders a 20 solicitudes por minuto por clave API, devolviendo 429 con un encabezado Retry-After cuando la persona que llama se excede.

Paso 1 — escribe los criterios de aceptación primero, independiente de cualquiera de las herramientas

Antes de tocar un comando slash, escribe la historia de usuario y los criterios de aceptación en lenguaje simple — este es el documento que realmente revisarás y la entrada que ambas herramientas necesitan.

## User story

As an API consumer, I need predictable rate limiting on order creation
so a retrying client cannot overload the order service, and so I know
exactly when to retry.

## Acceptance criteria

### Scenario: under the limit
- GIVEN an API key with fewer than 20 requests in the current minute
- WHEN it sends POST /api/orders
- THEN the request is processed normally

### Scenario: over the limit
- GIVEN an API key with 20 requests already counted in the current minute
- WHEN it sends one more POST /api/orders
- THEN the response is 429 with a Retry-After header in seconds

### Scenario: window resets
- GIVEN an API key that was rate-limited in the previous minute
- WHEN a new minute window starts
- THEN its next request is processed normally

Paso 2 — conviértelo en el formato de especificación de la herramienta

Con OpenSpec, ejecuta /opsx:propose add-rate-limit y el agente crea openspec/changes/add-rate-limit/ para ti. Reemplaza el borrador generado specs/ con tus propios escenarios, traducidos a la gramática de requisitos de OpenSpec:

## ADDED Requirements

### Requirement: Order creation rate limit
The orders API SHALL limit POST /api/orders to 20 requests per minute
per API key and SHALL reject requests over that limit with 429.

#### Scenario: Over the limit
- **WHEN** an API key sends a 21st request within the same minute
- **THEN** the API responds 429 and includes a Retry-After header in seconds

#### Scenario: Window resets
- **WHEN** a new minute window starts for a previously limited key
- **THEN** that key's next request is processed normally

Con Spec Kit, ejecuta /speckit-specify y pega la historia de usuario y escenarios como argumento. Si un escenario es ambiguo para el agente — ¿por clave API o por IP? — ejecuta /speckit-clarify antes de pasar; ese es exactamente el tipo de ambigüedad para el que fue construido.

Paso 3 — planificar, implementar, revisar contra la especificación

OpenSpec: edita design.md si tienes una preferencia técnica, luego /opsx:apply para implementar. Spec Kit: /speckit-plan con tus restricciones técnicas, luego /speckit-tasks, luego /speckit-implement.

Luego revisa el archivo de especificación junto al diff, escenario por escenario: ¿obtiene el 21º solicitud un 429? ¿Contiene Retry-After un número de segundos? ¿Se reinicia una clave después de que pase la ventana? Mantén pruebas en el bucle — ver flujo de trabajo TDD con un agente de IA. Con Spec Kit, ejecuta /speckit-converge y espera Converged; tareas adjuntas significan un escenario perdido, no un error de herramienta. Con OpenSpec, ejecuta openspec validate add-rate-limit antes de /opsx:archive para que la especificación archivada y el código enviado coincidan. Solo entonces archiva o converge el cambio — el mismo mecanismo de comando slash que ambos toolkits usan se cubre en el laboratorio de comandos personalizados.

Trampas

Las especificaciones vagas producen código vago. «Agregar limitación de velocidad» no es una especificación — ningún número, ninguna ventana, ningún contrato de respuesta. Sin eso, el agente los inventa, y tu revisión no tiene nada concreto para verificar.

Especificación drift: el agente edita la especificación para que coincida con su propio código. Si una ejecución que se suponía debía escribir código también silenciosamente reescribió un requisito en spec.md, ese requisito ahora describe lo que el agente construyó, no lo que pediste. Diferencia los archivos de especificación después de cada ejecución de /opsx:apply o /speckit-implement, no solo el código de aplicación.

Un /speckit-converge verde o un /opsx:apply limpio no es la revisión. /speckit-converge solo verifica los artefactos que se le dieron; dirá Converged en una especificación mala que fue implementada consistentemente. La lectura escenario-por-escenario en el Paso 3 anterior es la parte que ninguna verificación automatizada reemplaza.

Ejecutar ambas herramientas en el mismo repo sin elegir una como fuente de verdad. OpenSpec escribe a openspec/; Spec Kit escribe a .specify/. Tu agente no tiene forma de saber cuál honrar para un cambio dado — decide por proyecto, no por sesión.

Omitiendo /speckit-clarify u openspec validate porque la característica se ve pequeña. Un limitador de 20-solicitudes-por-minuto tiene decisiones sin establecer — por clave o por IP, ventana fija o deslizante — que son baratas de resolver antes de la planificación y caras de encontrar después de que /speckit-implement ya ha elegido una respuesta.

Preguntas frecuentes

¿Qué es el desarrollo impulsado por especificación con agentes de codificación de IA?

Es un flujo de trabajo donde escribes una especificación primero — requisitos, historias de usuario y criterios de aceptación como escenarios concretos — y el agente de codificación genera el plan, la lista de tareas y el código de ese documento. Revisas la especificación antes de que exista ningún código, en lugar de revisar un diff después de que el agente ya haya adivinado tu intención.

¿Cómo es OpenSpec diferente de GitHub Spec Kit?

OpenSpec se envía como un único binario con un bucle predeterminado ligero: proponer, aplicar, archivar. GitHub Spec Kit es una CLI de Python (instalada con uv) con un flujo más largo controlado por fase — constitución, especificar, planificar, tareas, implementar, converger — más puertas de calidad opcionales de aclaración, lista de verificación y análisis. OpenSpec favorece iterar en cualquier artefacto en cualquier momento; Spec Kit favorece una secuencia más estricta y verificada.

¿Cuál es el comando OpenSpec exacto para iniciar un nuevo cambio?

En el chat del agente, escribe /opsx:propose <nombre-cambio> (Cursor y GitHub Copilot lo escriben /opsx-propose, Amazon Q usa @opsx-propose, Codex usa $openspec-propose). Desde una terminal en lugar del agente, openspec new change <nombre-cambio> crea la misma carpeta sin pasar por el agente.

¿Qué comando de Spec Kit realmente escribe el código?

/speckit-implement es el único comando que ejecuta tasks.md y produce código, ejecutando cada fase en orden de dependencia. /speckit-specify, /speckit-plan y /speckit-tasks solo producen artefactos Markdown (spec.md, plan.md, tasks.md); /speckit-converge verifica el resultado después y solo agrega tareas nuevas, nunca edita código.

¿Necesito Python para OpenSpec o Spec Kit?

GitHub Spec Kit necesita Python 3.11+ y la herramienta uv, instalada con uv tool install specify-cli. El instalador independiente de OpenSpec es un único binario sin requisito de Node.js; su ruta de instalación npm (npm install -g @fission-ai/openspec@latest) necesita Node.js 20.19.0 o superior, y también está disponible una fórmula de Homebrew.