Ingeniería de contexto para agentes de IA: cómo el harness oficial Flow enseña la arquitectura de AdonisJSArtículo · digest del 17 de noviembre
Diorama técnico en forma de armazón arquitectónico de AdonisJS con rieles guía para agentes de IA.
Artículo3 secciones≈ 9 min

Ingeniería de contexto para agentes de IA: cómo el harness oficial Flow enseña la arquitectura de AdonisJS

Este artículo responde a una pregunta práctica directa: ¿cómo lograr que un agente de programación escriba código para la versión actual de AdonisJS sin alucinar con APIs obsoletas y sin tener que revisar línea por línea cada archivo generado? Para resolverlo, el creador del framework, Harminder Virk, lanzó Flow, un harness oficial de ingeniería de contexto incluido en la plataforma AdonisJS Plus, cuyo lanzamiento anunció el equipo el 16 de noviembre de 2026 en su comunicado público.

En lugar de otro prompt del sistema de un par de cientos de líneas, el harness cierra dos circuitos a la vez: le da al agente las reglas actualizadas del stack antes de generar código y filtra los errores típicos ya en la fase de pull request, funcionando dentro de Claude Code, Cursor y otros entornos locales. He analizado cómo funciona la herramienta sobre un escenario con AdonisJS 6 para ver cómo opera este ciclo en la práctica y dónde están sus límites.

Por qué los agentes se lían con las versiones del framework y dónde se rompe el contexto

Cuando trabajas con Claude Code, Cursor, Codex, GitHub Copilot u OpenCode, el cuello de botella deja de ser la velocidad al escribir código y pasa a ser el tiempo que dedicas a leerlo. Según la experiencia de Virk, con un contexto impreciso el modelo rellena los huecos con datos de entrenamiento antiguos, y el ahorro de la generación se evapora en la revisión línea por línea.

El autor llama a su enfoque «software factory», pero aclara enseguida que no es una cadena de montaje sin supervisión. Quien define las tareas en los issues sigue siendo una persona, y la última palabra antes de fusionar la rama también es suya, mientras que los agentes se encargan de la implementación y abren los pull requests. Así es exactamente como Virk construyó el sitio web, el registro de paquetes y el panel de AdonisJS Plus.

Para que ese flujo no se atasque en los mismos errores una y otra vez, conviene dividir el contexto en dos mitades:

  • Contexto de producto: la lógica de negocio, los compromisos de dominio y el criterio arquitectónico del equipo, que son únicos para cada proyecto.
  • Contexto del stack tecnológico: la estructura de carpetas, las reglas de validación, el trabajo con el ORM y los estándares de pruebas, que son iguales en todas las aplicaciones de AdonisJS.

Mantener esa segunda mitad a mano en cada repositorio es trabajo extra, aunque muchos equipos ya guardan reglas comunes en la raíz como CLAUDE.md, algo que ya comentamos en el artículo sobre cómo estructurar procesos AI-native en un repositorio. Flow asume el contexto del stack por ti: lo escriben los propios autores del framework y lo actualizan en sincronía con los lanzamientos de los paquetes.

Pensemos en una tarea real: en una aplicación con AdonisJS 6 y Lucid ORM le pides al agente que cree un controlador de autenticación y perfil de usuario. Sin harness, el modelo mezcla fácilmente llamadas de v4, v5 y v6, crea archivos a mano con una estructura arbitraria, lee campos sin validar mediante request.all() u olvida filtrar por el usuario actual. Con Flow, el recorrido cambia en cada fase.

Los cuatro cuadrantes de la ingeniería de contexto: cómo Flow cierra el ciclo

La observación más acertada en la arquitectura de Flow es separar la prevención de la verificación. Las instrucciones sin control posterior no saben si surtieron efecto, y las comprobaciones aisladas sin reglas previas vuelven a cazar el mismo fallo en cada commit. Por eso el harness se apoya en la matriz 2×2 de la charla de Joël Quenneville «Harness Engineering on Rails» y del artículo de Birgitta Böckeler sobre harness engineering: actuar antes de escribir el código (feed forward) o después (feedback), mediante una herramienta determinista (computational) o mediante un modelo (inferential).

El primer cuadrante son los generadores (feed forward + computational). Los agentes tienden a crear archivos desde cero a mano, lo que acaba desordenando la estructura de controladores del proyecto. Las skills de Flow obligan al modelo a ejecutar primero node ace make:controller AuthController o node ace make:model para obtener un esqueleto predecible según las convenciones de AdonisJS 6 y solo después escribir la lógica.

El segundo cuadrante es la documentación versionada y ocho skills (feed forward + inferential). Flow instala guías locales ajustadas exactamente a las versiones mayores de Lucid ORM, VineJS y Bouncer presentes en el proyecto, eliminando explicaciones obvias para un LLM y dejando reglas estrictas allí donde los modelos suelen adivinar. A su lado funcionan ocho skills integradas con el prefijo /flow-, un enfoque modular cercano al que vimos al analizar la evolución de las skills para agentes. Estas fijan la elección de capas y el control de acceso: en nuestro AuthController, el agente usa de inmediato esquemas de VineJS para el payload entrante y Bouncer para verificar permisos, y restringe las consultas en listados y operaciones masivas al usuario actual.

El tercer cuadrante son las reglas de linter (feedback + computational). Los requisitos deterministas sobre la estructura del proyecto y la cobertura de pruebas están empaquetados como reglas de ast-grep dentro de ESLint. Se ejecutan en el editor, al lanzar npm run lint y en CI sin importar quién haya escrito el código, y no consumen tokens de la ventana de contexto del modelo.

El cuarto cuadrante es la revisión de pull requests (feedback + inferential). El revisor analiza el diff siguiendo las mismas reglas codificadas en las skills y detecta cuatro problemas clásicos de AdonisJS:

  • IDOR: una acción del controlador carga un registro ajeno sin comprobar quién es el propietario.
  • N+1: una consulta de listado lanza una petición a la base de datos por cada fila por haber omitido preload.
  • Migración bloqueante: un cambio de esquema en una tabla capaz de detener las escrituras en producción durante el despliegue.
  • Evasión de validación: datos de la petición como request.all() llegan a capas internas saltándose VineJS.

Si al montar el perfil de usuario el agente aun así colara un acceso directo a request.all(), la revisión frenará ese pull request antes de fusionarlo.

Integración en agentes locales, límites de uso y primer paso

Flow funciona encima del agente local que ya tengas instalado en un proyecto con Node.js v20+ y AdonisJS 6+, siempre que cuentes con una suscripción activa con acceso al registro privado @adonisplus. Para conectar el harness al repositorio basta con añadir el paquete mediante Ace CLI y lanzar el asistente de configuración:

node ace add @adonisplus/flow
node ace flow:install

El primer comando descarga @adonisplus/flow y el segundo enlaza la documentación versionada, las reglas ast-grep para ESLint y las skills con el entorno que elijas: Claude Code, Cursor, Codex, GitHub Copilot u OpenCode. A partir de ese momento, al escribir /flow- en el chat con el agente aparece la lista de todos los flujos arquitectónicos integrados.

Para lanzar la revisión en local sobre cambios sin confirmar o sobre un pull request abierto antes de subirlo al repositorio, basta un único comando:

npx @adonisplus/flow review

La comprobación se ejecuta en local o en tu propio pipeline de GitHub Actions usando tus claves de API o tu suscripción al LLM: el código no se envía a los servidores de AdonisJS, y la plataforma no revende créditos ni tokens. Si lo prefieres, Flow convive sin problemas junto a revisores generales como CodeRabbit o Pullfrog.

Además del propio harness, la suscripción a AdonisJS Plus por $19 al mes con pago anual ($228 al año, con devolución a 30 días) incluye Feature packs —recetas de funcionalidades transversales como passkeys, 2FA y restablecimiento seguro de contraseña que el agente integra directamente en tu código existente en lugar de imponer una plantilla rígida—, los módulos Persona y Permissions para cuentas y roles, y acceso a un Discord privado. Para Virk, que pasó a trabajar a tiempo completo en el framework en julio de 2025 y superó el centenar de primeros suscriptores desde marzo de 2026, es la vía para sostener el desarrollo gratuito y open-source de AdonisJS.

Con todo, no conviene adoptar la herramienta a ciegas: tiene tres limitaciones claras:

  • Requisitos del stack: el harness está pensado para la sexta rama actual del framework (AdonisJS 6+) y un entorno de ejecución moderno; no cubre proyectos en las versiones antiguas 4 y 5.
  • Modelo cerrado y de pago: por ahora solo existe suscripción individual (el plan para equipos está previsto), y el código fuente de las reglas ast-grep y de las skills no está publicado en GitHub.
  • Límite de responsabilidad: Flow conoce el framework, pero no sustituye a las reglas de producto ni al criterio final del desarrollador antes de hacer merge.

Puedes comprobar hoy mismo si tu equipo necesita un circuito así sin pagar nada: abre el último pull request generado por un agente de programación y repasa la lista de fallos típicos que caza Flow —evasión del validador, ausencia de preload, falta de comprobación de propietario y migraciones arriesgadas—. Si encuentras al menos un par de estos defectos, un harness sistemático o unas reglas estrictas en el repositorio se amortizarán en la primera revisión.

Quiero un análisis detalladoLos votos ayudan a elegir qué analizar a fondo. Este material tiene 0 votos.
Fuentes · 3