Flujo de trabajo primero la especificación
Define los requisitos antes de escribir código.
OpenSpecDesarrollo Guiado por Especificaciones para Asistentes de IA
Una especificación ligera para construir y gestionar proyectos de asistentes de IA.
Bienvenido. Este es el hogar de todo lo relacionado con OpenSpec.
OpenSpec te ayuda a ti y a tu asistente de codificación con IA a ponerse de acuerdo sobre qué construir antes de escribir cualquier código. Describes el cambio, la IA redacta una especificación corta y una lista de tareas, ambos revisan el mismo plan y luego se realiza el trabajo. Ya no tendrás que descubrir a mitad de camino que la IA construyó algo equivocado.
Si no lees nada más, lee estas dos páginas:
/opsx:propose (pista: en el chat de tu IA, no en la terminal). Esto le suele pasar a casi todo el mundo la primera vez.Esa segunda página es más importante de lo que parece. OpenSpec tiene dos partes: una herramienta de línea de comandos que ejecutas en tu terminal, y comandos de barra que le das a tu asistente de IA. Saber cuál es cuál te ahorra el momento de confusión más común.
El mejor hábito que puedes adoptar primero: cuando no estés seguro de qué construir, empieza con
/opsx:explore. Es un compañero de reflexión sin riesgos que lee tu código, evalúa opciones y convierte una idea difusa en un plan concreto antes de que exista cualquier artefacto o código. La guía Explorar primero explica por qué.
Soy nuevo en esto. Empieza por Comenzar, luego echa un vistazo rápido a Conceptos básicos de un vistazo. Cuando algo te parezca confuso, tienes cerca la Preguntas frecuentes (FAQ) y el Glosario.
Tengo un problema pero no un plan. Este es el caso más común, y tiene una respuesta dedicada: Explorar primero. Usa /opsx:explore para pensarlo con la IA antes de comprometerte con nada.
Tengo una base de código existente grande. No tienes que documentarla toda. Usar OpenSpec en un proyecto existente muestra cómo empezar con código brownfield real sin tener que abordar una tarea de una envergadura excesiva.
Solo quiero que funcione. Instala, ejecuta openspec init, luego lee Cómo funcionan los comandos para que tu primer comando de barra se ejecute en el lugar correcto.
Aprendo con ejemplos. La página Ejemplos y recetas recorre cambios reales de principio a fin: una funcionalidad pequeña, una corrección de errores, una refactorización, una exploración.
La IA acaba de redactar un plan — ¿y ahora qué? Léelo. Revisar un cambio muestra la revisión de dos minutos que detecta un giro equivocado mientras el coste de corregirlo todavía es bajo, y Escribir buenas especificaciones explica de qué está hecho un plan que vale la pena aprobar.
Trabajo en equipo. OpenSpec en equipo muestra cómo se corresponde un cambio con una rama y una solicitud de extracción, y cómo los compañeros revisan un plan antes de escribir el código.
Vengo del flujo de trabajo anterior. La Guía de migración explica qué cambió y por qué, y garantiza que tu trabajo existente está seguro.
Quiero adaptarlo al proceso de mi equipo. Personalización cubre la configuración del proyecto, esquemas personalizados y contexto compartido.
Algo no funciona. Solución de problemas recopila los fallos con los que se encuentran realmente los usuarios, con sus soluciones.
| Documento | Qué te ofrece |
|---|---|
| Comenzar | Instala, inicializa y ejecuta tu primer cambio de principio a fin |
| Explorar primero | Usa /opsx:explore para reflexionar sobre una idea antes de comprometerte con ella |
| Cómo funcionan los comandos | Dónde se ejecutan los comandos de barra, qué significa el "modo interactivo", terminal frente a chat |
| Conceptos básicos de un vistazo | Todo el modelo mental en una página: especificaciones, cambios, deltas, archivo |
| Instalación | npm, pnpm, yarn, bun, Nix, y cómo verificar que funcionó |
| Documento | Qué te ofrece |
|---|---|
| Flujos de trabajo | Patrones comunes y cuándo usar cada comando |
| Ejemplos y recetas | Recorridos completos de cambios reales, listos para copiar y pegar |
| Escribir buenas especificaciones | Cómo son un requisito y un escenario sólidos, y cómo ajustar el tamaño de un cambio correctamente |
| Revisar un cambio | La revisión de dos minutos de un plan redactado antes de escribir cualquier código |
| OpenSpec en equipo | Cómo encajan los cambios en las ramas, las solicitudes de extracción y la revisión |
| Usar OpenSpec en un proyecto existente | Adoptar OpenSpec en una base de código brownfield grande |
| Editar e iterar sobre un cambio | Actualizar artefactos, retroceder, reconciliar ediciones manuales |
| Comandos | Referencia de todos los comandos de barra /opsx:* |
| CLI | Referencia de todos los comandos de terminal openspec |
| Documento | Qué te ofrece |
|---|---|
| Conceptos | La explicación detallada de especificaciones, cambios, artefactos, esquemas y archivo |
| Flujo de trabajo OPSX | Por qué el flujo de trabajo es fluido en lugar de estar bloqueado por fases, además de un análisis profundo de la arquitectura |
| Glosario | Todos los términos definidos en un solo lugar |
| Documento | Qué te ofrece |
|---|---|
| Personalización | Configuración del proyecto, esquemas personalizados, contexto compartido |
| Multiidioma | Generar artefactos en idiomas distintos al inglés |
| Herramientas compatibles | Las más de 25 herramientas de IA con las que se integra OpenSpec, y dónde se guardan los archivos |
| Documento | Qué te ofrece |
|---|---|
| Preguntas frecuentes (FAQ) | Respuestas rápidas a las preguntas más frecuentes |
| Solución de problemas | Soluciones concretas para fallos concretos |
| Guía de migración | Pasar del flujo de trabajo heredado a OPSX |
| Documento | Qué te ofrece |
|---|---|
| Stores: Guía de usuario | Planifica en su propio repositorio cuando tu trabajo abarque varios repositorios o equipos |
| Contrato de agente | Las interfaces de CLI legibles por máquina que utilizan los agentes |
1. Install npm install -g @fission-ai/openspec@latest
2. Initialize cd your-project && openspec init
3. Explore (in your AI chat) /opsx:explore ← optional, but a great habit
4. Propose (in your AI chat) /opsx:propose add-dark-mode
5. Build (in your AI chat) /opsx:apply
6. Archive (in your AI chat) /opsx:archiveLos pasos 1 y 2 se ejecutan en tu terminal. El resto se realiza en el chat de tu asistente de IA. Esa división es lo único que vale la pena memorizar, y Cómo funcionan los comandos lo explica exactamente. El paso 3 es opcional, pero empezar con /opsx:explore cuando no estés seguro es el hábito que más vale la pena adoptar.
openspec feedback "tu mensaje" envía comentarios directamente desde tu terminal (abre un problema en GitHub).¿Has encontrado algo en esta documentación que sea erróneo, obsoleto o confuso? Eso es un fallo. Abre un problema o una solicitud de extracción (PR). Las mejoras en la documentación son algunas de las contribuciones más valiosas que puedes realizar.