OpenSpec: una forma ordenada de desarrollar software con IA usando especificaciones

La inteligencia artificial está cambiando la forma en que desarrollamos software. Herramientas como Cursor, GitHub Copilot, Claude Code, Codex, Windsurf y otros asistentes permiten escribir código mucho más rápido, pero también traen un problema importante: si las instrucciones no están bien definidas, el resultado puede ser inconsistente, difícil de mantener o alejado de lo que realmente necesitábamos construir.

En ese contexto aparece OpenSpec, un framework liviano orientado al Spec-Driven Development, o desarrollo guiado por especificaciones. Su objetivo es ayudar a que los desarrolladores y los asistentes de IA trabajen sobre una base más clara: primero se define qué se quiere construir, cómo debería comportarse el sistema y qué tareas deben realizarse; recién después se pasa a la implementación. Según su sitio oficial, OpenSpec se presenta como un framework “lightweight spec-driven” y open source, pensado para funcionar sin API keys ni MCP obligatorio.

¿Qué es OpenSpec?

OpenSpec es una herramienta que permite organizar el desarrollo de software alrededor de especificaciones. En lugar de pedirle directamente a una IA “haceme esta funcionalidad”, OpenSpec propone crear una estructura previa con documentos de propuesta, diseño, tareas y cambios en las especificaciones del sistema.

La idea central es simple: antes de escribir código, se documenta la intención del cambio. Esto permite que tanto el programador como la IA entiendan mejor qué se quiere lograr, qué partes del sistema se van a modificar y qué criterios deben cumplirse.

En el repositorio oficial se lo define como una herramienta de Spec-Driven Development para asistentes de programación con IA. Su filosofía se resume en varios principios: ser fluido y no rígido, iterativo y no waterfall, fácil y no complejo, útil tanto para proyectos nuevos como para sistemas existentes, y escalable desde proyectos personales hasta equipos empresariales.

¿Para qué sirve OpenSpec?

OpenSpec sirve principalmente para darle estructura al trabajo con inteligencia artificial en proyectos de software. Cuando usamos IA para programar, muchas veces el contexto queda encerrado en una conversación. Si cerramos el chat, cambiamos de herramienta o se suma otro desarrollador, gran parte de esa intención original puede perderse.

OpenSpec busca resolver ese problema guardando las especificaciones dentro del propio repositorio del proyecto. Es decir, las specs viven junto al código, organizadas por capacidades o funcionalidades. Por ejemplo, un sistema podría tener especificaciones para login, sesiones, carrito de compras, pagos, usuarios o reportes.

Esto tiene varias ventajas. Primero, permite que el asistente de IA tenga un contexto más claro sobre cómo debería funcionar una parte del sistema. Segundo, ayuda a que un nuevo desarrollador pueda entender la lógica funcional sin tener que leer todo el código fuente. Tercero, deja registro de la intención detrás de cada funcionalidad, no solamente de la implementación técnica.

En otras palabras, OpenSpec no reemplaza al programador ni al criterio técnico. Lo que hace es ordenar el diálogo entre la persona, el equipo y la IA.

El problema de programar solo con prompts

Uno de los errores más comunes al usar IA para programar es trabajar únicamente con prompts sueltos. Por ejemplo:

“Agregá un botón para recordar sesión durante 30 días”.

Ese pedido puede parecer claro, pero en realidad deja muchas preguntas abiertas. ¿Qué pasa con la cookie? ¿Cuánto dura la sesión normal? ¿Debe invalidarse el token? ¿Qué ocurre si el usuario cierra sesión manualmente? ¿Hay que modificar la base de datos? ¿Se debe actualizar la documentación?

OpenSpec propone convertir ese pedido en una especificación revisable. En su sitio oficial se muestra un ejemplo de una funcionalidad de “Remember me”, donde el cambio no se limita al código, sino que genera una propuesta, decisiones técnicas, tareas de implementación y deltas de especificación que muestran cómo cambian los requisitos del sistema.

Esto permite revisar la intención antes de escribir código. Y eso es clave: muchas fallas de software no ocurren porque el código esté mal escrito, sino porque se programó algo distinto a lo que realmente se necesitaba.

¿Cómo funciona OpenSpec?

El flujo general de OpenSpec puede resumirse en tres momentos: proponer, implementar y archivar.

Primero, el desarrollador describe una idea o cambio. Por ejemplo: agregar modo oscuro, implementar recuperación de contraseña o crear un módulo de reportes. OpenSpec ayuda a generar una carpeta de cambio dentro del proyecto, que puede incluir archivos como proposal.md, design.md, tasks.md y una carpeta de especificaciones. En el README oficial se muestra un ejemplo donde el comando /opsx:propose add-dark-mode genera esos artefactos antes de pasar a la implementación.

Segundo, se revisan esos documentos. Esta etapa es importante porque permite detectar problemas antes de programar. El programador puede ajustar el alcance, corregir requisitos, dividir tareas o aclarar decisiones técnicas.

Tercero, se implementa el cambio. La IA puede usar esos documentos como contexto para escribir código de forma más alineada. Luego, cuando el cambio ya está incorporado, se archiva y las especificaciones quedan actualizadas como documentación viva del sistema.

Este enfoque convierte a las especificaciones en parte del ciclo de vida del desarrollo, no en documentos que se escriben una vez y después se abandonan.

OpenSpec y los proyectos existentes

Un punto interesante de OpenSpec es que no está pensado solamente para proyectos nuevos. De hecho, su documentación destaca el enfoque brownfield-first, es decir, orientado a sistemas existentes y maduros, donde el gran desafío no es empezar de cero, sino entender cómo funciona lo que ya está construido.

Esto es especialmente útil en entornos reales de trabajo, donde muchas veces heredamos sistemas con años de historia, documentación incompleta, decisiones técnicas acumuladas y funcionalidades que nadie recuerda exactamente por qué fueron hechas de determinada manera.

En esos casos, OpenSpec puede ayudar a documentar progresivamente. No hace falta escribir todas las especificaciones del sistema desde el primer día. Se pueden crear specs a medida que se modifican módulos o se agregan nuevas funcionalidades. Esta forma incremental resulta más realista para equipos de desarrollo que trabajan sobre sistemas en producción.

Herramientas compatibles

Otro aspecto importante es que OpenSpec busca ser una capa universal para distintos asistentes de programación. Según su sitio oficial, tiene soporte para herramientas como Claude Code, Cursor, Codex, GitHub Copilot, OpenCode, Windsurf, Gemini CLI, Cline, RooCode, Amazon Q y otras.

Esto es relevante porque el mundo de los asistentes de IA cambia muy rápido. Una herramienta que hoy es popular puede dejar de serlo en pocos meses. OpenSpec intenta evitar que las especificaciones dependan de un único editor, modelo o proveedor. La idea es que el conocimiento funcional del proyecto permanezca en el repositorio, independientemente de la IA que se use para programar.

Instalación básica

Para empezar, OpenSpec requiere Node.js 20.19.0 o superior. La instalación global se realiza con npm:

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

Luego se ingresa al directorio del proyecto y se inicializa:

cd tu-proyecto
openspec init

A partir de ahí, se puede comenzar a trabajar con comandos como:

/opsx:propose agregar-login-con-dni

Diferencia entre OpenSpec y el “modo plan” de una IA

Muchas herramientas de IA ya tienen algún tipo de “plan mode” o modo de planificación. Entonces, ¿para qué usar OpenSpec?

La diferencia principal está en la persistencia. Un modo plan suele servir dentro de una conversación específica. OpenSpec, en cambio, busca que ese plan quede guardado en el repositorio y pueda acompañar todo el ciclo de vida del desarrollo. Según la propia explicación de OpenSpec, el objetivo no es solamente planificar una respuesta, sino construir una capa de planificación que pueda extenderse a varias sesiones y compartirse con otros desarrolladores.

Esto lo vuelve más útil para equipos, revisiones de código, pull requests y mantenimiento a largo plazo.

¿OpenSpec es volver al modelo waterfall?

Una crítica posible es pensar que escribir especificaciones antes de programar significa volver a metodologías pesadas, lentas y burocráticas. Sin embargo, OpenSpec aclara que su propuesta no es esa. La idea no es pasar meses documentando antes de escribir una línea de código, sino dedicar unos minutos a pensar, ordenar y acordar lo que se va a construir.

Esto se parece más a una práctica de ingeniería liviana que a una metodología rígida. El objetivo es evitar que la velocidad de la IA nos lleve a construir rápido, pero mal. En proyectos reales, especialmente cuando hay usuarios, clientes o áreas institucionales involucradas, esa diferencia es muy importante.