Harness engineering: o esqueleto que mantém código de IA coerente

Tese e origem

Harness engineering é a prática de cercar a geração de código assistida por IA com ferramentas determinísticas, revisão por agentes e verificações periódicas de entropia. A proposta parte da observação de Birgitta Boeckeler de que assistentes produzem código plausível, mas podem esquecer convenções, repetir erros e degradar silenciosamente a coerência interna de uma base - mesmo quando o programa continua compilando e passando nos testes. A analogia é o test harness: não se presume que o código esteja correto; verifica-se continuamente se ele atende a um padrão. No caso da IA, o padrão inclui não apenas comportamento funcional, mas também decisões arquiteturais, nomenclatura, segurança e estrutura.

Três componentes

O primeiro componente é a engenharia de contexto: registrar em HARNESS.md a pilha tecnológica, as decisões arquiteturais, as convenções, as restrições e suas justificativas. O documento serve como base de conhecimento para agentes, não como um README voltado a pessoas, e precisa permanecer específico e atualizado. Informar as regras reduz violações, mas não as elimina, porque o modelo otimiza plausibilidade em vez de seguir regras de modo determinístico.

O segundo componente são as restrições arquiteturais, aplicadas em “verification slots”, momentos definidos do fluxo em que uma checagem pode aprovar ou bloquear o avanço. Linters, scripts, expressões regulares e asserções estruturais são preferíveis quando a regra pode ser especificada com precisão: são rápidos, baratos e confiáveis dentro de seu escopo. Revisões por agentes são úteis para intenção, semântica e padrões difíceis de transformar em regras mecânicas, mas custam mais e são menos determinísticas.

O terceiro é a coleta de lixo, uma rotina periódica para combater entropia: código morto, TODOs antigos, dependências desatualizadas, abstrações que se tornaram obstáculos e convenções abandonadas. Diferentemente das outras verificações, ela ocorre porque passou tempo, não por causa de um evento específico de programação, e normalmente produz relatórios em vez de bloquear uma solicitação de alteração.

Harness vivo e endurecimento progressivo

O harness deve evoluir junto com a base. HARNESS.md declara as regras e registra se cada uma está sem verificação, sob revisão de agente ou aplicada deterministicamente. Agentes, hooks e CI conferem a realidade, enquanto o auditor do harness atualiza os status; o comando /harness-sync expõe divergências entre o documento e as verificações existentes.

O endurecimento progressivo é a passagem de “não verificado” para “agente” e, quando a regra estiver suficientemente compreendida, para “determinístico”. Violações repetidas identificadas por agentes podem indicar que chegou o momento de automatizar a checagem. A progressão evita tanto tentar automatizar desde o início restrições novas ou semânticas quanto manter indefinidamente uma fiscalização cara e pouco confiável por agentes.

Implementação e aprendizado

O plugin organiza a prática em três ciclos: um ciclo interno, consultivo e de baixa fricção, durante a edição; um ciclo intermediário, rigoroso, no momento da solicitação de alteração, com poder de bloquear a integração; e um ciclo externo, periódico e investigativo, para coleta de lixo, funções de adequação e auditorias. Os agentes têm confiança limitada: revisam, sugerem, relatam e sinalizam, mas não podem alterar unilateralmente código de produção nem integrar mudanças.

O plugin acrescenta uma dimensão de autoaperfeiçoamento. /reflect registra resultados, falhas, violações e padrões de sessões anteriores; o histórico ajuda a detectar recorrências e propor mudanças no contexto ou na forma de enforcement. O processo harness-init também pode inferir restrições a partir do código existente e gerar um HARNESS.md candidato para confirmação, rejeição ou refinamento humano. A adoção pode ser incremental, preservando configurações já existentes e permitindo adicionar depois coleta de lixo, CI e observabilidade.