Claude e Codex ficam cada vez mais burros? Porque o teu contexto está demasiado pesado

Autor: sysls

Compilado por: Deep潮 TechFlow

Leitura recomendada por Deep潮: O criador de conteúdo e desenvolvedor sysls, com 2,6 milhões de seguidores, escreveu um artigo prático e detalhado que foi compartilhado por 827 pessoas e recebeu 7.000 curtidas. O núcleo da mensagem é simples: provavelmente, seus plugins, sistemas de memória e diversos harnesses estão atrapalhando mais do que ajudando. Este artigo não discute teorias abstratas; é uma coleção de princípios operacionais derivados de projetos reais em produção — desde como controlar o contexto, lidar com tendências de agradar a IA, até como definir condições de término de tarefas. É, até agora, a explicação mais clara que já vi sobre a prática de engenharia com Claude e Codex.

O texto completo segue:

Introdução

Você é um desenvolvedor, que usa diariamente Claude e Codex CLI, e se questiona se está explorando ao máximo suas capacidades. De vez em quando, vê-os fazerem coisas absurdamente idiotas e não entende por que algumas pessoas parecem construir foguetes com IA, enquanto você mal consegue empilhar duas pedras.

Você pensa que o problema é seu harness, seus plugins, seu terminal, ou algo assim. Usa beads, opencode, zep, e seu arquivo CLAUDE.md tem 26.000 linhas. Mas, por mais que tente, não consegue entender por que está cada vez mais longe do paraíso, enquanto outros parecem brincar com anjos.

Essa é a matéria que você aguardava.

E, para deixar claro, não tenho interesses comerciais envolvidos. Quando digo CLAUDE.md, incluo também AGENT.md; quando falo de Claude, também me refiro a Codex — ambos são ferramentas que uso intensamente.

Nos últimos meses, percebi algo interessante: quase ninguém sabe realmente como maximizar o potencial de um agente.

Parece que há um pequeno grupo capaz de fazer o agente construir um universo inteiro, enquanto a maioria se perde no mar de ferramentas, sofrendo de síndrome de escolha — achando que, ao encontrar o pacote, habilidade ou harness certos, desbloquearão a AGI.

Hoje, quero quebrar essa lógica, deixar uma mensagem simples e honesta, e partir daí. Você não precisa da última novidade em harness de agentes, nem de mil plugins, nem de ler um milhão de artigos só para se manter competitivo. Na verdade, seu entusiasmo pode estar fazendo mais mal do que bem.

Não estou aqui para uma viagem de lazer — comecei a usar agentes quando eles mal conseguiam escrever código. Testei todos os pacotes, harnesses e paradigmas. Usei a fábrica de agentes para escrever sinais, infraestrutura e pipelines de dados — não projetos de brinquedo, mas casos reais em produção. E, após tudo isso…

Hoje, trabalho com uma configuração quase minimalista, usando apenas o CLI básico (Claude Code e Codex), além de uma compreensão fundamental dos princípios de engenharia de agentes, e consegui minha maior inovação até agora.

Compreendendo que o mundo está avançando rapidamente

Primeiro, é importante entender que as empresas de modelos básicos estão em uma corrida revolucionária, e claramente não vão desacelerar em breve. Cada avanço na “inteligência de agentes” muda a forma como você colabora com eles, pois eles foram projetados para obedecer comandos cada vez mais facilmente.

Há algumas gerações, se você escrevesse em CLAUDE.md algo como “Antes de fazer qualquer coisa, leia READTHISBEFOREDOINGANYTHING.md”, havia 50% de chance de ele responder “vai se ferrar” e fazer o que quisesse. Hoje, ele geralmente segue a maioria das instruções, incluindo comandos complexos e aninhados — como “primeiro leia A, depois leia B, se C, então leia D” — e, na maioria das vezes, acompanha a orientação.

O que isso significa? O princípio mais importante é reconhecer que cada nova geração de agentes força você a repensar o que é a solução ótima, e é por isso que menos é mais.

Quando você usa muitas bibliotecas e harnesses diferentes, acaba se prendendo a uma “solução” específica, mas esse problema pode nem existir na próxima geração de agentes. Sabe quem são os usuários mais entusiasmados e que mais usam esses agentes? Exatamente — funcionários de empresas de ponta, com orçamento ilimitado de tokens, usando os modelos mais recentes. Você entende o que isso implica?

Significa que, se um problema real existe e há uma boa solução, as empresas de ponta serão os maiores usuários dessa solução. E o que farão depois? Incorporarão essa solução em seus produtos. Pense: por que uma empresa permitiria que outro produto resolvesse um problema real, criando dependências externas? Como posso saber se isso é verdade? Olhe para as habilidades, sistemas de memória, harnesses, subagentes… tudo começa com uma “solução” que resolve um problema real, testada na prática e comprovada útil.

Portanto, se algo realmente inovador e capaz de expandir de forma significativa os casos de uso de agentes aparecer, cedo ou tarde será incorporado ao núcleo dos produtos das empresas de base tecnológica. Acredite, elas estão avançando rapidamente. Então, relaxe: você pode fazer um excelente trabalho sem precisar instalar nada ou depender de terceiros.

Prevejo que nos comentários logo aparecerá algo como: “SysLS, usei o harness X, e ficou ótimo! Recriei o Google em um dia!” — e eu digo: parabéns! Mas você não é o público-alvo. Você representa uma comunidade extremamente pequena, que realmente entende de engenharia de agentes.

Contexto é tudo

Sério. Contexto é tudo. Outro problema de usar muitas plugins e dependências externas é o risco de “expansão de contexto” — ou seja, seu agente fica sobrecarregado de informações.

Quer que eu faça um jogo de adivinhação com Python? Fácil. Mas o que é aquela nota de “gerenciar memória” de 26 mensagens atrás? Ah, o usuário ficou travado numa tela há 71 sessões porque geramos muitos subprocessos. Precisa sempre fazer anotações? Sem problema… Mas isso tem a ver com o jogo de adivinhação?

Você entende. Você quer fornecer ao agente exatamente as informações necessárias para completar a tarefa, nem mais, nem menos! Quanto melhor você controlar isso, melhor será o desempenho do agente. Mas, assim que você introduz sistemas de memória estranhos, plugins, ou habilidades com nomes confusos e chamadas desorganizadas, você está entregando ao agente uma receita para fazer uma bomba ou um bolo — enquanto só quer que ele escreva um poema sobre uma floresta de sequoias.

Por isso, prego novamente: remova todas as dependências, e…

Faça algo realmente útil

Descreva com precisão os detalhes de implementação

Lembra que o contexto é tudo?

Lembra que você quer fornecer ao agente exatamente as informações necessárias, nem mais, nem menos?

A primeira estratégia para isso é separar pesquisa e implementação. Você precisa ser extremamente preciso ao definir o que quer que o agente faça.

E o que acontece se você não for preciso? “Faça um sistema de autenticação.” O agente precisa pesquisar: o que é um sistema de autenticação? Quais são as opções? Quais as vantagens e desvantagens? Agora ele vai procurar na internet uma pilha de informações que, na prática, não servem, e o contexto fica cheio de detalhes de implementação possíveis. Quando chegar na hora de implementar, ele fica mais confuso ou cria ilusões desnecessárias ou irrelevantes sobre as soluções.

Por outro lado, se você disser: “Use bcrypt-12 para hash de senha, implemente JWT para autenticação, rotação de tokens de atualização, validade de 7 dias…”, ele não precisa pesquisar alternativas, sabe exatamente o que quer, e o contexto fica cheio de detalhes de implementação.

Claro que você nem sempre conhece os detalhes de implementação. Muitas vezes, você não sabe qual é a solução correta, e às vezes quer delegar essa decisão ao agente. Como fazer? Simples: crie uma tarefa de pesquisa para explorar várias possibilidades, decida você ou deixe o agente decidir qual usar, e depois envie essa decisão para outro agente com um contexto totalmente novo para implementar.

Ao pensar assim, você perceberá onde o fluxo de trabalho está sendo poluído por informações desnecessárias, e poderá criar barreiras no fluxo, abstraindo o que não precisa estar ali, deixando apenas o que faz o agente se destacar na tarefa. Lembre-se: você tem uma equipe talentosa e inteligente, que conhece todas as possibilidades do universo — mas, a menos que diga a ela que deve criar um espaço para que as pessoas dancem e se divirtam, ela continuará falando sobre as vantagens de objetos esféricos.

Limitações do design de agradar

Ninguém quer usar um produto que fica criticando você, dizendo que você está errado, ou ignorando suas instruções. Então, esses agentes vão se esforçar para concordar com você, fazer o que você pede.

Se você pedir para colocar a palavra “feliz” a cada três palavras, eles vão tentar obedecer — e a maioria entende isso. Essa obediência é o que torna o produto tão útil. Mas há uma característica interessante: isso significa que, se você disser “encontre um bug no código”, eles vão encontrar um bug — mesmo que tenham que “criar” um. Por quê? Porque eles querem muito seguir suas instruções!

Muita gente reclama que LLMs criam alucinações e inventam coisas que não existem, mas não percebe que o problema está nelas mesmas. Você pede algo, e elas entregam — mesmo que precisem distorcer um pouco a realidade.

E aí, o que fazer? Descobri que “prompt neutro” funciona bem — ou seja, não direcionar o agente para um resultado específico. Por exemplo, ao invés de “encontre um bug no banco de dados”, diga “varra todo o banco de dados, siga a lógica de cada componente, e reporte tudo que encontrar”.

Esse prompt neutro às vezes encontra bugs, às vezes apenas descreve como o código funciona de forma objetiva. Mas não direciona o agente para presumir que há um bug.

Outra estratégia para lidar com a tendência de agradar é transformá-la em vantagem. Sei que o agente está tentando agradar e seguir minhas instruções, então posso direcionar essa inclinação.

Por exemplo, peço a um agente de busca de bugs que identifique todos os bugs no banco de dados, atribuindo +1 ponto para bugs de baixo impacto, +5 para de impacto moderado, +10 para de impacto grave. Sei que esse agente vai identificar com entusiasmo todos os tipos de bugs (inclusive os que não são bugs de verdade), e me reportar uma pontuação total, como 104 pontos. Vejo isso como um superconjunto de todos os possíveis bugs.

Depois, peço a um agente adversário que refute, atribuindo pontos ao bug se conseguir refutá-lo, e penalizando se errar — por exemplo, -2 vezes o valor do bug. Esse agente tentará refutar o máximo possível, mas com penalidades, será cauteloso. Ainda assim, tentará refutar bugs reais também. Vejo isso como um subconjunto de bugs reais.

Por fim, uso um árbitro que combina as respostas e atribui uma pontuação final. Informo ao árbitro que tenho uma resposta correta, que acerta +1 ponto, que erra -1 ponto. Assim, ele avalia as respostas dos dois agentes para cada “bug”. O que o árbitro diz ser a verdade, eu verifico. Na maioria das vezes, esse método é surpreendentemente preciso, com alguma margem de erro, mas já é uma operação quase à prova de falhas.

Talvez você ache que só o busca de bugs já seja suficiente, mas esse método funciona bem para mim porque explora a tendência natural do agente de querer agradar.

Como saber o que é útil e o que vale a pena usar?

Essa questão parece complexa, como se fosse preciso estudar profundamente, acompanhar as últimas novidades em IA, mas na verdade é simples… Se a OpenAI e a Claude implementaram ou adquiriram a tecnologia, provavelmente ela é útil.

Percebeu que “skills” (habilidades) já estão por toda parte, e fazem parte da documentação oficial do Claude e Codex? Percebeu que a OpenAI comprou a OpenClaw? Percebeu que Claude logo adicionou memória, voz e funcionalidades remotas?

E o planejamento? Ainda lembra que muita gente descobriu que planejar antes de implementar é extremamente útil, e isso virou uma funcionalidade central?

Sim, essas coisas são úteis!

E os “stop-hooks” infinitos, que eram super úteis porque os agentes relutavam em fazer tarefas longas… e então, com o lançamento do Codex 5.2, essa necessidade desapareceu de uma noite para a outra?

Isso é tudo que você precisa saber… Se algo realmente importante e útil, Claude e Codex vão implementar por conta própria! Então, não se preocupe demais em usar “coisas novas” ou “familiarizar-se com novidades”. Você nem precisa “ficar atualizado”.

Faça um favor: atualize ocasionalmente sua ferramenta CLI preferida, veja o que foi acrescentado. Isso já é suficiente.

Compressão, contexto e suposições

Algumas pessoas descobrem um grande problema ao usar agentes: às vezes eles parecem os seres mais inteligentes do planeta, e às vezes você duvida que não esteja sendo enganado.

“Esse negócio é inteligente? É um idiota!”

A maior diferença está em se o agente foi forçado a fazer suposições ou “preencher lacunas”. Hoje, eles ainda são péssimos em conectar pontos, preencher lacunas ou fazer suposições. Assim que fazem isso, fica evidente que a situação piora drasticamente.

Uma das regras mais importantes do CLAUDE.md é sobre como obter o contexto, e orientar o agente a ler essa regra toda vez que lê o CLAUDE.md (ou seja, após cada compressão). Como parte dessa regra, algumas instruções simples podem fazer uma enorme diferença: reler o plano de tarefa, e, antes de continuar, reler os arquivos relevantes.

Dizer ao agente como terminar a tarefa

Nosso senso de “tarefa concluída” é bastante claro. Para o agente, o maior problema atual é que ele sabe como começar, mas não como terminar.

Isso frequentemente leva a resultados frustrantes: o agente implementa uma série de stub e para por aí.

Testar é uma ótima métrica para o progresso do agente, porque é determinístico. Você pode definir expectativas claras. Se esses testes não passarem, a tarefa não está concluída; e você não deve alterar os testes.

Depois, basta revisar os testes. Quando todos passarem, você fica tranquilo. Pode automatizar isso, mas o mais importante é — lembre-se: “fim da tarefa” é algo natural para humanos, mas não para agentes.

Você sabe qual virou uma forma viável de definir o fim de uma tarefa? Tirar screenshots e fazer validações. Você pode fazer o agente implementar algo até passar nos testes, depois tirar uma captura de tela e verificar se o “design ou comportamento” está de acordo.

Assim, você pode fazer o agente iterar e trabalhar na direção do seu objetivo, sem se preocupar que ele pare na primeira tentativa!

Essa ideia naturalmente evolui para criar um “contrato” com o agente, embutido nas regras. Por exemplo, um arquivo {TASK}CONTRACT.md que define o que fazer antes de terminar a sessão. Nesse arquivo, você especifica testes, capturas de tela e outras validações necessárias antes de considerar a tarefa concluída.

Agentes que operam continuamente

Frequentemente me perguntam: como fazer um agente rodar 24 horas por dia, garantindo que não se desvie do objetivo?

Tenho uma solução simples: crie um stop-hook que impeça o agente de terminar a sessão, a menos que todas as partes do {TASK}_CONTRACT.md tenham sido cumpridas.

Se você tiver 100 contratos bem definidos, cada um contendo o que deseja construir, o stop-hook impedirá que o agente pare até que todos eles estejam completos, incluindo testes e validações.

Dica profissional: descobri que sessões de 24 horas contínuas nem sempre são as melhores. Parte do problema é que esse método, por sua estrutura, tende a introduzir expansão de contexto, pois informações de contratos irrelevantes entram na mesma sessão.

Por isso, não recomendo essa abordagem.

Uma alternativa melhor é abrir uma nova sessão para cada contrato. Sempre que precisar fazer algo, crie um contrato separado.

Crie uma camada de orquestração que, ao detectar a necessidade de uma ação, crie um novo contrato e uma nova sessão para executá-lo.

Isso mudará completamente sua experiência com agentes.

Iterar, iterar, iterar

Você contratou um assistente administrativo. Espera que ele saiba sua agenda desde o primeiro dia? Ou que saiba como tomar café? Que jante às 6 da tarde em vez de às 8? Claro que não. Você vai ajustando suas preferências ao longo do tempo.

O mesmo vale para o agente. Comece com uma configuração simples, deixe de lado estruturas complexas ou harnesses, e dê uma chance ao CLI básico.

Depois, vá ajustando suas preferências passo a passo. Como fazer isso?

Regras

Se você não quer que o agente faça algo, escreva uma regra. Depois, informe ao agente essa regra no CLAUDE.md. Por exemplo: “Antes de escrever código, leia coding-rules.md.” Regras podem ser aninhadas, podem ser condicionais! Se estiver escrevendo código, leia coding-rules.md; se estiver escrevendo testes, leia coding-test-rules.md; se os testes falharem, leia coding-test-failing-rules.md. Você pode criar regras com lógica condicional para o agente seguir, e o Claude (e Codex) farão isso com prazer, desde que esteja claramente explicado no CLAUDE.md.

Na verdade, essa é minha primeira recomendação prática: trate seu CLAUDE.md como um diretório lógico e aninhado, indicando onde procurar o contexto em diferentes cenários e resultados. Deve ser o mais enxuto possível, contendo apenas uma lógica IF-ELSE que diga “em certas condições, procurar aqui ou ali”.

Se você perceber que o agente está fazendo algo que não aprova, adicione uma regra, e diga a ele para reler essa regra antes de agir novamente. Assim, ele evitará repetir o erro.

Habilidades (Skills)

Skills são semelhantes às regras, mas, ao invés de preferências de codificação, representam passos operacionais. Se você quer que algo seja feito de uma maneira específica, pode embutir isso em uma skill.

Muita gente reclama que não sabe como o agente vai resolver um problema, o que gera insegurança. Para tornar isso mais previsível, faça o agente estudar como resolveria, e escreva essa solução como uma skill. Assim, você pode antecipar a abordagem dele e ajustar antes que o problema aconteça de fato.

Como fazer o agente saber que essa skill existe? Fácil! No CLAUDE.md, escreva que, ao encontrar esse cenário, ele deve ler o arquivo SKILL.md correspondente.

Gerenciar regras e skills

Você certamente desejará adicionar regras e skills continuamente. Essa é a forma de dar personalidade e memória de preferência ao seu agente. Quase tudo o mais é supérfluo.

Ao fazer isso, seu agente parecerá mágico. Ele agirá “como você quer”. E, finalmente, você sentirá que “entendeu” a engenharia de agentes.

E então…

Você verá o desempenho começar a declinar novamente.

Por quê?

Muito simples. À medida que adiciona mais regras e skills, elas podem conflitar entre si, ou o agente pode sofrer de expansão de contexto severa. Se precisar que ele leia 14 arquivos markdown antes de começar a programar, terá o mesmo problema de informações inúteis acumuladas.

O que fazer?

Limpar. Faça seu agente “fazer um spa”, consolidando regras e skills, e ajustando suas preferências para eliminar conflitos.

Assim, ele voltará a parecer mágico.

É isso. Essa é a verdadeira chave: mantenha tudo simples, use regras e skills, trate seu CLAUDE.md como um índice, e esteja atento às limitações de contexto e design.

Responsabilidade pelos resultados

Hoje, não existe um agente perfeito. Você pode delegar muitas tarefas de design e implementação ao agente, mas precisa ser responsável pelos resultados.

Então, seja cuidadoso… e aproveite!

Brincar com brinquedos do futuro (enquanto usa isso para tarefas sérias) é uma diversão!