Agente de código: 4 travas antes do primeiro commit

Nos últimos dias eu vi um sinal que vale mais do que mais um modelo novo.

O repositório maestro, criado para dar memória, trilha e coordenação a Claude Code, Codex e CI, passou de 207 estrelas e entrou no radar do X justamente pelo ponto certo: agente de código sem memória vira um estagiário veloz com mania de commit.

Se você lidera tecnologia, produto ou operação, eu acho que a pergunta útil não é "qual agente escreve mais linha por minuto".

A pergunta útil é outra: como eu libero um agente de código sem transformar meu repositório em um reality show com git?

TL;DR

• Eu não julgo agente de código por demo bonita. Eu julgo por memória útil, rastro auditável, aprovação humana e cerca de segurança.

• Eu uso o método T.R.A.V.A. para decidir rápido: Tarefa clara, Rastro, Aprovação, Validação e Ambiente isolado.

• Se duas dessas travas falham, eu não libero commit. Agente sem freio não é autonomia. É retrabalho com autoestima.

O problema

Eu vejo muita empresa errando a ordem das coisas quando o assunto é agente de código.

Primeiro vem o encanto.

O time vê Claude Code, Codex ou Cursor resolvendo uma issue em minutos e pronto: alguém já quer jogar isso direto no repositório principal.

Depois vem a vida adulta.

Ninguém define qual tarefa o agente pode pegar, ninguém registra decisão, ninguém exige prova, e o histórico vira uma mistura de tentativa, palpite e fé. Git aceita tudo. O problema é o seu time depois.

Foi por isso que eu parei para ler o README do maestro e a conversa no X sobre workflow para agentes. O projeto não vende só "mais um copiloto". Ele fala de shared task system, verdict ledger, state store, memória persistente entre sessões, proof gates e trabalho local, sem daemon e sem nuvem escondida.

Em português claro: a discussão saiu de "qual agente escreve código" e entrou em "qual agente consegue trabalhar sem esquecer o que decidiu e sem sumir com a trilha".

Se você quiser montar a base antes, eu ligaria esse assunto com memória de agentes e com skills de IA. Sem essas duas peças, o agente até impressiona. Mas tropeça na segunda volta.

Eu gosto mais dessa fase.

Ela é menos sexy. E muito mais útil.

O framework / método

Quando eu preciso decidir se um agente de código merece tocar no meu repositório, eu uso o método T.R.A.V.A.

Nome simples. Porque framework com nome pomposo costuma compensar a falta de freio.

1. T de tarefa clara

Eu começo pelo básico.

O agente vai mexer em quê, exatamente?

"Corrigir bug na tela de login" é vago.

"Ajustar a validação do campo de e-mail no formulário X, sem mexer em autenticação e com teste passando" é melhor.

Agente sem tarefa clara não trabalha. Ele passeia.

E agente passeando em código alheio carrega um talento especial para abrir arquivo que ninguém pediu.

2. R de rastro auditável

Aqui muita gente pula a parte chata. Depois descobre por que ela existia.

Eu quero saber:

• qual tarefa o agente pegou;

• quais arquivos ele mexeu;

• qual decisão ficou registrada;

• qual evidência ele trouxe para dizer que terminou.

No README do maestro, esse rastro aparece em plain files dentro de .maestro/, com card, task, proof e QA. Eu gosto dessa ideia porque diff eu consigo revisar. Magia invisível eu não compro. Já basta orçamento de software.

3. A de aprovação humana

Eu não acho maduro liberar um agente para commitar em fluxo crítico sem ponto de parada.

Aprovação humana não é atraso.

É o momento em que alguém confere se o agente resolveu o problema certo, e não só se produziu código com cara de trabalho.

Eu colocaria aprovação antes de:

• abrir PR em branch sensível;

• alterar autenticação, cobrança ou permissão;

• apagar ou renomear bloco que afeta outras áreas;

• aceitar mudança sem teste claro.

4. V de validação com prova

"Funcionou na minha máquina" já era ruim quando vinha de humano.

Na boca do agente, vira piada pronta.

Eu só considero um ciclo fechado quando existe validação explícita.

No caso do maestro, isso aparece com comandos como maestro doctor, maestro status e gates de proof e QA. Eu não preciso usar a ferramenta para entender a lição: agente bom não entrega só código. Entrega evidência.

Se o agente mexeu no fluxo de exportação, eu quero ver teste, cenário ou comando que prove aquilo.

Sem prova, não é entrega.

É fanfic técnica.

5. A de ambiente isolado

O primeiro piloto não nasce em produção.

Ele nasce em uma cerca.

Conta de teste. Branch de teste. Escopo pequeno. Dependência conhecida. Regra clara de rollback.

Se o primeiro experimento já exige acesso irrestrito ao repositório, à pipeline e ao banco, eu não tenho piloto.

Eu tenho coragem mal calibrada.

Como aplicar hoje

Se eu fosse testar isso ainda hoje, eu faria assim.

Passo 1: escolher uma tarefa pequena e chata

Eu pegaria uma tarefa que ninguém ama fazer, mas que acontece toda semana.

Exemplo bom:

• renomear campos em uma tela específica;

• adicionar teste para um bug já conhecido;

• ajustar mensagem de erro sem mexer na regra de negócio;

• organizar documentação de um módulo com arquivo e escopo definidos.

Exemplo ruim:

• "refatora o sistema";

• "melhora a arquitetura";

• "deixa mais performático".

Isso não é briefing.

Isso é preguiça com licença poética.

Passo 2: instalar a trilha antes da autonomia

Se eu quiser experimentar o fluxo do maestro, o próprio README já dá um começo simples:

maestro init --yes
maestro install --agent codex
maestro doctor
maestro status

Eu não começaria pelo comando mais bonito.

Eu começaria garantindo que o agente sabe onde registrar tarefa, prova e estado.

Se você não quiser usar maestro, a lógica continua valendo: crie uma esteira mínima para tarefa, evidência e revisão antes de deixar o agente brincar de herói.

Passo 3: liberar só uma faixa da pista

Eu deixaria o agente tocar em uma área conhecida do código, com regra clara do que ele não deve fazer.

No próprio README aparece a ideia de feature card, task start, task done e verify. O detalhe técnico muda de stack para stack. O princípio não muda: o agente precisa de faixa, placa e acostamento.

Se ele puder mexer em tudo, ele vai testar a sua tolerância ao caos. E geralmente com confiança admirável.

Passo 4: medir quatro números

Eu mediria só o que interessa:

• tempo humano antes;

• tempo humano depois;

• taxa de retrabalho;

• bugs introduzidos por tarefa.

Se esses quatro números não melhoram, eu corto.

Ferramenta não é pet.

Se o seu time quiser dar o próximo passo depois desse piloto, aí sim eu olharia para Google ADK ou para servidor MCP. Antes disso, eu prefiro processo pequeno com rastro a arquitetura grande com PowerPoint bonito.

Resultados esperados

Quando o piloto é bem desenhado, eu espero três ganhos rápidos.

Primeiro, menos tempo de desenvolvedor em tarefa repetitiva e de baixo risco.

Segundo, mais clareza sobre o que o agente fez e por que fez.

Terceiro, menos discussão filosófica e mais critério operacional.

Isso vale ouro.

A maioria dos times não sofre por falta de agente.

Sofre por falta de processo mínimo para usar agente sem bagunça.

No fim do dia, o melhor agente de código não é o que impressiona no vídeo.

É o que consegue trabalhar, deixar rastro, pedir revisão na hora certa e ir embora sem destruir o contexto do próximo turno.

Perguntas rápidas

Agente de código é a mesma coisa que copiloto?

Não exatamente. Eu vejo copiloto como ajuda pontual dentro do editor. Agente de código tenta assumir uma tarefa com começo, meio e fim, chamando ferramenta, lendo contexto e propondo entrega.

Eu preciso de memória persistente no primeiro piloto?

Eu acho que sim, mas em formato simples. Dá para usar task log, decisão curta e próximos passos. O erro é achar que toda memória precisa virar banco complexo no dia um.

Aprovação humana não mata a velocidade?

Não mata. Mata desastre. Aprovação bem colocada acelera confiança, e confiança acelera adoção.

Isso substitui servidor MCP?

Não. Eu vejo servidor MCP como ponte para ferramenta. Eu vejo esse tema como governança do trabalho do agente em cima do repositório.

Onde eu aprofundo esse assunto?

Se eu fosse montar a base hoje, eu leria estes três textos meus em sequência: O que é memória de agentes de IA?, O que são skills de IA? e Google ADK: 4 filtros para não errar no piloto.

Se você quer usar agente de código na empresa, eu começaria com uma regra simples: primeiro trava, depois autonomia.

Na prática, esse é o corte entre piloto sério e demo que vira incêndio.