Flujo de Trabajo con Especificación Primero
Define los requisitos antes de escribir código.
OpenSpecDesarrollo Guiado por Especificaciones para Asistentes de IA
Una especificación ligera para crear 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 código con IA a acordar qué construir antes de escribir cualquier código. Tú describes el cambio, la IA redacta una especificación breve y una lista de tareas, ambos revisan el mismo plan, y entonces se realiza el trabajo. Ya no más descubrir a mitad de camino que la IA construyó algo incorrecto.
Si no lees nada más, lee estas dos páginas:
/opsx:propose (pista: en tu chat de IA, no en la terminal). Esto confunde a casi todos al menos una vez.Esa segunda página es más importante de lo que parece. OpenSpec tiene dos mitades: una herramienta de línea de comandos que ejecutas en tu terminal, y comandos con barra diagonal 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 para cultivar primero: cuando no estás seguro de qué construir, comienza con
/opsx:explore. Es un compañero de pensamiento sin riesgos que lee tu código, evalúa opciones y afina una idea vaga en un plan concreto antes de que exista cualquier artefacto o código. La guía Explore First hace el caso.
Soy completamente nuevo. Comienza con Getting Started, luego repasa los Core Concepts at a Glance. Cuando algo se sienta misterioso, el FAQ y el Glossary están cerca.
Tengo un problema pero no un plan. Este es el caso común, y tiene una respuesta dedicada: Explore First. Usa /opsx:explore para pensarlo con la IA antes de comprometerte con algo.
Tengo una base de código grande existente. No documentas todo. Using OpenSpec in an Existing Project muestra cómo comenzar con código real, brownfield, sin hervir el océano.
Solo quiero que funcione. Instala, ejecuta openspec init, luego lee How Commands Work para que tu primer comando con barra diagonal llegue al lugar correcto. O entrega la configuración a tu asistente con el prompt de instalación asistida por IA.
Aprendo con ejemplos. La página Examples & Recipes recorre cambios reales de principio a fin: una pequeña funcionalidad, una corrección de error, una refactorización, una exploración.
La IA acaba de redactar un plan — ¿y ahora qué? Léelo. Reviewing a Change muestra la revisión de dos minutos que detecta un desvío mientras aún es barato, y Writing Good Specs cubre de qué está hecho un plan digno de aprobación.
Trabajo en un equipo. OpenSpec on a Team muestra cómo un cambio se mapea a una rama y una pull request, y cómo los compañeros de equipo revisan un plan antes del código.
Vengo del flujo de trabajo antiguo. La Migration Guide explica qué cambió y por qué, y promete que tu trabajo existente está a salvo.
Quiero adaptarlo al proceso de mi equipo. Customization cubre la configuración del proyecto, esquemas personalizados y contexto compartido.
Algo está roto. Troubleshooting recopila los fallos que la gente realmente encuentra, con soluciones.
| Documento | Qué te ofrece |
|---|---|
| Getting Started | Instala, inicializa y ejecuta tu primer cambio de principio a fin |
| Explore First | Usa /opsx:explore para pensar una idea antes de comprometerte |
| How Commands Work | Dónde se ejecutan los comandos con barra diagonal, qué significa "modo interactivo", terminal vs chat |
| Core Concepts at a Glance | Todo el modelo mental en una página: especificaciones, cambios, deltas, archivo |
| Installation | npm, pnpm, yarn, bun, Nix, un prompt que entrega la configuración a tu asistente de IA, y cómo verificar que funcionó |
| Documento | Qué te ofrece |
|---|---|
| Workflows | Patrones comunes y cuándo usar cada comando |
| Examples & Recipes | Recorridos completos de cambios reales, listos para copiar y pegar |
| Writing Good Specs | Cómo se ven un requisito y un escenario sólidos, y cómo dimensionar adecuadamente un cambio |
| Reviewing a Change | La revisión de dos minutos sobre un plan redactado antes de escribir código |
| OpenSpec on a Team | Cómo los cambios encajan con ramas, pull requests y revisiones |
| Using OpenSpec in an Existing Project | Adoptar OpenSpec en una gran base de código brownfield |
| Editing & Iterating on a Change | Actualizar artefactos, retroceder, reconciliar ediciones manuales |
| Commands | Referencia de cada comando con barra diagonal /opsx:* |
| CLI | Referencia de cada comando de terminal openspec |
| Documento | Qué te ofrece |
|---|---|
| Concepts | La explicación extensa de especificaciones, cambios, artefactos, esquemas y archivo |
| OPSX Workflow | Por qué el flujo de trabajo es fluido en lugar de bloqueado por fases, más una profundización en la arquitectura |
| Glossary | Cada término definido en un solo lugar |
| Documento | Qué te ofrece |
|---|---|
| Customization | Configuración del proyecto, esquemas personalizados, contexto compartido |
| Multi-Language | Generar artefactos en idiomas distintos al inglés |
| Supported Tools | Las más de 30 herramientas de IA con las que se integra OpenSpec, y dónde se ubican los archivos |
| Community Showcase | Proyectos y recursos creados con y para OpenSpec |
| Documento | Qué te ofrece |
|---|---|
| FAQ | Respuestas rápidas a las preguntas que más se hacen |
| Troubleshooting | Soluciones concretas para fallos concretos |
| Migration Guide | Migrar del flujo de trabajo legado a OPSX |
| Documento | Qué te ofrece |
|---|---|
| Stores: User Guide | Planifica en su propio repositorio cuando tu trabajo abarca repositorios o equipos |
| Agent Contract | Las superficies de CLI legibles por máquina que los agentes utilizan |
1. Install npm install -g @fission-ai/openspec@latest
2. Initialize cd your-project && openspec init
3. Explore (en tu chat de IA) /opsx:explore ← opcional, pero un gran hábito
4. Propose (en tu chat de IA) /opsx:propose add-dark-mode
5. Build (en tu chat de IA) /opsx:apply
6. Archive (en tu chat de IA) /opsx:archiveLos pasos 1 y 2 ocurren en tu terminal. El resto ocurre en el chat de tu asistente de IA. Esa división es lo único que vale la pena memorizar, y How Commands Work explica exactamente por qué. El paso 3 es opcional, pero comenzar con /opsx:explore cuando no estás seguro es el hábito más valioso para formar.
openspec feedback "your message" envía comentarios directamente desde tu terminal (abre un issue de GitHub).¿Encontraste algo en esta documentación que está mal, desactualizado o confuso? Eso es un error. Abre un issue o un PR. Las mejoras en la documentación son algunas de las contribuciones más valiosas que puedes hacer.