Un pull request llega a tu cola con 340 líneas modificadas repartidas en nueve archivos. Lo ha escrito un agente de código. El diff no te dice qué se le pidió al agente, qué enfoques probó y descartó, qué ejecutó para convencerse de que el cambio funciona ni en qué puntos sabe que se ha saltado algo. Así que haces una de dos cosas: revisarlo por encima y aprobarlo, o reconstruir todo el cambio desde cero. La primera es la vía por la que se despliega código malo. La segunda significa que el agente no te ha ahorrado nada.
Revisar bien código generado por IA no es lo mismo que revisar el PR de un colega, porque el autor no puede sentarse a tu lado a explicarte su razonamiento. La solución es revisar el diff junto con su evidencia: el objetivo, las comprobaciones que se ejecutaron y los límites que el propio agente ya señaló. Sharkly está construido precisamente en torno a eso. Sharkly se sitúa por encima de tus agentes de código (Claude Code, Codex, Gemini y demás) y mantiene el objetivo, el cambio, los resultados de verificación y la revisión humana de cada ejecución dentro de una misma Tarea, en lugar de repartidos entre terminales y descripciones de PR.
Esta guía repasa el modelo operativo que hay detrás: quién asigna el trabajo, quién lo ejecuta, quién lo revisa, quién lo acepta, los estados y las puertas que separan el trabajo de un agente del de una persona, y un ejemplo práctico desde el ticket hasta el PR fusionado.
Respuesta rápida
Revisa el código generado por IA a nivel de Tarea, no de diff. Haz que el agente adjunte a una Tarea compartida un resumen del cambio, los resultados de typecheck, tests y build que ejecutó, y los límites conocidos; después mueve esa Tarea a un estado de revisión. Una persona lee la evidencia junto al diff, solicita cambios o los acepta, y toma la decisión de fusionar. Los agentes producen y verifican; las personas aceptan.
Por qué revisar solo el diff no funciona
Leer código es más difícil que escribirlo. Una realidad bien documentada de la revisión de código es que quien revisa tiene menos contexto que el autor y, cuando el autor es un agente, esa brecha es total. Un diff de GitHub te muestra el destino, nunca el camino. No puedes ver que el agente probó primero una capa de caché, se topó con una condición de carrera y la revirtió. No puedes ver que ejecutó la batería de tests y que falló uno inestable sin relación con el cambio.
Sin ese contexto, la revisión se reduce a dos modos de fallo. Aprobar a ciegas da luz verde a código que parece razonable pero rompe en silencio un caso límite que el agente nunca tuvo en cuenta. La reconstrucción completa te obliga a rehacer el razonamiento por tu cuenta, y en ese punto la ventaja de velocidad del agente ha desaparecido. Ninguna de las dos opciones escala cuando tres agentes abren PRs a la vez. La salida es hacer que el trabajo del agente sea revisable, no solo su resultado.
Qué significa realmente la evidencia a nivel de Tarea
La evidencia a nivel de Tarea es el registro que un Agente adjunta a su Tarea: el objetivo con el que trabajó, el cambio que produjo, las comprobaciones que ejecutó y los límites que conoce. En lugar de un diff sin más, obtienes un diff con su rastro de procedencia.
En la práctica, el paquete de evidencia consta de cuatro elementos:
- El objetivo y los criterios de aceptación, en la descripción de la Tarea, para que la revisión se mida contra lo que se pidió y no contra lo que parece razonable.
- El resumen del cambio, en palabras del propio agente: qué tocó y por qué.
- Los resultados de verificación: la salida del typecheck, los tests y el build que el agente ejecutó antes de entregar.
- Los límites conocidos: los casos límite, los supuestos y las tareas de seguimiento que el agente señaló en lugar de ocultarlos.
Todo ello vuelve a la Tarea. La ejecución, los bloqueos, los resultados y la conversación de seguimiento viven en una misma línea temporal, de modo que quien revisa abre un único registro en lugar de recomponer un PR, un hilo de Slack y un prompt que recuerda a medias. Esa es la disciplina que hay detrás de un flujo de trabajo trazable de requisitos a código: la evidencia forma parte del entregable.
El modelo operativo: quién asigna, quién ejecuta, quién revisa, quién acepta
Una buena revisión depende de roles claros. El contrato es breve: los agentes investigan, ejecutan, prueban e informan; las personas marcan la dirección, otorgan autoridad y aceptan el resultado. La automatización se detiene donde hace falta el criterio del equipo.
| Rol | Quién | Función |
|---|---|---|
| Asignador | Una persona (normalmente el propietario de la Tarea) | Describe la necesidad, define los criterios de aceptación y asigna la Tarea |
| Ejecutor | Un Agente, en una Computadora conectada, a través de un runtime | Toma la Tarea, la ejecuta en un worktree aislado y adjunta la evidencia |
| Revisor | Una persona | Lee el diff a la luz de la evidencia, solicita cambios o los aprueba |
| Aceptador | Una persona (el propietario o un aprobador designado) | Toma la decisión final de aceptación y de fusión o publicación |
Sharkly no sustituye a Claude Code, Codex ni a otras herramientas de ejecución. Añade la Tarea compartida, la Computadora, el contexto y la capa de revisión alrededor de las herramientas que tu equipo ya usa. El runtime escribe el código; Sharkly decide en la cola de quién cae la revisión y qué evidencia debe estar presente antes de que la mire una persona. Si quieres la versión ampliada de la parte de asignación, consulta quién asigna y quién acepta el trabajo de los agentes.
Estados y puertas de revisión: los agentes pasan a Ready for review, las personas pasan a Done
La puerta de revisión es una frontera de estado. En Sharkly, cada estado de tarea pertenece a una categoría fija que tiene un significado para el sistema: Backlog (aparcado), Unstarted (listo, sin empezar), Started (en curso) y Completed (terminal). Varios estados visibles pueden compartir una misma categoría, de modo que el flujo de trabajo de un tipo de tarea puede tener Development y Ready for review como dos estados Started distintos antes de que algo llegue a Completed.
Esa estructura es lo que hace que la puerta sea real. Un Agente puede llevar una Tarea de Development a Ready for review, y puede dejar la Tarea esperando la revisión humana. No puede moverla por su cuenta a un estado Completed. La aceptación es una transición humana, por diseño.
| Estado | Categoría | Quién lo mueve hasta aquí |
|---|---|---|
| Backlog | Backlog | Una persona, al aparcar el trabajo |
| Todo | Unstarted | Una persona, cuando la Tarea está lista |
| Development | Started | El Agente, cuando toma la Tarea y trabaja en ella |
| Ready for review | Started | El Agente, cuando la evidencia está adjunta |
| Done | Completed | Una persona, después de aceptarla |
Configura el flujo de trabajo para que la transición a tu estado Completed exija una persona y tendrás una puerta de revisión que se mantiene incluso cuando los agentes producen más rápido de lo que puedes supervisar. Esta es la versión mecánica de mantener a una persona en el bucle con los agentes de código, y es donde decides dónde detener a los agentes antes de que fusionen.
Un ejemplo práctico: del ticket al PR fusionado
Tomemos SH-312: «Añadir limitación de tasa al endpoint público de búsqueda, 60 peticiones por minuto por clave de API».
- Una persona crea SH-312 con ese objetivo y dos criterios de aceptación: las peticiones que superen el límite devuelven HTTP 429, y el límite es por clave, no por IP. La Tarea empieza en Todo.
- Un Agente la toma, la mueve a Development y se ejecuta en un worktree aislado para que su checkout nunca choque con el de otros agentes que trabajan en el mismo repositorio. (Los worktrees son la razón de que las ejecuciones en paralelo se mantengan limpias; consulta un checkout por tarea).
- El Agente implementa un limitador de token bucket, abre un PR y adjunta su evidencia a SH-312: un resumen del cambio, el typecheck y los tests unitarios superados, el resultado del build y un límite conocido: «El bucket vive en la memoria del proceso, así que los límites se reinician en cada despliegue y no se comparten entre instancias».
- El Agente mueve SH-312 a Ready for review. La tarea llega a la cola de una persona con el diff y la evidencia juntos.
- Quien revisa lee primero la nota del límite conocido, decide que el bucket en memoria está bien por ahora y solicita un cambio: devolver la cabecera
Retry-Afteren las respuestas 429. El Agente aplica el cambio y vuelve a adjuntar la salida actualizada de los tests. - Quien revisa acepta, fusiona el PR y mueve SH-312 a Done, con un ticket de seguimiento para un limitador compartido ya enlazado.
La revisión llevó minutos porque quien revisaba no tuvo que reconstruir el cambio; la evidencia hizo ese trabajo. Es el mismo circuito que la gestión de proyectos con Claude Code desde el issue hasta la revisión, con el paquete de evidencia haciendo que la revisión sea rápida en lugar de un cuello de botella.
Cómo revisar la evidencia rápido y cuándo aplicar un proceso ligero
No todos los cambios necesitan el tratamiento completo. Usa una regla de decisión.
Actúa a fondo cuando el cambio toque autenticación, facturación, migraciones de datos, API públicas o cualquier cosa difícil de revertir: lee el diff línea por línea, vuelve a ejecutar los tests tú mismo y contrasta la nota de límites conocidos con tus propios casos límite. Sé más ligero cuando el cambio sea un ajuste de textos, una refactorización interna bien probada o una actualización de dependencias con las comprobaciones en verde: lee el resumen, repasa el diff, confirma que la verificación ha pasado y acepta.
Lista rápida para una revisión exhaustiva:
- ¿El diff cumple todos los criterios de aceptación, no solo el camino feliz?
- ¿El agente ejecutó realmente las comprobaciones o solo dice que lo hizo? Verifica la salida adjunta.
- Lee la nota de límites conocidos. ¿Algún límite es un bloqueante y no una tarea de seguimiento?
- ¿El cambio se ciñe a la petición o el agente tocó archivos que no venían al caso?
Si ya trabajas con varios agentes de código, este es el flujo de trabajo que Sharkly te permite gestionar en un solo sitio: asigna la Tarea, deja que el agente adjunte la evidencia y revisa en la puerta. Puedes montar las piezas a mano con worktrees, plantillas de PR y un tablero de estados, o descargar Sharkly y tener la Tarea, la evidencia y la puerta como un único sistema.
Preguntas frecuentes
¿Qué es la evidencia a nivel de Tarea para código generado por IA? Es el registro que un agente adjunta a su Tarea junto al diff: el objetivo, un resumen del cambio, los resultados de typecheck, tests y build que ejecutó, y los límites conocidos. Revisar ese paquete es más rápido y más seguro que revisar solo el diff.
¿Puede un agente de IA aprobar su propio código? No, y esa es precisamente la razón de ser de una puerta de revisión. Un agente puede mover una Tarea a Ready for review, pero la transición a un estado Completed es una decisión humana. Los agentes producen y verifican; las personas aceptan.
¿Cómo puedo revisar código de IA más rápido sin aprobarlo a ciegas? Ajusta el esfuerzo al riesgo. Lee la evidencia en todos los cambios, pero reserva la revisión línea por línea y la reejecución de tests para áreas de alto riesgo como la autenticación y las migraciones. Descubre cómo escala la capacidad de revisión cuando los agentes van más rápido que las personas.
¿Sigo usando pull requests? Sí. Los agentes abren pull requests reales en GitHub; la capa de Tareas añade la evidencia y la puerta a su alrededor para que el PR no sea el único lugar donde vive el contexto.
