Los asistentes de programación con IA han cambiado la forma de escribir software, pero también han dejado al descubierto un problema nuevo: cuando los requisitos viven solo en el chat, el desarrollo se vuelve difícil de controlar. Una conversación larga puede empezar con una idea clara y acabar en una implementación que no encaja del todo con el producto, rompe una convención interna o resuelve un problema distinto al que se quería atacar.
OpenSpec nace precisamente para cubrir ese hueco. El proyecto, publicado en GitHub por Fission AI bajo licencia MIT, se presenta como un marco de desarrollo guiado por especificaciones para asistentes de código. Su objetivo no es sustituir a herramientas como Claude Code, Codex, Cursor, Gemini CLI o similares, sino añadir una capa ligera de planificación y trazabilidad antes de que la IA empiece a tocar código.
La idea es sencilla: antes de implementar, se acuerda qué se va a construir, por qué, qué requisitos debe cumplir, qué diseño técnico seguirá y qué tareas concretas tendrá que ejecutar el agente. En lugar de lanzar un prompt genérico y confiar en que el modelo entienda todo el contexto, OpenSpec organiza el trabajo en artefactos dentro del repositorio.
Especificaciones antes de código
OpenSpec parte de una filosofía bastante práctica: fluido antes que rígido, iterativo antes que secuencial, fácil antes que complejo y preparado para proyectos ya existentes, no solo para repositorios nuevos. Ese último punto es importante. Muchas herramientas de desarrollo asistido por IA funcionan muy bien en demos limpias, pero sufren cuando entran en un producto real con años de decisiones, módulos heredados, convenciones internas y cambios parciales.
El flujo básico empieza con comandos como /opsx:explore y /opsx:propose. El primero permite explorar una idea sin compromiso. Por ejemplo, un desarrollador puede pedir “quiero añadir modo oscuro, pero no sé cuál es la forma más limpia”. El asistente revisa el proyecto, estudia la configuración de estilos y propone un camino técnico. Si el usuario acepta, puede pasar a /opsx:propose add-dark-mode.
A partir de ahí, OpenSpec crea una carpeta de cambio con varios documentos: proposal.md, para explicar el motivo y el alcance; specs/, con requisitos y escenarios; design.md, con el enfoque técnico; y tasks.md, con la lista de implementación. Después, el agente puede aplicar las tareas con /opsx:apply y, cuando todo termina, archivar el cambio con /opsx:archive.
| Artefacto | Para qué sirve |
|---|---|
proposal.md | Explica por qué se hace el cambio y qué se espera conseguir |
specs/ | Define requisitos, escenarios y comportamiento esperado |
design.md | Describe el enfoque técnico antes de implementar |
tasks.md | Divide el trabajo en pasos verificables |
archive/ | Guarda el cambio cerrado y actualiza las especificaciones |
Este enfoque reduce uno de los problemas más habituales con agentes de código: la improvisación. La IA puede ser muy eficaz escribiendo, modificando o revisando código, pero necesita límites. OpenSpec intenta que esos límites queden escritos, versionados y disponibles para el propio agente y para el equipo.
Pensado para proyectos reales, no solo para demos
Una de las partes más interesantes de OpenSpec es su orientación a repositorios ya existentes. En un proyecto real, el problema no suele ser crear una función desde cero, sino cambiar algo sin romper el resto. Puede haber varios paquetes, una API, una aplicación web, una librería compartida y distintos equipos con responsabilidades separadas.
Para ese tipo de escenarios, OpenSpec introduce el concepto de stores, todavía en beta. Un store permite mantener la planificación en un repositorio separado, con la misma estructura de openspec/, pero compartida por Git entre varios equipos y repositorios. La utilidad aparece cuando una funcionalidad afecta a tres codebases distintos o cuando un equipo de plataforma define requisitos que otros equipos consumen en modo lectura.
La alternativa habitual es una mezcla de documentos en wikis, tickets, hilos de Slack, comentarios en pull requests y memoria de equipo. Ese modelo funciona hasta que la IA entra en el flujo. Un agente no puede leer fácilmente una decisión perdida en una reunión ni una convención enterrada en una página antigua. Si la especificación vive en el repositorio, el agente puede consultarla y trabajar con más contexto.
Aquí OpenSpec conecta con una tendencia más amplia en ingeniería: convertir decisiones en artefactos versionados. Igual que la infraestructura como código llevó la configuración a Git, el desarrollo con agentes necesita que requisitos y planes también sean legibles por máquinas.
La diferencia frente a trabajar solo con prompts
El desarrollo con IA sin especificaciones suele depender demasiado del prompt inicial. Si el usuario pide “añade modo oscuro”, el modelo puede elegir una solución razonable, pero quizá no la mejor para ese proyecto. Puede añadir una dependencia innecesaria, ignorar la preferencia del sistema, duplicar estilos o no contemplar accesibilidad.
Con OpenSpec, la conversación se desplaza antes de la implementación. Primero se explora, después se propone, luego se revisan los artefactos y solo entonces se aplica. Esto no convierte el proceso en burocracia pesada, porque los documentos son editables en cualquier momento y no hay fases cerradas al estilo de una metodología rígida. La intención es mantener la agilidad del chat, pero con una memoria más fiable.
El propio proyecto se compara con otras propuestas. Frente a Spec Kit de GitHub, se presenta como una alternativa más ligera y menos rígida. Frente a Kiro de AWS, destaca que no obliga a usar un IDE concreto ni limita el trabajo a unos modelos determinados. Frente a no usar nada, ofrece una capa mínima para que el asistente no dependa solo de una conversación volátil.
| Enfoque | Ventaja | Límite |
|---|---|---|
| Prompt directo | Rápido y flexible | Poca trazabilidad y resultados menos previsibles |
| OpenSpec | Plan ligero, editable y versionado | Exige disciplina mínima de especificación |
| Spec Kit | Más estructurado y completo | Puede resultar más pesado |
| Kiro | Integración fuerte en su entorno | Más dependencia de una plataforma concreta |
Cómo se instala y dónde encaja
OpenSpec requiere Node.js 20.19.0 o superior. La instalación global se hace con npm install -g @fission-ai/openspec@latest y después se inicializa dentro del proyecto con openspec init. A partir de ese momento, el usuario puede trabajar con comandos de barra como /opsx:explore o /opsx:propose.
El proyecto afirma que funciona con más de 30 asistentes de IA mediante comandos y perfiles. También recomienda usar modelos de razonamiento alto para planificación e implementación, y cuidar la higiene del contexto: limpiar la ventana antes de empezar una implementación y evitar que el agente arrastre conversaciones antiguas que puedan contaminar la tarea.
Esto último es una recomendación muy realista. Muchos fallos de agentes de código no vienen de que el modelo sea incapaz, sino de que trabaja con contexto sucio, instrucciones contradictorias o requisitos que han cambiado durante la conversación. OpenSpec intenta fijar la parte importante en archivos.
Su uso tiene sentido en proyectos personales donde un desarrollador quiere mantener orden con su asistente, pero también en equipos que quieren dar más control al desarrollo con IA. Un cambio puede revisarse no solo por el código final, sino por la propuesta, la especificación y las tareas que llevaron hasta él.
Por qué importa para la nueva ingeniería con IA
Los agentes de código están entrando en una fase más madura. Ya no se trata solo de pedirles que escriban una función, sino de integrarlos en el ciclo completo: entender requisitos, explorar soluciones, planificar cambios, modificar repositorios, ejecutar pruebas, abrir pull requests y documentar decisiones.
Ese salto exige algo más que modelos potentes. Exige procesos que los humanos puedan revisar y que las máquinas puedan leer. OpenSpec apunta justo a esa capa intermedia entre el chat y el repositorio.
La ventaja no está en escribir más documentos, sino en evitar que la especificación desaparezca cuando se cierra la sesión. Si mañana otro desarrollador, otro agente o el mismo equipo necesita entender por qué se hizo un cambio, los artefactos siguen ahí.
También ayuda a reducir el riesgo de que la IA implemente demasiado. Una petición mal acotada puede acabar en cambios excesivos. Con una propuesta y una lista de tareas, el alcance queda más claro. Y si el plan cambia, se edita antes de escribir código.
OpenSpec no resuelve todos los problemas del desarrollo con IA. Sigue haciendo falta revisión humana, tests, criterios de arquitectura, seguridad, control de dependencias y buenas prácticas de ingeniería. Pero sí aborda una carencia evidente: los agentes necesitan trabajar con especificaciones más estables que una conversación.
La programación asistida por IA no va solo de generar código más rápido. Va de construir sistemas donde humanos y modelos puedan compartir contexto, intención y límites. OpenSpec intenta convertir esa coordinación en una parte natural del repositorio.
Preguntas frecuentes
¿Qué es OpenSpec?
Es un framework open source para desarrollo guiado por especificaciones con asistentes de código basados en IA.
¿Para qué sirve?
Sirve para definir propuestas, requisitos, diseño y tareas antes de que la IA implemente cambios en un repositorio.
¿Sustituye a herramientas como Claude Code o Codex?
No. OpenSpec se integra con asistentes de IA y añade una capa de especificaciones y flujo de trabajo.
¿Está pensado solo para proyectos nuevos?
No. Uno de sus puntos fuertes es que está diseñado también para proyectos existentes y repositorios con historia.
¿Qué son los stores de OpenSpec?
Son repositorios separados para planificar cambios y compartir especificaciones entre varios equipos o codebases. Actualmente están en beta.
