Cómo elegir un arnés y resumen de la serie
Una tabla para elegir entre los cuatro arneses de la serie según tu arquitectura, qué comparten todos y un resumen de lo que funcionó, lo que no y lo que queda abierto, solo con lo que pasó de verdad.
Antes de empezar
- Punto de partida: la mini app sin arnésArnés
La app que comparten todos los arneses de la serie, tal cual: funciona y tiene pruebas, pero no tiene arnés ni una arquitectura definida.
Publicado
La idea clave: elige la arquitectura por tu proyecto, no por el arnés. Las tres piezas (seguridad, calidad y código limpio) son las mismas en todos los arneses de la serie. Lo que cambia es la regla de la arquitectura, el hook que la comprueba y la ayuda que recibe el agente para respetarla.
Cómo elegir
La tabla resume los cuatro arneses de la serie y el punto de partida. «Cuándo usarla» son pistas sacadas de las fuentes de cada página, no reglas: un mismo proyecto puede encajar en dos columnas.
| Arnés | Cuándo usarlo | Regla que comprueba el hook | Ayuda para el agente | Dificultad |
|---|---|---|---|---|
| Punto de partida | Para comparar, o para un prototipo que vas a tirar | Ninguna: no tiene arnés | Ninguna | — |
| Por capas | Quieres que cada parte tenga un trabajo claro y que las llamadas vayan en un solo sentido: rutas, servicios, datos | Un controlador no importa un repositorio y ninguna capa importa la de arriba (6 reglas) | Skill add-endpoint |
Baja |
| Hexagonal | Las reglas de negocio no deben depender de lo técnico, y quieres probarlas sin servidor ni base de datos | Las dependencias apuntan hacia el núcleo, que no importa nada de fuera (7 reglas) | Skill add-use-case |
Media |
| Monolito modular | Varias partes del negocio que crecen por separado, quizá con personas distintas, sin repartirlas en servicios | Un módulo solo usa otro a través de su index.ts (5 reglas) |
Un AGENTS.md por módulo y un subagente |
Media |
| Orientado a eventos | Un cambio en una parte tiene que provocar efectos en otras que no deben conocerse, como avisos o registros | Los módulos solo se hablan con eventos (6 reglas), y cada evento tiene un suscriptor | Skill add-event y el mapa de eventos |
Alta |
Las tres piezas van en los cuatro arneses: la pieza de seguridad, la pieza de calidad y la pieza de código limpio.
La dificultad es mi valoración: cuántas reglas y conceptos hay que entender, y cuánto cuesta seguir el código de una petición. El arnés por capas se lee de arriba abajo. En el hexagonal y en el monolito modular hay que saber qué es un puerto o una API pública. En el de eventos, el flujo de una petición está repartido por varios módulos que no se importan entre sí, y por eso su arnés trae más herramientas para seguirlo.
Si dudas, estas dos preguntas me ayudan a decidir. Son mi criterio, no una regla:
- ¿Dónde está lo que más cambia? Si cambian las reglas de negocio y la tecnología se queda, el hexagonal las protege. Si cambian partes enteras del negocio, el monolito modular las separa. Si lo que crece son las reacciones a lo que pasa (avisar, registrar, recalcular), los eventos permiten añadirlas sin tocar al que publica.
- ¿Qué error de tu agente te preocupa más? Cada arnés comprueba uno: saltarse una capa, meter la tecnología en el núcleo, entrar en el interior de otro módulo o llamar a otro módulo en lugar de publicar un evento. Elige el que vigile el error que más te costaría.
Qué tienen en común
Los cinco proyectos son la misma API de una biblioteca, en TypeScript con Node y Express, y pasan las mismas 11 pruebas de aceptación: test/library.test.ts es idéntico byte a byte en todos. Por eso se pueden comparar.
Los cuatro arneses comparten además:
- Un
AGENTS.mdque explica dónde va cada cosa, la regla clave y los comandos de verificación, más las secciones de seguridad, calidad y código limpio de las piezas. - Una carpeta
.agents/con los hooks, las skills, los permisos y, en el monolito modular, un subagente. Ningún archivo es de un agente concreto, y cada página explica cómo conectarlos. - Cuatro hooks de parada. Uno comprueba la regla de la arquitectura, y los otros tres son los de las piezas: secretos, calidad (formato, lint, tipos y pruebas) y duplicados. Si el de arquitectura, el de secretos o el de calidad falla, el agente no puede terminar; el de duplicados avisa una vez y deja terminar.
- Dos hooks más: uno bloquea comandos peligrosos antes de ejecutarlos y otro formatea cada archivo que edita el agente.
- Las piezas, copiadas sin cambios. Cada día comprobé con
cmpque sus archivos y sus 56 pruebas son idénticos a los de las piezas originales.
| Arnés | Reglas de arquitectura | Archivos de src/ sin pruebas |
Pruebas | Instrucciones | Dependencias de producción |
|---|---|---|---|---|---|
| Punto de partida | 0 | 2 | 11 | Ninguna | Express |
| Por capas | 6 | 14 | 70 | Un AGENTS.md |
Express |
| Hexagonal | 7 | 22 | 70 | Un AGENTS.md |
Express |
| Monolito modular | 5 | 19 | 70 | Cuatro AGENTS.md |
Express |
| Orientado a eventos | 6 y la comprobación de eventos | 26 | 80 | Un AGENTS.md |
Express y Zod |
Qué funcionó
- La misma app en todos. Las 11 pruebas de aceptación pasaron sin tocarlas en los cinco proyectos. Cambiar de arquitectura nunca obligó a cambiar el contrato.
- Las piezas se reutilizaron tal cual. Salieron del arnés por capas los días 3 a 5 y entraron sin cambios en el hexagonal, en el monolito modular y en el de eventos. Lo que cambió en cada arnés fue solo la parte de arquitectura: las carpetas, las reglas, el mensaje del hook y la skill o el subagente.
- Un hook por cosa. Desde el día 3, cada pieza trae su propio hook de parada en lugar de editar el del arnés. El de arquitectura solo comprueba su regla. Así se puede copiar una pieza sin tocar las demás, y cada mensaje de error dice qué falló.
- Cada regla rota se detectó. En cada arnés rompí a propósito la regla principal, y desde el día 6 también las demás, una por una. El chequeo falló en todos los casos, y el hook, lanzado con un evento de parada simulado, salió con código 2.
- El hook bloqueó a un agente de verdad. El día 6, en el arnés hexagonal, le pedí a Claude Code que importara Express en el dominio y terminara. Los hooks de arquitectura y calidad bloquearon la parada, y el agente avisó y preguntó si quitaba el import.
- Las instrucciones guiaron al agente. En las sesiones de los días 7 y 8, nadie rompió la regla. En el monolito modular, el agente leyó el
AGENTS.mddel módulo antes de cambiarlo, y Claude Code lo cargó solo al abrir un archivo de ese módulo. En el de eventos, el agente resolvió con eventos las dos tareas que cruzaban módulos. - El botón de StackBlitz. Del día 1 al 7, las pruebas de cada plantilla pasaron en StackBlitz desde Chromium, sin instalar nada.
Qué no funcionó o costó más
- El primer agente real llegó el día 6. Los días 2 a 5 no pude probar ningún arnés en una sesión real: el CLI de Claude Code tenía la sesión caducada, Codex respondió que la cuenta había llegado a su límite de uso y Cursor no estaba instalado. Las pruebas de esos días se hicieron lanzando los hooks con entradas simuladas.
- Un hook que el agente no puede cumplir. En aquella sesión del día 6 nadie respondió a la pregunta del agente. Tras 9 bloqueos seguidos, Claude Code terminó el turno por su cuenta, y el import se quedó en el código. Un hook de parada impide que el agente diga que terminó, pero no arregla el código por él.
- StackBlitz no es Node. El día 3 fallaron 34 de 39 pruebas de la pieza de seguridad, porque leer la entrada estándar con
readFileSync(0)no funcionaba allí; el hook pasó a leerla como stream. El día 5 varias pruebas superaron el límite de 5 segundos y lo subí a 30. Tampoco sirvió incrustar StackBlitz en la página sin cabeceras de aislamiento, así que el botón abre una pestaña nueva. - Herramientas que no corren en el navegador. Descarté gitleaks porque es un binario de Go, y me quedé con jscpd 4 porque desde la versión 5 ejecuta un binario nativo. jscpd 4 trae 5 avisos altos de
npm auditque no tienen versión corregida. - StackBlitz, el día 8. El 25 de octubre Vitest no arrancó en StackBlitz, ni con el arnés nuevo ni con el del día 7, que el 21 pasaba. El error venía de una dependencia que StackBlitz descarga al arrancar, no de las plantillas. Está contado en la página del arnés orientado a eventos.
- Mis propios errores de montaje. El día 8, en el primer intento de las sesiones reales, pasé mal la lista de comandos permitidos y el agente no pudo ejecutar
npm. Repetí las dos sesiones. En ese primer intento, los hooks de parada ejecutaron las comprobaciones que el agente no pudo. - Lo que el agente se saltó. En la mayoría de las sesiones, el agente no usó la skill de revisión de código limpio, aunque
AGENTS.mdla pide antes de terminar. En una del día 8 dejó un nombre que ya no describía lo que guarda la clase. Las instrucciones guían, pero no obligan.
Lo que queda abierto
- Codex y Cursor, sin probar. Lo que dicen las páginas sale de su documentación. Según ella, el hook de parada de Codex espera JSON en la salida estándar cuando termina con 0, y el de Cursor espera
followup_message; no escribí los adaptadores. - Sistemas y navegadores. Probé en Windows 11 (días 2 a 5) y en Fedora Linux 44 (días 6 a 8), con Node 24. No probé macOS ni Node 22 en local, y StackBlitz solo en Chromium.
- Dos pruebas de las piezas, solo simuladas. Que la regla de permisos bloquee la lectura de
.envy que el hook de comandos bloquee un comando peligroso no los probé en una sesión real. Que el hook de calidad no deje terminar sí pasó en una sesión real, el día 6. - Hooks de parada en paralelo. Claude Code y Codex los ejecutan a la vez. Una prueba del hook de calidad escribe un secreto falso mientras el de secretos podría estar leyendo los archivos. No falló nunca, pero depende de los tiempos.
- Volver a probar StackBlitz. Desde el 25 de octubre, el botón «Ejecutar en el navegador» no llega a ejecutar las pruebas. Hasta que lo vuelva a probar, ejecuta los arneses en tu equipo.
- El repositorio es privado. El código se ve en el explorador de cada página y se ejecuta con el botón, pero no está publicado como repositorio.
- Fuera de la serie, para más adelante: microservicios y arquitecturas de frontend.
- Un tema propio sobre reutilizar piezas. El plan lo dejaba como opcional y no lo escribí.
La serie completa
| Día | Página | Tipo |
|---|---|---|
| 1 | Punto de partida: la mini app sin arnés | Punto de partida |
| 2 | Arnés por capas | Arnés base |
| 3 | Pieza: seguridad | Pieza |
| 4 | Pieza: calidad | Pieza |
| 5 | Pieza: código limpio | Pieza |
| 6 | Arnés hexagonal | Arnés base |
| 7 | Arnés de monolito modular | Arnés base |
| 8 | Arnés orientado a eventos | Arnés base |
| 9 | Cómo elegir un arnés y resumen de la serie (esta página) | Guía |
Siguiente paso
Si todavía no lo has hecho, empieza por el punto de partida y abre a la vez el arnés que elegiste: comparar los dos exploradores muestra qué añade el arnés a la misma app. Para entender cuándo actúa cada hook, mira la sección «Cómo funciona un arnés» de la portada, que recorre el bucle del agente paso a paso.
Contenido relacionado
- Hooks: comprobaciones que se ejecutan solasTécnica
Comandos que se ejecutan automáticamente en momentos concretos del trabajo del agente, como antes de editar un archivo o al terminar, para que los pasos importantes no dependan de que el agente se acuerde.
Publicado - Verificación y evaluaciónTécnica
Cómo comprobar que el agente hizo bien el trabajo sin fiarte de su palabra: darle formas de verificarse a sí mismo, revisar el resultado y el proceso, y comparar configuraciones con honestidad.
Publicado