Claude Code e a nova onda de ferramentas de programação com IA no terminal

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.

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:

1. A CLI reúne o contexto.
2. O modelo decide a próxima operação.
3. A CLI executa a operação.
4. O resultado é enviado de volta ao modelo.
5. 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:

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:

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.