Cómo integrar OpenSpec con Claude Code paso a paso

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:

Si ya tienes un CLAUDE.md en 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.md detallado

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