OpenSpec: cómo dejar atrás el “vibe coding” y construir software serio con IA

El uso de asistentes de IA en desarrollo de software ya no es una ventaja competitiva: es la norma. Cursor, GitHub Copilot y Claude Code están presentes en el día a día de muchos equipos.

Sin embargo, a medida que la adopción crece, también aparece un problema evidente: gran parte del código generado es inconsistente, difícil de mantener y, en muchos casos, no refleja correctamente las necesidades reales del negocio.

El problema no es la IA. El problema es cómo la estamos usando. Cuando el desarrollo se basa únicamente en prompts rápidos y contexto implícito, entramos en una forma de trabajo que muchos llaman “vibe coding”: se avanza rápido, pero sin contrato claro, sin trazabilidad y con un alto costo oculto en retrabajo. OpenSpec surge precisamente para resolver este punto, proponiendo un enfoque distinto: desarrollo guiado por especificaciones claras, explícitas y versionadas, diseñadas para trabajar con IA de forma estructurada.

Este artículo explora OpenSpec no como una herramienta más, sino como un cambio profundo en la forma de desarrollar software con asistentes de IA.

 

El problema de fondo: la IA no puede adivinar lo que no está escrito

Uno de los errores más comunes al trabajar con IA es asumir que “entiende” el sistema solo por ver el código. En la práctica, cuando no existe una especificación clara, la IA rellena vacíos. Y cuando rellena vacíos, aparecen comportamientos no deseados.

Qué suele pasar cuando no hay especificaciones

Se implementan funcionalidades que nadie pidió, pero que “parecen lógicas”. Se omiten reglas de negocio importantes porque no estaban explícitas. Los casos borde se pierden o se manejan de forma arbitraria. Cada desarrollador obtiene resultados distintos usando la misma IA. La IA no falla por ser imprecisa; falla porque no existe un contrato claro que defina qué se espera exactamente del sistema. OpenSpec parte de una premisa simple pero poderosa: antes de escribir código, hay que escribir intención.

 

Como instalarlo, configurarlo y usarlo con IA (Cursor, Copilot o Claude) sin perder el control

Si tu equipo ya usa IA para programar (Cursor, GitHub Copilot o Claude Code), probablemente ya viviste esto: con el mismo prompt, dos personas obtienen resultados distintos; aparecen cambios que nadie pidió; se rompen convenciones; y la “velocidad” termina convertida en retrabajo.

OpenSpec existe para resolver ese problema con una idea simple: antes de implementar, defines el comportamiento esperado con especificaciones claras (Spec-Driven Development). Luego la IA implementa siguiendo esas reglas, con trazabilidad y un flujo repetible.

En esta guía vas a ver lo que faltaba en la mayoría de explicaciones: cómo se instala, qué estructura crea, qué archivos debes completar y cuáles son los comandos y pasos concretos para ejecutar cambios de principio a fin.

 

Qué vas a lograr con OpenSpec (y por qué importa si usas IA)

 

OpenSpec no busca que escribas “más documentación”. Busca que la IA deje de adivinar.

Cuando el sistema tiene especificaciones y tareas verificables:

• reduces ambigüedad,

• mantienes coherencia técnica,

• puedes auditar cambios,

• y mejoras colaboración (aunque cada dev use una herramienta distinta).

Si hoy tu equipo depende de “prompts buenos” o “contexto en la cabeza de alguien”, OpenSpec te da una forma de trabajo más estable.

Instalación de OpenSpec: paso a paso

Paso 1: Requisitos mínimos

• Node.js y npm instalados en tu máquina (o en el entorno de desarrollo del equipo).
• Acceso al repositorio donde quieres activar OpenSpec.
• Idealmente: Cursor instalado si quieres usar los comandos slash directamente desde el editor (aunque OpenSpec también se maneja por CLI).

 

Paso 2: Instalar OpenSpec globalmente

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

 

Paso 3: Verificar la instalación

openspec --version

Si este comando responde con una versión, estás listo.

 

Inicialización: crear la estructura base en tu repositorio

Paso 4: Ejecutar init en la raíz del repo

Entra a la carpeta del repositorio y ejecuta:

cd /ruta/al/repositorio openspec init

Durante la inicialización normalmente se configura la herramienta de IA principal (por ejemplo Cursor). Al finalizar, OpenSpec crea una estructura que separa el estado actual del sistema (specs) de los cambios activos (changes) y los cambios archivados (archive).

 

Qué carpetas y archivos se crean (y para qué sirven)

• openspec/project.md: contexto del proyecto para que la IA entienda tu sistema.
• openspec/specs/: el “estado actual” del sistema descrito como especificaciones.
• openspec/changes/: cambios en curso (cada cambio vive en su propia carpeta).
• openspec/archive/: cambios completados (historial y trazabilidad).
• AGENTS.md: instrucciones y reglas para asistentes de IA (comandos, formato, convenciones).

Esta estructura es parte del valor: obliga a definir intención y deja registro real de los cambios.

 

Configuración recomendada: lo que debes completar antes de implementar tu primer cambio

Paso 5: Completar openspec/project.md (esto define la calidad del resultado)

Este archivo es el “contexto principal” del proyecto. Si lo dejas genérico, la IA generará soluciones genéricas.

Incluye, como mínimo:

• Stack (lenguajes, frameworks, build tool).
• Arquitectura (hexagonal, capas, modular, etc.).
• Convenciones (nombres, estilo, estructura de carpetas, manejo de errores, logging).
• Patrones usados (CQRS, repositorios, servicios de dominio, etc.).
• Flujos principales del producto.
• Integraciones críticas (auth, colas, DB, providers).

 

Paso 6: Crear openspec/ecosystem/workspace.md (opcional, pero clave si estás en microservicios)

Si tu repo depende de otros servicios o forma parte de un ecosistema, este archivo te permite documentar:

• servicios relacionados,
• convenciones compartidas,
• flujos de datos entre servicios,
• contratos transversales (headers, auth, observabilidad).

Si trabajas en entornos con múltiples repositorios, este archivo evita que la IA “invente integración” o rompa acuerdos.

 

Paso 7: Revisar y ajustar AGENTS.md (reglas de oro para que la IA no destruya tu estilo)

AGENTS.md es donde defines cómo esperas que la IA trabaje dentro de tu repo. Es el lugar perfecto para imponer reglas como:

• “no introducir librerías nuevas sin justificar”
• “no cambiar estilo de arquitectura”
• “si hay dudas, preguntar antes de implementar”
• “si tocas contratos, actualiza specs”

Este archivo es un multiplicador de calidad.

 

El flujo OpenSpec completo con comandos: de idea a cambio archivado

Ahora sí: la parte práctica, con comandos reales.

Paso 1: Crear una propuesta (desde Cursor)

En Cursor, abre el comando y ejecuta:

/openspec:proposal Agregar filtro de búsqueda por fecha

 

Esto crea una carpeta dentro de openspec/changes/ con:

• proposal.md
• tasks.md
• specs/ (deltas de especificaciones para ese cambio)

Paso 1 alternativa: si no estás en Cursor

Si tu equipo no está usando Cursor para ejecutar comandos slash, puedes igual usar el flujo creando manualmente la carpeta del cambio y sus archivos (aunque lo ideal es usar el comando, porque estandariza nombres y estructura).

 

Paso 2: Revisar el cambio creado (CLI)

Para inspeccionar el cambio:

openspec show add-date-filter

 

Esto te permite ver el detalle de lo generado y confirmar que el cambio tiene sentido antes de implementar.

 

Paso 3: Validar formato y consistencia (CLI)

Antes de ejecutar implementación, valida el cambio:

openspec validate add-date-filter

 

Si hay problemas de formato o estructura, es mejor corregirlos ahora que después.

 

Paso 4: Refinar propuesta y tareas (con IA, pero con intención)

En proposal.md refuerza:

• escenarios,
• casos borde,
• criterios de aceptación,
• restricciones técnicas.

En tasks.md asegúrate de que cada tarea sea:

• verificable,
• pequeña,
• medible,
• sin ambigüedad.

Este refinamiento es la diferencia entre “IA improvisando” y “IA ejecutando”.

 

Paso 5: Implementar el cambio (desde Cursor)

Cuando el cambio está claro:

/openspec apply add-date-filter

 

En este punto, Cursor lee tasks.md, implementa tarea por tarea y marca progreso. La IA trabaja con un plan.

 

Paso 6: Archivar el cambio (desde Cursor)

Una vez completado y validado el cambio, archiva:

/openspec archive add-date-filter

 

Qué ocurre aquí:

• el cambio se mueve a openspec/archive/

• se actualiza openspec/specs/ con el nuevo estado del sistema

• queda trazabilidad completa: qué se cambió, por qué, cómo y cuándo

Ese “cierre” es lo que evita que tu repo se convierta en una suma de decisiones perdidas.

 

Cómo escribir un buen proposal.md y un tasks.md que la IA pueda ejecutar sin inventar

Qué debe incluir proposal.md (estructura recomendada)

• Propósito: qué problema resuelve y para quién.
• Contexto: cómo funciona hoy y qué duele.
• Alcance: qué se toca y qué no se toca.
• Decisiones técnicas: trade-offs y restricciones.
• Impacto: efectos esperados en el sistema o ecosistema.
• Escenarios: casos normales y casos borde.

Mientras más claro esto esté, menos “creatividad” tendrá la IA.

Cómo debe verse tasks.md para que sea verificable

• Lista numerada o checklist.
• Agrupada por categorías (API, DB, tests, observabilidad, etc.).
• Cada tarea debe poder revisarse en PR.
• Evitar tareas tipo “arreglar lo necesario” o “ajustar detalles”.

Ejemplos de tareas bien definidas:

• “Agregar endpoint GET /system/info que retorne versión, timestamp y estado, sin tocar base de datos”
• “Agregar prueba unitaria que valide que el endpoint responde 200 y contiene los campos esperados”
• “Actualizar spec del dominio para incluir el nuevo contrato del endpoint”

 

Errores típicos al adoptar OpenSpec (y cómo evitarlos)

Adoptar OpenSpec no falla por la herramienta en sí, sino por cómo se introduce en el equipo. En la práctica, la mayoría de los problemas aparecen cuando se intenta “probar rápido” sin entender que OpenSpec es un cambio de forma de trabajo, no solo un comando nuevo.

A continuación, se describen los errores más comunes que suelen aparecer en las primeras semanas de adopción y cómo evitarlos para que OpenSpec entregue valor real.

 

Error 1: Instalar OpenSpec pero no completar el contexto del proyecto

Uno de los errores más frecuentes es ejecutar la instalación, ver la estructura creada y asumir que con eso basta. Cuando el archivo project.md queda vacío, incompleto o con descripciones genéricas, la IA no tiene información real para tomar buenas decisiones.

El resultado suele ser frustrante: la IA genera soluciones genéricas, rompe convenciones o propone arquitecturas que no encajan con el proyecto. Frente a eso, el equipo concluye que “OpenSpec no sirve”, cuando en realidad el problema es que nunca se le explicó al sistema cómo funciona el proyecto.

OpenSpec depende fuertemente del contexto. Mientras más claro, específico y alineado a la realidad esté project.md, mayor será la calidad y consistencia del código generado con IA.

 

Error 2: Saltarse el refinement por urgencia

Otro error habitual es tratar el flujo de OpenSpec como algo opcional. En momentos de presión, muchos equipos crean una propuesta mínima —o directamente la omiten— con la idea de “ir más rápido”.

En la práctica, esto devuelve al equipo al mismo problema de siempre: prompts vagos, decisiones implícitas y código que requiere correcciones posteriores. La urgencia aparente termina generando más retrabajo, no menos.

OpenSpec funciona cuando se respeta el flujo completo. El refinement no es burocracia, sino el momento donde se eliminan ambigüedades antes de que la IA empiece a escribir código.

 

Error 3: Definir tareas ambiguas o demasiado amplias

La IA ejecuta exactamente lo que entiende. Si una tarea está mal definida, es demasiado amplia o utiliza expresiones vagas como “ajustar”, “mejorar” o “dejar listo”, el resultado será inconsistente.

Tareas ambiguas obligan a la IA a tomar decisiones que deberían haber sido humanas. Esto no solo genera resultados distintos entre desarrolladores, sino que también introduce diferencias difíciles de detectar durante la revisión de código.

Las tareas en OpenSpec deben ser pequeñas, verificables y explícitas. Si una tarea no se puede validar fácilmente en un pull request, probablemente está mal definida.

 

Error 4: No archivar los cambios una vez completados

Archivar un cambio suele verse como un trámite final sin demasiado valor. Sin embargo, omitir este paso rompe uno de los pilares fundamentales de OpenSpec: mantener actualizado el estado real del sistema.

Cuando los cambios no se archivan correctamente, las especificaciones dejan de representar la realidad del código. Con el tiempo, esto provoca que nuevos cambios se diseñen sobre información desactualizada, acumulando errores y fricción.

Archivar no es solo cerrar un proceso. Es asegurar que el conocimiento del sistema no se pierda y que el repositorio siga siendo una fuente confiable de verdad.

 

OpenSpec y equipos reales: cuándo vale todavía más

OpenSpec demuestra su mayor valor en contextos donde la complejidad no está únicamente en el código, sino en la coordinación entre personas, repositorios y decisiones técnicas.

En equipos con alta rotación o procesos constantes de onboarding, OpenSpec reduce drásticamente el tiempo necesario para entender cómo funciona el sistema y por qué se tomaron ciertas decisiones. Las especificaciones reemplazan conversaciones que ya no existen.

En repositorios grandes con deuda técnica acumulada, OpenSpec ayuda a introducir cambios de forma controlada, evitando que cada nueva mejora agregue más inconsistencias y complejidad innecesaria.

En arquitecturas de microservicios, donde un cambio puede impactar múltiples componentes, la trazabilidad deja de ser un lujo y se vuelve una necesidad. OpenSpec permite entender el impacto real antes de implementar.

Finalmente, en equipos que ya usan IA y sienten que el repositorio se está “desordenando”, OpenSpec actúa como una capa de contención: la velocidad se mantiene, pero con límites claros y decisiones explícitas.

Cuando el desarrollo deja de ser un trabajo individual y pasa a ser un esfuerzo coordinado, la trazabilidad deja de ser “nice to have” y se vuelve parte esencial del sistema.

 

Cómo convertir OpenSpec en un sistema de trabajo para tu equipo

Para que OpenSpec funcione como un estándar y no como un experimento aislado, es necesario ir más allá de la instalación inicial. La adopción real ocurre cuando el equipo comparte reglas claras y expectativas comunes.

Esto normalmente implica definir reglas por tipo de repositorio, de modo que un Service, un Middle o un BFF no se trabajen de la misma forma, pero sí bajo principios coherentes.

También es clave contar con templates claros para proposal.md y tasks.md, que ayuden a escribir buenas especificaciones sin partir desde cero en cada cambio. Los templates reducen fricción y elevan la calidad promedio del trabajo.

Las convenciones de naming, el nivel de detalle esperado y los criterios sobre qué es obligatorio y qué es opcional deben ser explícitos. Cuando estas decisiones no se conversan, cada persona interpreta OpenSpec de forma distinta.

La diferencia entre una adopción superficial y una adopción real está en este punto: cuando OpenSpec deja de ser “algo que algunos usan” y pasa a ser parte del sistema de trabajo del equipo.

 

Hacer que OpenSpec funcione en una empresa no es solo instalarlo

Después de entender qué es OpenSpec, cómo se instala y cómo funciona su flujo, suele aparecer una conclusión natural: la herramienta tiene sentido, pero implementarla bien en un equipo real no es trivial.

En empresas y equipos de desarrollo, los problemas rara vez están en los comandos. Están en las decisiones que no se escriben, en los estándares que no se acuerdan y en la falta de una guía clara sobre cómo adaptar OpenSpec a la realidad de cada organización.

Por eso, muchos equipos instalan OpenSpec, lo prueban un par de semanas y luego lo abandonan. No porque no funcione, sino porque nadie los ayudó a convertirlo en un sistema de trabajo sostenible.

 

El punto donde la mayoría de los equipos se queda atascado

Cuando OpenSpec pasa del repositorio individual a un equipo completo, aparecen nuevas preguntas:

• ¿Qué nivel de detalle debe tener una propuesta?
• ¿Qué es obligatorio y qué es opcional en cada cambio?
• ¿Cómo se definen reglas distintas para un Service, un BFF o un Frontend?
• ¿Cómo se evita que OpenSpec se vuelva burocracia?

Estas preguntas no se responden con documentación genérica. Se responden analizando el contexto real del equipo, su madurez técnica, su presión de entrega y su arquitectura.

 

Aprender OpenSpec es una cosa. Hacer que funcione en tu empresa es otra

Usar OpenSpec de forma efectiva no se trata solo de conocer los comandos o seguir un tutorial. Se trata de saber cuándo ser estricto y cuándo flexible, cómo escribir especificaciones que realmente aporten valor y cómo integrar este enfoque sin frenar la entrega.

En empresas, además, hay factores que cambian completamente el escenario: equipos con distintos niveles de seniority, múltiples repositorios, deuda técnica, presión por resultados y rotación de personas.

Ahí es donde la diferencia entre “usar OpenSpec” y “sacarle provecho” se vuelve evidente.

 

Asesoría 1:1 y acompañamiento para equipos y empresas

En Mentores Tech trabajamos con personas y empresas que quieren implementar OpenSpec de forma realista, sin ensayo y error innecesario y sin convertir el proceso en una carga para el equipo.

La asesoría no es genérica ni teórica. Se trabaja directamente sobre tu contexto:

• Se revisa cómo está estructurado hoy tu repositorio o ecosistema de repositorios.
• Se define qué debe contener project.md para tu stack y arquitectura específica.
• Se diseñan templates prácticos para proposal.md y tasks.md que el equipo pueda usar sin fricción.
• Se establecen reglas claras para que la IA respete convenciones y límites técnicos.
• Y, si es necesario, se construye un modelo de adopción para múltiples equipos o áreas.

 

¿Para quién tiene sentido este acompañamiento?

• Para developers y líderes técnicos que ya están usando IA y sienten que el código se está desordenando.
• Para equipos que quieren estandarizar su forma de trabajar con IA sin perder velocidad.
• Para empresas que buscan trazabilidad, consistencia y menos retrabajo en sus proyectos.
• Para organizaciones que quieren pasar del experimento a un modelo de desarrollo sostenible.

 

El siguiente paso

Si después de leer este artículo sientes que OpenSpec podría ayudarte, pero también ves que implementarlo bien requiere criterio y experiencia, ese es el momento correcto para pedir apoyo.

Ya sea a nivel personal o como empresa, una sesión de asesoría puede ahorrarte semanas de prueba y error y ayudarte a construir una forma de trabajo que realmente escale.

Si te interesa aprender cómo hacer que OpenSpec funcione en tu contexto específico, puedes contactarnos a través de Mentores Tech y agendar una asesoría 1:1 o un acompañamiento para tu equipo.

La diferencia no está en usar la herramienta, sino en saber cómo integrarla de verdad.