No puedes pausar el desarrollo. Eso es lo primero que hay que aceptar. Los tickets siguen llegando, los clientes esperan envíos y tu código existente no deja de ejecutarse solo porque hayas decidido documentarlo. Ningún gerente de ingeniería dará luz verde a un congelamiento de un mes para que el equipo pueda escribir la especificación que debería haber existido desde el primer día. OpenSpec fue construido para la realidad, no para fantasías de proyectos desde cero. Funciona mejor cuando lo integras a lo que ya tienes, con clientes y todo.
El objetivo aquí no es una reescritura. Es una arqueología honesta. Excavas lo que realmente se está ejecutando en producción, lo describes con precisión y dejas que esa descripción evolucione a medida que tu código lo hace. Cuando tu especificación coincide con tu sistema, les facilitas la vida a los ingenieros que se incorporen el próximo trimestre y a las herramientas de IA que ahora residen en tu IDE. Aquí te explicamos cómo hacerlo sin perderse ni un solo lanzamiento.
Empieza con lo que realmente haces
Abre tu repositorio y verás carpetas llamadas controllers, models, services y utils. Esas son capas técnicas, y te mienten. No describen lo que tu sistema hace por el negocio. Una carpeta llena de archivos JavaScript no explica cómo un pedido se convierte en un envío. Para adaptar OpenSpec, necesitas pensar en capacidades.
Busca las operaciones comerciales estables que sobrevivirían incluso si reescribieras todo el stack en un lenguaje diferente. En la mayoría de las empresas de producto, estas aparecen una y otra vez: Pedidos, Facturación, Inventario, Clientes y Notificaciones. Nombra de cinco a ocho de estas capacidades principales.
Para cada una, oblígate a responder cinco preguntas específicas. ¿Qué problema del mundo real resuelve esta capacidad? ¿Dónde reside realmente el código: en un servicio, en tres microservicios o en un módulo heredado que nadie quiere tocar? ¿Qué lo activa: un clic de usuario, una tarea cron programada, un webhook entrante? ¿Qué datos entran y qué datos salen? Y finalmente, ¿de qué otros sistemas depende, es decir, qué se rompe si esta pieza deja de funcionar?
Sé brutalmente honesto. Si tu capacidad de "Clientes" está dispersa entre un monolito de Rails, una API de Node y un CRM externo, escríbelo exactamente así. Tu mapa debe parecerse al territorio, no al sueño de un arquitecto.
Escribe la verdad, no una lista de deseos
La frase más peligrosa en cualquier esfuerzo de documentación es: "Ya que estamos escribiendo esto, de paso lo arreglamos". Detente. No estás rediseñando el flujo de pago. Estás describiendo el flujo de pago que está cobrando tarjetas de crédito reales en este momento.
Si realizar un pedido activa una captura de pago inmediata y luego dispara un correo electrónico a través de un worker en segundo plano, documenta esa secuencia exacta. No insertes una cola de eventos que planeas añadir el próximo trimestre. No pretendas que la validación ocurre en el borde de la API si en realidad reside en lo profundo de una clase de servicio. La precisión importa mucho más que la aspiración.
La documentación incorrecta es peor que la inexistente. Entrena a las nuevas contrataciones para que esperen un comportamiento que no existe. Envía a los asistentes de codificación de IA por caminos imaginarios basados en deseos. Cuando tu especificación coincide con producción, creas una base confiable. La depuración se vuelve más rápida porque dejas de adivinar sobre el flujo "previsto". La refactorización se vuelve más segura porque sabes que el punto de partida es real.
Extrae contratos de tus APIs
Tus endpoints de API ya imponen reglas. Simplemente las mantienen implícitas. Adaptar OpenSpec significa sacar esas reglas a la luz.
Empieza con las entradas y la validación. ¿Qué acepta realmente el endpoint? Documenta los tipos, los campos obligatorios, las longitudes máximas y las dependencias entre campos. Luego, describe el comportamiento comercial. ¿Esta llamada crea un registro, activa un efecto secundario o simplemente valida el estado contra otro servicio? Sé específico.
Finalmente, cataloga las respuestas. ¿Qué devuelve el éxito? ¿Cuáles son los códigos de error exactos y bajo qué condiciones aparecen? No escribas "devuelve un error". Escribe "devuelve 422 cuando falta la dirección de facturación y 409 cuando el inventario ya fue reservado por otro proceso". Ese nivel de precisión convierte una ruta vaga en un contrato en el que los equipos de frontend, los ingenieros de QA y las herramientas automatizadas pueden confiar.
Rastrea las reglas ocultas
Some of the most expensive knowledge in your system lives in the gaps. It is buried in conditional blocks inside service classes, tucked into database triggers, or written into stored procedures that no one has touched in two years. These are your business rules, and they are usually rediscovered during outages or by cornering the one engineer who has been there since the beginning.
Pull them into daylight. Start with the ones you already know. Orders above a certain value need manager approval before they proceed. Inactive user accounts cannot create new orders. Refunds are only permitted before settlement completes. Write each rule next to the capability it governs, in language clear enough that a product manager could read it without a translator.
When you centralize these rules, you do more than document them. You expose duplication. You reveal conflicts. And you give the entire team a single place to debate policy before someone commits a one-line change that accidentally violates a constraint you forgot existed.
Map the Plumbing
Modern systems run on events. An action in one service ripples through half a dozen others before anything visible reaches the user. You need to chart those ripples. Map the flow from one event to the next for your core workflows. Order created leads to inventory reserved, which waits for payment confirmed. Draw the full chain, even if some links feel fragile or use different protocols.
Do not stop at internal traffic. External services are part of your system whether you treat them that way or not. For each integration, record its purpose, how your application authenticates, and how it fails. Does the payment gateway timeout after thirty seconds and return a generic 500? Does the shipping API return malformed JSON on weekends? Does the identity provider revoke refresh tokens earlier than its own documentation claims? These details look trivial