Arquitectura de diffox: 17 agentes especializados, cuatro etapas
diffox reparte una revisión de código con IA entre 17 agentes especializados. Cada hallazgo cita el código, y esa cita no la comprueba un modelo, sino código.
Resumen. diffox es una herramienta de revisión de código con IA que revisa pull requests en GitHub. Cada revisión pasa por cuatro etapas; este artículo explica qué ocurre en cada una y por qué. Los resultados los medimos en los dos primeros artículos: diffox ultra es el primero entre 23 herramientas en el benchmark de Martian; una revisión de diffox cuesta $0,41.
- Contexto y asignación. diffox reúne el cambio, sus archivos antes y después, y las reglas que has escrito. El tipo de cambio y su riesgo deciden qué agentes especializados lo leen.
- Revisión especializada. El equipo tiene 17 agentes especializados. Cada uno busca una sola cosa y respalda lo que encuentra con una cita literal del código.
- Verificación de pruebas. Cada hallazgo se comprueba con código, no con un modelo. ¿Está de verdad el código citado en ese archivo? ¿Tiene que ver el hallazgo con lo que cambió este pull request? ¿Aparece el mismo problema dos veces?
- Elegir y publicar. Cada hallazgo tiene una clase: Crítico, Advertencia o Sugerencia. Al pull request llega lo que tienes que corregir: los hallazgos críticos y las advertencias. Las sugerencias no se pierden; esperan en la página de Hallazgos. Una revisión nunca bloquea un merge.
Cómo funciona una revisión
La forma más rápida de revisar un cambio es preguntarle a un modelo: «¿Hay algún error aquí?». diffox no lo hace así. Pone a varios agentes especializados a leer el mismo cambio: uno busca errores de lógica, otro problemas de concurrencia, otro comprueba si un test prueba algo de verdad. Cada agente tiene una tarea acotada y bien definida. Después vienen dos pasos más. Unas comprobaciones atan cada hallazgo al propio archivo, no a la palabra del modelo, y una selección decide qué se publica.
Lo que da de sí este diseño lo medimos en el primer artículo: en el benchmark de Martian, con 50 pull requests, diffox ultra detectó 119 de los 158 errores conocidos y diffox, 106. Lo que cuesta está en el segundo artículo. A continuación, las cuatro etapas por orden.
Qué ven los agentes y cuáles entran en juego
Una revisión empieza sin que la pidas: cuando se abre un pull request y con cada push nuevo. diffox publica primero en el pull request un comentario que avisa de que la revisión ha empezado; cuando termina, ese mismo comentario pasa a mostrar el resultado. Antes de que los agentes especializados vean el cambio, se deciden dos cosas: qué se les pone delante y a cuáles se llama.
Cada una de las cuatro partes responde a una pregunta distinta. El diff dice qué cambió. Los archivos, antes y después, muestran dónde encaja el cambio. El título, la descripción y los mensajes de commit cuentan qué se quería hacer. Y AGENTS.md o CLAUDE.md, si tu repositorio tiene uno, dice qué reglas sigue tu equipo.
El archivo de reglas se lee de la rama en la que se fusionará el pull request, no de la rama del propio pull request. Así, un pull request no puede cambiar las reglas de su propia revisión: un cambio en el archivo de reglas se aplica cuando se fusiona. No se revisan los archivos de bloqueo, el código de terceros, como vendor/ y node_modules/, ni los archivos minificados.
Después viene la asignación. diffox determina el tipo de cambio (corrección de errores, función nueva, refactorización, migración, test…) y evalúa su riesgo: cuántos archivos toca, si afecta a otros archivos, si viene con tests. Algunos agentes leen todos los cambios; otros solo se ejecutan cuando aparece su tema. Si no se borró ninguna línea, el agente que busca comportamiento eliminado no tiene nada que hacer. Si no se tocó ningún test, tampoco el que busca tests vacíos.
Cuando llega un push nuevo al mismo pull request, diffox lee solo el cambio nuevo.
Cada agente especializado busca una sola cosa
En la segunda etapa, los agentes especializados leen el cambio. El equipo tiene 17 agentes, de dos tipos según lo que buscan.
12 agentes buscan errores: código que da un resultado incorrecto al ejecutarse. 5 buscan contradicciones: lugares donde el código no cuadra con el comentario, el test o el documento que lo acompaña. Cada agente tiene sus propias instrucciones; todos leen el mismo cambio y el mismo contexto.
Para que cuente, un hallazgo tiene que decir tres cosas: qué afirma, qué sale mal y en qué situación, y en qué código se apoya la afirmación, con una cita literal. Un hallazgo de contradicción lleva dos citas: el código y el texto que lo contradice. Si falta alguna, el hallazgo no cuenta.
Los agentes no dan números de línea. Los modelos de lenguaje no son fiables contando líneas, así que diffox le pide al modelo la cita en lugar del número de línea y encuentra la línea por su cuenta, buscando la cita en el archivo. Por eso, que un hallazgo caiga bajo la línea correcta no depende de lo que diga el modelo.
Junto a los agentes especializados se ejecutan detectores basados en reglas. No usan ningún modelo; buscan con reglas exactas: una credencial que se ha colado en el código, un método definido dos veces en la misma clase, una rama a la que nunca se puede llegar.
El equipo completo y lo que busca cada agente:
| Agente | Tipo | Qué busca |
|---|---|---|
| ➗ Logic | Error | Busca errores off-by-one, condiciones de borde, condiciones invertidas, operadores equivocados y contratos de función incumplidos. |
| ⭕ Null Path | Error | Busca un valor que puede faltar donde el código lo lee como presente: un None, un null o un resultado vacío usado como si contuviera algo. |
| 🔀 Race | Error | Busca condiciones de carrera, deadlocks, leer-modificar-escribir no atómico, estado compartido inseguro y riesgos en el orden de los locks. |
| 🔇 Silent Failure | Error | Busca excepciones tragadas, bloques catch demasiado amplios, valores de retorno ignorados y falsos fallbacks que ocultan errores. |
| 💾 Data Integrity | Error | Busca esquemas que no coinciden, migraciones retroincompatibles, escrituras perdidas y operaciones no idempotentes. |
| 🔓 Security | Error | Busca inyecciones, autenticación y autorización rotas, secretos filtrados, SSRF y deserialización o manejo de rutas inseguros. |
| 💥 Blast Radius | Error | Busca llamadores rotos, superficies de API cambiadas y cambios de firma o de tipo de retorno que rompen otros archivos afectados por el cambio. |
| 🐛 Regression | Error | Busca la reaparición de patrones de bug ya corregidos en estos archivos. |
| 🥅 Safety Net | Error | Busca una ruptura de contrato entre el cambio y las pruebas que lo cubren: un comportamiento que una prueba verifica y que este diff cambió sin actualizar la prueba. |
| 🔥 Hot Path | Error | Busca consultas N+1, asignaciones innecesarias en hot paths y regresiones algorítmicas. |
| 🏷️ Naming | Error | Solo busca cuatro casos demostrables: una errata en un identificador que contradice a un vecino del mismo diff, dos grafías de una misma clave, una etiqueta que nombra lo que no es y una prueba cuyo nombre promete algo que nunca ejecuta. |
| 📐 House Rules | Error | Busca líneas de este diff que incumplen las reglas de revisión que el propio repositorio escribió en AGENTS.md o CLAUDE.md, si las tiene. |
| 💬 Broken Promise | Contradicción | Busca texto que afirma algo que el código de al lado no cumple: un comentario, docstring o README que dice algo que el código no hace. |
| 🪦 Dead Code | Contradicción | Busca código cuyo efecto no se puede observar: inalcanzable después de este cambio, o duplicado. |
| 📜 Stale Contract | Contradicción | Busca una declaración que cambió aquí mientras algo a la vista sigue esperando la forma anterior. |
| 🗑️ Lost Behaviour | Contradicción | Busca comportamiento que este cambio eliminó sin reemplazarlo, y pregunta si algo todavía depende de él. |
| 📭 Empty Test | Contradicción | Busca una prueba que no ejercita lo que afirma: pasaría hiciera lo que hiciera el código. |
El comentario de un hallazgo lleva el símbolo y el nombre del agente que lo encontró, por ejemplo ➗ Logic Agent.
Cómo se contrasta cada hallazgo con el código
Un modelo de lenguaje puede escribir algo convincente y falso a la vez: cita una línea que no está en el archivo, pone pegas a código que este pull request no tocó o cuenta el mismo problema tres veces con tres frases distintas. La tercera etapa se encarga de atar cada hallazgo al propio archivo, no a la palabra del modelo.
Estas comprobaciones son código normal, no una llamada a un modelo: la misma entrada da siempre la misma respuesta.
- Anchor Verifier. La cita del hallazgo se busca en el archivo. Si no se encuentra, no hay ninguna línea que señalar. Si la línea donde aparece no está en lo que cambió este pull request, el hallazgo queda fuera de alcance.
- Second Witness. Los hallazgos que hacen la misma objeción en el mismo lugar se unen en uno solo, para que no recibas dos veces el mismo problema. Y si más de una fuente señala un mismo lugar, eso cuenta a favor del hallazgo.
- Verbatim Matcher. La segunda cita de un hallazgo de contradicción también se busca palabra por palabra: en el cambio, en los archivos, en la descripción del pull request, en los mensajes de commit y en tu archivo de reglas. Si el modelo afirma que un comentario dice algo que no dice, aquí se nota.
Hay una comprobación más: si un hallazgo dice que un valor puede estar vacío, queda refutado cuando el tipo del valor, o una comprobación unas líneas más arriba, ya lo descarta.
Qué hallazgos se publican
Después de las comprobaciones queda una lista de candidatos. La cuarta etapa decide cuáles se publican en el pull request.
Attention Ranker responde a una sola pregunta sobre cada candidato: ¿qué probabilidad hay de que este hallazgo sea un error real? En la puntuación cuentan la gravedad y el tipo del hallazgo, el resultado de la verificación de pruebas y si otros hallazgos señalan el mismo lugar. De los hallazgos que caen en líneas cercanas, solo se publica el más sólido.
En el pull request solo ves lo que hay que corregir: los hallazgos críticos y las advertencias. Las sugerencias esperan en la página de Hallazgos, sin que tengas que configurar nada.
Medimos las cifras de abajo en el mismo benchmark con tres ajustes de sensibilidad. Ese ajuste era un umbral sobre una puntuación. Alta fue la que más errores detectó. Media y Baja subían el umbral: diffox publicaba menos hallazgos y estaba más seguro de los que publicaba.
| Sensibilidad | diffox | diffox ultra | ||
|---|---|---|---|---|
| Errores reales | Falsas alarmas | Errores reales | Falsas alarmas | |
| Alta | 106 | 132 | 119 | 144 |
| Media | 89 | 55 | 98 | 51 |
| Baja | 59 | 19 | 70 | 19 |
Benchmark de Martian: 50 pull requests, 158 errores conocidos, Claude Opus 4.5 como juez. Sensibilidad alta: nuestra ejecución pública, 7 de octubre de 2026. Media y baja: nuestra medición interna sobre los mismos 50 pull requests, media de 5 ejecuciones para diffox ultra y 2 para diffox.
Lo que no se publica en el pull request no se pierde: espera 30 días en tu página de Hallazgos de la consola, y desde ahí puedes publicar cualquiera de esos hallazgos.
La publicación tiene dos partes: un comentario de resumen en el pull request y, por cada hallazgo, un comentario justo debajo de la línea a la que se refiere. Si un hallazgo se puede corregir, incluye una corrección sugerida que GitHub aplica con un clic; el commit se hace a tu nombre. Los títulos y las correcciones sugeridas se escriben después de la selección, solo para los hallazgos que se van a publicar. La revisión llega en el idioma de tu equipo. La última línea del resumen indica el precio de esa revisión, cuánto tardó y el commit que leyó.
El estado de diffox en un pull request nunca se pone en rojo: hacer merge o no lo decide tu equipo. Con cada 👍 y 👎 en sus comentarios, diffox te conoce mejor a ti y a tu repositorio, y sus revisiones se ajustan cada vez más a tu equipo.
Qué hace distinto diffox ultra
diffox ultra pasa por las mismas cuatro etapas; la diferencia está en la segunda y en la cuarta. Dos modelos distintos leen el cambio, y cada uno hace su propia revisión de principio a fin. Las dos revisiones se ejecutan en paralelo y se publican como una sola. En la etapa de selección interviene además un tercer modelo, un pequeño modelo de decisión: no escribe texto y responde sí o no a preguntas sobre cada hallazgo. La selección puntúa juntos los hallazgos de las dos revisiones con esas respuestas. Si los dos modelos señalan el mismo lugar, eso cuenta a favor del hallazgo. Después de la selección, el modelo de decisión encuentra los hallazgos que vienen de la misma causa raíz y los reduce a uno.
El resultado está en los dos primeros artículos: diffox ultra detectó 119 de los 158 errores conocidos y diffox 106; una revisión de diffox ultra cuesta de media $1,64 y una de diffox $0,41.
Preguntas frecuentes
¿Por qué diffox usa agentes especializados?
«¿Hay algún error aquí?» es una pregunta amplia, y la respuesta también lo es. Cada agente especializado busca una sola cosa y tiene que respaldar lo que encuentra con una cita del código. Así queda claro de qué agente viene cada hallazgo.
¿Puedo darle a diffox mis propias reglas de revisión?
Sí. Las reglas que escribes en AGENTS.md o CLAUDE.md, en la raíz de tu repositorio, se leen en cada revisión, y un agente aparte busca las líneas que las incumplen. Las reglas se leen de la rama en la que se fusionará el pull request: si un pull request cambia el archivo de reglas, el cambio se aplica cuando se fusiona.
¿Para qué sirven 👍 y 👎?
Con cada reacción, diffox te conoce mejor a ti y a tu repositorio: aprende qué te importa y qué es ruido. Sus revisiones se ajustan cada vez más a tu equipo.
¿diffox bloquea un merge?
No. El estado de diffox en un pull request nunca se pone en rojo y no es una comprobación obligatoria; tu equipo hace merge cuando quiere.
¿Se revisa de nuevo todo el pull request con cada push?
No. diffox revisa automáticamente cada push, pero lee solo el cambio nuevo. Después de los 5 primeros push, revisa cuando tú lo pides; puedes cambiar ese número en la consola.
¿Por qué las sugerencias no se publican en el pull request?
En nuestras mediciones, publicar también las sugerencias sumaba comentarios al pull request y bajaba la proporción de errores reales entre ellos. Por eso al pull request llegan los hallazgos críticos y las advertencias. Las sugerencias no se pierden: esperan 30 días en la página de Hallazgos, y desde ahí publicas las que quieras.
¿diffox guarda mi código?
No. diffox no guarda una copia del código que revisa; la copia del repositorio se elimina cuando termina la revisión. Qué servicios se usan está en nuestra página de privacidad.
Continuación: el modelo de decisión
El cuarto artículo describe el modelo de decisión que diffox ultra usaba entonces en la cuarta etapa y la regla que sacamos de nuestras mediciones: Cómo usamos Jev para dos tareas en la revisión de código con IA.