Sensores: verificação e autocorreção

Aula 24

Guias vs. sensores, computacionais vs. inferenciais

Birgitta Böckeler organiza o harness de quem usa agentes de código em dois grupos. Guias (feedforward) atuam antes da ação: instruções, skills, especificações. Sensores (feedback) atuam depois: observam o resultado e permitem que o agente se corrija. Os sensores, por sua vez, podem ser de dois tipos:

A recomendação é usar sensores computacionais sempre que possível e reservar os inferenciais para o que não dá para codificar. O artigo da Anthropic sobre o Agent SDK chega à mesma ordem: primeiro regras determinísticas como lint, depois feedback visual, e por último o LLM como juiz, que o artigo considera pouco robusto e com latência alta. A documentação do Claude Code transforma isso em conselho direto: dê ao agente uma checagem que ele consiga rodar, seja teste, build, linter ou screenshot.

Há um efeito colateral interessante na escolha de linguagem. O artigo do Agent SDK observa que TypeScript é melhor que JavaScript para agentes porque acrescenta uma camada de feedback: o compilador vira um sensor gratuito que roda em segundos.

Fontes desta aula: Böckeler: Harness engineering for coding agent users · Anthropic: Building agents with the Claude Agent SDK · Claude Code: Best practices

Aula 25

Lint, tipos e testes estruturais escritos para o agente

Um linter tradicional é escrito para pessoas, que entendem o contexto e sabem quando ignorar um aviso. Para um agente, a mensagem de erro é a única fonte de informação sobre o que fazer. Por isso, uma das práticas mais citadas em harness engineering é escrever as mensagens de lint como instruções de correção.

No relato da OpenAI, as regras de arquitetura do projeto, como quais camadas podem importar quais, foram impostas por linters próprios e testes estruturais, e as mensagens de erro diziam ao agente exatamente como resolver a violação. Böckeler mostra a mesma técnica com um formatador próprio para o ESLint: em vez de só listar violações, ele explica o motivo da regra e o caminho de correção, e permite exceções justificadas em vez de supressões em massa.

# Mensagem para pessoas
error  no-restricted-imports  'db' import is restricted

# Mensagem para o agente
error  Camada de UI não pode importar o banco (src/ui/Pedido.tsx:3).
       Motivo: ADR 0004, a UI só fala com a camada de serviços.
       Como corrigir: use pedidosService.listar() de src/services/pedidos.ts.
       Se for mesmo necessário, adicione // arch-exception: <motivo> e explique no PR.

Böckeler observa que sensores computacionais funcionam muito bem no nível de arquivo e função (lint, tipos, regras de dependência) e são baratos o bastante para rodar a cada mudança. Já problemas que atravessam vários arquivos, como modularidade e acoplamento, precisam de um sensor inferencial por cima dos dados brutos: um revisor que olhe as métricas de acoplamento e julgue se a estrutura faz sentido. Esse tipo de checagem automática de arquitetura tem raiz nas fitness functions do livro Building Evolutionary Architectures.

Fontes desta aula: OpenAI: Harness engineering (Ryan Lopopolo) · Böckeler: Maintainability sensors for coding agents

Aula 26

Testes de mutação e o limite da cobertura alta

Um agente que precisa fazer os testes passarem vai fazer os testes passarem, e nem sempre da forma que você quer. Uma suíte com cobertura alta pode esconder asserções fracas: testes que executam o código sem verificar o resultado, ou que verificam só que nenhuma exceção foi lançada. Böckeler aponta isso como um limite real dos sensores de teste e recomenda testes de mutação como sensor complementar.

A ideia é simples. Uma ferramenta de mutação altera o código de propósito (troca um > por >=, remove uma linha, inverte uma condição) e roda os testes. Se os testes continuam passando com o código alterado, aquela mutação "sobreviveu", o que prova que nenhum teste verifica aquele comportamento. A taxa de mutantes mortos mede a qualidade real da suíte, não só quantas linhas ela executa.

Para harnesses, testes de mutação são caros demais para rodar a cada edição, mas funcionam bem em dois momentos: periodicamente, para medir a qualidade dos testes que o agente escreve, e no fim de uma tarefa grande, como um sensor de qualidade final. A Anthropic acrescenta outra proteção, específica para agentes de longa duração: instruir explicitamente que é inaceitável remover ou editar testes para fazê-los passar, já que o agente tem acesso a eles.

• Teste vermelho antes do verde: peça ao agente que escreva o teste, confirme que ele falha e só então implemente.
• Proteja os testes: regra explícita e, se possível, permissão que impeça editar testes aprovados sem pedir.
• Meça a suíte, não só a cobertura: rode mutação periodicamente nos módulos críticos.

Fontes desta aula: Böckeler: Maintainability sensors for coding agents · Anthropic: Effective harnesses for long-running agents

Aula 27

Back-pressure: hooks silenciosos no sucesso e detalhados na falha

A HumanLayer usa o termo back-pressure (contrapressão) para os mecanismos que empurram o agente de volta quando ele tenta avançar com algo errado. O exemplo mais forte é um hook que roda testes e lint ao fim do turno e impede o agente de declarar a tarefa concluída enquanto houver falhas. O Claude Code oferece exatamente isso com um hook de parada, que bloqueia o fim do turno até a checagem passar, e um limite de segurança de oito bloqueios seguidos para evitar laços infinitos.

A regra de ouro para esse tipo de sensor é economia de contexto: silencioso no sucesso, detalhado na falha. Se o hook imprime a saída completa de 400 testes que passaram, desperdiça milhares de tokens a cada turno. Se, na falha, imprime só "testes falharam", o agente não sabe o que corrigir. O formato certo é nada quando dá certo e, quando dá errado, o teste, o arquivo, a linha, o valor esperado e o recebido.

O projeto do compilador C escrito por Claudes em paralelo levou esse princípio ao limite. O autor, Nicholas Carlini, relata que a qualidade dos testes e do pipeline de integração contínua foi o fator decisivo, e que os testes foram desenhados pensando nas limitações do modelo: saídas curtas, logs gravados em arquivo com a palavra ERROR na mesma linha da causa para facilitar a busca com grep, e um modo rápido que roda uma amostra de 1% ou 10% dos testes para feedback imediato.

Fontes desta aula: HumanLayer: Skill Issue · Claude Code: Best practices · Anthropic: Building a C compiler with parallel Claudes

Erros comuns

• Testes lentos demais para o loop. Se a suíte leva 20 minutos, o agente não roda depois de cada mudança. Crie um modo rápido.
• Saída verbosa. Logs completos de sucesso enchem o contexto. Imprima só falhas.
• Confiar só no LLM como juiz. É útil para o que não dá para codificar, mas é lento e varia entre execuções.
• Deixar o agente editar os testes livremente. O caminho mais curto para o verde é apagar o teste.
• Mensagens de erro escritas só para pessoas. Diga o motivo e o caminho de correção.

Aplicação prática

1. Liste os sensores do seu projeto e o tempo de cada um. Crie um comando rápido que rode os sensores de segundos (tipos, lint, testes unitários afetados).
2. Reescreva as mensagens das três regras de lint mais violadas pelo agente no formato motivo mais caminho de correção.
3. Configure um hook de fim de turno que só imprime saída quando algum sensor falha.
4. Rode uma ferramenta de mutação no módulo mais crítico e veja quantos mutantes sobrevivem aos testes escritos pelo agente.

Siglas usadas neste módulo

LLM:

Large Language Model, modelo de linguagem de grande escala.

CI:

Continuous Integration, integração contínua.

ADR:

Architecture Decision Record, registro de decisão de arquitetura.

PR:

Pull Request, pedido de integração de mudanças.

SDK:

Software Development Kit, kit de desenvolvimento de software.