Claude Code e Codex: o que é um harness e por que ele importa tanto quanto o modelo

Quando alguém fala em “programar com IA”, a conversa costuma girar em torno do modelo: qual é mais inteligente, qual escreve código melhor, qual saiu semana passada.

O modelo importa, claro. Mas tem uma peça que quase ninguém explica e que decide boa parte da experiência: o harness.

Entender o que ele é muda o jeito de usar ferramentas como o Claude Code, da Anthropic, e o Codex, da OpenAI. E, como quase tudo em computação, fica fácil quando a gente desenha as peças.

O modelo sozinho só devolve texto

Um modelo de linguagem, sozinho, faz uma coisa: recebe um texto e devolve outro. Só isso. Ele não abre arquivos, não roda programas, não sabe o que tem na sua pasta. Se você pergunta “por que meu teste falha?”, ele só pode adivinhar a partir do que você colou na conversa.

Para a IA trabalhar de verdade num projeto, alguém precisa:

mostrar a ela os arquivos certos;
executar o que ela decidir executar e devolver o resultado;
impedir que ela faça o que não deve;
lembrar das regras do projeto de uma conversa para outra.

Esse “alguém” é um programa comum, escrito por gente, que fica em volta do modelo. É o harness. A própria documentação do Claude Code usa esse nome: o harness é a camada em volta do modelo que fornece as ferramentas e administra o contexto que ele enxerga.

Uma analogia ajuda: o modelo é o motor; o harness é o resto do carro. Volante, freio, painel, cinto de segurança. Um motor potente solto no chão não leva ninguém a lugar nenhum.

As peças de um harness

1. Ferramentas

O harness oferece ao modelo um cardápio de ações: ler um arquivo, procurar um texto no projeto, editar um trecho, executar um comando no terminal, buscar na web. O modelo não executa nada diretamente: ele pede (“quero ler src/Pedido.java”), o harness executa e devolve o resultado como texto.

É isso que transforma um chat num agente.

2. O laço

Com ferramentas, o trabalho vira um ciclo. A documentação do Claude Code descreve três fases que se misturam: reunir contexto, agir e verificar. Peça “corrija o teste que está falhando” e o laço pode ser:

rodar os testes e ler a saída;
procurar o arquivo citado no erro e lê-lo;
editar a linha com problema;
rodar os testes de novo;
se ainda falhar, voltar ao passo 2.

Cada resultado alimenta a próxima decisão do modelo. Quem mantém esse laço girando, e sabe a hora de parar, é o harness.

3. Contexto

O modelo tem uma memória de trabalho limitada, a janela de contexto: tudo o que ele “vê” de uma vez, como a conversa, os arquivos lidos e as saídas de comando. Num projeto grande, ela enche rápido.

O harness decide o que entra e o que sai: resume a conversa quando ela fica longa, descarta saídas antigas, carrega instruções só quando são necessárias. Boa parte da diferença de qualidade entre ferramentas está aqui, e não no modelo.

4. Memória do projeto

Toda sessão nova começa do zero. Para não repetir as mesmas instruções todo dia, os dois harness leem um arquivo de instruções do projeto no começo de cada sessão:

o Claude Code lê o CLAUDE.md (e também sabe ler o AGENTS.md);
o Codex lê o AGENTS.md, um formato aberto que outras ferramentas também adotaram.

É ali que entram as regras da casa: como rodar os testes, o padrão de nomes, o que nunca fazer.

# Projeto Loja

- Java 21, Spring Boot. Testes: `./mvnw test` (rode antes de dizer que terminou).
- Entidades JPA: relacionamentos sempre LAZY; busque com JOIN FETCH quando a tela precisar.
- Nomes de classes e métodos em português, como no resto do código.
- Nunca altere arquivos em `src/main/resources/db/migration/` já aplicados.

Repare na segunda regra: ela evita, em todo código que o agente escrever, o problema que expliquei em O problema N+1 no JPA/Hibernate. Um bom arquivo de instruções é conhecimento de engenharia escrito uma vez e aplicado sempre.

5. Segurança

Um agente que roda comandos no seu computador pode, em tese, apagar arquivos, instalar coisas ou mandar dados para fora. Por isso o harness também é o sistema de freios:

No Claude Code, você escolhe um modo de permissão: no modo manual ele pede autorização antes de editar ou rodar comandos; dá para liberar só as edições; o modo plano só investiga e propõe, sem alterar nada; e o modo automático usa um classificador que barra as ações arriscadas. Além disso, ele guarda uma cópia dos arquivos antes de editar, e dá para voltar atrás.
No Codex, há duas chaves independentes: o sandbox define o que o agente consegue tocar (só leitura, escrita dentro da pasta do projeto, ou acesso total) e a política de aprovação define quando ele para e pergunta.

Repare que é o mesmo problema resolvido de dois jeitos. Nenhum dos dois confia cegamente no modelo, e você também não deveria.

6. Extensões

Por fim, os dois harness podem ser estendidos:

skills: pacotes de instruções que o agente carrega só quando a tarefa pede (escrevi um artigo inteiro sobre elas: Skills: como ensinar seu agente de IA a trabalhar do seu jeito);
MCP: um protocolo para conectar o agente a serviços externos, como banco de dados, sistema de tarefas ou navegador;
no Claude Code, ainda há hooks (comandos que rodam automaticamente em certos momentos, como formatar o código depois de cada edição) e subagentes (agentes auxiliares que fazem uma parte do trabalho num contexto separado).

Claude Code e Codex lado a lado

	Claude Code	Codex
Empresa	Anthropic	OpenAI
Modelos	Claude	modelos da OpenAI
Onde roda	terminal, IDE, desktop, web	terminal, IDE, web
Instruções do projeto	`CLAUDE.md` (lê `AGENTS.md`)	`AGENTS.md`
Segurança	modos de permissão + pontos de restauração	sandbox + política de aprovação
Skills	`.claude/skills/`	`.agents/skills/`
Código do harness	fechado	aberto (licença Apache 2.0)

As ferramentas mudam rápido. Esta tabela vale para o momento em que escrevo, e o detalhe de cada uma está sempre na documentação oficial. O que não muda é a anatomia: modelo + ferramentas + laço + contexto + memória + segurança + extensões. Aprenda as peças e qualquer ferramenta nova fica fácil de entender.

Como trabalhar bem com um agente

Estas são as práticas que eu recomendo para trabalhar com esses agentes:

Comece pedindo um plano. Para tarefas maiores, peça que o agente investigue e proponha antes de editar. É bem mais barato corrigir um plano do que um código.
Dê tarefas do tamanho de um commit. “Adicione validação de CPF no cadastro” funciona; “refaça o sistema” não.
Dê ao agente um jeito de verificar. Testes automatizados são o melhor amigo do agente: com eles, o laço “agir, verificar” fecha sozinho.
Leia cada alteração. O agente escreve; a responsabilidade continua sua. Se você não entende o que mudou, não aceite.
Use o git como rede de segurança. Commit antes de cada tarefa grande. Deu errado, você volta.
Escreva o arquivo de instruções. Cada vez que você corrigir o agente pela mesma coisa duas vezes, essa regra merece ir para o CLAUDE.md ou o AGENTS.md.
Não tire os freios no seu computador pessoal. Modos sem nenhuma restrição existem para ambientes isolados, não para a máquina onde estão suas senhas e seus documentos.

E onde ficam os fundamentos nisso tudo?

Mais importantes do que nunca.

Quando o agente propõe trocar uma lista por um mapa, você precisa saber se isso melhora ou piora. Quando ele escreve uma consulta, você precisa enxergar o N+1 escondido. Quando o teste passa, você precisa saber se o teste testa alguma coisa.

O trabalho do programador está mudando: menos digitação, mais especificação, revisão e julgamento. E julgamento técnico vem de base: algoritmos, estruturas de dados, arquitetura. É o que sempre defendi aqui e continuo defendendo, agora com mais motivo.

Conclusão

O modelo raciocina e escreve; o harness dá a ele mãos, olhos, memória e freios.
Ferramentas, laço, contexto, memória do projeto, segurança e extensões são as peças que aparecem no Claude Code, no Codex e em qualquer agente que surgir.
Saber como o harness funciona é o que permite usar esses agentes com produtividade e com segurança.

Programar é um ato de pensar. Com um agente ao lado, você pensa num nível acima, e por isso precisa pensar ainda melhor.