Guías · Agentes de IA
OpenSpec: qué es y cómo se usa para trabajar con agentes de código
Qué es OpenSpec, cómo se instala, cómo se escribe un requisito y el ciclo proponer, aplicar y archivar. Con nuestras cifras: 22 cambios y 439 tareas en quince días.
Por Rafa Martínez y el equipo de Kalmia Zen · 8 min de lectura · Actualizada el 9 de octubre de 2026
- Pides Cuentas qué quieres cambiar, con tus palabras.
- Propone Escribe la propuesta, los requisitos, el diseño y las tareas.
- Revisas Lees el plan y lo corriges antes de que se toque el código.
- Aplica Hace las tareas una a una y las va marcando.
- Archiva Los requisitos nuevos pasan a la especificación viva del proyecto.
Leer la transcripción
Hola, vamos a ir directos al grano en este nuevo análisis. Hoy toca hablar de un cambio verdaderamente radical en el mundo de la programación con inteligencia artificial. Pensemos en esto. Estamos dejando atrás esos caóticos e interminables chats con la máquina, ya sabéis, esos donde el contexto se evapora y los planes acaban en el olvido, para dar el salto a un desarrollo completamente estructurado gracias a OpenSpec. Es, sin duda, un cambio de mentalidad absoluto a la hora de trabajar con asistentes de código, y vamos a desgranar exactamente cómo funciona. A ver, seamos sinceros. Pedirle un arreglillo rápido a un agente directamente en un chat funciona a las mil maravillas. Pero ¿qué pasa cuando los proyectos crecen? Pues que caemos de lleno en la trampa del chat infinito. El plan inicial se pierde en cientos de mensajes. El agente acaba entendiendo una cosa. El equipo de desarrollo pensaba otra
totalmente distinta. Y a los pocos días, nadie recuerda por qué el sistema funciona de esa manera. Frente a este caos, la solución es evidente. Necesitamos una planificación estructurada. Un sistema donde la memoria del proyecto se conserve intacta, el contexto no se pierda jamás, y el alcance quede clarísimo desde el minuto 1. Y justo aquí es donde entra en juego OpenSpec. Hablamos de una herramienta de código abierto bajo licencia MIT, que por cierto es 100% compatible con más de 30 asistentes del mercado, como Claude Code, Cursor o GitHub Copilot. Al integrarlo, simplemente se añade una carpeta llamada OpenSpec al proyecto. Y esto impone una regla de oro que es inquebrantable. Antes de que el agente escriba una sola línea de código, el plan tiene que estar escrito y validado en los
ficheros del propio repositorio. O sea, primero acordamos qué debe hacer el sistema con total claridad, y solo después nos ponemos a programar. Si nos fijamos en la estructura, esa carpeta principal divide el entorno de trabajo en dos grandes pilares. Por un lado tenemos la carpeta Specs. Pensad en ella como la especificación viva del proyecto. Es la que guarda exactamente cómo se comporta el sistema a día de hoy, sin ninguna alteración. Y por el otro lado tenemos la carpeta Changes, que es la que almacena las modificaciones activas. Es decir, mientras un cambio está en curso, y cociéndose en su propio espacio, la especificación principal ni se toca. Es un aislamiento perfecto que corta el caos de raíz y mantiene la estabilidad del código en todo momento. Bueno, ¿y cómo se organiza un cambio activo por dentro? Pues resulta que consta de cuatro
piezas fundamentales, todas escritas en formato Markdown. Arrancamos con la propuesta, que define el problema y el alcance de forma súper concisa. Luego están los requisitos en la carpeta Specs, que indican explícitamente qué cosas del código se añaden, se modifican o se eliminan. Después pasamos al documento de diseño, donde van las decisiones técnicas clave. Y finalmente, un archivo de tareas con su clásica lista de casillas de verificación. Al trocear la información de una forma tan meticulosa, le estamos dando al agente de inteligencia artificial un contexto impecable para poder trabajar. Todo esto facilita un ciclo de trabajo rapidísimo y sin fricciones, dividido en cuatro pasos muy bien definidos. Primero, proponer. Primero, usando el comando /opsx:propose, el agente crea la carpeta del cambio ya con el plan completo. Segundo, validar y revisar ese plan a fondo. Tercero, aplicar. Con /opsx:apply, el agente se pone manos a la obra y ejecuta las tareas de la lista una a una, marcándola según avanza. Y cuarto, archivar. Mediante /opsx:archive, los nuevos requisitos pasan a ser parte de la especificación viva del proyecto. En resumen, una colaboración redonda y súper fluida entre humanos y máquinas. El gran secreto de todo este sistema se resume en una frase que, la verdad, da totalmente en el clavo. Corregir un plan cuesta minutos. Corregir código mal escrito lleva horas. Ese segundo paso de validación del que acabamos de hablar es, sin lugar a dudas, la parte más valiosa de OpenSpec. Aquí podemos usar el comando openspec validate --strict para comprobar el formato de los archivos automáticamente, pero lo verdaderamente crucial es que el equipo apruebe la lógica del plan. Arreglar un error en un texto plano es cuestión de segundos, pero deshacer una maraña de código mal
ejecutado por una IA, uff, eso cuesta horas o incluso días de trabajo perdidos. Ahora bien, para que la fase de ejecución vaya verdaderamente a toda pastilla, hay una práctica indispensable, el etiquetado de tareas. En el archivo Markdown usamos la etiqueta hashtag auto para indicarle a la máquina que puede ejecutar y comprobar esa tarea por su cuenta, porque tiene un método claro para verificarse. Y usamos la etiqueta hashtag manual para aquellas acciones que sí o sí requieren intervención humana, como meter claves de seguridad, dar permisos o procesar pagos. Esta separación tan sencilla es vital, porque evita que el agente se quede colgado esperando aprobaciones y le permite avanzar a toda velocidad en lo que sí puede automatizar. Y toda esta teoría nos lleva a una cifra espectacular, 439. Ojo, no es un número puesto al azar. Este es el altísimo volumen total
de tareas que se han gestionado con éxito utilizando este mismo marco de trabajo en los laboratorios de Kalmia Zen. No estamos hablando de un experimento de laboratorio teórico ni de una simple prueba de concepto. Es un sistema real, testeado en un entorno de trabajo del día a día, que escala la producción de software de una forma increíble. Para que nos hagamos una idea de lo bestia que es esto, vamos a ver los detalles. En apenas 15 días, partiendo de una auditoría técnica masiva, el sistema procesó 22 cambios complejos. Y de esas 439 tareas totales que se crearon en los planes de acción, el agente de código ejecutó y completó con éxito nada menos que 412. Es decir, utilizar especificaciones bien estructuradas y las etiquetas correctas permitió que la inteligencia artificial operase de manera casi totalmente autónoma en un tiempo verdaderamente récord.
Bueno, y para cerrar este análisis, vamos a dejar una reflexión bastante provocativa en el aire. Viendo el exitazo brutal de metodologías estructuradas como OpenSpec, cabe preguntarse ¿será que el futuro del desarrollo de software ya no pasa por teclear líneas y líneas de código, sino por ser increíblemente precisos, estructurados y claros al escribir especificaciones? Quizás el simple acto de organizar perfectamente nuestras ideas en texto plano sea la verdadera llave maestra para desatar todo el potencial de la inteligencia artificial en la programación. Muchísimas gracias por acompañarnos en este repaso a fondo.
Pedirle algo a un agente de código en una conversación funciona bien para cambios pequeños. Para los grandes, el plan se queda en el chat: el agente entiende una cosa, tú pensabas otra, y a la semana nadie recuerda por qué el sistema hace lo que hace. OpenSpec resuelve eso con una regla sencilla: antes de programar, se escribe el plan en ficheros del propio proyecto, se revisa y se valida. Después el agente lo ejecuta.
Esta guía explica qué es, cómo se instala, qué hay en cada carpeta y cómo lo usamos nosotros a diario. Si todavía no tienes ordenado el proyecto para trabajar con un agente, empieza por cómo se organiza un proyecto con Claude Code.
¿Prefieres verlo? Lo contamos en un vídeo de 4 minutos en nuestro canal de YouTube, con la demostración en nuestro propio proyecto: la lista de cambios, un requisito de verdad y las tareas marcadas #auto o #manual.
Qué es OpenSpec
Es una herramienta libre (licencia MIT) para lo que se llama desarrollo guiado por especificaciones: primero se acuerda qué debe hacer el sistema y después se programa. Se usa desde la línea de comandos y desde el propio asistente de código. Funciona con más de 30 asistentes, entre ellos Claude Code, Cursor, GitHub Copilot y Codex.
No sustituye a tu asistente ni a tu forma de trabajar. Añade una carpeta openspec/ al repositorio y unas órdenes (/opsx:propose, /opsx:apply, /opsx:archive) que el asistente sabe seguir. Todo es Markdown: lo lees y lo corriges como cualquier otro fichero, y va a git con el código.
Instalarlo
Necesita Node.js 20.19 o superior.
npm install -g @fission-ai/openspec@latest
cd tu-proyecto
openspec initopenspec init crea la carpeta openspec/ y prepara las órdenes y las skills para los asistentes que elijas. Si más adelante actualizas la herramienta, openspec update regenera esas instrucciones.
Dos ideas: lo que hay y lo que cambia
| Carpeta | Qué guarda |
|---|---|
openspec/specs/ | La especificación viva: cómo se comporta el sistema hoy, un spec.md por área |
openspec/changes/<nombre>/ | Un cambio en curso, con todo su plan |
openspec/changes/archive/ | Los cambios terminados, con su fecha delante |
openspec/config.yaml | El contexto del proyecto y tus reglas para escribir los planes |
La especificación dice cómo funciona el sistema; un cambio dice qué se va a tocar. Mientras el cambio está abierto, la especificación no se toca. Al archivarlo, lo nuevo pasa a la especificación y el cambio se guarda como historia.
Las cuatro piezas de un cambio
proposal.md: por qué y qué. El problema, el alcance y lo que se deja fuera a propósito.specs/: los requisitos que cambian, en forma de diferencias:ADDED(nuevos),MODIFIED(los que cambian) yREMOVED(los que se quitan).design.md: cómo se va a hacer. Decisiones técnicas y alternativas descartadas.tasks.md: la lista de tareas con casillas, que el agente marca según las termina.
Se escriben en ese orden porque cada una se apoya en la anterior: las tareas salen de los requisitos y del diseño. openspec status dice qué piezas tiene ya un cambio.
- Propuesta proposal.md: por qué y qué, el problema y el alcance
- Requisitos specs/: los requisitos que cambian (ADDED, MODIFIED, REMOVED)
- Diseño design.md: cómo se va a hacer, decisiones técnicas
- Tareas tasks.md: la lista de tareas con casillas
Cómo se escribe un requisito
Un requisito dice lo que el sistema debe hacer (SHALL o MUST) y se demuestra con escenarios del tipo «cuando pasa esto, entonces ocurre aquello»:
### Requirement: Una factura no se registra dos veces
El sistema SHALL ignorar una factura cuyo número y proveedor ya estén registrados.
#### Scenario: Llega la misma factura por correo y por la carpeta compartida
- **WHEN** entra una factura con un número y un proveedor que ya existen
- **THEN** no se crea otra y se avisa de que estaba repetidaDescribe el comportamiento que se observa desde fuera, no cómo se programa: eso va en el diseño. Lo bueno de este formato es que cada escenario se convierte casi solo en una prueba automática, y que un agente tiene mucho menos margen para entender otra cosa.
El ciclo: proponer, aplicar y archivar
/opsx:explore(opcional): piensas en voz alta con el agente antes de decidir nada./opsx:propose nombre-del-cambio: el agente crea la carpeta del cambio con las cuatro piezas.- Revisas. Es el paso que más rinde: corregir un plan cuesta minutos; corregir código ya escrito, horas.
openspec validate --strictcomprueba que el formato es correcto. /opsx:apply: el agente hace las tareas y las marca. Puede parar y retomarse otro día: el plan está en el fichero, no en la memoria de la conversación./opsx:archive: lo nuevo se funde con la especificación viva y el cambio pasa al archivo.
openspec list enseña los cambios abiertos y cuántas tareas lleva cada uno, y openspec view abre un panel en la terminal.
- Explorar Piensas en voz alta con el agente antes de decidir
- Proponer El agente crea la carpeta del cambio con las cuatro piezas
- Revisar Revisas el plan: es el paso que más rinde
- Validar openspec validate --strict comprueba que el formato es correcto
- Aplicar El agente hace las tareas y las marca
- Archivar Lo nuevo se funde con la especificación viva y el cambio pasa al archivo
config.yaml: tus reglas en cada plan
Este fichero tiene tres partes. context es un texto sobre el proyecto (tecnología, convenciones, idioma) que se le da al agente al escribir cualquier pieza. rules son reglas para una pieza concreta, como la propuesta o las tareas. operations son consejos para aplicar y archivar. Ninguna se comprueba sola: son instrucciones para el agente, y por eso conviene que sean pocas y claras.
Las nuestras, resumidas:
- Todo en español, salvo las palabras clave del formato (
SHALL,MUSTy los encabezados), que se quedan en inglés para que la herramienta los entienda. - Cada propuesta incluye una sección de lo que no se va a hacer.
- Ninguna tarea dura más de dos horas, y cada una termina con
#auto(la puede hacer un agente sin preguntar) o#manual(la tiene que hacer o decidir una persona: claves, gasto, configuración del equipo). - Cada tarea
#autodice cómo se comprueba: qué prueba se pasa o qué hay que mirar. - Ningún secreto en los ficheros del plan.
Cómo lo usamos nosotros
Lo adoptamos el 24 de septiembre de 2026 en el repositorio de nuestro asistente, a raíz de una auditoría técnica que dejó siete cambios de golpe. Quince días después llevamos 22 cambios y 439 tareas, de las que 412 están hechas. Unas tres de cada cuatro están marcadas #auto.
Esa marca es lo que más nos ha cambiado la forma de trabajar. Las tareas #auto las hace un agente, a menudo en sesiones largas sin nadie delante, porque cada una es pequeña, está escrita y dice cómo se comprueba. Las #manual aparecen en una lista aparte para la persona que tiene que decidir. Así el agente no se queda bloqueado esperando una decisión y nadie tiene que revisar trescientas tareas para encontrar las cinco que le tocan.
OpenSpec frente a otras herramientas
La propia página de OpenSpec se compara con dos alternativas. Presenta Spec Kit (de GitHub) como más completo pero más pesado, con fases rígidas y más documentos, y Kiro (de AWS) como potente pero ligado a su propio editor. OpenSpec se presenta como más ligero, pensado para avanzar poco a poco y para proyectos que ya existen, no sólo para empezar de cero. Es su opinión y no hemos probado las otras dos; para un equipo pequeño que ya trabaja con un asistente, lo ligero nos ha bastado.
Lo que hemos aprendido
- No todo necesita un cambio de OpenSpec. Un arreglo de diez minutos se pide en el chat. Lo usamos cuando hay más de un par de horas de trabajo o cuando el cambio toca algo delicado.
- Revisa la propuesta, no sólo el código. Ahí se decide qué se hace y qué no; el resto es ejecución.
- Tareas pequeñas y con su comprobación. Dos horas como mucho y una forma clara de saber que está bien. Es lo que permite dejar trabajar a un agente solo.
- Separa lo que hace la máquina de lo que decides tú. La marca
#auto/#manualha sido nuestra mejor regla. - Archiva. Si los cambios terminados se quedan abiertos, la lista deja de decir la verdad y la especificación viva se queda vieja.
Qué no resuelve
OpenSpec ordena el trabajo, pero no lo revisa por ti: un plan mal pensado y bien escrito se ejecuta igual de bien. Tampoco sustituye a las pruebas automáticas; los escenarios ayudan a escribirlas, pero hay que escribirlas. Y añade algo de trabajo al principio de cada cambio: compensa en los grandes y sobra en los pequeños.
Fuentes
- OpenSpec en GitHub (Fission-AI, licencia MIT)
- OpenSpec: conceptos (specs, cambios, deltas y archivo)
- OpenSpec: personalización (config.yaml y esquemas)
- OpenSpec: la línea de comandos
- OpenSpec: primeros pasos
- OpenSpec: herramientas compatibles
Registro de cambios
- 9 de octubre de 2026: primera versión.
Más sobre Agentes de IA
Hablas con Rafa Martínez, fundador ¿Qué tarea repites cada semana?
En 30 minutos te digo si merece un agente, cuánto costaría y por dónde empezar. Si no merece la pena, también te lo digo. Gratis.
¿Prefieres hablar ya? Llama al 910 052 322 (te atiende nuestro agente de voz, a cualquier hora) o escríbenos por WhatsApp.
