Sysls alerta: Sobrecarregar Claude e Codex com contexto pode reduzir o desempenho

Autor: sysls

Tradução: Deep潮 TechFlow

Guia da Shenchao: O desenvolvedor e blogueiro sysls, com 2,6 milhões de seguidores, escreveu um artigo detalhado e prático que foi compartilhado por 827 pessoas e recebeu 7.000 curtidas. O ponto central é apenas uma frase: seus plugins, sistemas de memória e diversos harnesses provavelmente estão atrapalhando mais do que ajudando. Este artigo não fala de teorias gerais, mas sim de princípios práticos extraídos de projetos reais em produção — desde como controlar o contexto e lidar com a tendência de agradar da IA até como definir condições de término da tarefa. É o artigo mais claro que já vi sobre práticas de engenharia com Claude/Codex.

O texto completo é:

Você é um desenvolvedor que usa Claude e Codex CLI todos os dias, pensando diariamente se realmente extraiu todo o potencial deles. De vez em quando, você vê eles fazendo coisas absurdamente tolas e não entende por que algumas pessoas parecem estar construindo foguetes com IA, enquanto você nem consegue empilhar duas pedras com estabilidade.

Você acha que é problema do seu harness, problema do plugin, problema do terminal, etc. Você usou beads, opencode, zep, e seu arquivo CLAUDE.md tem 26.000 linhas. Mas, não importa o que você tente, não consegue entender por que está se afastando cada vez mais do céu, enquanto os outros estão brincando com os anjos.

Este é o artigo que você estava esperando.

Além disso, não tenho interesses envolvidos. Quando falo sobre CLAUDE.md, também incluo AGENT.md; quando falo sobre Claude, também incluo Codex, e uso ambos amplamente.

Nos últimos meses, observei algo interessante: quase ninguém sabe realmente como maximizar o potencial dos agentes.

Parece que um pequeno grupo de pessoas consegue fazer os agentes construírem todo o mundo, enquanto os demais giram em meio a um oceano de ferramentas, desenvolvendo síndrome de escolha — acreditando que encontrar a combinação correta de pacotes, habilidades ou harnesss desbloqueará a AGI.

Hoje, quero romper tudo isso e deixar uma frase simples e honesta com vocês, e daí partimos. Você não precisa do último harness de agente, não precisa instalar um milhão de pacotes e absolutamente não precisa ler um milhão de artigos para manter-se competitivo. Na verdade, sua paixão provavelmente faz mais mal do que bem.

Não estou aqui para turistar — comecei a usá-lo desde a época em que os agentes mal conseguiam escrever código. Testei todos os pacotes, todos os harnesses, todos os paradigmas. Escrevi sinais, infraestrutura e pipelines de dados com agent factories, não são “projetos de brinquedo”, são casos de uso reais em produção. Depois de fazer tudo isso...

Hoje, usei uma configuração quase tão simples quanto possível, apenas os CLI básicos (Claude Code e Codex), além de uma compreensão dos princípios fundamentais da engenharia de proxy, para realizar o trabalho mais inovador da minha vida.

Primeiro, quero dizer que as empresas de modelos básicos estão em uma corrida histórica e, claramente, não desacelerarão em breve. Cada melhoria na "inteligência de agente" altera a maneira como você colabora com eles, pois os agentes estão sendo projetados para serem cada vez mais dispostos a seguir instruções.

Há apenas algumas gerações, se você escrevesse em CLAUDE.md: “Antes de fazer qualquer coisa, leia READTHISBEFOREDOINGANYTHING.md”, ele teria 50% de chance de responder: “Vá se f***”, e seguir seu próprio caminho. Hoje, ele segue a maioria dos comandos, inclusive comandos aninhados complexos — por exemplo, você pode dizer: “Primeiro leia A, depois leia B, e se C, então leia D”, e na maioria das vezes ele estará disposto a seguir.

O que isso significa? O princípio mais importante é reconhecer: cada nova geração de agentes o obriga a repensar qual é a solução ideal, exatamente por isso menos é mais.

Quando você usa muitas bibliotecas e harnesses diferentes, você se prende a uma “solução”, mas esse problema pode nem existir diante dos agentes da próxima geração. Você sabe quem são os usuários mais entusiasmados e que mais utilizam agentes? Sim — são os funcionários de empresas de ponta, que têm orçamentos ilimitados de tokens e utilizam os modelos mais recentes. Você entende o que isso significa?

Isso significa que, se existir um problema real e uma boa solução, as empresas de ponta serão os maiores usuários dessa solução. E o que elas fazem a seguir? Incorporam essa solução em seus próprios produtos. Pense: por que uma empresa permitiria que outro produto resolvesse uma dor real e criasse dependência externa? Como sei que isso é verdade? Veja habilidades, memory harness, subagents... todos começaram como soluções para problemas reais e foram comprovados como verdadeiramente úteis na prática.

Então, se algo realmente for inovador e conseguir expandir os casos de uso de agentes de forma significativa, acabará sendo incorporado ao produto principal da empresa base. Acredite em mim, a empresa base está avançando rapidamente. Então, relaxe, você não precisa instalar nada nem depender de nenhuma dependência externa para fazer o melhor trabalho.

Eu prevejo que os comentários logo aparecerão com: “SysLS, usei o harness tal, ótimo! Reconstruí o Google em um dia!” — e eu digo: Parabéns! Mas você não é o público-alvo; você representa um grupo extremamente, extremamente minoritário da comunidade que realmente entendeu a engenharia de agentes.

Sério. O contexto é tudo. Outro problema com o uso de milhares de plugins e dependências externas é que você sofre muito com o "inchaço de contexto" — ou seja, seu agente é inundado com demasiadas informações.

Vamos fazer um jogo de adivinhação de palavras com Python? Fácil. Espere, o que é essa observação sobre “gerenciamento de memória” de 26 sessões atrás? Ah, o usuário teve uma tela travada há 71 sessões porque geramos muitos subprocessos. Sempre escreva observações? Certo, tudo bem... O que isso tem a ver com o jogo de adivinhação?

Você entende. Você só quer fornecer ao agente exatamente as informações necessárias para concluir a tarefa, nem mais nem menos! Quanto melhor você controlar isso, melhor o desempenho do agente. Assim que você começar a introduzir sistemas de memória estranhos, plugins ou muitas habilidades com nomes e chamadas confusos, você estará dando ao agente um manual para fazer uma bomba e uma receita de bolo, quando só quer que ele escreva um poema sobre uma floresta de sequoias.

Então, eu novamente prego — remova todas as dependências e, em seguida...

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

Remember that context is everything?

Lembre-se de que você quer fornecer ao agente exatamente as informações necessárias para concluir a tarefa, nem mais nem menos?

A primeira maneira de fazer isso é separar a pesquisa da implementação. Você precisa ser extremamente preciso sobre o que está pedindo ao agente para fazer.

Quais são as consequências de ser impreciso? “Faça um sistema de autenticação.” O agente precisa pesquisar: o que é um sistema de autenticação? Quais são as opções disponíveis? Quais são as vantagens e desvantagens de cada uma? Agora, ele precisa buscar na internet uma série de informações que na verdade não precisa, enchendo o contexto com detalhes de implementação possíveis. Quando for realmente implementar, ele terá mais probabilidade de se confundir ou gerar ilusões desnecessárias ou irrelevantes sobre a solução escolhida.

Por outro lado, se você disser "implementar autenticação JWT com hash de senha bcrypt-12, rotação de tokens de atualização, expiração de 7 dias...", não será necessário pesquisar outras alternativas, pois ficará claro o que você deseja, permitindo que os detalhes da implementação preencham o contexto.

Claro, você nem sempre saberá os detalhes da implementação. Muitas vezes, você não sabe o que está correto, e às vezes até deseja delegar a decisão sobre os detalhes da implementação ao agente. O que fazer nesse caso? É simples — crie uma tarefa de pesquisa para explorar várias possibilidades de implementação, decida você mesmo ou deixe o agente escolher qual implementação usar, e depois peça a outro agente, com um novo contexto, para realizar a implementação.

Assim que você começar a pensar assim, perceberá os pontos no fluxo de trabalho onde o contexto do agente é poluído desnecessariamente; então, você poderá estabelecer barreiras de isolamento no fluxo de trabalho do agente, abstraindo as informações desnecessárias e mantendo apenas o contexto específico que permite que ele se destaque na tarefa. Lembre-se: você tem um membro da equipe muito talentoso e inteligente, que conhece todos os tipos de bolas do universo — mas, a menos que você lhe diga que quer projetar um espaço para as pessoas dançarem e se divertirem, ele continuará falando sobre as vantagens de objetos esféricos.

Limitações de design de tendência de agradar

Ninguém quer usar um produto que constantemente o critique, diga que você está errado ou ignore completamente suas instruções. Por isso, esses agentes se esforçarão para concordar com você e fazer o que você deseja.

Se você pedir para ele adicionar "feliz" após cada três palavras, ele tentará seguir — a maioria das pessoas entende isso. Sua obediência é exatamente o que o torna um produto tão útil. Mas há uma característica muito interessante: isso significa que, se você disser "me ajude a encontrar um bug no repositório de código", ele encontrará um bug — mesmo que precise "criar" um. Por quê? Porque ele quer muito, muito obedecer aos seus comandos!

A maioria das pessoas logo se queixa de que os LLMs criam ilusões e inventam coisas que não existem, sem perceber que o problema está neles mesmos. Você pede algo a eles, e eles entregam—mesmo que precise distorcer um pouco os fatos!

E agora o que fazer? Descobri que "dicas neutras" são muito eficazes, ou seja, não inclinar o agente para um resultado específico. Por exemplo, em vez de dizer "ajude-me a encontrar um bug no banco de dados", digo "escaneie todo o banco de dados, tente seguir a lógica de cada componente e relate todos os achados."

Essas dicas neutras às vezes revelam bugs, às vezes apenas descrevem objetivamente como o código funciona. Mas não tendem o agente para a premissa de que "há bugs".

Outra maneira de lidar com a tendência de agradar é transformá-la em uma vantagem. Sei que o agente está se esforçando para agradar-me e seguir minhas instruções, e posso inclinar-me para um lado ou para o outro.

Então, pedi a um agente de detecção de bugs para identificar todos os bugs no banco de dados, dizendo-lhe que bugs de baixo impacto valem +1 ponto, bugs com certo impacto valem +5 pontos e bugs graves valem +10 pontos. Sei que esse agente será muito entusiasmado em identificar todos os tipos de bugs (incluindo aqueles que não são realmente bugs) e me relatará uma pontuação como 104. Vejo isso como um superconjunto de todos os bugs possíveis.

Em seguida, eu faço com que um agente adversário refute, informando-lhe que, ao refutar com sucesso um bug, ele ganha o valor desse bug, mas se refutar incorretamente, perde o dobro do valor desse bug. Esse agente esforça-se para refutar o máximo possível de bugs, mas, devido ao mecanismo de penalidade, mantém-se cauteloso. Ele ainda assim ativamente "refuta" bugs (incluindo bugs reais). Vejo isso como um subconjunto de todos os bugs reais.

Por fim, eu usei um árbitro para sintetizar as entradas de ambos e atribuir pontuações. Eu informei ao árbitro que tinha a resposta correta real: acertar ganhava +1 ponto, errar ganhava -1 ponto. Em seguida, ele avaliou o agente de busca de bugs e o agente adversário em cada "bug" separadamente. O que o árbitro declarava como verdade, eu verificava. Na maioria das vezes, esse método apresentou uma fidelidade surpreendentemente alta; ocasionalmente ainda ocorrem erros, mas já se trata de uma operação quase impecável.

Talvez você descubra que apenas procurar por agents de bug seja suficiente, mas esse método funcionou muito bem para mim, pois aproveita a característica inerente de cada agent, programada para querer agradar.

Essa questão parece complicada, como se exigisse que você estudasse a fundo e acompanhasse constantemente as últimas tendências em IA, mas na verdade é simples... Se a OpenAI e a Claude já a implementaram ou adquiriram a empresa que a implementou, provavelmente é útil.

Você notou que "habilidades (skills)" já estão em toda parte e fazem parte da documentação oficial do Claude e do Codex? Você notou que a OpenAI adquiriu a OpenClaw? Você notou que o Claude imediatamente adicionou funcionalidades de memória, voz e trabalho remoto?

Como está o planejamento? Lembra-se de quando muitas pessoas descobriram que planejar antes de implementar é realmente útil, e isso se tornou uma função principal?

Sim, esses são úteis!

Você se lembra dos intermináveis stop-hooks, que eram extremamente úteis porque os agentes tinham grande relutância em realizar tarefas de longa duração... e então, com o lançamento do Codex 5.2, essa necessidade desapareceu da noite para o dia?

Isso é tudo o que você precisa saber... Se algo for realmente importante e útil, Claude e Codex já o implementarão por si mesmos! Então você não precisa se preocupar muito em usar "coisas novas" ou se familiarizar com "coisas novas", nem mesmo em "ficar atualizado".

Ajude-me. Atualize ocasionalmente a sua ferramenta CLI escolhida e leia quais novas funcionalidades foram adicionadas. Isso já é suficiente.

Algumas pessoas que usam proxies percebem uma grande armadilha: às vezes eles parecem ser as criaturas mais inteligentes da Terra, e outras vezes você não consegue acreditar que foi enganado por eles.

Is this smart? This is fucking stupid!

A principal 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 "ligar os pontos", "preencher lacunas" ou fazer suposições. Sempre que fazem isso, é imediatamente perceptível, e a situação fica claramente pior.

Uma das regras mais importantes no CLAUDE.md é a regra sobre como obter o contexto, instruindo o agente a ler primeiro essa regra sempre que ler o CLAUDE.md (ou seja, após cada compressão). Como parte da regra para obter contexto, algumas instruções simples podem ter um grande impacto: reler o plano da tarefa e reler os arquivos relacionados à tarefa antes de prosseguir.

Nós, humanos, temos uma sensação bastante clara do que significa "concluir" uma tarefa. Para agentes, o maior problema da inteligência atual é que eles sabem como começar uma tarefa, mas não sabem como terminá-la.

Isso frequentemente leva a resultados muito frustrantes: o agente acaba implementando um monte de stubs e para por aí.

O teste é um excelente marco para o agente, pois o teste é determinístico e você pode definir expectativas muito claras. A menos que esses X testes passem, sua tarefa não estará concluída; e você não pode modificar os testes.

Então você apenas revisa os testes; assim que todos passarem, você pode ficar tranquilo. Você também pode automatizar isso, mas o ponto principal é — lembre-se de que "o fim da tarefa" é natural para humanos, mas não para agentes.

Você sabe se algo mais recente se tornou um ponto final viável? Capture de tela + verificação. Você pode fazer com que o agente realize algo até que todos os testes passem, depois pedir que ele faça uma captura de tela e verifique o “design ou comportamento” na captura de tela.

Isso permite que o agente itere e avance em direção ao design que você deseja, sem se preocupar em parar após a primeira tentativa!

A extensão natural disso é criar um "contrato" com o agente e incorporá-lo às regras. Por exemplo, este `{TASK}CONTRACT.md` define o que precisa ser feito antes que você possa encerrar a sessão. Em `{TASK}CONTRACT.md`, você especificará os testes, capturas de tela e outras verificações necessárias antes de autorizar o término da tarefa!

Uma pergunta que recebo frequentemente é como as pessoas podem fazer com que o agente funcione 24 horas por dia, garantindo ao mesmo tempo que ele não se desvie.

Existe um método muito simples: crie um stop-hook que impeça o agente de encerrar a sessão até que todas as seções de `{TASK}_CONTRACT.md` estejam concluídas.

Se você tiver 100 contratos com especificações claras que contêm o conteúdo que deseja construir, o stop-hook impedirá que o agente seja encerrado até que todos os 100 contratos sejam concluídos, incluindo todos os testes e validações necessários!

Sugestão profissional: Descobri que sessões de 24 horas em execução prolongada não são ideais para "fazer tarefas". Parte da razão é que esse método estruturalmente força o inchaço de contexto, pois o contexto de contratos não relacionados entra na mesma sessão!

Então, eu não recomendo fazer isso.

Há uma maneira melhor de automatizar o agente — abra uma nova sessão para cada contrato. Crie o contrato sempre que precisar fazer algo.

Crie uma camada de orquestração para criar um novo contrato quando algo precisar ser feito e crie uma nova sessão para processar esse contrato.

Isso vai transformar completamente sua experiência de agente.

Você contratou um assistente administrativo e espera que ele saiba sua agenda desde o primeiro dia? Ou como você toma seu café? Você janta às 18h e não às 20h? Claramente não. Você desenvolve preferências aos poucos ao longo do tempo.

O mesmo vale para o agente. Comece com a configuração mais simples, esqueça estruturas ou harnesses complexos e dê uma chance ao CLI básico.

Em seguida, adicione gradualmente suas preferências. Como fazer?

Regras

Se você não quiser que o agente faça algo, escreva como uma regra. Em seguida, informe ao agente essa regra no arquivo CLAUDE.md. Por exemplo: “Antes de escrever código, leia `coding-rules.md`.” As regras podem ser aninhadas e podem ser condicionais! Se você estiver escrevendo código, leia `coding-rules.md`; se estiver escrevendo testes, leia `coding-test-rules.md`. Se seus testes estiverem falhando, leia `coding-test-failing-rules.md`. Você pode criar regras com ramificações lógicas arbitrárias para o agente seguir; Claude (e Codex) ficarão felizes em seguir, desde que haja instruções claras no arquivo CLAUDE.md.

Na verdade, esta é a primeira sugestão prática que dou: trate seu CLAUDE.md como um diretório lógico e aninhado, indicando onde encontrar o contexto em cenários específicos e com resultados específicos. Ele deve ser o mais conciso possível, contendo apenas lógica IF-ELSE sobre “em que situação procurar o contexto onde”.

Se você ver o agente fazendo algo que você não concorda, adicione isso como uma regra e diga ao agente para ler essa regra antes de fazer aquilo novamente; ele certamente não fará mais assim.

Habilidade

Habilidades (Skills) funcionam de forma semelhante às regras, mas, em vez de serem preferências de codificação, são mais adequadas para codificar "etapas de operação". Se você tem uma maneira específica de desejar que algo seja feito, deseja incorporá-la às habilidades.

Na verdade, as pessoas frequentemente se queixam de não saber como o agente resolverá um problema, o que gera insegurança. Se você deseja tornar isso mais previsível, faça com que o agente primeiro pesquise como resolveria o problema e depois documente a solução em um arquivo de habilidade. Assim, você poderá antecipar como o agente lidará com o problema e corrigir ou aprimorar antes que ele o enfrente realmente.

Como você faz com que o agente saiba que essa habilidade existe? Exatamente! Você escreve no CLAUDE.md que, quando enfrentar esse cenário e precisar lidar com isso, leia o `SKILL.md`.

Regras e habilidades de processamento

Você certamente quer continuar adicionando regras e habilidades ao agente. É assim que você dá a ele uma personalidade e memória das suas preferências. Quase tudo o mais é redundante.

Assim que você começar a fazer isso, seu agente parecerá mágico. Ele fará as coisas "da maneira que você deseja". Então, finalmente, você se sentirá como se tivesse "compreendido" a engenharia de agentes.

Então...

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

O que aconteceu?!

É muito simples. À medida que você adiciona mais regras e habilidades, elas começam a se contradizer, ou o agente sofre um grave inchamento de contexto. Se você precisar que o agente leia 14 arquivos Markdown antes de começar a programar, ele terá o mesmo problema de uma grande quantidade de informações inúteis.

O que fazer?

Limpeza. Envie seu agente para "fazer um spa", integre regras e habilidades, eliminando contradições ao especificar suas preferências atualizadas.

Then it will feel like magic again.

É isso. Essa é realmente a chave. Mantenha tudo simples, use regras e habilidades, trate o CLAUDE.md como um índice e preste atenção fiel ao seu contexto e limitações de design.

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

Então fique atento... e aproveite bem!

É um prazer brincar com brinquedos do futuro (enquanto claramente os usa para coisas sérias)!