Como Parar de Escrever Código Manualmente e Começar a Projetar Arneses para Redes Neurais

Recentemente me peguei sentindo algo estranho. Você está sentado em um editor, lançando um agente como Claude Code ou Cursor, dando a ele uma tarefa, e dez minutos depois você está tentando organizar uma bagunça de funções inventadas e tipos quebrados. Tentar ditar um prompt de sistema de cinco páginas geralmente piora as coisas: o modelo esquece o início da instrução já no terceiro passo.

Parece que na comunidade de engenharia em torno da OpenAI, Anthropic e Cursor, esse problema já foi formalizado como uma disciplina separada. Isso se chama Harness Engineering, que pode ser traduzido como projetar arneses ou freios para agentes.

O repositório deusyu/harness-engineering reuniu uma base de conhecimento extensa sobre este tema em um só lugar: análises de conceitos, traduções de dezenas de artigos em inglês de engenheiros como Martin Fowler, LangChain e os criadores do Bun, além de templates prontos para implementar essa abordagem em seus próprios projetos.

De Onde Veio a Ideia

Se no desenvolvimento clássico uma pessoa escreve código e a máquina executa, então com a chegada dos agentes autônomos a cadeia muda. Uma pessoa formula restrições e regras do jogo, a rede neural escreve código, e o ambiente executa verificações e retorna feedback ao agente.

O ponto é que o engenheiro para de ser o autor de cada linha. O principal produto do engenheiro se torna um sistema de restrições: arquivos de configuração AGENTS.md, linters personalizados, testes estruturais e gates rigorosos em CI.

O repositório cita dados de um experimento real de uma das equipes: em mais de 5 meses, uma equipe de 3-7 pessoas mergeou cerca de 15.000 pull requests totalizando quase um milhão de linhas de código, fechando uma média de 3,5 PRs por pessoa por dia. A maior parte da geração aconteceu durante a noite em sessões de seis horas.

Principios Principais do Harness Engineering

O autor do repositório deconstrói a abordagem em vários conceitos aplicados.

O Repositório como a Única Fonte da Verdade

Tudo o que não está dentro de um repositório git não existe para o agente. Suas chamadas no Zoom, discussões de arquitetura no Slack ou rascunhos no Google Docs não entram no contexto do modelo.

Se você decidiu mudar uma assinatura de API ou combinou uma estrutura de pastas, isso deve existir no repositório como arquivos versionados. Qualquer especificação e plano de tarefas é imediatamente commitado em uma branch.

Um Mapa em Vez de uma Enciclopédia

Um erro comum ao configurar o desenvolvimento agentic é criar um arquivo de sistema massivo com todas as instruções do projeto. Os modelos ficam sobrecarregados com prompts extensos.

Em vez disso, é usado um arquivo AGENTS.md de cerca de 100 linhas. Ele funciona como uma tabela de conteúdos ou mapa do terreno, apontando para o agente quais subdiretórios consultar para detalhes dependendo da tarefa. Cada subdiretório contém seu próprio AGENTS.md local. Este princípio é chamado de revelação progressiva de contexto.

Controle Mecânico em Vez de Persuasão Verbal

Regras de texto na documentação ficam desatualizadas rapidamente, e os agentes tendem a ignorar ou interpretar mal. Linters e testes unitários não ficam desatualizados.

Em vez de descrições extensas de estilo de arquitetura, são escritos linters personalizados. A parte mais interessante: mensagens de erro em tais linters contêm imediatamente instruções claras para corrigir o problema. O agente executa a verificação, captura o erro do linter, lê o texto de dica e reescreve a seção problemática do código por conta própria.

Legibilidade de código para agentes e gerenciamento de entropia

Ao escolher bibliotecas, a prioridade é dada a tecnologias estáveis, bem documentadas, com comportamento previsível. Se uma biblioteca é muito complexa ou usa magia negra de metaprogramação, o agente vai tropeçar constantemente. Às vezes é mais fácil implementar um módulo interno simples do zero do que fazer a rede neural adivinhar o comportamento de um pacote externo opaco.

Além disso, os agentes adoram copiar padrões ruins se os encontrarem no código existente. Para evitar que o repositório apodreça, agentes especiais de refatoração são executados em segundo plano, cuja tarefa se resume a encontrar desvios dos padrões e criar PRs corretivas.

Repositório Autorreferencial

O que torna o projeto deusyu/harness-engineering interessante é que ele é construído exatamente sobre os princípios que descreve.

Dentro do repositório, um script rigoroso scripts/check-consistency.sh é executado, acionado via pre-commit hooks e GitHub Actions. O script verifica treze níveis de integridade:

• Verifica o número exato de artigos mencionados em badges e documentação
• Monitora que a estrutura de diretórios corresponde à árvore de arquivos declarada
• Valida todos os links e tabelas
• Controla auditorias de imagens nas traduções de artigos para que nenhum diagrama dos originais seja perdido

O processo de adicionar novos materiais é automatizado através de uma skill especializada do Claude, onde os agentes realizam a análise e formatação inicial dos artigos, enquanto um humano atua apenas como censor final.

Para Quem Este Projeto É

Se você está escrevendo projetos pessoais sozinho ou quer configurar um trabalho eficiente com Cursor, Claude Code, Aider ou modelos locais na sua equipe, este repositório vale a pena favoritar.

Não há botões mágicos ou binários prontos aqui. Este é um manual e uma coleção de experiência de engenharia, explicando por que seus prompts param de funcionar à distância e como configurar o repositório para que redes neurais tragam benefícios em vez de transformar a base de código em um lixão.

A maneira mais fácil de começar a aprender é com os arquivos no diretório concepts/, depois olhe a implementação de AGENTS.md na raiz do projeto e experimente uma estrutura similar para seus próprios repositórios de trabalho.