Antes de uma tarefa longa no Claude Code: quando usar compact e como controlar subagentes e consumo

Antes de pedir ao Claude Code que passe um bom tempo lendo código, fazendo alterações e executando testes, não se apresse para limpar o contexto. Também não é necessário guardar todas as discussões antigas só para “aproveitar o 1M inteiro”.

Vale esclarecer primeiro outras questões: de quais detalhes originais a próxima etapa ainda vai precisar? O trabalho que você pretende delegar pode ser concluído de forma independente? Quando a tarefa terminar, como saber se a mudança ajudou de verdade, em vez de apenas produzir um número menor no indicador de consumo?

Em 19 de setembro, ZryMiller contou como mudou sua forma de trabalhar. Antes, ele compactava o contexto com frequência; depois, voltou à janela de 1M que chamou de padrão. Na percepção dele, a experiência melhorou bastante, e ele disse que estava se preparando para lançar seu primeiro aplicativo. Mas a publicação não trouxe tarefas comparáveis, dados de consumo antes e depois nem o resultado final do lançamento. É um relato pessoal útil, não uma demonstração de que “deixar de compactar melhora todas as tarefas longas”.

Em vez de escolher entre “compactar sempre” e “nunca compactar”, tome a decisão ao encerrar uma etapa concreta do trabalho.

Primeiro, confirme o que você está usando

Execute claude --version no terminal e anote a versão do cliente. Dentro da sessão, use /status para conferir a conta e o modelo atual, /model para ver os modelos disponíveis e as configurações relacionadas, e /context para verificar a ocupação do contexto. Para consultar o consumo, execute /usage. Esses comandos mostram informações diferentes; não são medidas intercambiáveis. Referência oficial de comandos · Documentação sobre consumo

O nome oficial do modelo desta discussão é Claude Fable 5.1. Seu ID na Claude API é claude-fable-5-1, e a especificação oficial informa uma janela de contexto de 1M de tokens. Modelo, versão do Claude Code e configuração de effort são coisas distintas. Não registre tudo apenas como “usei Fable” ou “usei Ultra”. Especificação oficial do modelo

O suporte a 1M em um modelo não significa que todas as contas, modelos e formas de acesso tenham automaticamente as mesmas condições de uso. Por exemplo, a documentação oficial distingue o acesso a 1M do Opus incluído nos planos Max, Team e Enterprise do acesso no Pro, que exige usage credits. A janela de 1M do Sonnet 4.6 também exige usage credits nos planos de assinatura. Não aplique essas regras diretamente a outros modelos. Também é preciso conferir a configuração do cliente, o mapeamento de modelos e o suporte do gateway: acrescentar [1m] no seletor não amplia, por si só, a capacidade do modelo no servidor. Condições para 1M e configuração de modelos

Separe também três números fáceis de confundir. A ocupação do contexto indica quanto conteúdo precisa caber na requisição atual. O consumo acumulado de tokens registra o volume de entrada, saída e conteúdo em cache processado pelas requisições. A cota da assinatura é o limite da conta dentro da janela de uso correspondente. Cinco horas ou uma semana são janelas de cota, não uma garantia de que a tarefa poderá rodar sem parar por cinco horas ou uma semana. O conteúdo atendido pelo cache continua ocupando contexto, embora a cobrança da API possa aplicar tarifas específicas de cache. Por isso, “30% do contexto ocupado” não pode ser convertido em “30% da cota de cinco horas consumida”, e 1M não é uma cota de tokens que você pode processar repetidamente de graça. Contexto e cache · Estrutura de preços da API

Antes de compactar, veja do que a próxima etapa ainda depende

Imagine que você está investigando um erro que envolve o frontend, uma API e o banco de dados. Os trechos de código que acabou de ler, uma requisição que falhou e um caso de borda ainda não resultaram em conclusões verificáveis. Compactar só porque “a conversa já está longa” pode descartar justamente os detalhes que você precisa comparar em seguida.

Por outro lado, se a causa já está clara, os arquivos relevantes e a localização das evidências estão registrados, e só falta uma pequena alteração de implementação conforme um plano aprovado, boa parte das buscas anteriores talvez não precise continuar na janela atual.

O momento adequado para compactar não é um percentual universal: é o encerramento de uma etapa a partir da qual seja possível continuar com registros confiáveis. Essa é uma recomendação de trabalho, não um limiar fixo do modelo.

Primeiro, peça ao Claude para escrever o estado necessário no registro de tarefa que você indicar: fatos confirmados e localização das evidências, arquivos realmente alterados, verificações executadas e seus resultados reais, questões pendentes e próximo passo. Não é necessário copiar toda a conversa, nem transformar hipóteses não verificadas em conclusões.

Depois, use o comando nativo /compact, especificando o que deve ser preservado: Como a compactação funciona

/compact Preserve o objetivo atual, as conclusões confirmadas e a localização das evidências, os arquivos alterados, as verificações executadas e seus resultados reais, as questões pendentes e o próximo passo. Remova buscas repetidas e discussões sobre possibilidades já descartadas.

Esse texto define o que você espera do resumo; não garante que nenhuma informação será perdida. Antes de continuar as alterações, peça ao Claude para explicar o próximo passo com base no contexto compactado e confira as restrições principais nos arquivos reais e no registro da tarefa. Se algum caso de borda tiver sumido, recupere-o antes que a implementação se desvie e precise ser refeita.

Se o próximo trabalho não tem relação com o anterior, normalmente é mais direto salvar os resultados e as informações necessárias para retomá-lo e iniciar uma nova sessão com /clear. Use /resume se precisar voltar à conversa original. Limpar a sessão não devolve o consumo já ocorrido nem reinicia a cota da assinatura. Comandos de sessão · O que é reiniciado na exibição de consumo

O Claude Code já tem compactação automática, portanto não é necessário instalar um plugin para adotar essa abordagem. As versões v2.1.221 e posteriores também oferecem /autocompact: sem argumentos, ele mostra a janela atual de compactação automática; /autocompact auto restaura a configuração de janela ajustada para o modelo. Este último salva uma configuração, em vez de apenas expressar uma preferência ao modelo. A janela máxima de contexto do modelo e a janela de compactação automática não são a mesma coisa. Comando de compactação automática

HKTECH_AI estimou que uma única compactação poderia consumir cerca de 15% da cota de cinco horas. A publicação não apresentou uma fatura nem um método de cálculo, então esse percentual não deve virar regra de uso. O que importa comparar é se a compactação reduziu o conteúdo carregado repetidamente nas requisições seguintes e se, em contrapartida, exigiu releitura, novas explicações ou correções.

Subagentes podem dividir o trabalho, mas “um por vez” depende de como isso é aplicado

SHCH compartilhou uma divisão de funções: Fable cuida do planejamento e das decisões, um Scout com Sonnet faz buscas, e um Builder com Opus executa tarefas bem definidas. Ele recomendou expressamente chamar apenas um subagente por vez.

A captura de tela do Builder publicada por ele enfatiza seguir o plano existente, parar e avisar se houver um problema no plano, não iniciar outros subagentes e informar os resultados das verificações. O valor dessas instruções está em delimitar responsabilidades. Mas “não inicie outros subagentes” em uma imagem ainda é uma restrição no prompt, não um limite imposto pelo software. O autor também mencionou várias sessões principais em execução e não publicou dados verificáveis de consumo antes e depois. Portanto, essa configuração não equivale a “apenas um agente em toda a conta”, muito menos permite prometer um percentual fixo de economia.

Um subagente comum começa com um contexto separado, recebendo a tarefa delegada e a configuração correspondente. Ele não ganha automaticamente todo o histórico da sessão principal; um subagente fork herda a conversa existente. Colocar uma investigação cheia de informações intermediárias em um subagente pode reduzir o conteúdo de processo mantido diretamente na sessão principal, mas as requisições do subagente também processam tokens, e o resultado devolvido entra na sessão principal. Limites de contexto dos subagentes

Por isso, pergunte primeiro “Vale a pena delegar esta tarefa?” e só depois “Quantos devem rodar ao mesmo tempo?”. Uma busca simples não precisa de uma cadeia completa de planejador, pesquisador e executor. Duas tarefas que editarão repetidamente o mesmo arquivo também podem não ser boas candidatas à execução simultânea. Investigações realmente independentes, com entregáveis claros, são mais adequadas a uma comparação em paralelo.

Você pode tornar as instruções de trabalho mais concretas, por exemplo:

Objetivo: Concluir as alterações acordadas e passar nas verificações diretamente relacionadas.
Escopo permitido: A implementação e os testes correspondentes a esta solicitação.
Execução: Faça buscas simples diretamente. Quando a delegação for necessária, forneça apenas o contexto e os requisitos de entrega de que a subtarefa precisa, e atribua um subagente por vez. Não consulte repetidamente o mesmo status durante a espera.
Critérios de conclusão: Entregue conforme os critérios de aceite e pare quando as verificações pertinentes passarem. Se houver um bloqueio, informe o que foi concluído e o motivo; não reinicie a mesma tarefa.

Essas continuam sendo instruções de comportamento. Para restringir de fato a criação de subagentes nativos, use os controles do cliente. O Claude Code v2.1.217 e posteriores permitem limitar a concorrência e a profundidade de delegação. O exemplo de inicialização abaixo, em Bash/Zsh para macOS e Linux, é um ponto de partida conservador para investigar paralelismo desnecessário: Referência de variáveis de ambiente

CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=1 \
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 \
claude

A primeira variável define uma verificação de concorrência por sessão ao criar novos subagentes pela ferramenta Agent. A segunda limita os subagentes a um nível, impedindo novas delegações aninhadas. Elas não são prompts e não alteram retroativamente outras sessões que já estejam em execução. Referência de variáveis de ambiente

Isso, porém, não é uma trava global que garanta “no máximo um agente, sempre e em qualquer lugar”. A documentação oficial lista exceções: sessões ultracode não aplicam esse limite de concorrência; chamadas manuais de /subtask e a retomada de subagentes já concluídos não são bloqueadas pela mesma verificação de nova criação; fluxos de trabalho e agent teams têm limites próprios. Uma única configuração também não controla em conjunto várias sessões principais e processos iniciados externamente. Limites de concorrência e exceções

Se o seu próprio agendador precisa de um limite global real, uma fila ou trava de concorrência deve coordenar inícios, retomadas e novas tentativas. Não basta escrever “um por vez” no prompt. Isso faz parte da implementação do seu agendador, não de outra configuração não documentada do Claude Code.

Esperar um resultado não significa pedir ao modelo que consulte o progresso o tempo todo

LeeLeepenkman não reclamava apenas de “usar subagentes”. Ele descreveu o Fable 5.1 enviando um prompt grande ao muse e depois consultando o status aproximadamente a cada cinco segundos, fazendo o contexto crescer rapidamente. A publicação original não explicou a implementação do muse, não forneceu registros de requisições e não mostrou o resultado após resolver o problema. Portanto, cinco segundos não pode ser apresentado como o intervalo fixo de polling do Claude Code.

Os subagentes nativos em segundo plano atualmente oferecem notificações de conclusão, e os resultados voltam à sessão principal em turnos posteriores. Você pode consultar o trabalho em execução com /tasks. Isso é diferente de fazer o modelo emitir repetidamente novas requisições perguntando “Já terminou?”. Subagentes em segundo plano e notificações de resultados

Durante a investigação, expanda os registros de ferramentas da sessão e acompanhe a mesma tarefa: as verificações repetidas trazem alguma informação nova? Um trabalho já concluído foi iniciado novamente? A consulta de status realmente gerou outra chamada ao modelo? Ctrl+O abre uma visualização mais detalhada da conversa, mas a quantidade de atualizações da interface não pode ser tratada diretamente como a quantidade de requisições ao modelo. Para obter consumo por requisição, confira também os registros do provedor que você está usando. Interação e visualização da sessão

Com notificações nativas, normalmente não é necessário adicionar um loop de consultas frequentes executado pelo modelo. Se uma ferramenta externa só permite polling, deixe o programa verificar mudanças de estado em intervalos razoáveis, definir um tempo limite e encaminhar informações ao modelo apenas quando houver um novo resultado ou uma exceção. A proposta é reduzir chamadas ao modelo que não acrescentam informações, não impedir o acompanhamento necessário do progresso.

Quando a cota for restabelecida, confira primeiro o que falta fazer

intwerpret relatou uma situação mais drástica. Após atingir um limite de uso, escolheu esperar e continuar automaticamente. Depois, afirmou que surgiram 39 agentes, que esgotaram a cota novamente, e acabou voltando ao Codex. Os materiais não incluem a versão do cliente, o conteúdo da tarefa, a configuração completa nem a origem do mecanismo de retomada. Também não se sabe se a tarefa acabou sendo concluída.

Esse relato é um motivo para revisar o fluxo de retomada, não uma prova de que “a retomada automática do Claude Code sempre inicia 39 agentes”. O uso da palavra “Ultra” pelo autor tampouco basta para afirmar que ele estava no modo ultracode mencionado antes.

Por outro lado, já não é correto atribuir toda continuação automática a scripts de terceiros. A documentação oficial do modo interativo descreve um recurso nativo para continuar depois que o limite de uso é restabelecido: desde a v2.1.234, sessões interativas de assinatura elegíveis podem esperar a renovação da cota e continuar trabalhando. Isso não equivale ao comportamento com chave de API, com -p ou em todos os modos de segundo plano. Retomar também não é simplesmente reenviar a última tarefa original do usuário. Espera nativa e continuação automática

Se você não pretende deixar a tarefa retomar sem supervisão, desative Continue automatically at usage limit (continuar automaticamente quando o limite de uso for restabelecido) em /config. Nas versões que aceitam essa configuração, também é possível executar:

/config autoContinueAtUsageLimit=false

Se a sessão já estiver esperando, cancele também aquela espera específica: pressione Esc com a caixa de entrada vazia ou escolha Don’t continue automatically (não continuar automaticamente) em /rate-limit-options. Alterar a configuração padrão e cancelar uma espera já selecionada são ações diferentes. Como cancelar e configurar a continuação automática

Em seguida, confira /tasks e o estado real dos arquivos. Quais tarefas ainda estão rodando, quais terminaram e quais precisam apenas de mais uma verificação? Reaproveite os resultados existentes e defina o que deve continuar nas tarefas inacabadas, em vez de reenviar toda a solicitação para que o trabalho seja dividido novamente.

Antes de fazer commits, implantações, enviar mensagens ou executar outras ações com efeitos externos, confira especialmente se a tentativa anterior já teve sucesso. A renovação da cota só responde “Podemos continuar fazendo requisições?”. Ela não garante que as próximas ações não repetirão algo já executado.

Avalie a entrega antes de decidir que o consumo melhorou

chasemdev explicou que não fazia o Fable escrever todo o código sozinho, mas o usava para coordenar subagentes Opus. Mesmo assim, esperava atingir o limite semanal em breve. Esse “em breve” era uma previsão do autor naquele momento, não um resultado final de consumo verificado. Mas lembra um ponto fácil de esquecer no registro: inclua os modelos e o trabalho dos subagentes, não apenas o modelo principal.

Atualmente, a seção Session de /usage mostra o consumo de tokens da sessão e uma estimativa de custo calculada localmente. Usuários de assinatura também veem o uso do plano na mesma interface. O valor em dólares de Session não é uma fatura de assinatura e não corresponde necessariamente à cobrança final do provedor de API. Quem paga por uso deve considerar a fatura do provedor real. O que /usage significa atualmente

A atribuição local do consumo da assinatura também é apenas uma pista. A divisão entre subagentes, plugins, skills e outros componentes vem do histórico recente desta máquina. Ela não representa todo o consumo de outros dispositivos ou da web, nem prova uma relação de causa e efeito sobre “quanto desperdício um plugin gerou”. Se aparecer Showing last-known usage, anote o horário dos dados exibidos e atualize antes de comparar. Escopo da atribuição e leituras em cache

Não é preciso criar um sistema complexo de avaliação. Escolha uma tarefa com escopo claro que possa ser reproduzida com segurança, escreva os critérios de aceite e registre as informações abaixo no início e no fim:

O que registrar	Quais perguntas responder
Tarefa, versão inicial do código, modelo, effort e versão do cliente	Você está comparando o mesmo tipo de trabalho e as mesmas configurações antes e depois?
/context e o processo de compactação	Alguma restrição foi perdida? Foi preciso reler ou explicar novamente?
Subagentes e comportamento durante a espera	Quais tarefas foram criadas ou retomadas, qual foi o pico de execução simultânea e houve consultas repetidas sem informação nova?
Leituras de consumo, horários e momentos de renovação da cota	A cota foi renovada durante a comparação, houve atividade de outras sessões e a contabilização da API incluiu todos os modelos envolvidos?
Entregas reais e resultados das verificações	Os requisitos foram atendidos, as verificações relevantes passaram e quanto retrabalho humano ainda falta?

Mude apenas uma prática, como esperar a investigação terminar para compactar ou limitar a concorrência na criação de novos subagentes. Mantenha os critérios de aceite originais; não diminua a tarefa discretamente para conseguir um consumo menor. Registre também diferenças no estado do cache. Se as duas execuções usaram modelos, versões de código ou tamanhos de tarefa diferentes, não atribua toda a diferença à compactação.

Gastar menos tokens deixando requisitos de fora ou a verificação para uma pessoa não é melhoria. Da mesma forma, se manter mais contexto permitiu concluir a tarefa de uma vez, sem repetir a investigação, uma janela mais ocupada não basta para classificar isso como desperdício.

Mantenha separados os registros do acesso independente à API e da assinatura. Mudar a origem da cobrança não reinicia a cota da assinatura original nem altera automaticamente a forma como o cliente delega, espera e compacta. Para decidir se a mudança vale a pena, compare o consumo total e o retrabalho para concluir a mesma tarefa, não apenas o preço unitário de um modelo. Diferenças entre formas de cobrança · Estrutura de cobrança de tokens na API

Antes de deixar um plugin decidir quando compactar, veja o que ele envia para fora

Kun Chen partiu de uma pergunta prática: “when should i /compact my session” — quando devo compactar a sessão atual? Seu compact-adviser usa o Jev da TypeSafe para avaliar se o trabalho chegou a um ponto adequado para compactação. Ele oferece um modo de sugestões e um modo automático que precisa ser ativado explicitamente. Descrição do projeto

A verificação deste artigo foi fixada no commit d1655faa16a22b68bff60c3d7deb0123e1e52a53, cujo manifesto do plugin para Claude Code indica a versão 0.1.4. O projeto exige Node.js 22 ou posterior e Claude Code 2.1.274 ou posterior, e declara ter sido verificado na 2.1.275. A integração com Claude Code depende de hooks de função experimentais e requer CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1. Essas são condições de compatibilidade declaradas pelo projeto, não resultados de uma instalação testada para este artigo. Manifesto da versão fixada · Requisitos de versão e integração

O mais importante é que o modo hint apenas não executa a compactação automaticamente. Ele não significa que a avaliação seja local nem que o contexto permaneça na máquina. A documentação de segurança informa que, após a instalação, se houver uma chave disponível no ambiente de inicialização, nas configurações salvas ou em um arquivo .env no diretório de trabalho, e as condições de chamada forem atendidas, trechos selecionados da sessão serão enviados à TypeSafe. Isso inclui restrições do usuário, respostas visíveis recentes e resultados de ferramentas, um resumo existente e nomes dos artefatos gerados. Não há outro controle separado para confirmar esse compartilhamento. Os trechos ainda podem conter código ou informações do negócio; a tentativa de remover dados sensíveis não garante a ausência deles. Limites do envio de contexto

Quem já instalou o plugin pode desativá-lo com /compact-adviser off ou iniciar assim:

COMPACT_ADVISER_DISABLE=1 claude

Segundo o projeto, isso interrompe as requisições, as sugestões e a compactação automática do plugin. O que é desativado é o plugin, não a compactação automática do próprio Claude Code. Se não for permitido enviar conteúdo de trabalho adicionalmente à TypeSafe, desative ou desinstale o plugin, em vez de apenas trocar auto por hint. Como desativar

A avaliação com 40 sessões mencionada pelo autor é uma avaliação do próprio projeto, e o conjunto de dados não é público. Ela não garante que os detalhes das suas tarefas serão preservados. Mesmo que o plugin considere o momento “adequado para compactar”, o que importa no fim é se o trabalho consegue continuar corretamente depois. Limites da avaliação

Tudo isso já pode ser feito sem um plugin: salvar o estado ao encerrar etapas e manter os detalhes realmente necessários para o próximo passo; atribuir trabalho claro e independente aos subagentes; evitar reinícios duplicados durante a espera e a retomada; e avaliar o efeito com base tanto na entrega quanto nos registros de consumo.

Gerenciar uma tarefa longa não tem como objetivo preencher a janela nem fazer cada requisição parecer a mais barata possível. O objetivo é reduzir o trabalho que não faz a tarefa avançar e concluir com segurança o que já foi iniciado.