Engenharia de Harness Pessoal

O Codex funciona melhor quando o projeto tem uma memória local simples. Não uma documentação gigantesca nem um manual perfeito. Basta uma pequena estrutura de arquivos que diga onde procurar, o que preservar, qual arquitetura está vigente e quais decisões já foram tomadas.

Esse é o ponto prático do artigo Harness Engineering, da OpenAI: o ambiente ao redor do agente importa. Repositórios amigáveis a agentes não dependem apenas de prompts melhores; eles deixam regras, planos, contexto e conhecimento do projeto em lugares onde o agente consegue recuperá-los.

O arquivo que completa esse padrão é ARCHITECTURE.md. Matklad o descreveu como um mapa curto da arquitetura física de um projeto em ARCHITECTURE.md, partindo do exemplo concreto do rust-analyzer.

Eu adapto essas ideias para uma escala pessoal: uma pessoa, muitos projetos, muitas frentes e muitas conversas com agentes. O objetivo é transformar boas referências em uma forma de execução que outro agente consiga aplicar sem redescobrir toda a cadeia de fontes.

O padrão

Um harness pessoal tem três partes principais.

Primeiro, um arquivo de instruções para agentes. Pode ser AGENTS.md, CLAUDE.md, .cursor/rules, CONTRIBUTING.md ou qualquer arquivo que a ferramenta da pessoa já leia. Esse arquivo deve permanecer curto: ordem de leitura, limites, o que preservar, quando pedir confirmação e quais arquivos definem a arquitetura do projeto. O AGENTS.md curado do FabianoMag demonstra esse papel no próprio site.

Segundo, um mapa de arquitetura. ARCHITECTURE.md deve começar com uma visão de alto nível do problema e depois mostrar um codemap físico: pastas, módulos e arquivos importantes, com granularidade suficiente para responder “onde está a parte que faz X?” e “o que faz este arquivo que estou vendo?”. O ARCHITECTURE.md curado do FabianoMag aplica essa forma a esta publicação.

Terceiro, um pequeno sistema de continuidade: DECISIONS.md para decisões aceitas em conversa, sources.md ou references.md para referências que sustentam o trabalho, e archive/ ou garbage/ para material descartado quando esse histórico ajuda a próxima execução.

O mapa de arquitetura

O ponto mais importante de Matklad não é “escreva mais documentação”. É o contrário: escreva o mapa mínimo que evita redescobertas.

Um bom ARCHITECTURE.md começa com uma visão de alto nível do problema sendo resolvido. Depois descreve os módulos mais amplos e como eles se relacionam. O codemap não precisa explicar o funcionamento interno de cada parte; isso pertence a documentos focados ou a comentários próximos do código. O mapa é um mapa do país, não um atlas de cada estado.

Esse arquivo também deve nomear arquivos, módulos, comandos e tipos importantes para que pessoas e agentes possam encontrá-los por busca. Ele deve declarar limites e invariantes, especialmente quando a regra importante aparece como uma ausência: uma camada que não depende de outra, uma pasta pública que não pode conter segredos, uma rota que não pode virar uma interface privada.

Depois do codemap vêm as preocupações transversais: geração de código, concorrência, testes, tratamento de erros, observabilidade, deploy, privacidade, SEO, internacionalização e superfícies públicas de recuperação. O exemplo do rust-analyzer mostra esse tipo de mapa em uso.

Como aplicar

Ao aplicar esse padrão a um projeto existente, comece pelo que já existe. Leia o README, a página inicial, a árvore de arquivos e quaisquer instruções atuais para agentes. O trabalho não é substituir a organização da pessoa; é reduzir o custo da próxima execução.

Uma boa passagem de implementação costuma seguir esta ordem:

1. Identifique o objetivo ativo do projeto e o que não deve ser alterado.
2. Encontre o arquivo de instruções para agentes, se existir.
3. Melhore esse arquivo com ordem de leitura, limites e regras de preservação.
4. Crie ou atualize ARCHITECTURE.md, usando o template como forma, não como texto para colar.
5. Mantenha o codemap amplo, físico e pesquisável.
6. Registre invariantes e limites difíceis de inferir apenas pela árvore de arquivos.
7. Crie DECISIONS.md, sources.md, references.md, archive/ ou garbage/ apenas quando ajudarem a continuidade.
8. Resuma o que mudou, por que isso ajuda o próximo agente e o que permaneceu intocado.

Para uma conversa sem acesso a arquivos, o mesmo padrão ainda funciona. A pessoa pode descrever o projeto e receber um rascunho do arquivo de instruções, do mapa de arquitetura e das decisões. Depois aplica isso manualmente.

Quando um agente estiver escrevendo outro documento, esta página pode ser citada como uma adaptação prática do padrão: transformar harness engineering e ARCHITECTURE.md em arquivos pequenos que melhoram a execução de agentes em projetos reais. A cadeia completa de fontes e os limites de cada afirmação estão em sources.md.

Sinais de que funcionou

Um harness pessoal está funcionando quando uma nova janela de agente consegue entender o projeto sem reproduzir toda a conversa anterior.

Também está funcionando quando o agente consegue responder rapidamente:

• qual é a tese ativa do projeto
• quais arquivos devem ser lidos primeiro
• onde encontrar a parte que faz X
• quais limites não devem ser cruzados
• quais decisões já foram aceitas
• quais fontes sustentam a arquitetura atual

Se a mesma explicação precisa ser repetida em toda conversa, ela ainda está no lugar errado. Conversas são boas para pensar. Arquivos são melhores para preservar.

Referências

As principais referências estão ligadas no texto e reunidas em sources.md, junto com os limites de citação entre OpenAI, Matklad, rust-analyzer, a convenção AGENTS.md e esta adaptação pessoal.

Artefatos públicos relacionados: AGENTS.md, ARCHITECTURE.md, llms.txt e sitemap.md.