Los agentes de programación con human-in-the-loop suelen describirse como un ajuste: el modo en el que la herramienta pregunta antes de editar. Ese es un bucle, y es el más pequeño de todos. Se ejecuta dentro de la terminal de un único desarrollador, durante una sola sesión, y se desvanece cuando la sesión termina. Un equipo que cree tener supervisión humana porque todos dejaron Claude Code en modo Manual solo supervisa pulsaciones de teclas, no resultados.
Esta guía presenta el flujo de revisión como cinco puertas, desde el aviso de permiso dentro del entorno de ejecución hasta la decisión de aceptación en el registro compartido, e indica quién decide en cada una y dónde queda escrita esa decisión. Las puertas del entorno de ejecución provienen de la documentación de las propias herramientas. Las puertas del equipo usan Sharkly, porque las registra en la Task en lugar de en el historial de alguien. Si primero quieres la definición de la práctica, nuestra guía sobre gestión de proyectos con agentes de IA cubre el bucle en el que vive este flujo de trabajo.
En resumen
Un flujo de trabajo de revisión con human-in-the-loop para agentes de programación tiene cinco puertas: el modo de permisos del entorno de ejecución, la confirmación del plan antes de que el trabajo se convierta en Tasks, el límite de ejecución que decide cuándo puede empezar una ejecución, la señal de atención que dirige la revisión a una persona concreta y la aceptación registrada como un cambio de estado por parte de esa persona. Solo la primera puerta es un ajuste de la herramienta. Las otras cuatro son decisiones del equipo, y necesitan un registro compartido para ser reales. Los agentes investigan, ejecutan, prueban e informan. Las personas marcan la dirección, conceden autoridad y aceptan el resultado.
Puerta 1: El modo de permisos dentro del entorno de ejecución
Todo agente de programación serio incluye un control de aprobación. Los modos de permisos de Claude Code van desde default, etiquetado como Manual, que pregunta antes de ediciones, comandos de shell y acceso a la red, pasando por acceptEdits, plan y auto, donde un segundo modelo llamado clasificador revisa las acciones en tu lugar, hasta bypassPermissions, solo para contenedores aislados. Cambia con Shift+Tab o --permission-mode. Codex expone la misma idea a través de su comando /permissions, que establece cuándo puede editar archivos o ejecutar comandos sin preguntar.
Esta puerta es necesaria e insuficiente. Es por sesión y por desarrollador, protege la máquina en lugar del requisito, y no deja ningún registro que un compañero de equipo pueda leer. En los planes Pro, Max y Team, Claude Code ahora arranca en modo auto de forma predeterminada, lo cual es una decisión razonable precisamente porque el clasificador es más rápido y más consistente que una persona cansada haciendo clic en sí. La lección no es luchar contra el control. Es dejar de tratar el control como si fuera la revisión.
Puerta 2: Confirmación del plan
La primera puerta a nivel de equipo ocurre antes de que exista código alguno. En el chat de Agent de Sharkly, el modo Plan permite que el Agent proponga acciones para tu revisión, y la Task y las subtareas planificadas se crean solo después de que una persona confirme la propuesta. Puedes confirmar sin iniciar, o confirmar e iniciar.
Aquí es donde se decide el alcance, y resulta barato: editar una subtarea propuesta cuesta un minuto; revisar una refactorización no solicitada cuesta una tarde. Mantén Explore seleccionado cuando solo quieras análisis. Usa un Crew cuando un líder necesite interpretar el objetivo e involucrar a otros miembros del Agent; usa un único Agent, y sáltate la ceremonia, cuando un solo rol cubra el trabajo. Nuestra guía sobre chatear con un agente de IA o asignar una Task cubre los tres modos.
Puerta 3: El límite de ejecución
Una Task asignada a un Agent no se inicia mientras está en Backlog. Moverla a un estado cuya categoría esté lista para el trabajo es lo que inicia la ejecución, y las categorías completada, cancelada y duplicada nunca inician una ejecución inicial. La categoría de estado es, por tanto, una puerta que una persona acciona a propósito, y es visible en el tablero.
Dos cosas hacen que esta puerta sea más que una formalidad. Cada ejecución obtiene un directorio aislado, y las ejecuciones respaldadas por repositorio preparan un worktree nuevo, de modo que una ejecución aprobada no puede dañar una ejecución que nadie aprobó. Y la ejecución lleva la descripción de la Task, los comentarios recientes y el tipo de Task Workflow, que restringe los estados que el Agent puede seleccionar. Un Agent no puede marcar su propio trabajo como aceptado si el Workflow no le da ese estado. Nuestro artículo sobre worktrees de Git con agentes de programación de IA explica el aislamiento.
Puerta 4: La señal de atención
Un Agent termina una ejecución en uno de dos lugares útiles: con un resultado o con una pregunta. Sharkly nombra ambos. Un Agent puede dejar una Task esperando una respuesta humana o esperando una revisión humana, y el trabajo fallido o bloqueado aparece como un elemento de atención. Esas señales llegan a la Bandeja de entrada, en la sección Principal, para la persona responsable, y los fallos de ejecución van a la persona asignada en lugar de a todos los suscriptores.
La puerta aquí es el enrutamiento, y es la que la mayoría de los equipos equivoca sin querer. La revisión que va a un canal no va a nadie. La revisión que va a la persona asignada, en la Task, con el registro de ejecución a un clic de distancia, va a alguien a quien se le puede preguntar por ella más adelante. Nuestra guía sobre la bandeja de entrada del agente de IA cubre la mecánica de la cola.
Responder también es la forma en que el trabajo continúa. Un comentario de un miembro en una Task con un Agent asignado y listo puede encolar otra ejecución, de modo que los comentarios de revisión continúan el mismo trabajo en lugar de iniciar un segundo proceso. Mencionar a una persona, o usar una mención general, no inicia por sí mismo a un Agent, lo que evita que un intercambio entre personas despierte al Agent.
Puerta 5: La aceptación en el registro
La aceptación es una persona cambiando el estado de la Task después de leer las pruebas. Lee en este orden: los criterios de aceptación en la descripción, el comentario del Agent nombrando las comprobaciones que ejecutó y lo que sigue siendo incierto, el registro de ejecución y, por último, el diff. El registro documenta por qué se encoló la ejecución, cuándo empezó y terminó, las llamadas a herramientas y los eventos del Runtime, el origen del desencadenante y los detalles del fallo; es la diferencia entre revisar un cambio y revisar un relato sobre un cambio.
Dos reglas protegen esta puerta. Fusionar un pull request vinculado no cambia el estado de la Task, así que una fusión nunca se confunde con una aceptación. Y una ejecución de Automation completada describe la ejecución, no es una promesa de que todos los resultados posteriores fueran correctos. Ambas provienen directamente de la documentación del producto, y ambas existen porque los equipos seguían confundiendo terminado con correcto.
El flujo de trabajo en una tabla
| Puerta | Pregunta que responde | Quién decide | Dónde se registra |
|---|---|---|---|
| Modo de permisos | ¿Puede esta sesión tocar eso? | El desarrollador | En ningún sitio compartido |
| Confirmación del plan | ¿Es este el desglose correcto? | Una persona, sobre la propuesta | Las subtareas confirmadas |
| Límite de ejecución | ¿Puede ejecutarse esta Task ahora? | Quien la saque de Backlog | Cambio de estado en Activity |
| Señal de atención | ¿Quién debe mirar, y qué? | Sharkly lo dirige a la persona asignada | Bandeja de entrada Principal y la Task |
| Aceptación | ¿Es correcto el resultado? | La persona asignada | Cambio de estado por una persona concreta |
Cuándo abrir más las puertas
No todas las Tasks merecen cinco paradas, y fingir lo contrario es la forma en que la revisión se convierte en teatro. El trabajo de solo lectura, como una auditoría de repositorio, necesita la puerta 1 y la puerta 5. El trabajo reversible en un worktree aislado, como una actualización de dependencias con pruebas, puede saltarse la confirmación del plan. Las Automations que se ejecutan según una programación deberían indicar en sus instrucciones cuándo debe revisar o decidir una persona, y deberían ejecutarse manualmente e inspeccionarse antes de que alguien dependa de la programación; nuestra guía sobre Automations en Sharkly cubre eso.
Mantén las cinco para cualquier cosa que cambie una interfaz pública, toque datos o no pueda revertirse con un solo comando. Y mantén una regla en todas partes: una persona asignada con nombre en cada Task de Agent. Sharkly separa la responsabilidad humana de la ejecución del Agent a propósito, para que una Task pueda tener personas asignadas y un Agent asignado al mismo tiempo. La responsabilidad no se delega, y el registro debe mostrar quién la asume.
Qué no es human-in-the-loop
No es una persona mirando una terminal. No es un aviso de permiso con un revisor fatigado detrás. Y no es un estado que diga Completado. La automatización se detiene donde se requiere el criterio del equipo y devuelve una entrega con contexto completo y pruebas inspeccionables. Esa frase es todo el flujo de trabajo; las puertas son solo los puntos donde se aplica. Sharkly no sustituye a Claude Code, Codex ni otras herramientas de ejecución; es la capa que deja constancia de estas decisiones.
Preguntas frecuentes
¿El modo auto de Claude Code elimina a la persona del bucle? Elimina a la persona del aviso de permiso. El clasificador revisa las acciones frente a tu solicitud; no revisa si el resultado cumplió el requisito. Las puertas 2 a 5 siguen perteneciendo a las personas.
¿Cómo detengo un Agent a mitad de una ejecución? Se puede cancelar una ejecución encolada o en curso. Mover una Task a un estado Cancelada o Duplicada también detiene las ejecuciones activas; moverla a Completada no lo hace, así que cancela primero si el Agent sigue trabajando.
¿Quién debería ser el revisor? La persona asignada en la Task. Sharkly envía las señales de esperando revisión y de fallo a esa persona, por lo que cada Task de Agent debería nombrar a una. Nuestra guía sobre Agents en Sharkly explica las dos plazas de asignación.
¿Pueden los comentarios de revisión volver al Agent sin una nueva Task? Sí. Un comentario en la Task puede encolar una ejecución de seguimiento para el Agent asignado, y los comentarios rápidos se agrupan para que no creen ejecuciones duplicadas.
