Seu Time Não Precisa de um Modelo Melhor. Precisa de um Repositório que Saiba Dizer Não.

Por alguém que acredita que dados são sobre pessoas, não apenas números

Como ler este texto. Ele foi escrito para dois públicos. Se você é gestor sênior, head ou C-level, leia O dado desconfortável, Os três níveis, A heurística que encerra a discussão e a Reflexão final — são as seções que mudam decisão de orçamento. Se você é engenheiro ou líder técnico, leia na ordem: as seções do meio são o argumento que você vai precisar para defender essas escolhas na próxima reunião de priorização.

1 Por que este tema me importa

Nos últimos dois anos, participei de conversas em que a pergunta na mesa era invariavelmente a mesma: qual modelo vamos usar? Copilot ou Codex? Claude ou Gemini? Quantas licenças? Qual o custo por desenvolvedor?

São perguntas razoáveis. São também, quase sempre, as perguntas erradas para se fazer primeiro.

Porque o modelo é a parte do sistema sobre a qual você tem menos controle e que muda sozinha a cada poucos meses. O que está sob seu controle — e o que decide se aquele investimento vira valor ou vira retrabalho — é o harness: a infraestrutura de verificação e contexto que existe dentro do seu repositório.

Este texto nasceu de uma pergunta prática que me fizeram e que eu considero uma das mais importantes que um time pode fazer hoje: se eu vou criar um repositório do zero, com o que eu preciso me preocupar? Vou responder em três níveis — essencial, desejável e dispensável — e vou defender cada escolha com evidência. Mas antes preciso explicar o que a palavra significa, porque ela virou jargão rápido demais.

2 O que é um “harness”, e por que o nome importa

Harness, em inglês, é o arreio: o conjunto de tiras que conecta o animal à carroça. Não é o cavalo. É o que transforma força bruta em movimento numa direção específica.

No vocabulário de engenharia de software com IA, harness passou a designar tudo o que cerca o modelo: as ferramentas que ele pode chamar, o ambiente em que executa, os limites do que pode tocar, o contexto que recebe e — o ponto central deste texto — os sinais de verificação que ele consegue ler.

A Anthropic publicou em março de 2026 um estudo de design de harness para desenvolvimento autônomo de longa duração, descrevendo uma arquitetura de três agentes (planejador, gerador e avaliador) capaz de sustentar sessões de várias horas.¹ O detalhe que mais me chamou atenção não foi a arquitetura em si, mas o papel do avaliador: ele usava o aplicativo, clicando na interface como um usuário faria, testando endpoints e checando o estado do banco antes de dar nota.² Ou seja: a peça mais sofisticada da arquitetura existia para responder a uma pergunta binária — isso funciona ou não?

Guarde essa imagem, porque ela é a tese do texto inteiro.

Vale dizer o óbvio: isso não é uma preocupação nova inventada pela IA. Ambiente reprodutível, testes automatizados e integração contínua são práticas de engenharia com décadas de estrada. O que a IA fez foi mudar radicalmente o retorno de cada uma delas. Quando o código era escrito exclusivamente por pessoas, um harness fraco custava tempo. Agora que boa parte do código é escrita por sistemas que produzem volume em minutos, um harness fraco custa confiança — e confiança é bem mais cara de recuperar.

3 O dado desconfortável que a planilha de ROI não mostra

O relatório DORA de 2025, do Google Cloud, ouviu quase 5.000 profissionais de tecnologia. Os números principais:³

• 90% dos respondentes usam IA no trabalho. Deixou de ser diferencial competitivo; virou linha de base.
• Mais de 80% relatam ganho de produtividade. A percepção de valor é real e majoritária.
• 30% relatam pouca ou nenhuma confiança no código gerado por IA. Um terço da força de trabalho não confia no principal insumo do próprio processo.
• A relação entre adoção de IA e estabilidade da entrega continua negativa. A IA acelera o desenvolvimento e, sem controles robustos, expõe as fraquezas rio abaixo.

A conclusão que o relatório escolheu como manchete é a que mais importa para quem toma decisão de investimento: a IA é um amplificador. Ela não conserta um time. Ela magnifica o que já existe. Times fortes ficam mais eficientes; times com problemas estruturais descobrem que os problemas agora acontecem mais rápido e em maior escala.⁴

Há um dado complementar que fecha o raciocínio: 90% das organizações já adotaram alguma plataforma interna, e existe correlação direta entre a qualidade dessa plataforma e a capacidade de extrair valor da IA.⁵ Não é o modelo que separa quem ganha de quem perde. É o trilho.

Do outro lado da estatística, o Octoverse 2025 do GitHub mostra a escala em que isso acontece: 180 milhões de desenvolvedores, 630 milhões de repositórios, 121 milhões de repositórios novos só em 2025 — cerca de 230 por minuto. E, no mesmo relatório, um contraste que vale reler: apenas 63% dos repositórios têm um README, 5,5% têm guia de contribuição e 2% têm código de conduta.⁶

Estamos criando repositórios em ritmo industrial e documentando-os em ritmo artesanal. Enquanto o autor era humano e estava na mesa ao lado, dava para compensar conversando. Não dá mais.

4 A regra de ouro: um comando que diz sim ou não

Se você só puder levar uma frase deste texto para a próxima reunião, leve esta: o harness existe para produzir um sinal confiável de que o repositório está saudável.

Concretamente, isso significa um único comando — make check, just check, npm run check, o nome não importa — que roda formatação, análise estática, tipos e testes, é rápido, é determinístico e devolve um código de saída honesto. Todo o resto é detalhe de implementação disso.

A documentação oficial de boas práticas do Claude Code, da Anthropic, coloca a questão de forma direta: “Claude para quando o trabalho parece pronto. Sem uma checagem que ele possa rodar, ‘parece pronto’ é o único sinal disponível — e você vira o loop de verificação: cada erro espera você notar.”⁷

Leia essa frase de novo trocando “Claude” por “qualquer pessoa contratada há três dias”. O diagnóstico não muda. A diferença é de velocidade: uma pessoa nova produz um erro por dia e você percebe; um agente produz quarenta e você não.

O mesmo documento nomeia o padrão de falha mais caro dessa dinâmica — a lacuna entre confiar e verificar: o sistema produz uma implementação plausível que não trata os casos de borda. E prescreve a regra em cinco palavras: se você não consegue verificar, não coloque em produção.⁸

Para um C-level, a tradução é quase financeira. Sem harness, o custo de verificação é pago em atenção humana, item por item, para sempre. Com harness, ele é pago uma vez, em engenharia, e amortizado em cada execução. É uma das poucas decisões técnicas cujo retorno é literalmente exponencial no volume — e o volume é exatamente o que a IA está aumentando.

5 Os três níveis: essencial, desejável, dispensável

Aqui está a resposta prática à pergunta original. Duas regras de leitura. Primeira: descrevo cada item pelo arquivo ou comando que passa a existir no repositório — se não dá para apontar para um arquivo, não é um item de harness, é uma intenção. Segunda: o critério de corte é sempre o mesmo — quanto custa adicionar isso depois?

5.1 Essencial — antes da primeira funcionalidade de verdade

São seis itens. Nenhum leva mais de um dia para montar. Todos são desproporcionalmente caros de adicionar em retrospecto.

1. Ambiente reprodutível

No repositório: um arquivo de trava de dependências (uv.lock, package-lock.json, go.sum, Cargo.lock) e a versão da linguagem fixada em arquivo (.python-version, .nvmrc). O que significa: qualquer pessoa que clonar o repositório — ou o servidor de CI, ou um agente — instala exatamente as mesmas versões de tudo, hoje e daqui a um ano. Por que agora: sem isso, nenhum outro sinal é confiável. “Na minha máquina funciona” contamina o harness inteiro, porque um teste que falha deixa de significar “o código está errado” e passa a significar “talvez o ambiente esteja diferente”.

2. O comando único de verificação

No repositório: um Makefile, um justfile ou a seção scripts do package.json, com um alvo chamado check. O que significa: existe um comando — make check, npm run check, o nome não importa — que qualquer pessoa roda sem argumentos e sem conhecer o projeto, e que responde uma pergunta binária: está saudável ou não. Ele apenas encadeia as verificações que já existem, e falha se qualquer uma delas falhar.

"scripts": {
  "fmt":   "prettier --check .",
  "lint":  "eslint .",
  "types": "tsc --noEmit",
  "test":  "vitest run",
  "check": "npm run fmt && npm run lint && npm run types && npm run test"
}

Cinco linhas. A última é o harness.

Por que agora: é o item que dá sentido a todos os outros. Sem ele, “o repositório está saudável” é uma opinião, sujeita a quem você perguntou e ao humor do dia. Com ele, é um código de saída: zero ou diferente de zero. E código de saída é a única coisa que uma pessoa recém-contratada, um pipeline de CI e um agente conseguem ler da mesma forma, sem intermediário e sem interpretação.

3. Um teste de fumaça de verdade

No repositório: um arquivo de teste que sobe o sistema e exercita o caminho principal ponta a ponta — a API responde, a página carrega, o job processa uma linha. O que significa: um teste que quebra se você quebrar o funcionamento básico. É o oposto do teste decorativo, que verifica se 2 + 2 == 4 só para que exista uma suíte no relatório. Por que agora: não é sobre cobertura, é sobre ter o mecanismo montado. Escrever o teste nº 40 é trivial. Montar infraestrutura de teste sobre seis meses de código que nunca foi pensado para ser testável é um projeto, e projetos disputam prioridade.

4. CI rodando exatamente o mesmo comando

No repositório: um workflow (.github/workflows/ci.yml ou equivalente) cujo passo de verificação é literalmente make check. O que significa: o servidor não mantém uma lista própria de verificações. Ele roda a mesma coisa que você roda no seu terminal, na mesma ordem. Por que agora: pipeline que diverge do ambiente local é a origem clássica do “verde aqui, vermelho lá”. E cada episódio desses corrói exatamente o ativo que o harness inteiro existe para construir: a confiança de que o sinal significa o que diz.

5. Higiene de segredos

No repositório: um .gitignore que exclui .env desde o primeiro commit, e um .env.example com os nomes das variáveis e valores fictícios. O que significa: nenhuma credencial real entra no histórico do Git, e quem clona descobre em dez segundos quais variáveis precisa preencher. Por que agora: aqui o retrofit significa reescrever histórico e rotacionar credenciais em produção. É o único item desta lista cujo erro pode gerar uma conversa com a ANPD em vez de uma conversa com o time de engenharia.

6. Um AGENTS.md (ou CLAUDE.md)

No repositório: um arquivo de no máximo uma página, na raiz. O que significa: os comandos para rodar e testar; três ou quatro convenções que o código não revela sozinho; e as armadilhas conhecidas, do tipo “não edite schema.sql à mão, ele é gerado” ou “os testes de integração exigem Docker rodando”. Nada além disso. Por que agora: é o que uma pessoa nova — ou um agente — leria antes de tocar em qualquer coisa. Escrever leva uma hora e evita a mesma explicação repetida a cada nova contratação.

Sobre esse último item: AGENTS.md deixou de ser convenção de uma empresa e virou formato aberto. É descrito como “um README para agentes: um lugar dedicado e previsível para fornecer contexto e instruções”, já é usado por mais de 60 mil projetos de código aberto e passou a ser mantido pela Agentic AI Foundation, sob a Linux Foundation, com suporte de OpenAI Codex, Google Jules, Cursor e outros.⁹ O conteúdo recomendado é modesto e específico: comandos de build e teste, guia de estilo, instruções de teste, considerações de segurança — “qualquer coisa que você diria a um colega novo”.¹⁰

Uma advertência que vale mais que o arquivo: não é um documento para impressionar. A orientação da Anthropic é aplicar um teste linha a linha — “remover isto faria o modelo cometer um erro?” Se não faria, corte. E o alerta é explícito: arquivos inchados fazem o modelo ignorar justamente as instruções que importam.¹¹ O mesmo vale, aliás, para pessoas.

5.2 Desejável — entra na segunda semana, quando começar a doer

5.3 O que pode ficar de fora — e frequentemente deveria

Para cada item, o gatilho que justifica adicioná-lo depois.

• Meta de cobertura como trava no CI (“o build falha abaixo de 80%”). Vira métrica gamificada: o time escreve teste para subir número, não para pegar erro. Relatório informativo, sim; portão, não.
• Ferramental de monorepo (Nx, Turborepo, Bazel). Adicione quando existir o segundo pacote com dependência real entre eles.
• Testes ponta a ponta de interface (Playwright, Cypress). Adicione quando a interface parar de mudar toda semana. Antes disso são caros de manter e instáveis — que é exatamente o que você não pode ter.
• CODEOWNERS, templates de PR, proteção elaborada de branch. Adicione quando houver mais de um time tocando o mesmo código.
• Changelog automático, versionamento semântico, site de documentação. Adicione quando houver alguém fora do time consumindo releases.
• Containerização (Dockerfile, docker-compose). Adicione quando for implantado em algum lugar, ou quando o ambiente local passar a exigir serviços externos.
• Matriz de CI (três sistemas operacionais × quatro versões de runtime). Adicione quando você souber quais combinações realmente suporta — cada uma delas custa minuto de CI em todo commit, para sempre.
• Geradores, scaffolding e arquitetura de plugins. O clássico YAGNI: you aren’t gonna need it.

O anti-padrão mais comum em repositório novo — e ele fica ainda mais tentador quando um agente monta a estrutura em trinta segundos — são quinze arquivos de configuração e zero funcionalidade. Facilidade de gerar não é justificativa para existir. Todo arquivo de configuração é uma promessa de manutenção que alguém vai ter que honrar.

6 A heurística que encerra a discussão: custo de retrofit

Quando a discussão sobre prioridade empaca, uma única pergunta costuma resolvê-la: isto é caro de adicionar depois?

Repare no que essa tabela realmente faz: ela transforma uma discussão de gosto pessoal — que costuma consumir uma reunião inteira e terminar com o mais insistente vencendo — em uma decisão econômica com critério explícito. Para quem lidera, isso vale mais do que a lista em si.

7 O que muda quando quem escreve o código é um agente

Três mudanças concretas, cada uma com uma fonte que vale citar em uma apresentação.

Primeira: o ambiente precisa estar pronto, não descobrível. A documentação do GitHub para o agente de codificação do Copilot recomenda declarar os passos de preparação do ambiente em um arquivo versionado, e justifica em uma frase que eu adotei como argumento padrão: “o Copilot consegue descobrir e instalar essas dependências sozinho por tentativa e erro, mas isso pode ser lento e não confiável.”¹² Toda a economia do harness está nessa frase. Tentativa e erro é caro em tempo, em tokens e — pior — em variância. Um processo que às vezes funciona não é um processo.

Segunda: o limite precisa ser técnico, não confiança. A OpenAI define o sandbox do Codex como “a fronteira que permite ao agente agir de forma autônoma sem dar a ele acesso irrestrito à sua máquina”, com escrita restrita ao espaço de trabalho e acesso de rede limitado por padrão.¹³ O raciocínio declarado é interessante para quem pensa em governança: o sandbox reduz a fadiga de aprovação. Sem fronteira técnica, ou você aprova cada ação — e para de ler por volta da décima — ou aprova tudo. As duas saídas são ruins, e a segunda é a que acontece na prática.

Terceira: contexto é um recurso escasso e caro. A equipe do Manus publicou o relato mais honesto que li sobre isso, afirmando que a taxa de acerto de cache é a métrica mais importante de um agente em produção, com uma diferença de custo da ordem de dez vezes entre token em cache e token fora dele.¹⁴ Do mesmo texto vêm duas lições que mudam o desenho de um repositório: use o sistema de arquivos como memória — ele é ilimitado, persistente e diretamente operável pelo agente — e não esconda os erros do contexto, porque ver o caminho errado é o que impede repeti-lo.¹⁵

A tradução dessa terceira lição para o seu repositório é mais direta do que parece: a saída do seu comando de verificação é contexto. Um teste que falha despejando cinco mil linhas de log não é um sinal — é um custo. Mensagens de erro curtas, específicas e acionáveis deixaram de ser cortesia com o desenvolvedor e viraram requisito de eficiência econômica.

8 O sinal precisa ser confiável — e este é o ponto que quase todo mundo subestima

Aqui está a parte que, na minha experiência, separa harness que funciona de harness que existe só no organograma.

O Google publicou números sobre testes instáveis — aqueles que ora passam, ora falham sem que nada tenha mudado — que continuam sendo a melhor referência pública sobre o tema: quase 16% dos testes apresentam algum nível de instabilidade; cerca de 1,5% de todas as execuções reportam resultado instável; e, mais grave, aproximadamente 84% das transições observadas de “passou” para “falhou” envolvem um teste instável.¹⁶

Ou seja: em cinco de cada seis vezes que o sinal grita, ele está gritando à toa.

A consequência humana está no mesmo texto, e é uma frase que eu gostaria que estivesse pendurada em toda sala de arquitetura: “É natureza humana ignorar alarmes quando há um histórico de sinais falsos vindos de um sistema.”¹⁷

Junte isso ao dado do DORA — 30% de pouca ou nenhuma confiança no código gerado por IA¹⁸ — e você tem o desenho completo do problema. Um harness com sinal ruidoso não é melhor que a ausência de harness. É pior: consome orçamento, produz relatórios verdes e treina o time inteiro a ignorar exatamente o alarme que um dia vai ser verdadeiro.

E vale notar que determinismo não é gratuito nem automático nem apenas uma questão de disciplina de código. Em cargas de aprendizado de máquina, ele exige trabalho deliberado até na camada de hardware — a NVIDIA mantém um repositório inteiro documentando como obter resultados determinísticos em frameworks de aprendizado profundo, o que diz bastante sobre o tamanho do problema.¹⁹

Recomendação prática, e ela é impopular: teste instável deve ser tratado como falha de produção, não como inconveniência. Quarentena imediata, correção com prazo, ou remoção. A tentação de “rodar de novo até passar” é a forma mais barata de destruir o ativo mais caro que você construiu.

9 A dimensão que os frameworks de engenharia costumam esquecer

Tudo o que escrevi até aqui pode ser lido como eficiência. Mas há uma leitura que me parece mais verdadeira, e ela é sobre pessoas.

Um harness ausente não elimina o trabalho de verificação. Ele transfere esse trabalho para alguém. Normalmente para quem tem menos poder de recusar: a pessoa de plantão às três da manhã, o profissional que entrou no time semana passada e ainda não sabe o que é normal, o júnior que vai gastar a tarde investigando um teste que falha por acaso e sair da experiência achando que o problema é a própria competência.

Quando um líder decide não investir em harness, ele não está economizando. Está escolhendo — quase sempre sem perceber, o que não torna a escolha menos real — quem vai pagar a conta, e em que moeda. É uma decisão distributiva disfarçada de decisão técnica.

Há também uma dimensão específica de produtos de dados que me interessa particularmente. O harness é o lugar onde a governança deixa de ser documento e vira prática. Um teste automatizado que falha quando dados pessoais aparecem em log é governança executável. Um teste que compara a taxa de erro de um modelo entre subgrupos demográficos e barra o deploy quando a diferença ultrapassa um limite acordado é equidade executável. Uma política de privacidade em PDF, aprovada em comitê e arquivada, é intenção.

A diferença entre as duas coisas não é retórica. É que a primeira acorda alguém às três da manhã quando é violada, e a segunda não acorda ninguém — inclusive quando deveria.

Quem paga o preço de um modelo enviesado que passou por todos os comitês raramente está na sala onde ele foi aprovado. Colocar essa verificação no mesmo comando que roda os testes unitários é, na prática, a forma mais concreta que conheço de transformar valores declarados em restrição de sistema. Não é a única coisa necessária. Mas é a única que roda sozinha, toda vez, sem depender de alguém lembrar.

10 Aplicação no contexto brasileiro

Três adaptações que considero relevantes para times no Brasil.

A primeira é regulatória. A LGPD torna a higiene de segredos e a detecção automatizada de dados pessoais em logs e fixtures de teste um item de conformidade, não de capricho técnico. Colocar isso no harness desde o primeiro dia custa poucas horas; descobrir dados pessoais em um repositório com dois anos de histórico custa consideravelmente mais — e a conversa deixa de ser com o time de engenharia.

A segunda é econômica. Boa parte dos times brasileiros opera com equipes menores e orçamento mais apertado do que os benchmarks internacionais assumem. Isso me parece um argumento a favor do harness, não contra: quanto menor o time, maior o custo relativo de cada hora gasta em verificação manual e em investigação de falso positivo. O harness é a única automação de qualidade cujo retorno cresce quando a equipe encolhe.

A terceira é de talento. Somos um mercado com alta rotatividade e muita gente entrando na carreira. Um repositório com comando único de verificação e um AGENTS.md honesto reduz drasticamente o tempo de rampa de quem chega — e, o que raramente é dito, reduz a carga sobre quem já está. Nenhum time sênior escala explicando as mesmas convenções a cada nova contratação.

11 Como eu faço isso na prática

Um roteiro curto, que uso e recomendo.

Dia 1 — Repositório, .gitignore, lockfile e versão fixa do runtime. Um Makefile com o alvo check, ainda que ele rode um teste só. Um teste de fumaça de verdade. Um README de vinte linhas: o que é, como rodar, como testar.

Semana 1 — CI executando exatamente o comando check. Formatter e linter com autofix. AGENTS.md com os comandos, três convenções que importam e duas armadilhas conhecidas. .env.example.

Mês 1 — Verificação de tipos. Hook de pré-commit rápido. Atualização automática de dependências. Uma política explícita para testes instáveis, escrita antes de o primeiro aparecer — porque depois que aparece, a decisão é tomada sob pressão de prazo.

Continuamente — Podar. O AGENTS.md que ninguém revisa há seis meses está mentindo, e um documento que mente é pior que documento nenhum, porque tem a autoridade de estar versionado.

12 Uma reflexão final

O título deste texto é provocativo de propósito, mas não é retórico. O modelo que seu time usa vai mudar duas ou três vezes nos próximos dezoito meses, sem que você decida grande coisa a respeito. O harness que você construir vai continuar lá, cobrando ou pagando juros todos os dias.

O DORA disse isso com mais autoridade do que eu conseguiria: a IA é um amplificador, e o maior retorno não vem das ferramentas, mas do foco estratégico no sistema organizacional subjacente.²⁰ Amplificador é um instrumento honesto — ele aumenta o que existe. Se o que existe é um sinal claro de qualidade, você recebe mais qualidade. Se o que existe é ambiguidade, você recebe mais ambiguidade, mais rápido, e com uma nota fiscal de licenças anexada.

Construir harness é, no fundo, um ato de humildade organizacional: é admitir que ninguém — nem a pessoa mais experiente do time, nem o modelo mais caro do mercado — consegue julgar com segurança o próprio trabalho o tempo todo. E é um ato de cuidado com quem vem depois, que vai herdar este repositório sem herdar as conversas que o produziram.

E aí: se você listar hoje os repositórios ativos da sua organização, em quantos deles existe um único comando que responde, em menos de cinco minutos, se aquilo está saudável? Fico realmente curioso com as respostas — inclusive, e principalmente, com as desconfortáveis. Vamos conversar.

13 Referências