🧰 Entenda o que é um harness
O harness define: o que o agente consegue ver, quais ferramentas pode usar, quais ações pode executar, quais regras deve seguir, como o contexto é selecionado, como o estado é preservado, como os resultados são verificados, quando parar e o que exige aprovação. O diferencial não está no prompt — está no sistema criado ao redor do agente.
🆕 Novo aqui?
Harness significa literalmente "arreio": o equipamento que conecta a força ao trabalho e dá direção. Aqui é tudo que fica em volta do modelo. Sandbox é um ambiente descartável, isolado do resto. Observabilidade é o conjunto de logs e métricas que permite reconstruir o que aconteceu depois do fato.
Como ler: o pedido entra à esquerda e só chega à caixa iluminada (entrega) depois de passar por execução isolada, testes, revisão e gates. Repare que nenhuma seta pula direto do plano para a entrega — é essa ausência de atalho que caracteriza um harness.
Ver
Contexto selecionado
Fazer
Ferramentas e permissões
Provar
Verificadores
Parar
Limites e aprovação
🗂️ Selecione contexto de propósito
Contexto é o conjunto de arquivos, documentos, exemplos e informações relevantes para a tarefa. A tentação é jogar tudo. O resultado de jogar tudo é um agente que imita o pior padrão do repositório com a mesma naturalidade com que imita o melhor.
✓ Contexto que ajuda
- ✓A especificação da tarefa (fonte da verdade)
- ✓Os 3–8 arquivos que serão realmente tocados
- ✓Um exemplo bom do padrão que você quer replicado
- ✓Os testes relacionados e como rodá-los
- ✓O AGENTS.md com comandos e regras do projeto
✗ Contexto que atrapalha
- ✗O repositório inteiro "por precaução"
- ✗Documentação desatualizada que contradiz o código
- ✗Código legado que você quer justamente abandonar
- ✗Duas fontes de verdade dizendo coisas diferentes
- ✗Histórico de chat irrelevante arrastado adiante
💡 Dica prática
Antes de rodar o agente, escreva em uma linha: "o que ele precisa ler para não supor nada?". Se a resposta tem mais de dez arquivos, provavelmente a tarefa está grande demais — quebre antes de executar.
Curadoria
Escolher é o trabalho
Exemplo bom
Vale mais que descrição
Fonte única
Evita instrução conflitante
Tarefa grande
Quebre antes de rodar
🔑 Defina ferramentas e permissões
Ferramentas são terminal, editor, busca, testes, banco de dados, APIs. Permissões definem o que pode ser lido, alterado, executado ou publicado com cada uma. Permissão implícita é permissão total — e a maior parte dos incidentes com agentes é acesso que ninguém decidiu conceder, apenas não negou.
🧪 Exercício copiável — declare o harness em AGENTS.md
Objetivo: tirar as permissões da sua cabeça e colocá-las num arquivo versionado, que o agente lê antes de agir. Crie AGENTS.md na raiz do repositório com este conteúdo, ajustando o que está entre < >.
# AGENTS.md ## Comandos - instalar: <comando> - testar: <comando de teste> - lint: <comando de lint> - build: <comando de build> ## Pode (sem perguntar) - ler qualquer arquivo do repositório - criar branch e commitar na branch de trabalho - rodar testes, lint e build - criar e editar arquivos em <pastas permitidas> ## Não pode (exige aprovação humana explícita) - alterar arquivos de teste existentes - adicionar ou atualizar dependências - rodar migração de banco - alterar CI/CD, secrets, infraestrutura ou permissões - fazer push na branch principal ou deploy ## Limites - no máximo <N> arquivos alterados por tarefa - no máximo <N> tentativas de correção antes de parar e me perguntar - se a mesma falha ocorrer 2 vezes, pare e relate — não tente uma terceira ## Definição de pronto - os testes passam (cole a saída real, não resuma) - nenhum arquivo fora do escopo foi tocado - o diff cabe em uma revisão de 10 minutos
Como verificar: peça ao agente "leia o AGENTS.md e me diga, em lista, o que você NÃO pode fazer nesta tarefa". Se ele não repetir suas proibições corretamente, o arquivo está ambíguo — reescreva antes de delegar qualquer coisa.
⚠️ Atenção
Um agente com acesso a secrets, produção ou CI/CD é um usuário privilegiado — trate-o como tal: identidade própria, credencial de menor privilégio e trilha de auditoria. "É só um assistente" não é modelo de ameaça.
Menor privilégio
O padrão é negar
Escrito
Regra fora do arquivo não existe
Identidade
Agente é usuário, não mágica
Auditoria
Toda ação deixa rastro
📦 Isole a execução em sandbox
Sandbox é o ambiente isolado onde o agente executa sem afetar produção nem o seu ambiente de trabalho. É o que transforma "erro do agente" em "tentativa descartada" — e é o que permite conceder mais autonomia com menos medo.
Isolamento de código
Branch dedicada ou git worktree separado. Descartar é git worktree remove — custo zero, sem sujar seu diretório de trabalho.
Isolamento de execução
Container ou VM com rede restrita. O agente pode rodar o que quiser lá dentro; o que ele não alcança, não quebra.
Isolamento de dados
Base descartável com dados sintéticos ou anonimizados. Nunca aponte um agente autônomo para o banco de produção — nem para leitura, se lá houver dado pessoal.
Errar barato
É o objetivo do sandbox
Worktree
Isolamento barato de código
Rede restrita
Limita o alcance real
Dado sintético
Produção fica fora
🧠 Gerencie memória, estado e observabilidade
Memória é o que ele carrega; estado é onde ele parou; observabilidade é o que ficou registrado. Os três resolvem problemas diferentes e são confundidos com frequência.
📊 O que registrar em cada execução
- • Entrada: qual spec, qual contexto, qual versão do repositório (commit).
- • Ações: comandos executados e arquivos alterados, em ordem.
- • Verificação: saída real dos testes — não o resumo do agente.
- • Custo: tempo, tentativas e tokens consumidos.
- • Desfecho: sucesso, desistência ou interrupção — e por quê.
Monitor de execução (recriação ilustrativa, não é screenshot real)
[plano] 3 passos · 4 arquivos previstos
[exec ] editou src/pagamentos/idempotencia.ts
[teste] 128 passaram · 1 falhou (duplicidade)
[exec ] tentativa 2/3 · corrigiu chave composta
[teste] 129 passaram · 0 falharam
[gate ] aguardando aprovação: migração detectada
Como ler: cada linha é um evento auditável. "tentativa 2/3" mostra o limite funcionando; a última linha mostra o loop parando sozinho diante de uma ação irreversível — exatamente o comportamento que você quer.
Memória
O que ele carrega
Estado
Onde ele parou
Log
O que ficou provado
Saída real
Nunca o resumo dele
✅ Instale verificadores e limites
Verificadores são os testes e validações que avaliam a qualidade do resultado. Limites são os tetos de tempo, custo, tentativas, arquivos modificados e ações permitidas. A qualidade do verificador determina quanta autonomia você pode conceder — não a qualidade do modelo.
📏 Os limites que valem a pena configurar hoje
- •Arquivos alterados: mantém o diff revisável e denuncia escopo estourado.
- •Tentativas: impede a repetição da mesma correção com outra roupa.
- •Tempo e custo: transforma "ficou rodando a noite toda" em alerta, não em fatura.
- •Ações proibidas: deploy, migração, secret, branch principal — sempre com humano.
Checagem rápida: você quer aumentar a autonomia do agente num repositório. Qual investimento tem mais efeito?
Verificador
Autoriza a autonomia
Teste rápido
Loop só funciona se for veloz
Teto
Freio quando o resto falha
Aprovação
Parte do harness, não extra
📌 Resumo do Módulo
Próximo Módulo:
2.2 - Loop Engineering: o ciclo que executa, testa, corrige — e sabe parar.