OpenSpec

Preguntas frecuentes ​

Respuestas rápidas a las preguntas más comunes. Si tu pregunta es realmente un caso de "algo está roto", la página Solución de problemas es más adecuada. Si quieres la definición de un término, consulta el Glosario.

Lo básico ​

¿Qué es OpenSpec en una sola frase? ​

Una capa ligera que te permite llegar a un acuerdo con tu asistente de código IA sobre qué construir, por escrito, antes de escribir cualquier código.

¿Por qué querría hacer eso? ​

Porque los asistentes IA son confiables incluso cuando se equivocan. Cuando los requisitos solo viven en un hilo de chat, la IA rellena los vacíos con suposiciones y te enteras después de que el código ya existe. OpenSpec adelanta el acuerdo, donde los errores son baratos de corregir. Consulta Conceptos clave de un vistazo para el caso completo.

¿Tengo que usarlo para todo? ​

No. Úsalo donde el acuerdo importa, que es la mayoría del trabajo no trivial. Para corregir un error tipográfico de un carácter, probablemente no vale la pena el trámite, y eso está bien.

¿Puedo usarlo en una base de código existente grande, o solo en proyectos nuevos? ​

Las bases de código existentes son el caso principal. OpenSpec está diseñado para entornos existentes: no documentas toda tu aplicación de antemano. Escribes especificaciones solo para lo que cada cambio toca, y tus especificaciones se completan con el tiempo alrededor del trabajo que realmente haces. Hay una guía dedicada: Uso de OpenSpec en un proyecto existente.

¿Está ligado a una sola herramienta de IA? ​

No. OpenSpec funciona con más de 30 asistentes, incluyendo Claude Code, Cursor, Devin Desktop, GitHub Copilot, Gemini CLI, Codex y más. La lista completa y los detalles por herramienta están en Herramientas compatibles.

Ejecución de comandos ​

¿Dónde escribo /opsx:propose? ​

En el chat de tu asistente IA, no en tu terminal. Este es el punto de confusión más común, por lo que tiene su propia página: Cómo funcionan los comandos. Versión corta: openspec ... se ejecuta en la terminal, /opsx:... se ejecuta en el chat.

¿Cómo "inicio el modo interactivo"? ​

No hay un modo separado que iniciar. Abres tu asistente IA como de costumbre y escribes un comando con barra diagonal en su chat. El comando con barra diagonal es la forma de "entrar" a OpenSpec. (La única función de terminal genuinamente interactiva es openspec view, un panel para navegar especificaciones y cambios.) Explicación completa en Cómo funcionan los comandos.

Escribí un comando con barra diagonal y no pasó nada. ¿Por qué? ​

Lo más probable es que lo escribiste en la terminal en lugar de en tu chat de IA, que usaste una ortografía que tu herramienta no reconoce, o que los comandos aún no están instalados. Si los archivos faltan — o nunca configuraste la herramienta — ejecuta openspec init; openspec update solo actualiza archivos que ya existen. Luego reinicia tu asistente y usa el formato impreso bajo "Getting started" — consulta Cómo invocar. Solución de problemas tiene la lista de verificación completa.

¿Por qué la sintaxis es /opsx:propose en una herramienta y /opsx-propose en otra? ​

Cada herramienta de IA muestra los comandos personalizados de manera ligeramente diferente, y OpenSpec los escribe de la forma en que tu herramienta carga el archivo que escribió. Un archivo de comando llamado opsx-propose.md se escribe /opsx-propose; uno archivado bajo commands/opsx/ se escribe /opsx:propose. Las herramientas que usan habilidades en lugar de comandos usan el nombre de la habilidad — Codex necesita $openspec-propose, Kimi Code /skill:openspec-propose. La línea "Getting started" de openspec init ya imprime el formato correcto para las herramientas que elegiste; la tabla completa está en Cómo invocar.

¿Cuál es la diferencia entre una habilidad y un comando? ​

Ambos son archivos que OpenSpec escribe para que tu asistente pueda ejecutar el flujo de trabajo. Las habilidades (.../skills/openspec-*/SKILL.md) son el estándar más nuevo entre herramientas; los comandos (.../commands/opsx-*) son los archivos con barra diagonal más antiguos por herramienta. No necesitas elegir. Solo escribes el comando con barra diagonal y OpenSpec instala el que tu herramienta usa.

El flujo de trabajo ​

¿Dónde debería empezar si no estoy seguro de qué construir? ​

Con /opsx:explore. Es un compañero de pensamiento sin riesgos que lee tu base de código, presenta opciones y convierte un problema difuso en un plan concreto, todo antes de que exista algún cambio o código. Está en el perfil predeterminado, por lo que siempre está disponible. Cuando el plan está claro, lo transfiere a /opsx:propose. Este es el mejor hábito que puedes formar, porque evita que una IA entusiasta construya confiadamente lo equivocado. Consulta Explora primero.

¿Cuál es el flujo más simple posible? ​

text
/opsx:explore (opcional)   luego   /opsx:propose <lo que quieres>   luego   /opsx:apply   luego   /opsx:archive

Explora para pensarlo, propón para redactar el plan, aplica para construirlo, archiva para guardarlo. Omite explorar cuando ya sabes exactamente qué quieres.

¿Cuál es la diferencia entre /opsx:propose y /opsx:new? ​

/opsx:propose es el comando de un solo paso predeterminado: crea el cambio y redacta todos los artefactos de planificación a la vez. /opsx:new es parte del conjunto de comandos ampliado y solo crea un cambio vacío, dejándote crear los artefactos uno a uno con /opsx:continue (o todos a la vez con /opsx:ff). Usa propose a menos que quieras control paso a paso. Consulta Comandos.

¿Qué son los perfiles core y ampliado? ​

Un perfil decide qué comandos con barra diagonal se instalan. Core (el predeterminado) te da propose, explore, apply, update, sync, archive. El conjunto ampliado agrega new, continue, ff, verify, bulk-archive y onboard para un control más fino. Cambia con openspec config profile, luego aplica con openspec update.

¿Necesito ejecutar /opsx:sync? ​

Normalmente no. Sync fusiona las especificaciones delta de un cambio en tus especificaciones principales, y /opsx:archive te ofrecerá hacerlo por ti. Ejecuta sync manualmente solo cuando quieras fusionar las especificaciones antes de archivar, por ejemplo en un cambio de larga duración. Consulta Comandos.

¿Cómo edito una propuesta, especificación o tarea después de haber empezado? ​

Simplemente edita el archivo. Cada artefacto es Markdown plano en openspec/changes/<name>/, y no hay una fase bloqueada ni un modo de edición especial. Cámbialo manualmente o pídele a tu IA que lo revise ("actualiza el diseño para usar una cola"), y luego continúa. La IA siempre trabaja desde el contenido actual del archivo. Guía completa: Edición e iteración de un cambio.

¿Puedo volver atrás y cambiar el plan después de implementar parte de él? ​

Sí, en cualquier momento. El flujo de trabajo es fluido, por lo que la revisión y la edición no son fases de las que te bloqueen. Edita el artefacto y luego continúa. Si quieres una verificación estructurada de que el código aún coincide con el plan, ejecuta /opsx:verify. Consulta Edición e iteración de un cambio.

Edité el código manualmente. ¿Cómo lo reconcilio con la especificación? ​

Vuelve a sincronizarlos antes de archivar, ya que archivar convierte tus especificaciones en el registro de verdad. Si el código ahora es correcto, actualiza la especificación delta para que coincida con lo que enviaste; si la especificación es correcta, sigue construyendo hasta que el código coincida. /opsx:verify muestra las discrepancias. Consulta Edición e iteración de un cambio.

¿Cuándo debería actualizar un cambio existente versus empezar uno nuevo? ​

Actualiza cuando es el mismo trabajo, refinado. Empieza de nuevo cuando la intención cambió fundamentalmente o el alcance se expandió a trabajo diferente. Hay un diagrama de flujo de decisión y ejemplos en Flujos de trabajo.

¿Qué pasa si mi sesión se queda sin contexto o los requisitos cambian durante la implementación? ​

Aquí es donde las especificaciones justifican su valor. Como el plan vive en archivos (no solo en el historial de chat), puedes limpiar tu contexto, iniciar una nueva sesión de IA y retomar con /opsx:apply; lee los artefactos y retoma desde la primera tarea sin verificar. Si los requisitos cambian, edita los artefactos para que coincidan con la nueva realidad y continúa. Mantener una ventana de contexto limpia también produce mejores resultados; límpiala antes de la implementación.

¿Debo hacer commit de la carpeta openspec/ en git? ​

Sí. Tus especificaciones, cambios activos y archivo son parte del historial de tu proyecto. Haz commit como cualquier otro código fuente. El archivo en particular se convierte en un registro duradero de por qué tu sistema funciona de la manera en que lo hace.

Especificaciones y cambios ​

¿Qué va en una especificación versus un diseño? ​

Una especificación describe el comportamiento observable: qué hace el sistema, sus entradas, salidas y condiciones de error. Un diseño describe cómo lo vas a construir: el enfoque técnico, las decisiones de arquitectura, los cambios de archivos. Si la implementación podría cambiar sin alterar el comportamiento externamente visible, pertenece al diseño, no a la especificación. Conceptos profundiza en esto.

¿Qué es una especificación delta? ​

Una especificación que describe solo lo que está cambiando, usando secciones ADDED, MODIFIED y REMOVED, en lugar de repetir toda la especificación. Es la forma en que OpenSpec maneja las ediciones a sistemas existentes de manera limpia. Consulta Conceptos.

¿Dónde van los cambios archivados? ​

A openspec/changes/archive/YYYY-MM-DD-<name>/, con todos los artefactos del cambio preservados. El cambio se mueve fuera de tu lista activa. Un cambio que declara explícitamente retire_capabilities: true también puede eliminar una especificación de capacidad principal cuando elimina el último requisito de esa capacidad.

Configuración y personalización ​

¿Cómo le digo a la IA sobre mi stack tecnológico? ​

Ponlo en openspec/config.yaml bajo context:. Ese texto se inyecta en cada solicitud de planificación, por lo que la IA siempre conoce tu stack y convenciones. Consulta Personalización.

¿Puedo generar especificaciones en un idioma distinto al inglés? ​

Sí. Agrega una instrucción de idioma en el context: de tu configuración. Multi-idioma tiene fragmentos para copiar y pegar en varios idiomas.

¿Puedo cambiar el flujo de trabajo mismo? ​

Sí, con esquemas personalizados. Un esquema define qué artefactos existen y cómo dependen entre sí. Haz fork del predeterminado con openspec schema fork spec-driven my-workflow, luego edítalo. Consulta Personalización.

Modelos, privacidad y actualizaciones ​

¿Qué modelo de IA debería usar? ​

OpenSpec funciona mejor con modelos de alto razonamiento. El README recomienda modelos como Codex 5.5 y Opus 4.7 tanto para planificación como para implementación. También mantén tu ventana de contexto limpia: límpiala antes de la implementación para obtener los mejores resultados.

¿OpenSpec recopila datos? ​

Recopila estadísticas de uso anónimas: solo nombres de comandos y versión. Sin argumentos, rutas, contenido ni datos personales, y se desactiva automáticamente en CI. Desactívalo con export OPENSPEC_TELEMETRY=0 o export DO_NOT_TRACK=1.

¿Cómo actualizo? ​

Dos pasos. Actualiza el paquete (npm install -g @fission-ai/openspec@latest), luego ejecuta openspec update dentro de cada proyecto para refrescar las habilidades y comandos generados.

¿Cómo desinstalo OpenSpec? ​

No hay un comando de desinstalación, porque es solo un paquete global más archivos en tu proyecto. Elimina el paquete (npm uninstall -g @fission-ai/openspec) y opcionalmente borra el directorio openspec/ y los archivos de herramientas generados. Paso a paso, incluyendo qué es seguro conservar, está en Instalación: Desinstalación.

Obtener ayuda ​

¿Dónde pregunto o reporto errores? ​

Esta documentación está mal o es confusa. ¿Qué hago? ​

Dínoslo o corrígela. Los PR de documentación son bienvenidos y valorados. Abre un issue o envía un pull request.