Os agentes de código com human-in-the-loop geralmente são descritos como uma configuração: o modo em que a ferramenta pergunta antes de editar. Esse é um loop, e é o menor deles. Ele roda dentro do terminal de um único desenvolvedor, por uma única sessão, e desaparece quando a sessão termina. Uma equipe que acha que tem supervisão humana porque todos deixaram o Claude Code no modo Manual tem supervisão de teclas digitadas, não de resultados.
Este guia apresenta o fluxo de trabalho de revisão como cinco portões, do prompt de permissão dentro do runtime até a decisão de aceitação no registro compartilhado, e indica quem decide em cada um e onde essa decisão é registrada. Os portões do runtime vêm da própria documentação das ferramentas. Os portões da equipe usam o Sharkly, porque ele os registra na Tarefa em vez do histórico de rolagem de alguém. Se você quer primeiro a definição da prática, nosso guia sobre gestão de projetos de agentes de IA cobre o loop em que este fluxo de trabalho se insere.
TL;DR
Um fluxo de trabalho de revisão com human-in-the-loop para agentes de código tem cinco portões: o modo de permissão do runtime, a confirmação do plano antes de o trabalho virar Tarefas, a fronteira de execução que decide quando uma execução pode começar, o sinal de atenção que encaminha a revisão para uma pessoa nomeada e a aceitação registrada como uma mudança de status feita por essa pessoa. Apenas o primeiro portão é uma configuração da ferramenta. Os outros quatro são decisões da equipe, e precisam de um registro compartilhado para serem reais. Os agentes pesquisam, executam, testam e relatam. As pessoas definem a direção, concedem autoridade e aceitam o resultado.
Portão 1: O modo de permissão dentro do runtime
Todo agente de código sério traz um botão de aprovação. Os modos de permissão do Claude Code vão do default, rotulado como Manual, que pergunta antes de edições, comandos de shell e acesso à rede, passando por acceptEdits, plan e auto, em que um segundo modelo chamado de classificador revisa as ações no seu lugar, até bypassPermissions, apenas para contêineres isolados. Alterne com Shift+Tab ou --permission-mode. O Codex expõe a mesma ideia por meio do comando /permissions, que define quando ele pode editar arquivos ou executar comandos sem perguntar.
Este portão é necessário e insuficiente. Ele é por sessão e por desenvolvedor, protege a máquina em vez do requisito e não deixa nenhum registro que um colega de equipe possa ler. Nos planos Pro, Max e Team, o Claude Code agora começa no modo auto por padrão, o que é uma escolha razoável justamente porque o classificador é mais rápido e mais consistente do que um humano cansado clicando em sim. A lição não é brigar com o botão. É parar de tratar o botão como a revisão.
Portão 2: Confirmação do plano
O primeiro portão no nível da equipe acontece antes de existir qualquer código. No chat de Agente do Sharkly, o modo Plan permite que o Agente proponha ações para a sua revisão, e a Tarefa e as subtarefas planejadas só são criadas depois que uma pessoa confirma a proposta. Você pode confirmar sem iniciar, ou confirmar e iniciar.
É aqui que o escopo é decidido, e isso é barato: editar uma subtarefa proposta custa um minuto, revisar uma refatoração não solicitada custa uma tarde. Mantenha o Explore selecionado quando você quiser apenas análise. Use um Crew quando um líder precisar interpretar o objetivo e envolver outros membros Agente; use um único Agente, e pule a cerimônia, quando um só papel cobrir o trabalho. Nosso guia sobre conversar com um agente de IA ou atribuir uma Tarefa cobre os três modos.
Portão 3: A fronteira de execução
Uma Tarefa atribuída a um Agente não começa enquanto estiver no Backlog. Movê-la para um status cuja categoria seja pronta para trabalho é o que inicia a execução, e as categorias concluída, cancelada e duplicada nunca iniciam uma execução inicial. A categoria de status é, portanto, um portão que uma pessoa aciona de propósito, e é visível no quadro.
Duas coisas fazem deste portão mais do que uma formalidade. Cada execução recebe um diretório isolado, e as execuções com repositório preparam um worktree novo, então uma execução aprovada não pode danificar uma execução que ninguém aprovou. E a execução carrega a descrição da Tarefa, os comentários recentes e o tipo de Tarefa Workflow, que restringe os status que o Agente pode selecionar. Um Agente não pode marcar o próprio trabalho como aceito se o Workflow não lhe conceder esse status. Nosso artigo sobre worktrees do Git com agentes de código de IA explica o isolamento.
Portão 4: O sinal de atenção
Um Agente termina uma execução em um de dois lugares úteis: com um resultado, ou com uma pergunta. O Sharkly nomeia os dois. Um Agente pode deixar uma Tarefa aguardando uma resposta humana ou aguardando revisão humana, e o trabalho falho ou bloqueado surge como um item de atenção. Esses sinais chegam ao Inbox, na seção Primary, para a pessoa responsável, e as falhas de execução vão para a pessoa atribuída, e não para todos os inscritos.
O portão aqui é o roteamento, e é o que a maioria das equipes erra sem perceber. Revisão que vai para um canal não vai para ninguém. Revisão que vai para o responsável humano, na Tarefa, com o log de execução a um clique de distância, vai para alguém que pode ser questionado sobre isso depois. Nosso guia sobre o inbox de agentes de IA cobre a mecânica da fila.
Responder também é como o trabalho continua. Um comentário de um membro em uma Tarefa com um Agente responsável pronto pode enfileirar outra execução, então o feedback de revisão continua o mesmo trabalho em vez de iniciar um segundo processo. Mencionar uma pessoa, ou usar uma menção geral, não inicia um Agente por si só, o que impede que uma troca entre humanos acorde o Agente.
Portão 5: Aceitação no registro
Aceitação é uma pessoa mudando o status da Tarefa depois de ler as evidências. Leia nesta ordem: os critérios de aceitação na descrição, o comentário do Agente nomeando as verificações que executou e o que ainda é incerto, o log de execução e, por fim, o diff. O log registra por que a execução foi enfileirada, quando começou e terminou, chamadas de ferramentas e eventos de Runtime, a origem do gatilho e detalhes de falhas; é a diferença entre revisar uma mudança e revisar uma história sobre uma mudança.
Duas regras protegem este portão. Fazer merge de um pull request vinculado não muda o status da Tarefa, então um merge nunca é confundido com aceitação. E uma execução de Automação concluída descreve a execução, não uma promessa de que todo resultado posterior estava correto. Ambas vêm direto da documentação do produto, e ambas existem porque as equipes insistiam em confundir terminado com correto.
O fluxo de trabalho em uma tabela
| Portão | Pergunta que responde | Quem decide | Onde é registrado |
|---|---|---|---|
| Modo de permissão | Esta sessão pode mexer naquilo? | O desenvolvedor | Em nenhum lugar compartilhado |
| Confirmação do plano | Esta é a decomposição certa? | Uma pessoa, sobre a proposta | As subtarefas confirmadas |
| Fronteira de execução | Esta Tarefa pode rodar agora? | Quem a move para fora do Backlog | Mudança de status na Activity |
| Sinal de atenção | Quem precisa olhar, e para quê? | O Sharkly encaminha para o responsável | Inbox Primary e a Tarefa |
| Aceitação | O resultado está correto? | O responsável humano | Mudança de status feita por uma pessoa nomeada |
Quando abrir os portões mais
Nem toda Tarefa merece cinco paradas, e fingir o contrário é como a revisão vira teatro. Trabalho somente leitura, como uma auditoria de repositório, precisa dos portões 1 e 5. Trabalho reversível em um worktree isolado, como uma atualização de dependência com testes, pode pular a confirmação do plano. As Automações que rodam em uma programação devem ter em suas instruções quando uma pessoa precisa revisar ou decidir, e devem ser executadas manualmente e inspecionadas antes que alguém dependa da programação; nosso guia sobre Automações no Sharkly cobre isso.
Mantenha todos os cinco para qualquer coisa que altere uma interface pública, mexa em dados ou não possa ser revertida com um único comando. E mantenha uma regra em todos os lugares: um responsável humano nomeado em cada Tarefa de Agente. O Sharkly separa a responsabilidade humana da execução do Agente de propósito, então uma Tarefa pode ter pessoas atribuídas e um Agente atribuído ao mesmo tempo. A responsabilidade não se delega, e o registro deve mostrar quem a detém.
O que human-in-the-loop não é
Não é uma pessoa olhando para um terminal. Não é um prompt de permissão com um revisor fatigado atrás dele. E não é um status que diz Concluído. A automação para onde o julgamento da equipe é necessário e devolve uma entrega com contexto completo e evidências inspecionáveis. Essa frase é o fluxo de trabalho inteiro; os portões são apenas onde ele é imposto. O Sharkly não substitui o Claude Code, o Codex ou outras ferramentas de execução; é a camada que registra essas decisões.
FAQ
O modo auto do Claude Code remove o humano do loop? Ele remove o humano do prompt de permissão. O classificador revisa as ações em relação ao seu pedido; ele não revisa se o resultado atendeu ao requisito. Os Portões 2 a 5 continuam pertencendo às pessoas.
Como interromper um Agente no meio de uma execução? Uma execução enfileirada ou em andamento pode ser cancelada. Mover uma Tarefa para um status Cancelado ou Duplicado também interrompe as execuções ativas; movê-la para Concluído não, então cancele primeiro se o Agente ainda estiver trabalhando.
Quem deve ser o revisor? O responsável humano na Tarefa. O Sharkly envia os sinais de aguardando revisão e de falha para essa pessoa, e é por isso que toda Tarefa de Agente deve nomear um. Nosso guia sobre Agentes no Sharkly explica os dois espaços de atribuição.
O feedback de revisão pode voltar para o Agente sem uma nova Tarefa? Sim. Um comentário na Tarefa pode enfileirar uma execução de acompanhamento para o Agente atribuído, e comentários rápidos são agrupados para não criar execuções duplicadas.
