Toda vez que um agente de código termina uma tarefa, abre-se a mesma lacuna. Você recebe um diff e um animado "pronto", mas não o que mudou, o que foi deixado de lado, o que foi testado ou sobre o que o agente ainda tem dúvidas. Então você relê o diff, roda os testes por conta própria e refaz perguntas que o agente poderia ter respondido quando devolveu o trabalho. Coloque dois agentes para rodar e esse custo dobra. O trabalho não é o problema. A passagem de bastão é: o que circula entre quem pediu e o agente que executou, e o que volta.
Um template de passagem de bastão para agentes de código é uma estrutura fixa para o que uma tarefa carrega quando muda de mãos: de uma pessoa para um agente na atribuição, e de um agente de volta para uma pessoa na revisão. Em vez de improvisar o formato de cada transferência, você preenche os mesmos campos sempre. O agente sabe o que significa "pronto" antes de começar, e você recebe o mesmo resumo, as mesmas evidências e as mesmas perguntas em aberto quando ele para.
Este artigo percorre os dois templates que se sustentam na prática, usando o Sharkly como fluxo de trabalho: a camada acima dos seus agentes de código que mantém contexto, progresso, bloqueios, resultados e revisão humana visíveis da solicitação até a entrega. Você já tem agentes de código. O Sharkly os transforma em um time, e o template de passagem de bastão é o que faz de cada transferência um registro em vez de um chute.
O que é um template de passagem de bastão para agentes de código
Um template de passagem de bastão é um checklist transformado em estrutura. Ele responde a três perguntas que um diff cru nunca responde: o que foi pedido, o que aconteceu e de quem é a vez agora. Quando essas três coisas viajam juntas, o próximo profissional lê um único registro em vez de reconstruir três.
Vale a pena criar templates para duas passagens de bastão, porque elas correm em direções opostas e carregam coisas opostas:
- Passagem de atribuição (de uma pessoa ou Agente líder para um Agente): o objetivo, os limites e a definição de pronto, entregues antes do início do trabalho.
- Passagem de revisão (do Agente de volta para uma pessoa): a mudança, a evidência de que funciona e as partes que um humano ainda precisa julgar, entregues quando o trabalho para.
Criar template para as duas é o ponto central. A maioria dos times escreve um ticket vago e não cria template algum na volta, então toda revisão começa como um interrogatório. Consertar a viagem de volta é onde está o ganho de tempo.
O modelo operacional que o template codifica
Um template só é tão bom quanto o modelo operacional por baixo dele. Quatro verbos decidem quem é dono de cada junção: quem atribui, quem executa, quem revisa, quem aceita. Agentes pesquisam, executam, testam e relatam. Pessoas definem a direção, concedem autoridade e aceitam o resultado. A automação para onde o julgamento do time é necessário.
Esse contrato é a razão pela qual os dois templates carregam campos diferentes. Um Agente nunca deve adivinhar como é a aceitação, então o template de atribuição obriga quem pede a escrevê-la. Uma pessoa nunca deve adivinhar se verde significa seguro, então o template de revisão obriga o Agente a mostrar seu trabalho. Aqui está a passagem de atribuição como um bloco para copiar e colar:
## Assignment handoff
Task ID: SH-###
Goal: one sentence, in plain language
In scope: the specific files, endpoints, or behaviors to touch
Out of scope: what to leave alone (auth, billing, public contracts)
Definition of done:
- [ ] observable acceptance criterion 1
- [ ] observable acceptance criterion 2
Constraints: frameworks, patterns, or limits to respect
Assignee: the exact Agent that owns this
As linhas "out of scope" e "definition of done" carregam o peso. Sem elas, um agente otimiza por um diff que passa, não pelo resultado que você pretendia. Com elas, o critério de aceitação está escrito antes de existir uma única linha de código.
A passagem de revisão: o que volta
O template de retorno é o que a maioria dos fluxos de trabalho pula, e o que salva sua tarde. Quando um Agente termina, ele não deveria te avisar com um "pronto" e um link. Ele deveria devolver uma estrutura preenchida:
## Review handoff
Task ID: SH-###
Summary: what changed, in 2-3 sentences
Acceptance: each definition-of-done item, checked with how it was verified
Tests: typecheck / unit / build results, pasted or linked
Diff: the PR or worktree branch
Known limits: what this does NOT cover, and any risky assumption
Open questions: decisions left for a human
Os campos "known limits" e "open questions" são o que separa uma passagem de bastão de verdade de uma parede de checkmarks verdes. Um limite honesto ("o contador do Redis pressupõe uma única região") transforma um merge às cegas em um merge informado. É o mesmo princípio por trás de revisar código gerado por IA com evidências por tarefa: o revisor lê uma afirmação mais sua prova, não um diff mais uma esperança.
Vale declarar um limite com clareza: a passagem de revisão não é um pedido de merge. É um pedido de revisão. O Agente apresenta; a pessoa decide. Manter esses dois atos separados é o que impede que trabalho não revisado seja entregue.
Status e portões de revisão: onde o template vive
Um template que vive em um buffer de histórico é um template que ninguém lê. A passagem de bastão precisa estar anexada a algo compartilhado, e os status são o lar natural. Cada Tarefa percorre uma única faixa, e cada mudança de status é uma passagem de bastão com seu template anexado:
| Status | Responsável | Template anexado |
|---|---|---|
| Todo | Pessoa ou Agente líder | Passagem de atribuição |
| In progress | Agente | (trabalhando em um worktree isolado) |
| Ready for review | Agente | Passagem de revisão |
| Done | Pessoa | nota de aceitação + decisão de merge |
A regra que torna isso legível: Agentes movem uma Tarefa para Ready for review; Pessoas a movem para Done. Um Agente nunca marca seu próprio trabalho como Done, e uma pessoa nunca precisa reconstruir o que aconteceu, porque a passagem de revisão já está na Tarefa. No Sharkly, execução, bloqueios, resultados e discussão de acompanhamento retornam à linha do tempo da Tarefa, então quando dez agentes estão rodando você lê o quadro, não dez terminais. Essa é a diferença entre acompanhar o que os agentes concluíram e esperar que um log de commits explique isso depois. Onde o trabalho autônomo deve parar é, por si só, uma decisão de design, abordada em onde colocar portões de aprovação.
Um exemplo prático: do ticket ao PR com merge
Pegue uma Tarefa com forma realista, SH-441: "Adicionar exportação CSV à página de relatórios". Observe os templates sendo preenchidos, não o código.
Uma pessoa abre a SH-441 e um Agente líder completa a passagem de atribuição: objetivo ("permitir que usuários baixem o relatório atual como CSV"), dentro do escopo (o controller de relatórios e um novo módulo de exportação), fora do escopo (autenticação, as consultas de relatório existentes) e uma definição de pronto com três itens verificáveis (um botão de download, escape correto para vírgulas e aspas, um teste com um fixture de 10 mil linhas). O Responsável é um Agente de backend. Nada é ambíguo, porque o template se recusou a deixar que fosse.
O Agente de backend assume a Tarefa, trabalha em um worktree isolado para nunca colidir com outro trabalho, e executa os itens da definição de pronto como seu próprio checklist. Quando o typecheck, os testes unitários e o build ficam verdes, ele move a SH-441 para Ready for review com o template de retorno preenchido: um resumo curto, cada item de aceitação verificado com a forma como foi validado, o diff e um limite conhecido ("exportações acima de 100 mil linhas são bufferizadas em memória; streaming não está implementado").
Agora a passagem de bastão inverte a direção. Uma pessoa lê um único registro, não um histórico. Ela confirma o teste de escape, pondera o limite de memória contra os tamanhos reais dos relatórios, aceita por enquanto e move a SH-441 para Done, o que dispara o merge. Do ticket ao PR com merge, com um template preenchido nas duas junções e um registro de quem foi dono de cada uma. Esse é o caminho de requisitos até código tornado rastreável de ponta a ponta.
Quando um template é exagero
Templates têm um custo, então aqui está o par de decisões honesto. Pule o template completo para trabalhos pequenos e bem definidos que um único Agente termina em uma só passada, onde o objetivo e a aceitação são óbvios a partir do título da Tarefa. Recorra a ele no momento em que o trabalho cruza uma junção que importa: vários agentes em um único objetivo, uma mudança em um contrato público, ou qualquer coisa que toque autenticação, cobrança ou dados que você não consegue facilmente desfazer. Um template é um seguro contra contexto perdido, e você compra seguro onde a perda doeria.
Você pode executar tudo isso manualmente com um quadro compartilhado e disciplina. Isso funciona até que o número de agentes, tarefas e repositórios aumente e a disciplina seja a primeira coisa a ir embora. Se você já roda vários agentes, o Sharkly oferece um só lugar para gerenciar suas tarefas e resultados: Tarefas compartilhadas que carregam as passagens de atribuição e revisão, Responsáveis por Tarefa, worktrees isolados e uma faixa de status onde Agentes chegam a Ready for review e Pessoas decidem Done. Mantenha os agentes de código que você já usa. Baixe o Sharkly quando as junções entre eles começarem a custar mais do que o trabalho.
Perguntas frequentes
O que é um template de passagem de bastão para agentes de código? É uma estrutura fixa para o que uma tarefa carrega quando muda de mãos. Existem dois: uma passagem de atribuição (objetivo, escopo e definição de pronto, de uma pessoa para um Agente) e uma passagem de revisão (resumo, evidências e limites conhecidos, de um Agente de volta para uma pessoa). Preencher os mesmos campos sempre é o que impede o contexto de evaporar entre os profissionais.
Por que criar template para a viagem de volta e não apenas para o ticket? A maioria dos times escreve um ticket e não cria template algum na volta, então toda revisão começa como um interrogatório. A passagem de revisão, com seu resumo, itens de aceitação verificados e limites conhecidos, é onde um template economiza mais tempo. Veja agentes de código com humano no circuito.
Um agente deveria marcar seu próprio trabalho como concluído? Não. Deixe um Agente mover uma Tarefa para Ready for review com o template de retorno preenchido; deixe a mudança para Done, e a decisão de merge, para uma pessoa. Separar "apresentado" de "aceito" é o que impede que código não revisado seja entregue.
Onde o template deveria viver? Em uma Tarefa compartilhada, anexado a uma mudança de status, não em um terminal que só um agente viu. Quando a passagem de bastão é um status com seu template anexado, o próximo profissional vê exatamente o que está esperando por ele. Isso também evita que a revisão se torne o gargalo quando muitos agentes terminam ao mesmo tempo.
Preciso de uma ferramenta para isso, ou posso fazer manualmente? Você pode executar com um quadro compartilhado e disciplina. Uma camada dedicada compensa assim que você coordena vários agentes em vários repositórios e o acompanhamento manual vira o trabalho em si. Compare com um gerenciador de tarefas de IA para trabalho de agentes de propósito geral.
