Si usas Claude Code para programar ya sabes lo que pasa: abres una nueva sesión y el agente vuelve a improvisar. El contexto de la sesión anterior desapareció. Le describes la feature de nuevo, asume cosas distintas, y acabas corrigiendo código que nadie pidió.
OpenSpec resuelve exactamente eso.
Es un CLI open-source que inserta una capa de especificación versionada dentro de tu proyecto. Claude Code la lee en cualquier sesión, sabe qué se acordó construir, y trabaja contra esa spec — no contra tus prompts.
En este artículo te muestro la integración completa, paso a paso, con una demo real.
Qué es OpenSpec (en 2 párrafos)
OpenSpec es un toolkit de spec-driven development para agentes de IA. Antes de que el agente toque el código, tú y él acuerdan en un documento estructurado qué se va a construir, por qué y cómo. A partir de ahí el agente trabaja contra esa especificación.
Lo que lo diferencia de SpecKit (GitHub) o BMAD Method es que está diseñado para proyectos que ya existen y evolucionan — proyectos brownfield. Usa marcadores de cambio (ADDED, MODIFIED, REMOVED) para registrar exactamente qué cambia sobre el código existente. Es ligero (~250 líneas de spec vs ~800 de SpecKit) y se integra mediante slash commands directamente en Claude Code.
Requisitos
- Node.js 20+
- Claude Code instalado
- Un proyecto existente (la demo usa una API en TypeScript)
Paso 1 — Instalación
npm install -g openspec
Verifica:
openspec --version
# openspec/1.3.x
Paso 2 — Inicializar en tu proyecto
Ve a la raíz de tu proyecto y ejecuta:
cd mi-proyecto
openspec init
Aparece un selector interactivo con todas las herramientas compatibles. Selecciona Claude Code.
? Select your AI coding tool:
GitHub Copilot
Cursor
❯ Claude Code
Kilo Code
Windsurf
(more...)
Al confirmar, OpenSpec genera esta estructura:
openspec/
project.md ← contexto general del proyecto
specs/ ← estado actual de las specs (se actualiza con cada archive)
changes/ ← propuestas en curso
archive/ ← historial de cambios completados
agents.md ← instrucciones para Claude Code (NO modificar manualmente)
Paso 3 — Llenar project.md
Este paso es el más importante y el que más se saltea. Abre openspec/project.md y rellena el contexto real de tu proyecto:
# Mi API de Gestión de Tareas
## Stack técnico
- Runtime: Node.js 22 + TypeScript
- Framework: Fastify
- ORM: Prisma + PostgreSQL
- Testing: Vitest
## Convenciones
- Nombres de archivos: kebab-case
- Variables de entorno: siempre validar con zod al inicio
- Errores: usar clase AppError con statusCode y message
- No usar `any` — tipado estricto
## Estructura de carpetas
src/
routes/ ← definición de endpoints
services/ ← lógica de negocio
middleware/ ← guards, validación
lib/ ← utilidades compartidas
Por qué importa: Claude Code lee este archivo al inicio de cada sesión. Con buen contexto aquí, las propuestas que genera son precisas desde la primera iteración.
Paso 4 — Entender agents.md
OpenSpec generó un agents.md en la raíz. Claude Code lo lee automáticamente como instrucción de proyecto, igual que un CLAUDE.md. Dentro están definidos los tres slash commands que vas a usar:
| Comando | Qué hace |
|---|---|
/openspec-proposal |
Activa modo planificación. Claude pregunta sobre la feature y genera los archivos de propuesta. |
/openspec-apply |
Implementa el cambio aprobado, tarea por tarea, referenciando la spec. |
/openspec-archive |
Cierra el cambio, actualiza las specs actuales y limpia changes/. |
Si ya tienes un
CLAUDE.mden tu proyecto, no hay conflicto — Claude Code lee ambos archivos. Déjalos en la raíz.
Paso 5 — Demo completa: añadir autenticación JWT
Vamos a añadir autenticación JWT a la API. Proyecto que ya existe, feature real.
5.1 — Crear la propuesta
En Claude Code, ejecuta:
/openspec-proposal
Claude Code entra en modo planificación y empieza a hacer preguntas:
OpenSpec Proposal Mode activated.
Tell me about the feature you want to build:
> Autenticación JWT — login, logout, refresh token, y proteger rutas existentes
What routes need protection?
> /tasks, /projects — todas las rutas excepto /auth/*
Token strategy?
> Access token (15min) + Refresh token (7 días) en httpOnly cookie
Algorithm preference?
> HS256
Al responder, genera tres archivos en openspec/changes/jwt-auth/:
proposal.md — descripción del cambio y decisiones de diseño:
# JWT Authentication
## Objetivo
Proteger las rutas /tasks y /projects con autenticación JWT.
## Decisiones
- Access token: HS256, 15 minutos, en Authorization header
- Refresh token: 7 días, httpOnly cookie
- Secret: JWT_SECRET en variables de entorno (validar con zod al init)
- Logout: blacklist en Redis (TTL = expiración del access token)
tasks.md — lista de tareas atómicas en orden de dependencia:
# Tasks: jwt-auth
- [ ] 1. Instalar dependencias: jsonwebtoken, @types/jsonwebtoken
- [ ] 2. Crear lib/jwt.ts con sign, verify, decode
- [ ] 3. Crear servicio auth.service.ts con login y refresh
- [ ] 4. Crear middleware/auth.guard.ts que valida el token
- [ ] 5. Añadir rutas POST /auth/login y POST /auth/refresh
- [ ] 6. Proteger rutas /tasks/* y /projects/* con el guard
- [ ] 7. Añadir JWT_SECRET a validación de env vars
- [ ] 8. Tests unitarios para lib/jwt.ts
spec.md — cambios sobre las specs actuales con marcadores delta:
# Spec delta: jwt-auth
[ADDED] lib/jwt.ts — utilidades de sign/verify
[ADDED] services/auth.service.ts
[ADDED] middleware/auth.guard.ts
[ADDED] routes/auth.route.ts
[MODIFIED] routes/tasks.route.ts — añadir preHandler: authGuard
[MODIFIED] routes/projects.route.ts — añadir preHandler: authGuard
[MODIFIED] lib/env.ts — añadir JWT_SECRET a schema zod
5.2 — Revisar y ajustar
Este paso es el valor real de OpenSpec. Revisa los archivos y corrige las asunciones del agente antes de que escriba código.
En la revisión encontramos que el agente asumió Redis para la blacklist pero no tenemos Redis en el proyecto. Editamos proposal.md:
## Decisiones
- ...
- Logout: no blacklist por ahora — invalidación por expiración de token
(se añadirá Redis en una feature separada)
Valida que todo esté consistente:
openspec validate
# ✓ Spec is valid
5.3 — Implementar
/openspec-apply jwt-auth
Claude Code lee tasks.md y spec.md, y ejecuta cada tarea en orden:
[1/8] Installing dependencies...
[2/8] Creating lib/jwt.ts...
[3/8] Creating services/auth.service.ts...
[4/8] Creating middleware/auth.guard.ts...
...
[8/8] Writing tests for lib/jwt.ts...
✓ All tasks completed
El agente no improvisa nada fuera de la spec. Si necesita tomar una decisión que no estaba en el documento, te pregunta antes de proceder.
5.4 — Archivar
Revisa el código generado. Cuando estés conforme:
openspec archive jwt-auth --yes
✓ Specs updated
✓ Change moved to archive/jwt-auth/
✓ changes/ cleared
openspec/specs/ ahora refleja el estado actual con la autenticación incluida. changes/ está vacío y listo para la siguiente feature.
Tips para sacarle partido con Claude Code
1. Combina con CLAUDE.md para reglas globales
agents.md gestiona el workflow de OpenSpec. Tu CLAUDE.md puede tener reglas más generales del proyecto que aplican siempre, independientemente de OpenSpec. Se complementan bien.
2. Revisa siempre entre proposal y apply
La revisión humana es la clave. Un agente bien orientado con una spec correcta produce código predecible. Un agente con una spec con errores produce los mismos errores a escala.
3. Usa openspec validate antes de cada apply
Detecta referencias rotas o inconsistencias en los archivos de spec antes de lanzar la implementación.
4. Features pequeñas, ciclos cortos
OpenSpec funciona mejor con cambios atómicos (una feature bien delimitada) que con cambios masivos. Si la lista de tareas supera 12-15 items, divide la feature en dos propuestas.
5. Comitea openspec/ junto con el código
Los archivos en openspec/ son documentación ejecutable. Versionalos en git. El archive/ es especialmente valioso — es el historial de decisiones de diseño del proyecto.
Cuándo usarlo y cuándo no
Vale la pena si:
- El proyecto tiene más de unas semanas de vida y sigue creciendo
- Las features tienen 5+ tareas de implementación
- El agente ha roto cosas antes por falta de contexto
- Quieres un historial auditable de qué se construyó y por qué
Es overkill si:
- Es un proyecto de demo o prueba de concepto
- La tarea es una sola pieza pequeña (un componente, un endpoint sencillo)
- Ya tienes un flujo que funciona bien con solo un
CLAUDE.mddetallado
Conclusión
OpenSpec + Claude Code resuelve el problema más frustrante del desarrollo con agentes: el contexto perdido entre sesiones. La inversión inicial (5-10 minutos de setup) se recupera en la primera feature donde el agente no improvisa nada que no estabas esperando.
El repo está en github.com/Fission-AI/OpenSpec y la documentación oficial en intent-driven.dev/knowledge/openspec.
Tutorial en video con demo completa en el canal de YouTube → dominicode.com