Intensivo Grátis 21–22/11Intensivo gratuito de 2 dias em Vibecoding (21–22/11 às 16:00 MSK) · Turma 3 começa 23/11Inscrever-se grátis →Turma 3 (23/11)
LançamentoCódigo / SDK · Pronto p/ usoHabr AI→ original

Como fazer um agente de IA levar a tarefa até o fim: testes automatizados de 12 minutos e merge manual

O agente costuma escrever "pronto" mesmo sem ter testado o código, por isso o autor de um shooter online cercou o modelo com um harness, um conjunto de regras e verificações. O agente escreve o código e os testes, sobe o jogo no Docker e roda testes e2e de ponta a ponta: bots jogam uma partida inteira, que dura cerca de 12 minutos. Depois, o agente abre um PR (pull request, pedido de merge do código), mas o botão de merge só é apertado por uma pessoa. A conclusão: confie no agente apenas na medida das verificações que ele passou.

Processado por IA de Habr AI; editado por Hamidun News
Como fazer um agente de IA levar a tarefa até o fim: testes automatizados de 12 minutos e merge manual
Fonte: Habr AI. Colagem: Hamidun News.
Ouvir artigo
Ficha técnica e números-chave
ParâmetroDados
Fonte originalHabr AI ↗
Editor-chefe
Dado-chave #1Os testes e2e só são necessários quando há alterações na lógica do jogo, não no frontend
Dado-chave #2Depois de cerca de 60% do contexto preenchido, a atenção do modelo cai
Dado-chave #3As tarefas ficam em docs/tasks, em arquivos md curtos e separados

Uma IA que escreve código adora dizer "pronto" logo após a primeira execução, mesmo que tenha quebrado um módulo vizinho. O autor de um shooter online feito quase inteiramente com IA resolveu o problema cercando o modelo com um harness, um conjunto de regras, ferramentas e verificações que conduz o agente passo a passo. No caso dele, o agente escreve o código e os testes, sobe o jogo no Docker e roda testes e2e (end-to-end: bots entram no jogo e disputam uma partida de verdade, que dura cerca de 12 minutos).

Depois disso, o agente abre um PR (pull request, pedido de merge do código na branch principal), mas o botão de merge só é apertado por uma pessoa. A abordagem serve para quem delega tarefas reais a agentes e acompanha o consumo de tokens.

O que é um harness, em termos simples

A fórmula que sustenta a análise é: agente = LLM + harness. O modelo sabe raciocinar, e todo o resto fica por conta da estrutura ao redor: ele executa o ciclo de chamadas, aciona ferramentas, monta o contexto, guarda memória e cache e verifica o resultado. Segundo o autor, o termo se popularizou no início de 2026, após textos de Mitchell Hashimoto, da HashiCorp, um relatório da OpenAI sobre o Codex e artigos da LangChain.

O autor destaca cinco componentes:

  • ciclo: o modelo é chamado até a tarefa ser concluída ou até atingir o limite;
  • ferramentas: processamento do tool_call enviado pelo modelo e execução do código da ferramenta;
  • contexto: montagem do prompt levando em conta todas as camadas;
  • restrições: papéis e orçamentos de tokens;
  • verificações: LLM as judge e guardrails.

Os grandes players já têm seus harnesses: o Claude Code, da Anthropic, e o Codex, da OpenAI. Até o simples upload de um arquivo no chat esconde muita lógica: salvar, ler, reconhecer o texto por OCR ou por um modelo de visão, gravar no S3 e verificar se o arquivo cabe no contexto. Para tarefas típicas, um prompt one-shot basta. Mas, quando é preciso um processo sob medida para um produto específico, o harness padrão não basta, e é preciso complementá-lo.

Como personalizar o harness para um projeto

O primeiro passo é o arquivo claude.md (ou agents.md): instruções que são incluídas no prompt a cada requisição. O autor dá um exemplo didático: a regra "sempre comece a resposta com !" faz o agente responder "!Olá, em que posso ajudar?". Assim são fixadas as regras básicas, que o agente quase nunca esquece.

O segundo passo é organizar as tarefas. Dá para usar um framework como o openspec, mas, para um único projeto dentro de um monorepo, uma pasta /docs é suficiente. No claude.md fica a regra de começar pelo arquivo principal em docs, que traz links cruzados para os demais documentos (status da funcionalidade, arquitetura). Cada tarefa é um arquivo md pequeno e separado em docs/tasks. Isso economiza contexto: segundo a experiência do autor, depois de preencher cerca de 60% da janela, a atenção do modelo começa a se perder, e então é preciso abrir um novo chat ou comprimir a conversa com a skill compact.

O pipeline do próprio autor é, em grande parte, linear:

  1. Ele define a tarefa no chat e conduz uma sessão de grilling (uma série de perguntas de esclarecimento) com um plugin de skills de Matt Pocock.
  2. O agente lê a tarefa e, quando necessário, aciona skills como system-design.
  3. Monta o protótipo com o claude design, escreve o código e os testes.
  4. Prepara a release: sobe a versão do pacote e escreve o changelog.
  5. Sobe a stack local no Docker e roda as verificações estáticas.
  6. Se o código de mecânicas do jogo mudou, roda os e2e: na stack local são criadas sessões reais, nas quais entram bots com roteiros definidos.
  7. Abre um PR para a master, onde os linters rodam mais uma vez.
  8. Apenas uma pessoa aperta o merge, e só então acontece o deploy.

Três conclusões e ressalvas honestas

Primeiro, "pronto" precisa ser comprovado. O agente pode descumprir uma instrução, mas um teste que falha ou um teste suspeitamente reescrito aparece no pipeline. Testes unitários e e2e e analisadores estáticos como o SonarQube formam uma camada em que se pode confiar mais do que nas palavras do modelo.

Segundo, o harness cresce junto com o projeto. Por exemplo, os testes e2e levam cerca de 12 minutos, o tempo de uma partida. Quando o autor mudava apenas o frontend ou o backend sem lógica de jogo, eles não eram necessários, e no harness foi acrescentada a regra "rodar somente quando houver mudanças nas mecânicas". Isso significa economia direta de tempo e de tokens em cada iteração.

Terceiro, quanto menos contexto desnecessário, maior a chance de obter uma boa solução com menos rodadas de correção. Especificações e documentação no repositório são especialmente úteis em assinaturas de entrada, nas quais é importante gastar o mínimo possível de tokens por funcionalidade.

As ressalvas são evidentes. É a experiência de uma única pessoa em um único projeto, um shooter online com bots, em que os e2e são fáceis de automatizar. O próprio autor ressalta que não existe um pipeline único e correto: em alguns pontos vale sacrificar velocidade em nome das verificações, e em outros é melhor montar um protótipo mais rápido sem olhar a qualidade do código.

Não há no texto métricas como a taxa de tarefas concluídas com sucesso ou o custo de uma funcionalidade em tokens, então o que se tem é um conjunto de práticas, e não resultados medidos. Dá para começar pequeno: um claude.md com regras básicas, uma pasta docs com arquivos curtos de tarefas e a execução obrigatória dos testes antes de qualquer PR.

O resto se acrescenta quando o agente tropeçar nas mesmas pedras outra vez.

História

Perguntas frequentes sobre a notícia

O que é um harness, em termos simples?

A fórmula que sustenta a análise é: agente = LLM + harness. O modelo sabe raciocinar, e todo o resto fica por conta da estrutura ao redor: ele executa o ciclo de chamadas, aciona ferramentas, monta o contexto, guarda memória e cache e verifica o resultado. Segundo o autor, o termo se popularizou no início de 2026, após textos de Mitchell Hashimoto, da HashiCorp, um relatório da OpenAI sobre o Codex e artigos da LangChain.

Como personalizar o harness para um projeto?

O primeiro passo é o arquivo claude.md (ou agents.md): instruções que são incluídas no prompt a cada requisição. O autor dá um exemplo didático: a regra "sempre comece a resposta com !" faz o agente responder "!Olá, em que posso ajudar?". Assim são fixadas as regras básicas, que o agente quase nunca esquece. O segundo passo é organizar as tarefas. Dá para usar um framework como o openspec, mas, para um único projeto dentro de um monorepo, uma pasta /docs é suficiente.

O que se sabe sobre Três conclusões e ressalvas honestas?

Primeiro, "pronto" precisa ser comprovado. O agente pode descumprir uma instrução, mas um teste que falha ou um teste suspeitamente reescrito aparece no pipeline. Testes unitários e e2e e analisadores estáticos como o SonarQube formam uma camada em que se pode confiar mais do que nas palavras do modelo. Segundo, o harness cresce junto com o projeto. Por exemplo, os testes e2e levam cerca de 12 minutos, o tempo de uma partida.

ZK
Zhemal Khamidun — CPO da Alpina Digital, gerente de produto do AlpinaGPT. Cria produtos de IA desde 2019. O Hamidun News é um projeto pessoal que virou um agregador em produção com mais de 6.000 leitores.
✦ Unified AI Workspace · Nomad

Test Frontier LLMs & Autonomous Agents in One Workspace

Run Claude Opus 5.5, GPT-6, Gemini 3.1, and DeepSeek side-by-side in Nomad AI (nomadnet.ai) — unified model routing, deep research, and multimodal workflows under one subscription.

Try Nomad AI →Launch Nomad Agent
O que você acha?
Carregando comentários…