Um agente de código capaz de abrir um pull request é útil. Um agente de código capaz de fazer o merge enquanto ninguém está olhando é um risco com acesso de commit. A distância entre essas duas frases é o problema inteiro. Assim que um agente consegue fazer push para uma branch, rodar testes e clicar em merge, a pergunta deixa de ser “ele consegue fazer o trabalho” e passa a ser “onde termina a autoridade dele”.
Na maioria das equipes, essa pergunta é respondida por acidente. O agente tem as permissões que o ambiente de execução recebeu, a revisão acontece no terminal em que a execução começou, e o registro de quem aprovou o quê fica no histórico de rolagem de uma pessoa. Isso se sustenta até o momento em que você está rodando três agentes em dois repositórios e um deploy de sexta-feira publica algo que ninguém leu. Um portão de aprovação é a solução, mas só se for um ponto de verificação real em um sistema compartilhado, e não um hábito que você torce para que todos mantenham.
Esse sistema compartilhado é o que a Sharkly oferece. Você já tem agentes de código; a Sharkly transforma as execuções deles em Tasks com status, responsáveis (Assignees) e uma etapa de revisão que uma pessoa precisa fazer de propósito. Este artigo percorre o modelo operacional por trás disso: quem atribui o trabalho, quem o executa, quem o revisa, quem o aceita e exatamente onde fica o ponto de parada, para que um agente nunca faça o merge da própria alteração sem revisão.
O que é, de fato, um portão de aprovação
Um portão de aprovação é um ponto no ciclo de vida de uma tarefa em que a execução automatizada para e espera que uma pessoa decida o próximo passo. Não é um aviso, nem uma linha de log que você pode rolar para ignorar: é um estado em que o trabalho permanece até que um humano o mova.
A distinção que mais importa é entre um agente propor uma alteração e um agente efetivá-la. Abrir um pull request é uma proposta. Fazer o merge é uma decisão sobre produção. São atos de autoridade diferentes, e é no segundo que o julgamento da equipe precisa estar. A Sharkly torna essa fronteira explícita: mesmo com o GitHub conectado, fazer o merge de um pull request não altera o status da Task. O merge continua sendo uma ação humana registrada, e não um efeito colateral que o agente dispara ao terminar.
Tenha essa fronteira em mente, porque a maioria das histórias de “o agente quebrou a produção” é, na verdade, a história de um portão que faltou entre a proposta e a efetivação.
O modelo operacional: atribuir, executar, revisar, aceitar
A Sharkly divide uma tarefa em quatro papéis, cada um com uma única função. O contrato é simples: os agentes pesquisam, executam, testam e relatam; as pessoas definem a direção, concedem autoridade e aceitam o resultado.
- Atribuir. Uma pessoa descreve a necessidade e define o Assignee. Uma Task carrega duas atribuições distintas: as Pessoas envolvidas nela e um único responsável de execução, que é o Agente ou a Crew que roda o trabalho. Alterar uma não altera a outra.
- Executar. O responsável de execução faz o trabalho em um git worktree isolado, para que execuções paralelas não mexam nos arquivos umas das outras. Progresso, bloqueios e resultados voltam para a Task.
- Revisar. Quando o Agente termina, ele deixa a Task aguardando revisão humana em vez de fechá-la. O diff, a saída dos testes e o resumo da alteração ficam anexados à Task, e não a um terminal.
- Aceitar. Uma pessoa lê as evidências e decide: solicitar alterações, ou aceitar e fazer o merge. A aceitação é o movimento final, e só uma pessoa pode fazê-lo.
O valor aqui não está no fato de a Sharkly executar o agente. Está em que os quatro papéis permanecem visíveis em um só lugar, em vez de se dissolverem no terminal que por acaso estava aberto. Para uma versão mais aprofundada da metade da revisão, veja agentes de código com human-in-the-loop.
Faça do portão um status, não um hábito
Um portão do qual você precisa se lembrar é um portão que você vai acabar pulando. Então codifique-o no ciclo de vida da tarefa.
Os status da Sharkly carregam significado de sistema por meio de suas categorias. Backlog é um estado de estacionamento: uma Task ali não é executada, mesmo com um Agente atribuído. Movê-la para uma categoria de pronta para trabalho é o que permite que a execução comece. Completed é terminal, e chegar até ele é um movimento humano, não algo que o Agente concede a si mesmo.
O status da Task é deliberadamente separado do estado de trabalho do Agente. Enquanto o status do ciclo de vida mostra In Progress, o Agente por baixo pode estar trabalhando, aguardando uma resposta humana, aguardando revisão humana ou relatando um erro. Essa separação é o portão: o Agente pode concluir sua execução e sinalizar “aguardando revisão humana” sem que a Task jamais passe para um estado que implique que ela foi entregue. O trabalho retorna à Task e para ali até que alguém o aceite.
É isso também que torna seguro executar vários agentes ao mesmo tempo. Quando cinco agentes paralelos em worktrees isolados chegam todos à mesma coluna de revisão, você tem um único lugar para triá-los, em vez de cinco terminais para ficar de olho.
Um exemplo prático: do ticket ao PR com merge
Acompanhe uma única Task do início ao fim, usando o formato de identificador SH-312 da Sharkly.
- Abrir o ticket. Uma pessoa cria a
SH-312, uma tarefa de bug: “A busca retorna resultados desatualizados após uma mudança de filtro”. A descrição traz o objetivo, a reprodução e os critérios de aceite. Assignee: um Agente do Claude Code vinculado ao repositório de busca. - Dar forma. O Agente pesquisa a base de código e o histórico relacionado, confirma o escopo e publica seu plano de volta na Task. A pessoa lê o plano e move a
SH-312do Backlog para um status de pronta para trabalho, que é o sinal para começar. - Executar. O Agente assume a Task e trabalha em um worktree novo. Ele escreve a correção, roda o typecheck e a suíte de testes, e abre um pull request cujo título inclui
SH-312, para que a Sharkly vincule o PR de volta à Task. - Parar no portão. O Agente não faz o merge. Ele anexa o resumo da alteração, a saída dos testes aprovados e quaisquer limitações conhecidas, e então deixa a
SH-312aguardando revisão humana. O trabalho voltou para a Task. - Revisar. Uma pessoa abre a
SH-312, lê o diff e as evidências em uma única visão e percebe que a correção tocou um helper de consulta compartilhado. Ela deixa um comentário pedindo uma alteração mais restrita. Em uma Task com um Agente responsável pronto, esse comentário reenfileira a execução, de modo que o ciclo de solicitação de alterações permanece registrado, em vez de recomeçar em um chat privado. - Aceitar e fazer o merge. A segunda execução passa pela revisão. A pessoa aprova o pull request, faz o merge e move a
SH-312para Completed. Como o merge não fecha a Task automaticamente, a aceitação e o merge são duas decisões humanas registradas, e não uma cascata automática.
Cada passo dessa cadeia pode ser inspecionado depois, e é esse o ponto de um fluxo de trabalho rastreável de requisitos até o código: você consegue responder “quem aprovou isso, e com base em qual evidência” sem precisar fazer arqueologia no histórico de rolagem de alguém.
Onde não colocar um portão
Mais portões não são automaticamente mais seguros; eles adicionam atrito que treina as pessoas a clicar sem ler. Coloque um portão onde o custo de um merge errado é real. Para uma alteração pequena, bem definida e de baixo risco atribuída a um único Agente, a parada de revisão antes do merge já basta, e você não precisa de uma Crew nem de etapas extras de aprovação empilhadas por cima. Adicione revisão mais pesada quando o raio de impacto for grande: código compartilhado, migrações, qualquer coisa que toque autenticação ou cobrança.
O único portão que você nunca remove é o portão do merge. Um Agente pode pesquisar, escrever, testar e propor o dia inteiro. Se a alteração dele chega à sua branch principal é uma decisão humana, e deve continuar sendo mesmo quando o Agente acerta na maioria das vezes. Combine a revisão no nível da Task da Sharkly com a proteção de branch que você já usa, para que a plataforma imponha aquilo que o fluxo de trabalho pretende, e mantenha as ferramentas que sua equipe já utiliza: conecte o GitHub e atribua o ticket a um agente de IA sem refazer seu processo.
Se você já está rodando vários agentes de código e perdendo o rastro de qual terminou, qual falhou e qual está esperando por você, essa coluna de revisão é o motivo para experimentar a Sharkly. Rode seus agentes atuais por ela e mantenha a decisão de merge onde ela pertence.
FAQ
A Sharkly consegue impedir que um agente faça o merge sozinho? Sim. Fazer o merge de um pull request não altera o status de uma Task na Sharkly, então a execução termina em “aguardando revisão humana” em vez de efetivar uma alteração. Combine isso com a proteção de branch do GitHub para impor revisões obrigatórias no nível do repositório.
Qual é a diferença entre o status da task e o estado do agente? O status da Task é a categoria do ciclo de vida (Backlog, Started, Completed e assim por diante). O estado do Agente é o que a execução está fazendo agora: trabalhando, aguardando uma resposta humana, aguardando revisão ou com erro. Uma Task pode ficar In Progress enquanto o Agente espera por você.
Preciso de uma Crew para toda tarefa revisada? Não. Para trabalhos pequenos e bem delimitados, atribua a Task a um único Agente e use o portão de revisão antes do merge. Reserve uma Crew para um objetivo que exija um Agente líder coordenando vários membros.
