Respuesta rápida: Para que los agentes de IA revisen pull requests, asigna la revisión a un segundo agente con sus propias instrucciones, su propio checkout y, si es posible, un modelo diferente. Inícialo automáticamente cuando el trabajo pase a un estado de revisión, haz que ejecute las pruebas y publique un veredicto de PASS o CHANGES REQUIRED, y devuelve los fallos al desarrollador. La decisión final de hacer merge sigue en manos de una persona.
Por qué los agentes de IA deberían revisar las pull requests antes que tú
Cada pull request generada por un agente acaba en el mismo lugar: tu mesa de trabajo. Cuando un solo agente envía una PR por hora, no hay problema. Pero cuando tienes cinco agentes trabajando en paralelo, la cola crece más rápido de lo que puedes leer los diffs, y esa primera revisión se convierte en el cuello de botella.
Un agente revisor se encarga de esa primera pasada. No sustituye tu criterio: simplemente filtra las PRs que no pasan las pruebas, se salen del alcance o exponen algún secreto, garantizando que las que lleguen a ti realmente merezcan tu tiempo. En Sharkly, esto se configura con un Agent adicional y dos Automations; el resto de esta guía explica cada uno de estos pasos.
Si primero quieres conocer los límites de las revisiones automáticas, consulta qué pueden y qué no pueden verificar los agentes de code review con IA. En este artículo nos centraremos en la configuración.
Por qué un mismo agente no puede revisar su propio código
El agente que escribió el código también construyó la narrativa en torno a él. Si le pides que revise su propio trabajo, releerá su propio razonamiento y le dará la razón. Los mismos puntos ciegos que dieron origen al bug serán los encargados de revisarlo.
Esto se nota sobre todo en las pruebas. Un desarrollador que no logre hacer pasar un test podría relajar una aserción y dar la tarea por concluida. Ya analizamos estos patrones en cómo detectar trampas en las pruebas hechas por agentes programadores. En cambio, un revisor sin ningún apego al resultado analiza el diff con objetividad y se plantea una pregunta distinta: ¿este cambio hace lo que pedía la tarea, y nada más?
El ensayo de diseño sobre superagentes del equipo de DeepSeek Harness llega a una división similar: varios Workers vinculados a una misma PR ven todos sus eventos y pueden resolver conflictos entre sí. Aunque describe el diseño de un prototipo y no un producto en producción, la idea es muy sólida: la revisión funciona mucho mejor cuando el revisor es una entidad independiente.
Paso 1: Separa el desarrollador del revisor
Crea dos Agents en lugar de un único Agent con dos modos. Cada uno debe contar con sus propias instrucciones, repositorios y entorno de ejecución.
| Builder Agent | Reviewer Agent | |
|---|---|---|
| Función | Implementar la tarea y abrir la PR | Evaluar la PR frente a la tarea |
| Escribe código | Sí | No |
| Hace push | A una rama de funcionalidad (feature branch) | Nunca |
| Runtime | Por ejemplo, Claude Code | Idealmente otro distinto, como Codex |
| Salida | Rama, PR, comentario de resumen | Comentario con el veredicto |
Un Agent de Sharkly no tiene un selector de modelos. Su objetivo de ejecución es una Computer junto con un Runtime detectado en ella; por lo tanto, «usar un modelo diferente» significa vincular al revisor a un Runtime distinto. Un segundo Runtime aporta otra perspectiva y otros hábitos al analizar el diff. Además, cada ejecución se factura según el plan asociado a ese Runtime, ya que Sharkly no vende tokens.
Configura el directorio de trabajo del revisor en modo Temporary. La documentación de Computers explica cómo cada ejecución obtiene un directorio aislado y cómo las tareas de repositorio pueden preparar un Git worktree limpio. Así, el revisor hace checkout de la rama de la PR en su propia copia y no puede sobrescribir ni interferir con los archivos del desarrollador. Nuestro artículo sobre agentes paralelos en worktrees aislados profundiza en por qué esto es crucial cuando varios agentes comparten un mismo repositorio.
Paso 2: Escribe las instrucciones del revisor
Las instrucciones del agente definen su rol, las comprobaciones que debe realizar y el formato del informe. Los detalles específicos de cada tarea deben permanecer en la propia tarea. Procura que las instrucciones del revisor sean breves y verificables:
You are the code reviewer for this Space. You never push, merge or edit files.
1. Read the triggering task. If it is not a code task in this Space, reply "not mine" and stop.
2. Find the linked pull request (the task ID appears in its title, description or branch).
3. Check out the PR branch in your worktree. Run the test command from the repo README.
4. Compare the diff to the task's acceptance criteria.
5. Post one verdict comment on the task in the format below. Nothing else.
El primer paso es más importante de lo que parece. Actualmente, los activadores por estado y por comentario coinciden en toda la Organization, por lo que las instrucciones deben validar la tarea antes de actuar. La documentación de Automations lo indica explícitamente.
Paso 3: Elige el activador
Las Automations de Sharkly combinan instrucciones, un Agent o Crew, y uno o varios activadores. Para la revisión de PRs, dos tipos de activadores encajan a la perfección.
Cambio de estado de la tarea. Añade un estado como In Review al flujo de trabajo de tu Space. El desarrollador traslada la tarea a ese estado tras abrir la PR, y el revisor se pone en marcha. Una ejecución activada por cambio de estado crea una conversación en esa tarea, de modo que el veredicto y el consumo de tokens quedan vinculados al trabajo correspondiente.
Esa captura de pantalla muestra el control que este mismo blog aplica a sus propios borradores: una tarea pasa a Ready for Release y un Agent revisor se hace cargo de ella. El patrón es exactamente el mismo para el código.
Webhook. Si las PRs se abren fuera de tu panel de tareas, apunta un webhook pull_request de GitHub a la URL de webhook de una Automation. Al activar la verificación de firma, Sharkly también admite el encabezado X-Hub-Signature-256 de GitHub, por lo que basta con pegar el secreto de firma en el campo Secret de GitHub. Las ejecuciones por webhook no están vinculadas a una tarea, de modo que el revisor publica su veredicto directamente en la PR utilizando la CLI de GitHub.
Prueba cualquiera de las dos vías con Run now antes de implementarla en producción.
Paso 4: Proporciona una lista de comprobación al revisor
Un revisor sin una lista de comprobación escribe ensayos; con ella, elabora informes con hallazgos concretos. Cinco preguntas son suficientes para cubrir la gran mayoría de las PRs generadas por agentes:
- ¿Las pruebas se ejecutan y pasan con éxito? El revisor debe ejecutarlas por sí mismo, sin fiarse nunca del resumen del desarrollador.
- ¿Se respetó el alcance? Cualquier archivo modificado fuera de la tarea constituye un hallazgo, incluso si el cambio parece inofensivo.
- ¿Se ha expuesto algún secreto? Tokens, claves o valores de
.envpresentes en el diff o en los registros. - ¿Se ha roto la compatibilidad para quienes llaman al código? Firmas modificadas, endpoints eliminados o migraciones sin rollback.
- ¿Se debilitaron las pruebas? Aserciones eliminadas, nuevos skips o valores esperados más permisivos.
Si varios Agents revisores comparten esta lista, guárdala en una Skill; así, una sola edición los actualizará a todos.
Paso 5: Define un formato fijo para el veredicto
Un veredicto que una persona pueda escanear en diez segundos es mucho más útil que uno exhaustivo que nadie lea. Utiliza una estructura fija:
VERDICT: CHANGES REQUIRED
Tests: 41 passed, 2 failed (test_refund_rounding, test_refund_zero)
Scope: OK, 3 files, all under billing/
Secrets: none found
Breaking changes: refund() now raises on amount=0; two callers in api/ not updated
Weakened tests: none
Required:
1. Handle amount=0 in refund() or update both callers.
2. Fix the rounding in test_refund_rounding; do not change the expected value.
Un veredicto PASS incluye los mismos campos y deja vacía la lista Required. Estos campos fijos también permiten cuantificar los resultados: puedes medir con qué frecuencia falla cada comprobación y ajustar en consecuencia las instrucciones del agente desarrollador.
Paso 6: Cierra el ciclo de retroalimentación con el desarrollador
Un veredicto de CHANGES REQUIRED debería reactivar al desarrollador automáticamente, sin que tengas que intervenir. Para lograrlo, crea una segunda Automation asignada al Agent desarrollador, con un activador por comentario basado en una frase distintiva.
La coincidencia de comentarios no distingue entre mayúsculas y minúsculas y se activa cuando la frase aparece en cualquier parte del comentario. Elige una frase que nadie escribiría por accidente e indícale al revisor que solo la incluya en su línea de CHANGES REQUIRED. Si el desarrollador cita esa misma frase en su respuesta, podría activarse a sí mismo en bucle, por lo que debes indicarle explícitamente que nunca la repita.
Limita el ciclo: establece un máximo de dos rondas de revisión y corrección. Si no se resuelve, el revisor debe transferir la tarea a una persona, adjuntando su último veredicto.
Lo que sigue dependiendo del factor humano
El merge sigue estando bajo tu control. En la integración con GitHub de Sharkly, incluir el ID de la tarea en el título de la PR vincula ambos elementos, y hacer merge no modifica el estado de la tarea. Nada llega a producción únicamente porque un agente haya emitido un veredicto de PASS.
Refuerza esto también en GitHub: configurar ramas protegidas que exijan la aprobación de una persona evita que un revisor demasiado confiado se convierta en la última línea de defensa. Asimismo, las decisiones de fondo que escapan a una lista de comprobación dependen de ti: ¿es este el diseño adecuado? ¿Tiene sentido que este cambio exista? Para descubrir cómo priorizar lo que llega a tu bandeja, consulta cómo clasificar la cola de PRs de agentes y por qué la revisión humana es el cuello de botella.
Conclusión
Las pull requests generadas por agentes dejarán de acumularse en cuanto un segundo agente asuma la primera revisión. Separa al desarrollador del revisor, dota al revisor de su propio worktree y Runtime, inícialo mediante un cambio de estado o un webhook, y haz que responda a cinco preguntas concretas en un formato predefinido. Devuelve los fallos mediante una frase en los comentarios, limita el ciclo a dos rondas y resérvate siempre la decisión final de hacer merge.
Si ya ejecutas diez agentes programadores a la vez, esta es la siguiente pieza que debes incorporar. Empieza gratis en Sharkly creando primero el Agent revisor.
Preguntas frecuentes
¿Puede un agente de IA revisar su propia pull request?
Poder puede, pero detectará muchos menos errores. El agente comparte las mismas premisas que dieron origen al código. Un revisor independiente, con sus propias instrucciones e idealmente un Runtime distinto, analizará el diff sin ese sesgo.
¿Debería el revisor utilizar un modelo diferente al del desarrollador?
Sí, siempre que sea posible. En Sharkly, el modelo depende del Runtime, así que vincula el Agent revisor a un Runtime distinto al del desarrollador; por ejemplo, Codex revisando el trabajo de Claude Code.
¿Qué es lo primero que debe comprobar un revisor de código con IA?
Las pruebas. Haz que ejecute la suite de tests por su cuenta y reporte el recuento de pruebas superadas y fallidas. Después, en este orden: el alcance, la presencia de secretos, los cambios incompatibles y el posible debilitamiento de las pruebas.
¿Puede un agente revisor aprobar y hacer merge de una PR?
No lo permitas. Mantén los permisos de merge en manos de personas mediante la protección de ramas. El revisor emite un veredicto en un comentario; la persona decide.
¿Cómo evito que el ciclo de revisión se ejecute en un bucle infinito?
Limítalo a dos rondas en las instrucciones del revisor y utiliza una frase de comentario que el desarrollador nunca repita. Una vez alcanzado el límite, el revisor transfiere la tarea a una persona.
¿Funciona esto con pull requests de GitHub abiertas fuera de Sharkly?
Sí. Conecta un webhook de GitHub al activador de webhook de una Automation. Sharkly acepta el encabezado de firma de GitHub cuando la verificación está activada.
