Esta guía documenta un flujo de trabajo práctico para integrar OpenSpec en un proyecto existente (brownfield), utilizando Claude Code como entorno operativo y Engram como capa de memoria persistente local.
El objetivo no es solamente generar especificaciones, sino convertir la base de código actual en una fuente de verdad documentada y evolutiva.
En proyectos brownfield normalmente ocurre lo siguiente:
- la arquitectura real difiere de la documentación,
- las decisiones históricas se pierden,
- las nuevas funcionalidades se implementan sin contexto,
- la IA termina generando código inconsistente,
- y cada desarrollador interpreta el sistema de forma distinta.
La combinación de:
- OpenSpec,
- Claude Code,
- Engram,
- y Repomix,
permite convertir el código existente en una especificación viva que puede evolucionar de forma controlada.
El flujo completo tiene cinco grandes etapas:
- Instalación y limpieza del entorno.
- Inicialización de OpenSpec y Engram.
- Compresión y análisis arquitectónico del proyecto.
- Generación de especificaciones base del sistema actual.
- Flujo diario de cambios usando OPSX.
Antes de comenzar, asegúrate de estar en la raíz de tu proyecto.
Si ya habías experimentado con OpenSpec, Claude Code o agentes MCP, elimina configuraciones antiguas para evitar conflictos.
Important
Es importante aclarar que esta guía es para una implementación en un proyecto que no tenía previamente OpenSpec.
rm -rf .openspec .claude .agent .opencode openspecEsto elimina:
- configuraciones previas,
- agentes antiguos,
- integraciones incompletas,
- y estados inconsistentes.
OpenSpec requiere Node.js 20.19.0+.
Instala la herramienta globalmente:
npm install -g @fission-ai/openspec@latestEngram actúa como memoria persistente local para Claude Code.
Internamente utiliza SQLite para almacenar:
- decisiones,
- contexto,
- conversaciones,
- y relaciones entre cambios.
Instalación:
brew install gentleman-programming/tap/engramEjecuta:
openspec initDurante el asistente interactivo:
- selecciona
Claude Code, - permite que OpenSpec genere la estructura base,
- y deja que cree automáticamente las integraciones necesarias.
Esto normalmente generará:
.openspec/
.claude/
openspec/
y archivos asociados como:
openspec/config.yaml
Y las integraciones específicas de la herramienta.
Instala el plugin oficial:
claude plugin marketplace add Gentleman-Programming/engram && claude plugin install engramEste paso es importante porque:
- registra el servidor MCP y los hooks del ciclo de vida para automatizar el guardado en la base de datos SQLite,
- habilita hooks automáticos,
- y permite persistencia contextual entre sesiones.
Sin esto, Claude Code perderá parte del contexto histórico entre iteraciones.
Una IA no puede analizar eficientemente un repositorio o monorepo enorme leyendo archivo por archivo.
Por eso se utiliza Repomix.
Ejecuta:
npx repomix@latest --compressEsto generará:
repomix-output.xml
El objetivo de --compress es crítico:
- extraer arquitectura,
- relaciones entre módulos,
- firmas de funciones,
- contratos,
- estructura de clases,
sin incluir toda la implementación interna.
En otras palabras:
Reduces ruido y maximizas contexto útil para la IA ya que evita desbordar la ventana de contexto de la IA.
Ahora abre Claude Code:
claudey ejecuta el siguiente prompt:
Lee el archivo repomix-output.xml. Actúa como un Arquitecto de Sistemas. Analiza el código y actualiza el campo context dentro del archivo openspec/config.yaml. Detalla estrictamente el stack tecnológico (frameworks y versiones), patrones arquitectónicos, base de datos y convenciones de testing que descubras. Mantén el formato YAML válido y el contenido conciso.
Este paso es extremadamente importante.
El archivo openspec/config.yaml terminará funcionando como contexto raíz del sistema.
Ahí deben quedar documentados:
- frameworks,
- lenguajes,
- patrones arquitectónicos,
- infraestructura,
- bases de datos,
- testing,
- convenciones,
- y restricciones globales.
Dentro de la misma sesión de Claude Code, extrae la "fuente de verdad" del código actual.
La idea es transformar el comportamiento actual del sistema en especificaciones explícitas.
No estás diseñando algo nuevo todavía.
Estás extrayendo la "fuente de verdad" desde el código existente.
Antes de continuar, es importante entender el concepto de /opsx:explore
Piensa en: explore como una conversación de arquitectura o lluvia de ideas.
/opsx:explore es una fase puramente conversacional.
No modifica archivos.
No genera código.
No altera especificaciones.
Su propósito es:
- investigar,
- razonar,
- explorar alternativas,
- descubrir restricciones,
- y clarificar requisitos.
Durante esta etapa:
- tú explicas el problema,
- la IA analiza la base de código,
- evalúa alternativas,
- y te ayuda a decidir una dirección técnica.
Dejando esto claro, ahora ejecuta:
/opsx:explore
Prompt sugerido:
Lee el archivo repomix-output.xml y analiza la arquitectura y el comportamiento actual del sistema. No generes código ni edites archivos, solo asimila cómo funciona la base de código existente.
La meta aquí es que la IA construya un modelo mental correcto del sistema antes de intentar documentarlo.
Aquí es donde las ideas se vuelven estructura formal.
/opsx:propose baseline
La IA genera:
proposal.mddesign.mdtasks.md- especificaciones dentro de
specs/
Este paso convierte una conversación en documentación ejecutable.
La IA debe:
- documentar comportamiento existente,
- describir módulos actuales,
- capturar contratos reales,
- y evitar inventar funcionalidades nuevas.
Esto es importante:
El objetivo no es modernizar el sistema todavía.
Primero necesitas representar correctamente la realidad actual por eso es importante que revises lo que ha generado.
Busca especialmente:
- ambigüedades,
- suposiciones incorrectas,
- malas interpretaciones,
- decisiones técnicas cuestionables,
- tareas demasiado grandes,
- o requisitos omitidos.
En este puedes realizar correcciones mediante bien sea mediante:
- comando
propose - puedes editarlos manualmente,
- pedirle a la IA que los corrija.
Ejemplo:
Actualiza design.md para usar refresh tokens y separar autenticación de autorización.
Nunca asumas que la primera versión generada es perfecta.
Debes tratar las especificaciones como documentación viva.
En esta fase creas la estructura base, es por esto que solo vamos a archivar lo que se ha definido para consolidarlo como fuente de la verdad.
/opsx:archive
La consola mostrará una advertencia sobre tareas incompletas y especificaciones delta.
Selecciona la opción:
1. Sincronizar specs y archivar
Esto ignorará las tareas vacías y moverá las especificaciones base generadas a tu carpeta maestra openspec/specs/.
Debe responder:
- ¿Qué problema se resuelve?
- ¿Por qué existe el cambio?
- ¿Cuál es el alcance?
- ¿Qué restricciones existen?
Debe contener:
- arquitectura,
- patrones,
- contratos,
- decisiones técnicas,
- tradeoffs,
- riesgos,
- flujo de datos,
- integración entre módulos.
Debe dividir el trabajo en tareas:
- pequeñas,
- concretas,
- verificables,
- y ejecutables sin ambigüedad.
Nunca ejecutes:
/opsx:apply
hasta que confirmes que:
proposal.md,design.md,- y
tasks.md
representan exactamente lo que deseas construir.
Si la especificación es ambigua, la implementación probablemente también lo será.
Con el entorno estabilizado, utiliza exclusivamente el flujo OPSX de cuatro pasos para cualquier cambio.
/opsx:explore [explica el error que encontraste o la nueva función que quieres]
Aquí evalúas:
- alternativas,
- impacto arquitectónico,
- dependencias,
- riesgos,
- y posibles enfoques.
/opsx:propose [nombre-del-cambio-en-kebab-case]
La IA generará:
proposal.mddesign.mdtasks.md- especificaciones delta
Este es el momento de revisar y corregir.
Solo cuando la especificación esté correcta:
/opsx:apply
Claude Code escribirá el código real paso a paso, tachando las casillas de tasks.md sin desviarse del diseño acordado.
Finalmente:
/opsx:archive
Esto:
- cierra la iteración,
- limpia el workspace,
- sincroniza especificaciones,
- y preserva el aprendizaje acumulado.
El valor real de OpenSpec no está únicamente en generar código.
Está en obligar al proyecto a desarrollar una memoria arquitectónica explícita.
En proyectos brownfield eso cambia completamente la dinámica de mantenimiento porque:
- reduce ambigüedad,
- preserva decisiones,
- mejora consistencia,
- facilita onboarding,
- y convierte a la IA en una herramienta contextualizada en lugar de un generador aislado de código.
Si estas en linux, para instalar engram, asegurate de tener go instalado en tu maquina