DEV Community: David Bernardo

Spec-Driven Development (SDD) con IA: Dejando atrás el 'Vibe Coding' para construir software multiplataforma de grado profesional

David Bernardo — Mon, 21 Sep 2026 21:11:20 +0000

En los últimos meses, el término "Vibe Coding" se ha popularizado en redes y comunidades técnicas: sentarte frente al editor, lanzar prompts vagos a un modelo de lenguaje de última generación, ver cómo el código aparece mágicamente y ajustar a prueba y error hasta que "parezca funcionar".

Para un script de fin de semana o un prototipo desechable, esto puede sentirse como magia. Pero cuando intentas construir software de producción, con concurrencia real, arquitecturas multiplataforma, contratos estrictos y rendimiento de ultra-baja latencia, el "Vibe Coding" se estrella contra la realidad:

La muerte por mil parches: Pides un botón, la IA rompe el estado. Pides arreglar el estado, rompe el ciclo de vida. Pides arreglar el ciclo de vida, introduce fugas de memoria.
La ilusión de avance: El código crece exponencialmente, pero la comprensibilidad del sistema cae en picada.
Imposibilidad de auditoría: Ningún desarrollador humano —ni ningún otro agente de IA en el futuro— puede entender por qué se tomaron ciertas decisiones, cuáles eran los supuestos de diseño o cómo refactorizar sin derrumbar el castillo de naipes.

Existe una alternativa profesional, rigurosa y escalable: Spec-Driven Development (SDD) asistido por Inteligencia Artificial.

En este artículo, desglosaremos la metodología exacta, la arquitectura y los prompts operativos que utilizamos para construir Virtual Studio Companion: una suite multiplataforma con Kotlin Multiplatform (KMP) y Compose Multiplatform que transforma un dispositivo móvil Android en una cámara de transmisión de ultra-baja latencia para OBS Studio en Windows, integrando monitor de video nativo con Skia, código QR ISO/IEC 18004, telemetría bidireccional y cero dependencias de Java en el cliente final.

Todo el código y sus especificaciones están disponibles en el repositorio de código abierto:

👉 GitHub: dhbernardo/virtual-studio-companion (Tag v1.0.1)

1. ¿Qué es Spec-Driven Development (SDD)?

En el desarrollo tradicional, el código fuente suele ser la única fuente de verdad ("el código es la documentación"). Con la llegada de los agentes de IA, esta premisa es peligrosa: los modelos operan sobre ventanas de contexto limitadas y tienden a optimizar soluciones locales a corto plazo sin considerar la integridad global.

En Spec-Driven Development (SDD):

Las especificaciones son documentos vivos y la ÚNICA fuente de verdad (Single Source of Truth). Ninguna línea de código de producción se escribe o modifica si no está expresamente modelada en su especificación.

flowchart LR
    A["📜 spec.md<br/>(Requisitos EARS & Criterios BDD)"] --> B["📐 plan.md<br/>(Arquitectura & Diagramas)"]
    B --> C["✅ tasks.md<br/>(Tareas Atómicas 'Hecho cuando:')"]
    C --> D["🧪 TDD Estricto<br/>(Test Primero -> Código -> Build)"]
    D --> E["📦 Conventional Commit<br/>(Trazabilidad 1:1)"]

La regla de oro ante defectos y restricciones imprevistas

Cuando durante las pruebas de integración descubrimos una restricción de plataforma (por ejemplo, la política Cleartext de Android o una condición de carrera de concurrencia en sockets), NO creamos tareas sueltas ni parches desordenados (e.g. T09: arreglar socket, T10: parche de botones).

Crear tareas sueltas convierte el repositorio en un historial caótico de parches y debilita la especificación principal. Lo canónico en SDD es refinar las especificaciones y tareas existentes en su contexto original (spec.md, plan.md, tasks.md). De este modo, cualquier ingeniero o agente que audite el sistema meses después encontrará la especificación exacta, autocontenida y fiel a la realidad.

2. El Marco de Gobernanza: `docs/constitution.md` y `AGENTS.md`

Para que un agente de IA trabaje con autonomía de alto nivel sin descarriarse, necesita barreras innegociables. En nuestro proyecto, esto se implementó a través de dos archivos fundamentales:

1. La Constitución del Proyecto (`docs/constitution.md`)

Establece las 8 leyes fundamentales que ningún prompt ni decisión técnica puede violar:

Principio	Regla Innegociable
1. Núcleo Puro (`commonMain`)	Prohibido importar `android.`, `java.` o librerías de plataforma en el código compartido. Todo se resuelve mediante Puertos e Interfaces.
2. Cero Java en el Cliente	El ejecutable de Windows se empaqueta con `jpackage` y un micro-runtime Temurin (`jlink`). El usuario final no necesita Java.
3. Licenciamiento Permisivo	Prohibidas librerías con copyleft restrictivo (GPLv3). Solo Apache 2.0, MIT, BSD.
4. Resiliencia de Red	Nunca asumir que mDNS funciona (por routers con AP Isolation). El código QR es el mecanismo primario incondicional.
5. Paridad de Temas	Soporte estricto para modo oscuro (`StudioDarkColors`) y modo claro (`StudioLightColors`), detectando el sistema (`isSystemInDarkTheme()`).
6. SDD y TDD Primero	No se implementa código sin prueba unitaria previa que valide el comportamiento esperado.
7. CI/CD sin Fricción	Pipelines automatizados en GitHub Actions para Linux (`app-debug.apk`) y Windows (`.exe` / `.msi`).
8. Cero Hardcoded Strings	Prohibido escribir texto literal en UI o composables. El 100% de textos proviene de `Res.string.*`.

2. El Contexto del Agente (`AGENTS.md`)

Define la topología del monorepo, los comandos frecuentes (./gradlew allTests, ./gradlew :desktopApp:desktopTest), el flujo de trabajo SDD y la prohibición expresa de improvisar código.

3. La Anatomía de una Especificación SDD (`specs/<feature>/`)

Cada módulo o funcionalidad del sistema vive dentro de specs/ y se descompone en tres artefactos complementarios:

specs/003-desktop-windows-host/
├── spec.md      # Requisitos del Negocio y Criterios de Aceptación
├── plan.md      # Diseño Técnico, Diagramas y Decisiones Arquitectónicas
└── tasks.md     # Checklist de Tareas Incrementales y Verificables

A. `spec.md`: Requisitos EARS y Criterios BDD

Los requisitos se redactan usando la sintaxis EARS (Easy Approach to Requirements Syntax) y criterios de aceptación BDD (Dado-Cuando-Entonces):

### RF-003: Integración Automática, Control Simétrico y Resiliencia con OBS Studio
- **Tipo:** Event-driven
- **Definición:** CUANDO el Host detecte que OBS Studio está en ejecución (o al pulsar "Conectar OBS"), el sistema DEBE conectarse al puerto 4455 implementando IObsConnector, resolver el desafío SHA256 y crear/actualizar la fuente Browser Source "Virtual Studio Camera".
- **Criterio de Aceptación:**
  - **DADO QUE** OBS Studio está conectado activamente
  - **CUANDO** el usuario pulsa "Desconectar OBS" en el dashboard
  - **ENTONCES** el Host debe cerrar limpiamente el socket con OBS, transitar a DISCONNECTED y cancelar reintentos, preservando intacta la transmisión móvil activa y el monitor de retorno Skia.

B. `plan.md`: Diagramas de Secuencia y Arquitectura

Incluye diagramas Mermaid que modelan el flujo de estados y la secuencia de comunicación entre el streamer, el Host Ktor, la app Android y OBS Studio:

sequenceDiagram
    autonumber
    actor Streamer as Streamer (Windows)
    participant Host as Desktop Host (Compose + Ktor)
    participant Phone as Android App
    participant OBS as OBS Studio (:4455)

    Host->>Host: Enlaza Ktor (8080-8090) & Genera QR con TTL (120s)
    Phone->>Host: Escanea QR y envía HANDSHAKE_INIT(token)
    Host->>Phone: HANDSHAKE_ACK (Sesión validada)
    Host->>OBS: CreateInput / SetInputSettings ("browser_source")
    Phone->>Host: Transmite tramas JPEG binarias (/ws/stream)
    Host->>Host: Decodifica con Skia (Image.makeFromEncoded)
    Host->>Streamer: Renderiza Monitor de Retorno 16:9 en Compose Desktop
    Host->>OBS: Sirve stream multipart (/stream/mjpeg)

C. `tasks.md`: La Condición "Hecho cuando:"

Cada tarea atómica define una condición estricta e incontrovertible. Un checkbox [x] no se marca por intuición; solo se marca si la condición se cumple y la terminal lo certifica:

- [x] **T04: Implementación de `ObsWebSocketAdapter` implementando `IObsConnector`**  
  *Requisitos cubiertos:* `RF-003`, `RNF-003`  
  *Hecho cuando:* El adaptador resuelva el handshake autenticado en `ws://localhost:4455`, implemente `KtorObsTransport` con buffer de repetición (`replay = 1`) previniendo pérdida del frame `op: 0`, soporte desconexión explícita (`disconnect()`) sin bucles en `finally`, configure de forma idempotente la fuente Browser Source `Virtual Studio Camera`, y apruebe las pruebas de `T03`.

4. El Kit de Prompts Operativos (Copia y Pega)

Aquí radica el secreto para que una IA no degrade el proyecto. Diseñamos cuatro prompts clave para cada momento del ciclo de vida del software:

Prompt 1: Ejecución Secuencial Completa (Batch SDD)

Utilízalo cuando la especificación, el plan y las tareas estén completamente definidos y desees que el agente ejecute con rigor senior:

Actúa como un desarrollador senior y ejecuta de forma autónoma y secuencial TODAS las tareas pendientes de `[NUMERO-NOMBRE-SPEC]/tasks.md`.

Antes de comenzar:
1. Lee `docs/constitution.md` y `AGENTS.md` (respetando todas las restricciones: cero strings en crudo, licencias permisivas, independencia de `shared/commonMain`).
2. Lee `[NUMERO-NOMBRE-SPEC]/plan.md` y `[NUMERO-NOMBRE-SPEC]/spec.md`.

Para CADA tarea pendiente en `tasks.md`, ejecuta en bucle estricto:
1. IDENTIFICACIÓN:
   - Identifica los requisitos (RF/RNF) y la condición "Hecho cuando:".
   - Clasifica la tarea:
     a) ¿Es Lógica de Dominio, Protocolo, Caso de Uso o ViewModel? -> APLICA TDD ESTRICTO (Paso 2A).
     b) ¿Es Infraestructura de Build, CI/CD, Tokens o Recursos? -> APLICA VERIFICACIÓN DE BUILD (Paso 2B).

2. EJECUCIÓN SEGÚN EL TIPO:
   - [Paso 2A - TDD]:
     1. Escribe primero las pruebas unitarias pertinentes (`*Test.kt`) cubriendo casos normales, límites y de error.
     2. Implementa el código mínimo para hacer pasar los tests.
     3. Ejecuta el comando de test correspondiente (ej. `./gradlew :shared:allTests` o `./gradlew :desktopApp:desktopTest`).
   - [Paso 2B - Infraestructura / Configuración]:
     1. Implementa los archivos de configuración, scripts de build o recursos.
     2. Ejecuta el comando de validación o compilación (ej. `./gradlew assembleDebug` o linters).

3. EVIDENCIA EN RESPUESTA:
   - Muestra el extracto de la terminal que certifique el éxito (`BUILD SUCCESSFUL` o `Tests PASSED`).

4. ACTUALIZACIÓN DE TASKS:
   - Marca con `[x]` el checkbox en `tasks.md` ÚNICAMENTE si se cumple la condición "Hecho cuando:".

5. GIT COMMIT:
   - Crea un commit con formato Conventional Commits en inglés (según `git-conventions`).

AL FINALIZAR TODAS LAS TAREAS DEL SPEC:
- Presenta la Matriz de Trazabilidad de Requisitos.
- Confirma que no se vulneró ningún Principio de `docs/constitution.md`.

Prompt 2: Ejecución Tarea por Tarea (Paso a Paso Supervisado)

Ideal para desarrolladores que prefieren un control minucioso antes de cada avance:

Actúa como un desarrollador senior.
Lee `docs/constitution.md`, `AGENTS.md`, y el trío `specs/[MODULO]/spec.md`, `plan.md` y `tasks.md`.

Ejecuta EXCLUSIVAMENTE la tarea [ID_TAREA] de `tasks.md`.
1. Aplica TDD estricto si es lógica/UI: escribe el test unitario primero, hazlo fallar, implementa el código mínimo para que pase.
2. Ejecuta el comando de verificación en terminal correspondiente.
3. Cumplida la condición "Hecho cuando:", marca `[x]` en `tasks.md`.
4. Crea el commit atómico en inglés siguiendo Conventional Commits.
5. DETENTE y espera mi confirmación antes de proceder con la siguiente tarea.

Prompt 3: El Diagnóstico Crítico ("Cero Parches Prematuros")

Cuando ocurre un error durante las pruebas manuales o automatizadas, nunca le pidas a la IA que lo arregle de inmediato. Primero aíslala para que analice la causa raíz:

[Pega aquí los logs de terminal, trazas de excepción, comportamiento anómalo observado o contexto de la prueba realizada]

Identifica los problemas, no plantees soluciones todavía. Solicita si requieres más contexto, trazas o mayor detalle de lo que está ocurriendo.

¿Por qué este prompt es vital?

Si le dices a la IA "tengo este error, arréglalo", asumirá una solución apresurada que casi siempre consiste en parchotear el código local, rompiendo contratos arquitectónicos. Al forzarla a limitarse a diagnosticar, la IA analiza el flujo de llamadas, identifica condiciones de carrera o inconsistencias de estado, y tú como desarrollador validas la hipótesis técnica antes de que toque un solo archivo.

Prompt 4: El Refinamiento SDD Canónico (Sin Tareas Sueltas)

Una vez identificado y consensuado el problema, utiliza este prompt para actualizar la especificación:

Crear un plan para refinar las especificaciones y tareas existentes, planes, evitar crear tareas sueltas, ya que esto convierte el proyecto en un historial caótico de parches y debilita la especificación principal (rompiendo las reglas de SDD).
De esta manera, cualquier desarrollador o agente que en el futuro vuelva a implementar o auditar el sistema tendrá la especificación exacta y autocontenida.

5. Caso de Estudio Real: Virtual Studio Companion

Para ilustrar el poder de esta metodología, veamos cómo resolvimos cuatro desafíos de alta complejidad durante el desarrollo de nuestro sistema.

¿Qué hace la aplicación?

Móvil Android: Captura video a 1080p con CameraX, comprime cuadros a JPEG aplicando la matriz de rotación del sensor en un subproceso dedicado (CameraX-Worker), calcula FPS/bitrate reales en una ventana deslizante de 1000 ms, y transmite tramas binarias por WebSocket hacia el Host. Escanea códigos QR con Google ML Kit acelerado por hardware.
Desktop Windows (Host): Servidor local embebido con Ktor (fallback automático en puertos 8080-8090). Genera códigos QR conforme a ISO/IEC 18004 con ZXing Core. Decodifica las tramas de video en tiempo real mediante Skia (org.jetbrains.skia.Image.makeFromEncoded) para renderizar un Monitor de Retorno de Video Nativo en Compose Desktop.
Integración con OBS Studio: Sirve un stream multipart HTTP continuo en /stream/mjpeg y una página web responsive en /stream/preview. Se comunica vía WebSocket con OBS Studio v5, resolviendo desafíos criptográficos SHA256 para inyectar automáticamente una fuente Browser Source en la escena activa.
Sincronización Bidireccional: Control remoto de zoom y linterna en ambas direcciones sin bucles de rebote (echo loops), junto a telemetría viva de batería, estado térmico y latencia RTT (Ping/Pong).

Caso 1: La Política Cleartext y el Visor Perforado en Android

El problema: Al intentar conectar por primera vez el teléfono al Host por Wi-Fi, Android abortaba con UnknownServiceException: CLEARTEXT communication not permitted. Además, el visor de escaneo de QR renderizaba un recuadro negro sólido sobre la cámara.
El enfoque "Vibe Coding" habría hecho: Agregar un flag suelto en el manifest y poner hacks en la vista.
Cómo se resolvió en SDD:
1. Se refinó RF-001 en specs/004-android-mobile-app/spec.md para abarcar el soporte de contingencia manual (ingreso de IP y token) y la política de red local como requisito no funcional formal (RNF-005).
2. Se implementó network_security_config.xml habilitando tráfico local en redes privadas.
3. En ScannerOverlay, se descubrió que BlendMode.Clear perforaba las capas de Compose hasta el fondo negro nativo. Se refinó la tarea canónica T08 para aplicar Modifier.graphicsLayer(compositingStrategy = CompositingStrategy.Offscreen), logrando un recorte translúcido al 50% con nitidez cristalina.

Caso 2: El Rebote Reactivo en el Arranque de Sesión

El problema: Al enfocar el código QR, la app móvil detectaba el token, abría la pantalla de streaming y de inmediato rebotaba hacia la pantalla de escaneo.
El diagnóstico con Prompt 3: La pantalla CameraScreen observaba uiState.connectionState. Como el ViewModel nacía por defecto en Disconnected y la corrutina de conexión demoraba unos milisegundos en arrancar, el observador interpretaba el estado inicial como una desconexión y llamaba a onDisconnect().
El refinamiento con Prompt 4: Se actualizaron las tareas canónicas T06 y T07 de 004-android-mobile-app:
- CameraStreamViewModel ahora acepta initialConfig: PairingConfig? y nace de inmediato en estado ConnectionState.Pairing(config).
- Se incorporó un guardián reactivo (hasActiveSession) que solo permite ejecutar onDisconnect() si la sesión estuvo previamente en Connected o Streaming.

Caso 3: La Condición de Carrera en el WebSocket de OBS (`replay = 1`)

El problema: Si el usuario conectaba OBS antes de emparejar el móvil, funcionaba perfecto. Pero si emparejaba el móvil primero y luego pulsaba "Conectar OBS", el Host caía invariablemente en OBS Error y Conectando..., a pesar de que el stream de video seguía activo en OBS.

El diagnóstico con Prompt 3:

En KtorObsTransport, el flujo de mensajes entrantes estaba configurado como:

 // ❌ ANTES: replay = 0 por defecto
 private val _incoming = MutableSharedFlow<String>(extraBufferCapacity = 64)

Cuando el móvil ya está transmitiendo video, el despachador de hilos de la CPU se encuentra bajo carga procesando tramas binarias y decodificando imágenes Skia.
Al pulsar "Conectar OBS", el socket se abría y OBS Studio respondía de inmediato con el frame inicial op: 0 (Hello).
Pero el recolector de corrutinas (transport.incoming.collect) tardaba unos pocos milisegundos en suscribirse. Al tener replay = 0, el mensaje op: 0 se descartaba.
El adaptador se quedaba esperando un saludo que nunca llegaría, alcanzaba el timeout de 4 segundos y caía en error.
En las pruebas unitarias pasaba porque el mock FakeObsTransport tenía por casualidad replay = 1 configurado.
- El refinamiento con Prompt 4: Se refinaron RF-003 y las tareas T03 y T04 en specs/003-desktop-windows-host/:

  // ✅ DESPUÉS: replay = 1 garantizado y suscripción atómica previa
  private val _incoming = MutableSharedFlow<String>(replay = 1, extraBufferCapacity = 64)

Además, la suscripción al canal se realiza antes de abrir el socket de red y bajo protección de un Mutex.

Caso 4: Desconexión Simétrica e Independiente de OBS

El problema: Cuando OBS se conectaba, el botón "Conectar OBS" desaparecía de la interfaz y no había forma de desconectarlo. El único botón visible era "Desconectar", pero ese botón cerraba la sesión del móvil y devolvía la app al código QR.
El refinamiento SDD: Se actualizaron RF-003, RF-004, T05 y T06:
- Se implementó DesktopHostViewModel.disconnectObs() desacoplado de disconnectSession().
- Se diseñaron botones contextuales en Compose Desktop: si está conectado, muestra Desconectar OBS (Res.string.desktop_action_disconnect_obs); si está desconectado, muestra Conectar OBS.
- El botón rojo general queda reservado para la sesión del teléfono.

6. El Flujo Git: Tareas Atómicas y Conventional Commits

En un flujo SDD profesional, Git no es un vertedero de cambios acumulados. Cada commit representa la culminación verificable de una tarea o refinamiento:

# Historial real del repositorio Virtual Studio Companion
58deef0 feat(desktop): support independent obs disconnect and fix websocket transport race condition
66c9063 docs(specs): refine obs connection and disconnect specifications and tasks
81e14c8 feat(android): implement jpeg frame streaming, live telemetry, and camera controls synchronization
0aaff28 feat(desktop): implement video frame ingestion, skia return monitor, and mjpeg preview for obs
36e58fc docs(specs): refine video streaming and camera controls sync specifications
8395458 fix(android): prevent premature screen exit and initialize CameraStreamViewModel in pairing state
75e5b79 docs(specs): refine mobile pairing initialization and transition guard in spec and tasks
2a64def docs(specs): refine desktop, android, and design system specs and tasks
0c9d6dc fix(desktop): handle client disconnect, restore session disconnect and obs connect in dashboard
a2db8ef fix(android): consume scanned config, handle server disconnect and lifecycle events

Observemos la simetría: cada cambio de código (feat o fix) está precedido o acompañado por su correspondiente actualización en especificaciones (docs(specs)).

7. Conclusiones: El Futuro del Desarrollo Asistido por IA

El debate actual no debería ser si los modelos de lenguaje pueden escribir código rápido —ya sabemos que pueden—. El verdadero desafío es cómo gobernar a la IA para construir sistemas duraderos, tolerantes a fallos y arquitectónicamente limpios.

Al adoptar Spec-Driven Development (SDD):

La IA se convierte en un multiplicador de ingeniería: En lugar de perder horas persiguiendo regresiones aleatorias, guías a la IA a través de contratos estrictos, TDD y validación determinista en terminal.
El proyecto es 100% auditable: Cualquier ingeniero humano o nuevo agente puede inspeccionar specs/, leer los requisitos EARS, revisar los diagramas de secuencia y entender la totalidad del sistema en minutos.
El código resiste el paso del tiempo: La arquitectura Clean y la separación de capas garantizan que el núcleo multiplataforma permanezca puro e inmune a las vicisitudes de las APIs de plataforma.

Recursos y Código Fuente

Repositorio completo (Kotlin 2.x, Compose Multiplatform, Ktor, CameraX, Skia, OBS WebSocket v5): 🔗 https://github.com/dhbernardo/virtual-studio-companion
Tag de la versión estable analizada: v1.0.1.

¿Has probado implementar Spec-Driven Development en tus flujos de trabajo con agentes de IA? ¡Déjame tus comentarios, dudas o experiencias abajo!

Spec-Driven Development (SDD) en Acción: Conectando una Extensión de Chrome (MV3) con Windows usando Node.js

David Bernardo — Sun, 20 Sep 2026 04:56:14 +0000

¿Alguna vez has necesitado que una extensión de Google Chrome interactúe directamente con el hardware de la máquina anfitriona, imprima en impresoras térmicas de tickets, lea puertos serie o extraiga telemetría en tiempo real del sistema operativo?

Si lo has intentado, probablemente te hayas topado con la jaula de cristal: el sandbox del navegador. Por motivos evidentes de seguridad, una extensión web no puede invocar libremente comandos del sistema ni acceder a la memoria de la máquina.

Para romper este aislamiento de forma controlada, Google provee la API Chrome Native Messaging. Sin embargo, cualquiera que haya intentado implementarla en un entorno de producción para Windows sabe que es un campo minado de errores:

Un simple console.log en el host nativo corrompe el socket binario y el navegador desconecta la extensión al instante sin dar pistas.
Obligar al usuario final a tener Node.js o Python preinstalado en su máquina arruina la adopción.
Exigir al usuario que abra regedit.exe para registrar claves en Windows es inviable para usuarios no técnicos.
En la era de la IA, pedirle a un LLM que construya este sistema sin una metodología estricta casi siempre termina en alucinaciones y código incompatible entre subsistemas.

En este artículo veremos cómo resolvimos este desafío de ingeniería aplicando Spec-Driven Development (SDD): diseñamos un sistema completo de Monitoreo de Hardware (CPU, RAM y Uptime) compuesto por una extensión en Manifest V3, un ejecutable nativo .exe autocontenido en Node.js y un instalador automatizado en Inno Setup 6, con cero dependencias externas y 100% de pruebas automatizadas.

Figura 1: Popup de la extensión System Monitor en Google Chrome mostrando telemetría de hardware en tiempo real (UI oscura con glassmorphism).

🏛️ 1. Spec-Driven Development (SDD): El Antídoto contra el Caos

Cuando desarrollas un proyecto con tecnologías heterogéneas (Frontend Web MV3 + Backend nativo PE x64 + Scripts de instalación en Pascal y claves del Registro de Windows), empezar tirando código es la receta garantizada para el fracaso.

En lugar de improvisar, adoptamos Spec-Driven Development (SDD). La regla de oro es simple:

"Ningún archivo de código fuente se crea ni se modifica si el cambio no está previamente especificado en un contrato formal."

La Constitución del Proyecto

Todo el proyecto está gobernado por una constitución innegociable (docs/constitution.md) que define 7 principios:

Protocolo Estricto de 4 Bytes: Toda comunicación por stdin/stdout debe anteponer un prefijo little-endian UInt32LE. Prohibido emitir texto plano o logs a stdout.
Cero Dependencia de Node.js en el Cliente: El host debe compilarse como binario .exe x64 independiente.
Instalación Transparente y Automatizada: Registro en Windows (HKCU\Software\Google\Chrome\NativeMessagingHosts) gestionado 100% por el instalador.
Compatibilidad Estricta con Manifest V3: Operación exclusiva mediante Service Workers asíncronos sin background pages obsoletas.
Aislamiento de Errores y Resiliencia: Captura de desconexiones y timeouts con degradación visual elegante sin bloquear el navegador.
Desarrollo Guiado por Especificación (SDD): Trazabilidad documental de cada requisito mediante sintaxis EARS (Easy Approach to Requirements Syntax).
Arquitectura Hexagonal (Puertos y Adaptadores): El dominio puro debe estar aislado de node:os, process.stdin o chrome.runtime.

La Topología del Monorepo

Siguiendo las directrices constitucionales, el repositorio se organizó en 3 subsistemas independientes:

chrome-native-messaging-sdd/
├── host/                             # SUBSISTEMA 1: Host Nativo en Node.js
│   ├── src/                          # Código fuente (core, ports, adapters)
│   ├── scripts/set-metadata.js       # Inyector PE que preserva el overlay de pkg
│   ├── dist/                         # Binario compilado: system_monitor_host.exe
│   └── tests/                        # Pruebas unitarias, integración y benchmarks
│
├── extension/                        # SUBSISTEMA 2: Extensión Chrome MV3
│   ├── manifest.json                 # Manifiesto V3 con clave RSA determinista
│   ├── background.js                 # Service Worker (Composition Root)
│   ├── core/                         # Formateadores matemáticos y máquina de estados
│   ├── popup/                        # Interfaz visual oscura (HTML/CSS/JS)
│   └── tests/                        # Suite de pruebas con simulación JSDOM
│
├── installer/                        # SUBSISTEMA 3: Instalador de Windows
│   ├── setup.iss                     # Script de Inno Setup 6 (Modo Usuario)
│   ├── manifest-template.json        # Plantilla JSON del host
│   └── output/                       # Artefacto final: Setup_SystemMonitor.exe
│
├── specs/                            # ESPECIFICACIONES SDD FORMALES
│   ├── 001-native-protocol-host/     # Fase 1: Protocolo y Host
│   ├── 002-chrome-extension-ui/      # Fase 2: Extensión y UI
│   └── 003-windows-installer-pkg/    # Fase 3: Empaquetado e Instalador
└── docs/constitution.md              # Constitución y principios innegociables

🔌 2. El Protocolo Binario: 4 Bytes UInt32LE y la Trampa de stdout

Chromium se comunica con los ejecutables nativos mediante tuberías estándar (process.stdin y process.stdout). La especificación oficial exige que cada mensaje tenga un formato exacto:

Prefijo de Longitud (4 bytes): Un entero sin signo de 32 bits en formato little-endian (UInt32LE) con la longitud $L$ del mensaje en bytes.
Payload JSON ($L$ bytes): El string JSON serializado en UTF-8 (tamaño máximo: 1 MB).

Estructura Binaria del Stream:
[ Byte 0 ] [ Byte 1 ] [ Byte 2 ] [ Byte 3 ] [ Byte 4 ... Byte 4 + L - 1 ]
└─────────────── UInt32LE (L) ──────────────┘└────── Payload JSON (UTF-8) ──────┘

La Trampa Mortal: ¿Por qué `console.log` Rompe Todo?

En Node.js, la primera reacción de cualquier desarrollador para depurar es escribir console.log("Mensaje recibido").

En Chrome Native Messaging, hacer esto es fatal: console.log emite texto plano por process.stdout sin la cabecera de 4 bytes. Chromium lee los primeros 4 caracteres ASCII como si fueran un entero binario (por ejemplo, el texto "Hola" equivale al número 0x616C6F48 = 1.634.553.672 bytes). Como el tamaño supera el límite de 1 MB o agota el stream, Chrome destruye el socket y cierra la extensión inmediatamente.

Nuestra Solución en SDD:

Todo el diagnóstico del sistema se redirige estrictamente a process.stderr, el cual Chrome captura en sus logs internos sin tocar el socket de datos.
La salida por stdout se gestiona a través de un adaptador exclusivo:

// host/src/adapters/outbound/binary-stream-writer.js
export class BinaryStreamWriter {
  constructor(writableStream = process.stdout) {
    this.stream = writableStream;
  }

  write(payload) {
    const jsonString = JSON.stringify(payload);
    const payloadBuffer = Buffer.from(jsonString, 'utf8');
    const lengthBuffer = Buffer.alloc(4);
    lengthBuffer.writeUInt32LE(payloadBuffer.length, 0);

    // Emisión atómica de cabecera + payload
    this.stream.write(Buffer.concat([lengthBuffer, payloadBuffer]));
  }
}

Tolerancia a Fragmentación de Chunks

En Windows, las tuberías de consola pueden entregar los datos fragmentados (por ejemplo, 2 bytes de longitud en un paquete y el resto en el siguiente). Nuestro lector acumula los fragmentos en memoria hasta completar exactamente la longitud esperada antes de intentar deserializar el JSON:

> npm --prefix host test

# Subtest: Inbound Adapter: BinaryStreamReader
    ok 1 - debe deserializar un mensaje completo en un único chunk
    ok 2 - debe tolerar fragmentación en múltiples chunks contiguos
    ok 3 - debe procesar múltiples mensajes consecutivos en un mismo buffer
    ok 4 - debe emitir error si la longitud supera el límite de 1 MB
    ok 5 - debe emitir error ante JSON corrupto o malformado

⚡ 3. La Extensión Chrome MV3: Determinismo y Sondeo Secuencial

En Google Chrome Manifest V3, las extensiones ya no tienen páginas de fondo (background pages) persistentes; ahora usan Service Workers efímeros que se suspenden cuando no hay actividad.

El Desafío del Extension ID

Para que el host nativo acepte comunicarse con una extensión, debe declararla explícitamente en el arreglo "allowed_origins" de su manifiesto JSON:

"allowed_origins": [
  "chrome-extension://nknhjeknlgdehgjeoddeiibmpoicbgdc/"
]

Normalmente, al cargar una extensión descomprimida en desarrollo, Chrome calcula un ID dinámico basado en la ruta absoluta de la carpeta en disco. Si mueves el proyecto de carpeta, el ID cambia y la conexión falla.

¿Cómo lo resolvimos?

Generamos un par de claves RSA e inyectamos la clave pública en el campo "key" de extension/manifest.json:

{
  "manifest_version": 3,
  "name": "System Monitor",
  "version": "1.0.0",
  "permissions": ["nativeMessaging"],
  "background": {
    "service_worker": "background.js",
    "type": "module"
  },
  "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAv4RuKyfoD6m..."
}

Gracias a esto, Chrome genera siempre el mismo ID determinista e inmutable:

Figura 2: La extensión cargada en chrome://extensions/ con su ID determinista garantizado por la clave pública RSA.

Sondeo Secuencial Anti-Solapamiento

En aplicaciones de monitoreo es común caer en la tentación de usar setInterval(fetchMetrics, 1000). Si una llamada tarda 1.2 segundos, las peticiones comienzan a encolarse en vuelo, saturando la tubería de Windows.

En su lugar, nuestro Service Worker implementa un sondeo secuencial con control de ciclo de vida:

Envía { "action": "GET_METRICS" } a través del puerto chrome.runtime.connectNative.
Espera la respuesta (con un timeout de seguridad de 5000 ms).
Tras procesar la respuesta, programa un reposo de 1000 ms mediante setTimeout.
Si el usuario cierra el popup, el Service Worker llama a port.disconnect() y Windows termina el proceso del host nativo de inmediato, liberando los recursos de la máquina.

📦 4. De Script a Binario Independiente (.exe) y el Secreto del Overlay

El Principio 2 de nuestra constitución prohíbe exigir Node.js en la máquina del usuario. Para compilar el código de Node.js a un único binario x64 utilizamos @yao-pkg/pkg:

"scripts": {
  "build:exe": "pkg . --targets node18-win-x64 --output dist/system_monitor_host.exe"
}

El "Gotcha" de Ingeniería: La Corrupción del Overlay PE

Cuando compilas un script con pkg, este empaqueta el runtime de Node.js junto con un archivo virtual que contiene tu código JS anexado al final del ejecutable (lo que en la estructura PE de Windows se conoce como Overlay).

Al intentar inyectar el icono de la aplicación (icon.ico) y los metadatos de versión utilizando la herramienta estándar rcedit:

rcedit expande la sección .rsrc de la cabecera PE.
Esto desplaza físicamente los bytes del overlay hacia adelante.
Al arrancar el .exe, el bootstrap de Node.js busca su código en las posiciones originales y arroja: Cannot find entry point / Invalid payload offset.

Para solucionarlo, construimos un script automatizado (host/scripts/set-metadata.js) que opera quirúrgicamente sobre el binario:

flowchart LR
  A["system_monitor_host.exe"] --> B["1. Extraer Overlay (Payload JS)"]
  B --> C["2. Ejecutar rcedit (Inyectar Icono en .rsrc)"]
  C --> D["3. Re-anexar Overlay al final del binario"]
  D --> E["4. Recalcular y parchar PAYLOAD_POSITION y PRELUDE_POSITION"]

El resultado es un ejecutable nativo de ~40 MB, con icono personalizado de Windows y arranque instantáneo.

🛠️ 5. Instalador Inno Setup: Cero Clics en el Registro y UTF-8 sin BOM

El último eslabón de la suite es la experiencia de instalación. Nadie quiere obligar a sus usuarios a abrir regedit.exe para registrar un archivo JSON.

Creamos un instalador con Inno Setup 6 (installer/setup.iss) configurado bajo premisas estrictas:

Despliegue en Modo Usuario (Sin UAC)

Configuramos PrivilegesRequired=lowest y desplegamos en {localappdata}\Programs\SystemMonitorHost. Cualquier usuario estándar puede instalar el software sin requerir permisos de Administrador ni ver advertencias de UAC.

Registro Automatizado en Windows

El instalador crea la clave de integración en la colmena del usuario actual:

[Registry]
Root: HKCU; Subkey: "Software\Google\Chrome\NativeMessagingHosts\com.tuempresa.systemmonitor"; \
    ValueType: string; ValueData: "{app}\com.tuempresa.systemmonitor.json"; Flags: uninsdeletekey

El Detalle Crítico: UTF-8 sin BOM

Chromium exige que el archivo de manifiesto JSON esté codificado en UTF-8 estricto sin BOM (Byte Order Mark). Si se guarda con los 3 bytes iniciales de BOM (\xEF\xBB\xBF), el parser C++ de Chrome falla en silencio y arroja Specified native messaging host not found.

En el script Pascal del instalador forzamos la codificación limpia:

SaveStringsToUTF8FileWithoutBOM(ManifestPath, Lines, False);

Terminación Atómica de Procesos

Si la extensión está abierta mientras el instalador se ejecuta, Windows bloquea el archivo .exe con un handle abierto. Las rutinas PrepareToInstall y CurUninstallStepChanged ejecutan de fondo taskkill /F /IM system_monitor_host.exe antes de reemplazar archivos o desinstalar, garantizando una instalación y remoción 100% limpia.

🧪 6. Resultados y Verificación de Calidad

Gracias a la metodología SDD, cada requisito funcional especificado cuenta con su correspondiente prueba automatizada:

> npm test

✔ Host Nativo (26 tests)
  - Deserialización de stream binario y tolerancia a fragmentación
  - Enrutamiento de comandos y envelopes estructurados
  - Rendimiento y latencia de respuesta (<50 ms)
✔ Extensión Chrome MV3 (61 tests)
  - Puerto de mensajería y ciclo de vida del Service Worker
  - Formateadores matemáticos de RAM (GB binarios 1024^3) y Uptime
  - Máquina de estados finita (LOADING, DASHBOARD, ERROR)
✔ Binario Independiente Windows (3 tests)
  - Validación de cabeceras PE x64
  - Ejecución aislada sin Node.js en variables de entorno
  - Respuesta a GET_METRICS vía stdio directo
----------------------------------------------------------------------
Total: 90 tests pasando al 100%

Además, el script de PowerShell tests/installer/verify-install.ps1 ejecuta un ciclo completo desatendido:

Instala el host en modo silencioso (/VERYSILENT).
Valida que el archivo JSON esté en UTF-8 sin BOM y con rutas dobles (\\).
Consulta el registro de Windows con Get-ItemProperty verificando la subclave en HKCU.
Desinstala la aplicación comprobando que no quede ningún rastro en el sistema.

🚀 Conclusiones y Código Fuente

Conectar la web con el sistema operativo anfitrión a través de Chrome Native Messaging es una herramienta con un potencial inmenso para arquitecturas híbridas, aplicaciones empresariales y herramientas de desarrollo.

La diferencia entre un prototipo frágil que se rompe con cualquier log y una solución de grado de producción radica en la disciplina metodológica:

Spec-Driven Development (SDD) proporcionó el marco para planificar contratos binarios antes de escribir código.
La Arquitectura Hexagonal aisló la lógica del DOM y del sistema operativo, permitiendo probar el 100% de la lógica sin mocks complejos.
La automatización de empaquetado e instalación convirtió un conjunto de scripts en un producto listo para el usuario final.

Todo el código fuente, especificaciones EARS y scripts de compilación están disponibles de forma abierta:

👉 Repositorio en GitHub: https://github.com/dhbernardo/chrome-native-messaging-sdd

¿Has trabajado antes con Chrome Native Messaging o aplicado Spec-Driven Development en tus proyectos? ¡Cuéntame tus experiencias y dudas en los comentarios!

Cómo construí mi portafolio en 4 frameworks (React 19, Vue 3.5, Angular 19 y Compose HTML) usando Clean Architecture

David Bernardo — Fri, 18 Sep 2026 19:43:40 +0000

Como desarrollador Full Stack & Mobile Senior, a menudo me encuentro con el mismo dilema en las entrevistas técnicas:

"Veo en tu CV que manejas React, Vue, Angular y Kotlin Multiplatform... ¿pero en cuál te sientes más cómodo?"

Cualquiera puede listar una docena de tecnologías en un PDF. Pero en el mundo del desarrollo de software, el código habla más fuerte que las palabras.

Por eso me propuse un reto de ingeniería: en lugar de crear un portafolio tradicional en una sola tecnología, decidí construir una misma aplicación idéntica en los cuatro ecosistemas más potentes de la actualidad, permitiendo al usuario cambiar de framework en caliente con un solo clic, sin perder el estado ni la posición de lectura:

⚛️ React 19 (Vite + Hooks personalizados)
💚 Vue 3.5 (Composition API + Composables)
🅰️ Angular 19 (Standalone Components + Nuevas Signals)
🟣 Kotlin Multiplatform / Compose HTML (Kotlin compilado a JS/Web)

¿La trampa? Si creas 4 proyectos separados, estás cuadruplicando el esfuerzo de mantenimiento: cada vez que actualizas un empleo, una habilidad o un proyecto, tendrías que modificar 4 bases de código distintas.

Aquí es donde entra la verdadera protagonista de este proyecto: Clean Architecture (Arquitectura Limpia) en un Monorepo.

🏛️ La Arquitectura: Separando la lógica del framework

Para evitar duplicar código, la regla de oro fue: ningún framework debe ser dueño de la lógica ni de los datos. Los frameworks son simplemente mecanismos de entrega (presenters o adaptadores de entrada).

Estructuré el proyecto en un monorepo con Yarn Workspaces:

├── packages/
│   ├── core/                  # 🧠 Dominio puro (Entidades, Casos de Uso, Puertos)
│   ├── content-json-adapter/  # 🔌 Adaptador de infraestructura (i18n, lectura de JSON)
│   └── tokens/                # 🎨 Variables CSS de diseño y temas
├── apps/
│   ├── react-app/             # ⚛️ UI en React 19
│   ├── vue-app/               # 💚 UI en Vue 3.5
│   ├── angular-app/           # 🅰️ UI en Angular 19
│   └── compose-app/           # 🟣 UI en Kotlin Compose HTML
└── shell/                     # 🐚 Host orquestador y Dock Switcher

1. El Núcleo de Dominio (`packages/core`)

Este paquete es TypeScript puro y no tiene una sola línea de código acoplada al navegador, al DOM o a librerías externas. Contiene:

Entidades: Modelos de dominio como Experience, Project, Profile, SkillCategory.
Puertos (Interfaces): Define el contrato ContentRepository:

  export interface ContentRepository {
    getProfile(): Profile;
    getExperiences(): Experience[];
    getProjects(): Project[];
    getSkills(): SkillCategory[];
  }

Casos de Uso: Funciones puras con la lógica de negocio, por ejemplo getExperienceTimeline o filterProjectsByTech:

  export function getExperienceTimeline(
    repo: ContentRepository, 
    locale: SupportedLocale
  ): ExperienceVM[] {
    const raw = repo.getExperiences();
    return raw
      .sort((a, b) => new Date(b.startDate).getTime() - new Date(a.startDate).getTime())
      .map(exp => mapToExperienceVM(exp, locale));
  }

2. El Adaptador de Datos (`packages/content-json-adapter`)

Implementa el puerto ContentRepository leyendo la fuente única de verdad (archivos JSON estructurados) y gestionando la traducción dinámica entre Español e Inglés.

⚔️ La Comparativa: ¿Cómo consume cada framework el mismo caso de uso?

Aquí viene la parte más fascinante: el consumo del caso de uso en cada tecnología.

Al estar la lógica en packages/core, los componentes de la interfaz solo tienen una responsabilidad: renderizar el ViewModel. Veamos cómo se implementa la reactividad en cada uno:

1. ⚛️ React 19: Con Custom Hooks

En React creamos un hook usePortfolio que encapsula la suscripción al idioma:

// apps/react-app/src/hooks/usePortfolio.ts
export function usePortfolio() {
  const { locale } = useI18n();
  const repo = useMemo(() => new JsonContentRepository(), []);

  const experiences = useMemo(
    () => getExperienceTimeline(repo, locale),
    [repo, locale]
  );

  return { experiences };
}

2. 💚 Vue 3.5: Con Composition API y Composables

En Vue aprovechamos la reactividad nativa con computed:

// apps/vue-app/src/composables/usePortfolio.ts
export function usePortfolio() {
  const { locale } = useI18n();
  const repo = new JsonContentRepository();

  const experiences = computed(() => 
    getExperienceTimeline(repo, locale.value)
  );

  return { experiences };
}

3. 🅰️ Angular 19: Con Signals Nativas

Angular 19 ha revolucionado su reactividad abandonando la complejidad excesiva de RxJS en componentes para adoptar Signals. Observa qué limpio queda:

// apps/angular-app/src/app/services/portfolio.service.ts
@Injectable({ providedIn: 'root' })
export class PortfolioService {
  private contentRepo = new JsonContentRepository();
  private i18n = inject(I18nService);

  // Signal calculada automáticamente cuando cambia locale()
  experiences = computed(() => 
    getExperienceTimeline(this.contentRepo, this.i18n.locale())
  );
}

4. 🟣 Kotlin Compose HTML: Declaratividad en la Web

En Compose para Web utilizamos el paradigma declarativo de Jetpack Compose:

// apps/compose-app/src/jsMain/kotlin/.../App.kt
@Composable
fun App(viewModel: PortfolioViewModel) {
    val locale by viewModel.locale.collectAsState()
    val experiences = remember(locale) { 
        viewModel.getExperienceTimeline(locale) 
    }

    ExperienceSection(experiences = experiences)
}

💡 Lección clave: Cada framework brilla a su manera, pero ninguno reinventa la rueda. Si mañana decido añadir un nuevo empleo a mi trayectoria profesional, solo edito un archivo JSON y los 4 frameworks lo reflejan al instante con sus respectivos badges (Full-time o Freelance).

🎨 Sistema de Diseño Agnóstico: Vanilla CSS

Uno de los errores comunes al hacer microfrontends es usar Tailwind o librerías pesadas (Material UI, Vuetify, PrimeNG) en cada aplicación, provocando colisiones de nombres de clases y una descarga masiva de megabytes innecesarios.

La solución fue Vanilla CSS moderno con Tokens de Diseño compartidos:

Se definieron variables CSS para colores, espaciados, fuentes y sombras (--color-primary, --color-surface, --radius-lg).
Se implementaron temas Oscuro y Claro (Dark/Light Mode) con color-scheme y variables en el elemento raíz.
Cada microfrontend utiliza exactamente las mismas clases semánticas (.timeline-card, .badge, .project-card). El resultado es una paridad visual del 100%.

🐚 El Shell Host y el Switcher Dinámico

¿Cómo orquestamos los 4 microfrontends en una sola página?

Diseñé un Shell Host ligero en TypeScript puro que:

Monta la aplicación seleccionada mediante un contenedor dinámico.
Dock lateral interactivo en pantallas de escritorio y Floating Action Button (FAB) flotante al estilo Android en dispositivos móviles.
Sincroniza el idioma actual (es / en), el tema visual y la posición de scroll para que la transición entre frameworks sea instantánea e imperceptible.

🐳 Despliegue y Build con Docker y Nginx

Compilar 4 frameworks con herramientas tan diversas (Vite, Angular CLI y el compilador de Kotlin/Gradle) puede ser un desafío en CI/CD.

Para resolverlo:

Usamos Docker para garantizar un entorno reproducible con Node.js 22 y OpenJDK 17.
Un script orquestador (scripts/assemble-dist.mjs) compila cada aplicación y las ensambla en una estructura de producción limpia:

   dist/
   ├── index.html        # Shell host
   ├── react/            # Bundle de React 19
   ├── vue/              # Bundle de Vue 3.5
   ├── angular/          # Bundle de Angular 19
   └── compose/          # Bundle Wasm/JS de Compose

Un contenedor Nginx sirve los artefactos con compresión Gzip, cabeceras de caché inmutable para assets versionados y soporte de rutas SPA.

📊 Conclusiones y Aprendizajes

Clean Architecture funciona de maravilla en Frontend: A menudo se piensa que la arquitectura limpia es solo para backend. Desacoplar el dominio de la vista demostró ser la mejor decisión para mantener la coherencia del proyecto.
Angular 19 con Signals es un placer: La simplicidad de las Signals en Angular 19 lo acerca a la agilidad de Vue y React sin perder la robustez de TypeScript.
Compose HTML / Kotlin Web es el futuro móvil/web unificado: Escribir interfaces web con la misma sintaxis que uso en Android nativo permite una reutilización de habilidades sin precedentes.

🚀 Pruébalo en vivo y Código Fuente

Puedes interactuar con el portafolio en vivo y cambiar de framework en tiempo real:

🔗 Demo en vivo: davidbernardo.dev

⭐ Repositorio en GitHub: github.com/dhbernardo/portfolio

💼 LinkedIn: linkedin.com/in/david-henry-bernardo-cardenas

¿Qué framework de los cuatro prefieres tú para tus proyectos? ¡Déjame tu opinión en los comentarios!