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

Desde como controlar o contexto, lidar com tendências de agradar a IA, até como definir condições de término de tarefas, este é atualmente um dos textos mais claros sobre a prática de engenharia com Claude/Codex.

Autor: sysls

Compilado por: Deep潮 TechFlow

Leitura recomendada pela Deep潮: O desenvolvedor e blogueiro sysls, com 2,6 milhões de seguidores, escreveu um artigo prático que foi compartilhado por 827 pessoas e recebeu 7000 curtidas. A essência é uma só: seus plugins, sistemas de memória e diversos harness provavelmente estão atrapalhando mais do que ajudando. Este artigo não discute teorias, mas sim princípios operacionais derivados de projetos reais — 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 vi sobre a prática de engenharia com Claude/Codex.

Texto completo:

Introdução

Você é um desenvolvedor, usando diariamente Claude e Codex CLI, sempre pensando se está explorando ao máximo suas capacidades. Às vezes, vê a IA fazer coisas absurdamente bobas e não entende por que alguns parecem construir foguetes com ela, enquanto você mal consegue empilhar duas pedras.

Você acha que o problema está no seu harness, plugins, terminal ou algo assim. Usa beads, opencode, zep, escreveu 26000 linhas no CLAUDE.md. Mas, por mais que tente, não consegue entender por que está cada vez mais longe do paraíso, enquanto outros brincam com anjos.

Essa é a matéria que você esperava.

Além disso, não tenho interesses comerciais. Quando falo de CLAUDE.md, incluo AGENT.md; quando falo de Claude, incluo Codex — ambos 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 que consegue fazer o agente construir um mundo inteiro, enquanto a maioria se perde na vastidão de ferramentas, sofrendo de síndrome de escolha — achando que encontrou o pacote, habilidade ou harness certos, e assim desbloqueando a AGI.

Hoje, quero quebrar tudo isso, deixar uma frase simples e honesta, e partir daí. Você não precisa do harness mais recente, nem de um milhão de pacotes, e nem precisa 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 passear — comecei a usar quando o agente mal conseguia escrever código. Testei todos os pacotes, harnesses, paradigmas. Usei o agente para escrever sinais, infraestrutura e pipelines de dados — não projetos de brinquedo, mas casos reais em produção. Depois de tudo isso…

Hoje, uso uma configuração quase simplificada ao máximo, com apenas o CLI básico (Claude Code e Codex), mais uma compreensão dos princípios fundamentais da engenharia de agentes, e consegui minha maior inovação até hoje.

Entendendo que o mundo está avançando rapidamente

Primeiro, preciso dizer que as empresas de modelos básicos estão em uma corrida revolucionária, e claramente não vão desacelerar tão cedo. Cada avanço na “inteligência do agente” muda a sua forma de colaborar com eles, pois os agentes estão sendo cada vez mais programados para seguir instruções.

Algumas gerações atrás, se você escrevesse no CLAUDE.md algo como “antes de fazer qualquer coisa, leia READTHISBEFOREDOINGANYTHING.md”, havia 50% de chance de ele responder “vai se danar” e fazer o que quisesse. Hoje, eles obedecem à maioria das instruções, inclusive às mais complexas e aninhadas — como “primeiro leia A, depois leia B, se C, leia D”. Na maioria das vezes, eles seguem.

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

Quando você usa muitas bibliotecas e harnesses, fica preso a uma “solução” específica, mas essa limitação pode desaparecer na próxima geração de agentes. Sabe quem são os usuários mais entusiasmados e que mais usam esses agentes? Os funcionários das empresas de ponta, com orçamentos ilimitados de tokens, usando os modelos mais recentes. Sabe o que isso implica?

Se um problema real existe e há uma boa solução, as empresas de ponta serão os maiores usuários dela. 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 e criasse dependências externas? Como eu sei que isso é verdade? Olhe para as habilidades, sistemas de memória, harnesses, subagentes… tudo começa com uma solução para um problema real, testada na prática, comprovada útil.

Portanto, se algo realmente inovador e escalável para o uso de agentes existir, cedo ou tarde será incorporado ao núcleo das empresas de base tecnológica. Acredite, elas estão avançando rapidamente. Então, relaxe: você não precisa instalar nada ou depender de terceiros para fazer um ótimo trabalho.

Prevejo que nos comentários logo aparecerá: “SysLS, usei tal harness, e reconstruí o Google em um dia!” — Parabéns! Mas você não é o público-alvo. Você representa um grupo extremamente pequeno, que realmente entende de engenharia de agentes.

Contexto é tudo

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

Vamos fazer um jogo de adivinhação com Python? Fácil. Mas o que é aquela nota de “gerenciar memória” de 26 conversas atrás? Ah, o usuário travou uma tela com muitas sub-processos por causa da geração excessiva. Precisa sempre fazer anotações? Ok… E qual a relação 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, ao introduzir sistemas de memória estranhos, plugins, ou habilidades com nomes e chamadas confusos, você está entregando uma receita para uma bomba — uma lista de ingredientes para um bolo, quando na verdade só quer que ele escreva um poema sobre uma floresta de sequoias.

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

Faça o que realmente importa

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

Lembra que “contexto é tudo”?

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

A primeira forma de fazer isso é separar pesquisa e implementação. Seja extremamente preciso ao pedir ao agente o que fazer.

Qual o risco de imprecisão? “Crie um sistema de autenticação.” O agente vai precisar pesquisar: o que é um sistema de autenticação? Quais opções existem? Quais as vantagens e desvantagens? Agora, ele vai procurar na internet uma pilha de informações que podem não ser úteis, e o contexto fica cheio de detalhes de implementação possíveis. Quando chegar na hora de implementar, ele pode se confundir ou criar ilusões irrelevantes.

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

Claro, você nem sempre sabe os detalhes. Muitas vezes, você não sabe o que é correto, e às vezes quer delegar a decisão ao agente. Nesse caso, crie uma tarefa de pesquisa para explorar possibilidades, ou decida você mesmo qual implementação usar, e peça a um outro agente com um contexto novo para fazer a implementação.

Ao pensar assim, você perceberá onde o fluxo de trabalho está 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 o agente precisa para se destacar na tarefa. Lembre-se: você tem uma equipe talentosa, inteligente, que conhece tudo no universo — mas, a menos que diga explicitamente que quer um espaço para dançar e se divertir, ele vai ficar falando sobre as vantagens de objetos esféricos.

Limitações do design de agradar

Ninguém quer um produto que critique você, diga que está errado, ou ignore suas instruções. Então, esses agentes tendem a concordar e fazer o que você pede.

Se você pedir para colocar um “feliz” a cada 3 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 — ou até criar — um bug. Por quê? Porque querem agradar você!

Muita gente reclama de alucinações e invenções de coisas que não existem, sem perceber que o problema está nelas mesmas. Você pede uma coisa, ela entrega — mesmo que precise distorcer um pouco a realidade.

Como resolver? Descobri que “prompt neutro” funciona bem: não direcionar a IA para um resultado específico. Por exemplo, ao invés de “encontre um bug no banco de dados”, diga “varra o banco de dados, seguindo 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. Mas não direciona a IA para assumir que há um bug.

Outra estratégia é transformar essa tendência em vantagem. Sei que o agente quer agradar e seguir minhas instruções, então posso explorar isso.

Por exemplo, peço a um agente de busca de bugs que identifique todos os bugs no banco, atribuindo pontuações: bugs de impacto baixo +1, médios +5, graves +10. Sei que ele vai identificar todos, inclusive os que não são bugs reais, e me dar uma pontuação total. Vejo isso como um superconjunto de possíveis bugs.

Depois, uso um agente adversário para refutar cada um, atribuindo pontos de acordo com a refutação: se acerta, ganha pontos; se erra, perde pontos. Assim, ele tenta refutar o máximo possível, mas com penalidades, mantendo cautela. Ele vai tentar refutar até os bugs reais, incluindo os verdadeiros problemas. Vejo isso como um subconjunto de bugs reais.

Por fim, uso um árbitro para combinar as respostas, com uma referência à verdade. O árbitro pontua cada um, e verifico a veracidade. Essa abordagem costuma ser altamente precisa, quase sem erros.

Talvez você ache que só o agente de busca de bugs já seja suficiente, mas essa estratégia me funciona bem, pois aproveita a tendência natural do agente de querer agradar.

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

Parece complicado, como se fosse preciso estudar muito e acompanhar as novidades. Mas, na prática, é simples: se a OpenAI ou a Claude implementarem ou adquirirem algo, provavelmente é útil.

Percebeu que “habilidades” (skills) estão por toda parte, e fazem parte da documentação oficial? Notou que a OpenAI comprou a OpenClaw? Que a Claude adicionou memória, voz e trabalho remoto?

E o planejamento (planning)? Você lembra que muita gente descobriu que planejar antes de implementar é muito útil, e virou uma funcionalidade central?

Sim, esses são úteis!

E os stop-hooks? Muito útil, pois os agentes relutam em fazer tarefas longas… Mas, com o lançamento do Codex 5.2, essa necessidade desapareceu de uma noite para a outra.

Isso tudo 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 “fazer upgrade”. Você nem precisa “ficar atualizado”.

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

Compressão, contexto e suposições

Algumas pessoas descobrem um grande problema ao usar agentes: às vezes parecem os mais inteligentes do mundo, às vezes parecem te enganar.

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

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

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

Diga ao agente como terminar a tarefa

Para nós, humanos, a sensação de “tarefa concluída” é clara. Para o agente, o maior problema é que ele sabe como começar, mas não como terminar.

Isso muitas vezes leva a resultados frustrantes: o agente termina com uma pilha de esboços e para.

Testar é uma ótima métrica, porque é determinístico: você define expectativas claras. Se os testes não passam, a tarefa não está concluída. Você pode automatizar isso, mas o mais importante: “fim da tarefa” é natural para humanos, nem tanto para IA.

Você sabe que recentemente há uma abordagem viável? Tirar screenshots e verificar. Você pode fazer o agente implementar algo até passar nos testes, tirar uma captura de tela e verificar se o design ou comportamento estão corretos.

Assim, o agente pode iterar em direção ao seu objetivo, sem parar na primeira tentativa!

Uma extensão natural é criar um “contrato” com o agente, embutido nas regras. Por exemplo, um {TASK}CONTRACT.md que define o que fazer antes de terminar a sessão. Nesse contrato, você especifica testes, capturas de tela e validações necessárias antes de encerrar.

Agentes que rodam continuamente

Uma dúvida comum é: como fazer o agente rodar 24h, sem se desviar do objetivo?

A solução simples é criar um stop-hook que impeça o agente de terminar, até que {TASK}_CONTRACT.md esteja completo.

Se você tiver 100 contratos bem definidos, o stop-hook impedirá a finalização até que todos sejam cumpridos, incluindo testes e validações.

Dica profissional: sessões de 24h não são ideais para “fazer coisas”. Por quê? Porque introduzem crescimento de contexto desnecessário, pois informações irrelevantes entram na mesma sessão.

Por isso, não recomendo.

Uma abordagem melhor é criar uma nova sessão para cada contrato. Sempre que precisar fazer algo, crie um novo contrato e uma nova sessão para ele.

Isso mudará completamente sua experiência com agentes.

Iterar, iterar, iterar

Você contrata um assistente, espera que ele saiba sua rotina desde o primeiro dia? Ou que saiba como tomar café? Que jante às 6h ou às 8h? Claro que não. Você vai ajustando ao longo do tempo.

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

Depois, vá ajustando suas preferências. Como?

Regras

Se não quer que o agente faça algo, escreva uma regra. E informe ao agente no CLAUDE.md. Por exemplo: “Antes de codar, leia coding-rules.md.” Regras podem ser condicionais e aninhadas! Se estiver escrevendo código, leia coding-rules.md; se for teste, leia coding-test-rules.md; se o teste falhar, leia coding-test-failing-rules.md. Você pode criar regras com lógica condicional, e Claude (e Codex) seguirá, desde que esteja claro no CLAUDE.md.

De fato, essa é minha primeira dica prática: trate seu CLAUDE.md como um índice lógico, com regras condicionais e aninhadas, indicando onde buscar o contexto em diferentes cenários. Deve ser enxuto, contendo apenas a lógica IF-ELSE de “quando procurar onde”.

Se perceber que o agente está fazendo algo que não gosta, adicione uma regra, diga a ele para ler antes de agir novamente. Assim, ele aprenderá.

Skills

Skills são semelhantes às regras, mas representam passos operacionais. Se você quer que algo seja feito de uma maneira específica, coloque 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 pesquisar como resolveria, e escreva essa solução em uma skill. Assim, você antecipa a abordagem dele e pode ajustar antes que ele realmente enfrente o problema.

Como informar ao agente que essa skill existe? Simples: no CLAUDE.md, diga que ao encontrar esse cenário, ele deve consultar o arquivo SKILL.md.

Gerenciando regras e skills

Você vai querer adicionar regras e skills constantemente. É assim que você dá personalidade e preferências ao seu agente. Quase tudo o mais é supérfluo.

Ao fazer isso, seu agente parecerá mágico. Ele fará as coisas “do jeito que você quer”. E você finalmente entenderá a engenharia de agentes.

Depois…

Você verá o desempenho cair novamente.

Por quê?!

Muito simples. Quanto mais regras e skills você adiciona, mais elas podem conflitar, ou o contexto fica inchado. Se precisar que ele leia 14 arquivos markdown antes de programar, terá o mesmo problema de informações inúteis.

Como resolver? Limpe. Faça seu agente “fazer um spa”, consolidando regras e skills, eliminando conflitos, atualizando suas preferências.

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 há agentes perfeitos. Você pode delegar muitas tarefas ao agente, mas precisa ser responsável pelos resultados.

Tenha cuidado… e aproveite!

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