Source: https://aiprimetech.io/pt/blog/claude-code-cli-guide/ Jun 19, 2026 · 6 min · Ferramentas # Claude Code e a nova onda de ferramentas de programação com IA no terminal A Por [AI Prime Tech](https://aiprimetech.io/pt/) · Com auxílio de IA Às 2:13 da manhã, observei um agente de programação no terminal gastar 1.8 milhões de tokens de entrada tentando “apenas corrigir o teste que estava falhando”. O bug real era uma incompatibilidade de esquema de três linhas. O agente não era burro; suas restrições eram mal definidas. Ele continuava relendo o repositório, executando novamente comandos de teste abrangentes, colando rastreamentos de pilha gigantescos de volta no modelo e pedindo reescritas de arquivos inteiros quando um diff pontual teria resolvido. Esse incidente mudou a forma como executo agentes de programação na CLI. Ferramentas como Claude Code, Aider, Cline e OpenCode não são apenas chatbots com um botão git diff . São ciclos de controle orientados por API que envolvem seu shell, editor, sistema de arquivos e, às vezes, navegador. Elas podem ser extremamente produtivas, especialmente com modelos poderosos como Claude Opus 4.8, Sonnet 4.6, GPT-5.5, Gemini 3 e sistemas de contexto longo como Fable 5. Também podem consumir tokens silenciosamente em um ritmo que surpreende equipes acostumadas a chamadas de API de um único turno. Este artigo traz a versão prática: o que os agentes de programação no terminal realmente fazem, como usam APIs de modelos, por que os ciclos de agentes mudam a dinâmica de custos dos tokens e como os configuro para que uma sessão longa continue útil em vez de virar uma encenação cara. ## O que os agentes de programação na CLI realmente são Um agente de programação no terminal geralmente reúne cinco componentes: - Um ciclo de chat com um modelo de ponta ou aberto - Um indexador de repositório ou uma camada de descoberta de arquivos - Uma camada de execução de ferramentas para comandos de shell e edições de arquivos - Um mecanismo de aplicação de patches - Uma camada de persistência para o histórico de conversa e o estado da sessão A diferença fundamental em relação ao preenchimento automático é a autonomia de ação. O preenchimento automático prevê o código na posição do cursor. Um agente pode decidir inspecionar arquivos, executar testes, modificar código, inspecionar falhas e repetir o processo. Um ciclo típico é assim: ``` User task ↓ Agent builds prompt from instructions + repo context + prior messages ↓ Model proposes actions: read file, edit file, run command ↓ CLI executes allowed actions ↓ Results are added back into context ↓ Model plans next step ↓ Repeat until done or stopped ``` Esse ciclo é o motivo pelo qual essas ferramentas parecem poderosas. Também é o motivo pelo qual custo e latência se comportam de maneira diferente do uso normal de API do tipo “faça uma pergunta, receba uma resposta”. Na prática, a maioria das surpresas de custo vem do fluxo de retorno: saídas de comandos, conteúdos de arquivos, mensagens anteriores e diffs incluídos repetidamente nos turnos seguintes. ## Claude Code, Aider, Cline e OpenCode: diferentes formas do mesmo padrão As ferramentas têm estilos de interação diferentes, mas o padrão central de engenharia é semelhante. | Ferramenta | Interface principal | Ponto forte típico | Risco comum de custo | Claude Code | Agente nativo do terminal | Fluxo de trabalho integrado entre shell e repositório, ciclo robusto de planejamento e edição | Sessões autônomas longas que acumulam contexto | Aider | Programador em pares na CLI com integração ao Git | Edição focada em diffs, seleção explícita de arquivos | Adicionar arquivos demais ao contexto | Cline | Agente centrado no editor | Integração com VS Code, uso visível de ferramentas | Saídas volumosas do terminal ou navegador entrando no contexto | OpenCode | Fluxo de trabalho de agente no terminal ou editor | Flexibilidade de modelos e controle do fluxo de trabalho local | Provedores mal configurados ou varreduras abrangentes do repositório A distinção importante não é “qual deles é o mais inteligente”. É quanto contexto a ferramenta envia, como seleciona arquivos, como resume o histórico e quanto controle você tem sobre a execução no shell. O Aider, por exemplo, tende a funcionar bem quando você adiciona intencionalmente os arquivos relevantes. Claude Code tem mais autonomia de agente e pode parecer um engenheiro sênior navegando pelo repositório, mas essa autonomia significa que você deve definir permissões e escopo com cuidado. O Cline é conveniente dentro do editor, especialmente quando você quer acompanhar as ações, mas a conveniência do editor pode facilitar a aprovação de etapas caras demais. Fluxos de trabalho no estilo do OpenCode atraem equipes que querem flexibilidade de provedores: Claude para trabalhos difíceis de arquitetura, GPT para implementação, Gemini para inspeção de grandes volumes de contexto ou modelos abertos como Qwen, DeepSeek, Kimi, MiniMax e Llama para execuções mais baratas, locais ou em infraestrutura própria. ## Como esses agentes usam a API Uma única solicitação de “corrija este bug” pode se transformar em dezenas de chamadas de API. Um corpo de requisição simplificado para uma etapa do agente se parece com isto: ``` { "model": "claude-sonnet-4.6", "messages": [ { "role": "system", "content": "You are a coding agent. Follow repo instructions. Use tools safely." }, { "role": "user", "content": "Fix the failing invoice total test." }, { "role": "assistant", "content": "I will inspect the test and related invoice code." }, { "role": "tool", "name": "read_file", "content": "tests/test_invoice_totals.py contents..." } ], "tools": [ { "name": "read_file" }, { "name": "apply_patch" }, { "name": "run_shell" } ] } ``` As implementações reais variam, mas o padrão é consistente: - A CLI reúne o contexto. - O modelo decide a próxima operação. - A CLI executa a operação. - O resultado é enviado de volta ao modelo. - O modelo continua. Geralmente, há duas formas de disponibilizar ferramentas. ### Protocolos de ferramentas baseados em texto Alguns agentes pedem ao modelo que produza texto estruturado: ``` RUN: pytest tests/test_invoice_totals.py -q ``` A CLI interpreta esse texto e o executa. Isso é simples e portável, mas frágil. Se o modelo formatar o comando de maneira estranha, a infraestrutura de execução precisará de mecanismos de proteção. ### Chamada nativa de funções Outros agentes usam chamadas de ferramentas/funções da API do modelo. O modelo retorna uma chamada de ferramenta estruturada: ``` { "tool_name": "run_shell", "arguments": { "command": "pytest tests/test_invoice_totals.py -q", "timeout_seconds": 60 } } ``` Isso é mais fácil de validar. O agente pode rejeitar comandos que correspondam a padrões perigosos, exigir aprovação para acesso à rede ou restringir gravações ao espaço de trabalho. Em ambas as abordagens, a parte cara não é o comando de shell. É o prompt cada vez maior ao redor do comando de shell. ## Por que os ciclos de agentes mudam os custos de tokens Uma integração comum com API pode enviar 2,000 tokens de entrada e receber 500 tokens de saída. Uma sessão de programação com um agente pode fazer o seguinte: | Etapa | O que acontece | Padrão de tokens de entrada | Padrão de tokens de saída | 1 | O usuário pede uma correção | Pequeno | Plano | 2 | O agente lê arquivos | Médio | Solicitação de ferramenta | 3 | O agente edita o código | Médio a grande | Patch | 4 | O teste falha | Grande se os logs completos forem incluídos | Diagnóstico | 5 | O agente lê mais arquivos | Maior devido ao histórico | Solicitação de ferramenta | 6 | O agente tenta novamente | Ainda maior | Patch | 7 | A execução completa dos testes falha em outro ponto | Muito grande se colado sem tratamento | Resumo/triagem A pegadinha: os tokens de entrada costumam predominar. Cada ciclo pode reenviar instruções do sistema, histórico da conversa, arquivos selecionados, saídas de ferramentas e resumos. Mesmo com cache ou compressão de contexto, sessões autônomas longas podem sair caras, porque o modelo precisa de informações suficientes sobre o estado atual para evitar agir às cegas. Há quatro fatores comuns que multiplicam o consumo de tokens: - Contexto de arquivos completos: enviar arquivos de 900 linhas quando apenas duas funções importam. - Saída detalhada dos testes: incluir avisos de dependências, barras de progresso e falhas não relacionadas. - Varreduras repetidas do repositório: executar find, tree, ou rg de forma abrangente e reinserir a saída. - Histórico de conversa sem limites: preservar cada tentativa malsucedida em vez de resumir as decisões. O que realmente acontece em uma sessão desorganizada não é que “o agente pensa mais a fundo”. Muitas vezes, ele apenas vê mais contexto desatualizado. Mais tokens podem tornar o modelo mais lento e menos preciso se as informações relevantes estiverem soterradas. ## O modelo mental: orçamento por ciclo, não por prompt Quando estimo os gastos, penso em ciclos. Uma tarefa pequena e bem delimitada poderia ser: ``` 8 turns × 12k input tokens average = 96k input tokens 8 turns × 1.5k output tokens average = 12k output tokens ``` Uma tarefa que perde o rumo poderia ser: ``` 35 turns × 55k input tokens average = 1.9M input tokens 35 turns × 3k output tokens average = 105k output tokens ``` O mesmo prompt do usuário. Custos muito diferentes. Você não precisa de preços exatos para entender o problema. O custo das sessões com agentes cresce conforme: ``` total cost ≈ Σ(input_tokens_per_step × input_price) + Σ(output_tokens_per_step × output_price) + tool/runtime overhead ``` Os tokens de saída são visíveis porque você vê o agente digitar. Os tokens de entrada ficam ocultos porque são montados pela CLI. É nesse lado oculto que a disciplina orçamentária importa. ## Como escolher modelos para o trabalho de agentes Raramente uso um único modelo para tudo. Para agentes de terminal, a escolha do modelo deve corresponder à fase: | Fase | Melhor tipo de modelo | Por quê | Reconhecimento do repositório | Modelo com contexto longo ou modelo competente mais barato | Exige leitura abrangente, não edições perfeitas | Decisão de arquitetura | Modelo com forte capacidade de raciocínio | Exige avaliar vantagens e desvantagens | Geração de patches | Modelo com forte capacidade de programação | Exige diffs precisos | Triagem de falhas nos testes | Modelo rápido de categoria intermediária | Frequentemente envolve reconhecimento de padrões | Refatorações mecânicas | Modelo barato ou aberto com mecanismos de proteção | Trabalho repetitivo e verificável Uma configuração prática pode usar modelos da classe Sonnet para a maior parte da programação, modelos da classe Opus/GPT-5.5 para depuração ou projeto complexos, modelos de contexto longo como Gemini/Fable para inspeções extensas e modelos abertos para refatorações locais semelhantes às feitas por ferramentas de lint. Os nomes exatos mudarão; o padrão permanece. Um erro comum é usar o modelo mais caro durante todo o ciclo. Esse modelo acaba gastando tokens de alto custo lendo node_modulese o ruído ao seu redor, avisos de testes e arquivos gerados. Reserve o modelo mais potente para decisões que realmente precisam dele. ## Dicas de configuração que fazem diferença A melhor configuração não é “autonomia máxima”. É “feedback rápido com permissões restritas”. ### 1. Ignore arquivos gerados e de terceiros Todo agente de programação deve ter uma lista de exclusão. Comece pelos mesmos itens que você exclui das buscas e da revisão: ``` node_modules/ dist/ build/ coverage/ .venv/ __pycache__/ target/ vendor/ *.lock *.min.js *.map ``` Normalmente, não excluo arquivos de lock globalmente se a tarefa envolve resolução de dependências, mas os excluo do contexto padrão. Um arquivo de lock pode ser incluído explicitamente quando necessário. ### 2. Use comandos de teste com escopo restrito Não deixe o agente executar toda a suíte por padrão a cada iteração. Forneça uma sequência progressiva de comandos: ``` # First loop: fastest relevant test pytest tests/billing/test_invoice_totals.py -q # Second loop: nearby package pytest tests/billing -q # Final confidence check pytest -q ``` Para JavaScript ou TypeScript: ``` pnpm test invoice-total.test.ts -- --runInBand pnpm lint src/billing pnpm test ``` A questão não é apenas o tempo de execução. Saídas menores significam prompts menores no próximo ciclo. ### 3. Limite a saída dos comandos Se o seu agente oferecer suporte a limites de saída, use-os. Caso contrário, envolva os comandos com essa lógica por conta própria: ``` pytest tests/billing -q 2>&1 | tail -120 ``` Ou, para builds com muita saída: ``` pnpm test 2>&1 | grep -E "FAIL|Error|Expected|Received|at " | head -200 ``` Tenha cuidado: a filtragem pode ocultar contexto útil. Uso isso depois da primeira falha, não antes. Primeiro, entenda como a falha se apresenta; depois, limite as execuções repetidas. ### 4. Peça diffs, não reescritas Para arquivos grandes, diga explicitamente ao agente: ``` Make the smallest safe patch. Do not rewrite unrelated functions. Show a concise diff summary before running tests. ``` Isso reduz o risco e geralmente reduz os tokens de saída. Mais importante ainda, mantém a revisão de código administrável. ### 5. Separe o planejamento da execução Para alterações não triviais, costumo começar com: ``` Inspect the relevant files and propose a plan. Do not edit yet. Limit repo inspection to payment, invoice, and tax modules unless needed. ``` Depois, aprovo o plano e deixo que ele implemente. Isso evita a falha em que o agente edita antes de entender. ## Controle de gastos durante sessões longas É nas sessões longas que os agentes de CLI se destacam e também se tornam perigosos. Esta é a lista de verificação de controle de gastos que uso no trabalho real: - Defina um objetivo para a sessão: “Faça test_invoice_rounding passar”, em vez de “corrija o faturamento”. - Fixe os arquivos quando possível: forneça caminhos exatos em vez de pedir ao agente que descubra tudo. - Reinicie o contexto após mudanças de direção: inicie uma nova sessão com um resumo quando a tarefa mudar. - Resuma as falhas manualmente: cole as 30 linhas importantes, não um log de 3,000 linhas. - Passe para modelos mais potentes de forma deliberada: use um modelo mais potente somente após encontrar um impedimento claro. - Pare após ciclos repetidos: se o agente falhar duas vezes da mesma forma, intervenha. Um bom prompt para reiniciar a sessão é assim: ``` We are fixing invoice rounding. Known facts: - Failure is in tests/billing/test_invoice_totals.py::test_round_half_even - Expected 10.24, actual 10.25 - Decimal quantization happens in src/billing/money.py - Tax calculation calls round_money() from src/billing/tax.py Continue from this summary. Inspect only those files first. ``` Esse prompt pode ser mais barato e mais claro do que carregar uma conversa inteira que não deu certo. ## Chaves de API, provedores e roteamento A maioria dos agentes de CLI pode se comunicar diretamente com a API de um provedor de modelos ou por meio de um gateway compatível. As principais questões de engenharia são: - Autenticação: onde as chaves de API ficam armazenadas e se elas vazam para o histórico do shell ou para os logs. - Roteamento de modelos: qual modelo cuida de cada etapa. - Limites de requisições: os ciclos dos agentes podem gerar rajadas de requisições rapidamente. - Observabilidade: relatórios de tokens e custos por sessão. - Limites de dados: se o código pode ser enviado a APIs externas. Uma configuração mínima do ambiente costuma ser assim: ``` export ANTHROPIC_API_KEY="..." export OPENAI_API_KEY="..." export GEMINI_API_KEY="..." ``` Para equipes, prefiro um script de encapsulamento que selecione os modelos e registre o uso: ``` #!/usr/bin/env bash set -euo pipefail export AGENT_MODEL="${AGENT_MODEL:-sonnet}" export AGENT_MAX_OUTPUT_TOKENS="${AGENT_MAX_OUTPUT_TOKENS:-4096}" export AGENT_SESSION_BUDGET_USD="${AGENT_SESSION_BUDGET_USD:-10}" coding-agent "$@" ``` Se você usa um gateway para vários modelos, é nesse ponto que pode ser útil rotear o tráfego de Claude, GPT, Gemini ou modelos abertos por uma única interface. O recurso importante não é a lista de logotipos; é saber se você tem contabilização confiável do uso e controles por modelo. ## O que incluo nas instruções do repositório A maioria dos agentes respeita algum tipo de arquivo de instruções do repositório. Mantenho o meu curto e operacional: ``` ## Agent Instructions - Prefer minimal diffs over rewrites. - Do not run full test suites until targeted tests pass. - Never edit generated files in `dist/`, `build/`, or `coverage/`. - Use `rg` for search. - Before large refactors, propose a plan and wait. - If a command emits more than 200 lines, rerun with a narrower command. ``` Não se trata de educação. Isso molda o ciclo. O agente ainda cometerá erros, mas boas instruções reduzem o desperdício recorrente. Uma armadilha comum: arquivos de instruções longos demais viram ruído de fundo. Se as instruções do seu agente têm 300 linhas de filosofia de estilo, o modelo pode deixar passar as três restrições operacionais que importam. Coloque as regras de maior valor primeiro. ## Latência: o outro custo Mesmo quando o gasto com tokens é aceitável, a latência pode interromper o fluxo de trabalho. A latência do agente vem de: - Tempo de inferência do modelo - Tempo de execução das ferramentas - Tempo de indexação dos arquivos - Tempo de execução dos testes - Pausas para aprovação humana Para ciclos curtos, otimizo o “tempo até a próxima observação útil”. Um teste direcionado de 15 segundos é melhor do que uma simulação completa de CI de 6 minutos. Um modelo menor que identifica corretamente um erro de sintaxe em 4 segundos é melhor do que um modelo premium que gasta 45 segundos produzindo uma bela explicação. As melhores sessões parecem programação em pares: ``` inspect → patch → targeted test → inspect failure → patch → targeted test → final suite ``` As piores sessões parecem uma encenação de CI: ``` scan repo → edit many files → run everything → drown in logs → repeat ``` ## Limitações e modos de falha Agentes de terminal são úteis, não mágicos. Eles têm dificuldade quando: - O repositório tem dependências ocultas de execução que não são cobertas pelos testes. - A tarefa exige julgamento sobre o produto em vez de transformação de código. - O erro depende de serviços externos ou de um estado instável. - A base de código tem abstrações enganosas ou documentação desatualizada. - O agente não consegue executar o comando de validação relevante. Eles também podem produzir correções plausíveis, mas erradas. Isso é especialmente comum quando os testes são fracos. Se o agente não consegue verificar o comportamento, trate o resultado como um patch não revisado de um engenheiro júnior: potencialmente útil, mas nunca automaticamente confiável. A segurança também importa. Não dê a um agente acesso irrestrito ao shell em um repositório sensível sem entender o modelo de aprovação da ferramenta. “Executar comandos” inclui a capacidade de exibir variáveis de ambiente, modificar arquivos, instalar pacotes ou acessar a rede, a menos que haja restrições. ## Recomendações Práticas - Trate as ferramentas de programação via CLI como ciclos de controle orientados por API, não como prompts isolados. - Otimize os custos reduzindo a quantidade de ciclos e o tamanho do contexto, especialmente a saída dos comandos. - Use modelos potentes para raciocínio difícil, não para cada etapa mecânica. - Mantenha as instruções do repositório curtas, operacionais e focadas no comportamento do agente. - Prefira testes direcionados primeiro e uma validação mais ampla por último. - Reinicie sessões longas com resumos concisos em vez de carregar um histórico desatualizado. - Fique de olho nos tokens de entrada; eles são o centro de custos oculto na programação com agentes. - Pare e intervenha quando o agente repetir a mesma estratégia que falhou. Claude Code, Aider, Cline e OpenCode fazem parte de uma mudança real: a assistência à programação está passando de mecanismos de sugestões para colaboradores nativos do terminal. As equipes que mais se beneficiarão não serão aquelas que simplesmente “ativam agentes”. Serão aquelas que projetam o ciclo: contexto restrito, ferramentas seguras, gastos observáveis e verificação a cada etapa. [Programação](/pt/blog/tag/coding/)[Claude](/pt/blog/tag/claude/)[Agentes](/pt/blog/tag/agents/) A [AI Prime Tech](https://aiprimetech.io/pt/) A AI Prime Tech publica este blog. Os artigos são redigidos com assistência de IA; confira detalhes específicos de cada versão, como IDs de modelos, preços e limites, na documentação oficial antes de se basear neles. Obtenha acesso mais barato à API do Claude Uma única chave de API para Claude Opus 5.5, Sonnet 5, Haiku 4.5 e Fable 5.1, além de GPT-6 modelos. Pague conforme o uso, sem assinatura. [Obtenha Sua Chave de API →](/register) A AI Prime Tech é um gateway de API independente de terceiros. Claude™ e Anthropic® são marcas comerciais da Anthropic, PBC. Não há afiliação nem endosso implícitos.