O que diferencia um agente de CLI de código do outro
Peça a um agente de CLI para código que conserte um teste que está falhando, e ele não vai responder com uma sugestão. Ele lê a saída do teste, abre o arquivo, edita uma linha, roda o teste de novo e avisa quando ele passar. Esse loop é o produto, não a janela de chat.
O modelo dentro do loop recebe a maior parte da atenção, e é também a parte que muda mais rápido: os fornecedores trocam de modelo a cada poucos meses, e vários agentes deixam você escolher. O que fica fixo é o harness ao redor do modelo — quais tools ele alcança, como gerencia o contexto, o que pode rodar sem perguntar, e onde esses comandos executam. Dois agentes rodando o mesmo modelo podem se comportar de forma bem diferente por causa disso. O harness é o que você está de fato escolhendo.
Como funciona o loop agentic
Tire a marca e todo agente de CLI para código roda o mesmo ciclo:
- O modelo recebe seu pedido mais o contexto que o harness já montou: arquivos abertos, saída recente do shell, instruções do projeto.
- Em vez de só escrever texto, o modelo pode emitir uma tool call: “rode esse comando de shell”, “escreva esses bytes nesse arquivo”, “procure esse padrão”.
- O harness executa essa chamada de verdade, no seu filesystem ou shell real, e devolve o resultado para o contexto do modelo.
- O modelo lê o resultado e decide o que fazer em seguida: chamar outra tool, ou responder a você.
Isso se repete até o modelo decidir que a tarefa terminou. Ele não precisa de um plano pronto antes de agir. Roda um comando, lê o que aconteceu e ajusta — o que também explica por que um agente pode gastar dezenas de tool calls numa tarefa que no fim era simples.
Nada disso exige uma arquitetura de modelo nova. Exige um modelo bom em escolher qual tool chamar e quando parar, e um harness que dê a ele tools que valham a pena chamar.
Que tools um agente de código realmente recebe
A lista de tools embutidas é curta e sem graça: ler um arquivo, escrever ou editar um arquivo, rodar um comando de shell, buscar no código por nome de arquivo ou por conteúdo, e em muitos agentes, buscar uma URL ou controlar um navegador. Refatorar, depurar, escrever testes, ler um stack trace: tudo isso é o modelo combinando essas primitivas, não um recurso separado que o fornecedor construiu.
As decisões de design que importam estão nos detalhes. “Editar um arquivo” exige uma correspondência exata de string contra o conteúdo atual, o que é mais seguro e fácil de revisar, ou o modelo pode sobrescrever o arquivo inteiro, o que é mais rápido e mais fácil de errar? “Rodar um comando de shell” executa direto, ou dentro de um sandbox que bloqueia acesso à rede e escrita fora do projeto? Coloque o mesmo modelo atrás de respostas diferentes para essas duas perguntas e você tem agentes que não se parecem em nada.
Como agentes de código lidam com contexto maior que a janela
Um codebase de verdade não cabe numa context window, e uma sessão longa produz muito mais saída de tools do que alguém colaria num prompt. Os agentes combinam várias técnicas para dar conta disso:
- Leitura seletiva. O agente busca o arquivo ou a função relevante em vez de carregar o repositório inteiro, o mesmo instinto que você tem quando faz
grepantes decat. - Compactação. Quando a conversa passa de um limite de tamanho, o harness resume os turnos anteriores numa forma mais curta e continua trabalhando a partir dali, trocando detalhe por espaço.
- Subagentes. Uma tarefa grande é dividida em partes menores, cada uma enviada a uma chamada de modelo nova, só com o contexto de que precisa. Só o resultado volta para a conversa principal.
- Retrieval. Alguns agentes indexam o codebase e usam o mesmo padrão de retrieval por trás do RAG para trazer só os chunks relevantes para a pergunta atual. Outros pulam o índice e dependem só da busca.
A compactação é a que morde. Um detalhe do início da sessão, como uma flag que você mencionou uma vez, pode sumir do resumo. Se um agente começa a ignorar algo que você disse uma hora atrás, essa costuma ser a causa, e uma sessão nova com os fatos principais repetidos resolve.
O que um agente de código pode rodar sem perguntar
O harness decide até onde o agente vai antes de parar e perguntar. Num extremo, toda edição de arquivo e todo comando de shell espera sua aprovação. Seguro, e lento: o agente te interrompe o tempo todo. No outro extremo, o agente roda num ambiente isolado sem ninguém olhando, o que serve para trabalho em segundo plano como consertar um teste instável e abrir um pull request enquanto você faz outra coisa.
A maior parte do uso diário fica no meio. Ações somente leitura, como buscar e abrir arquivos, acontecem automaticamente. Qualquer coisa destrutiva ou que sai para fora, como apagar um arquivo ou dar push num remote, espera um sim.
Isso é política aplicada pelo harness, não uma propriedade do modelo. O mesmo modelo é cuidadoso ou descuidado dependendo do que tem permissão para fazer sem supervisão.
Como o MCP dá novas tools a um agente de código
As tools embutidas cobrem filesystem e shell, mas o trabalho de verdade costuma precisar de mais: consultar um banco de dados interno, ou abrir um ticket no seu rastreador de issues. O Model Context Protocol (MCP) é o padrão aberto que oferece isso sem cada fornecedor de agente escrever uma integração sob medida para cada serviço.
Um servidor MCP descreve as tools que oferece e como chamá-las. Qualquer agente compatível com MCP consegue se conectar, listar essas tools e chamá-las exatamente como faria com as embutidas. O agente não precisa de código específico do serviço: ele lê as descrições das tools e decide quando são úteis, do mesmo jeito que decide quando rodar grep.
O custo é contexto. Em muitos agentes, as descrições de tools de cada servidor conectado ocupam espaço na janela a cada turno, então uma dezena de servidores que você raramente usa deixa cada requisição mais pesada. Conecte só os que o projeto precisa.
O que os arquivos AGENTS.md e CLAUDE.md fazem
Quase todo agente procura um arquivo de instruções em markdown na raiz do seu repositório e o lê antes de fazer qualquer coisa. AGENTS.md é a convenção neutra entre fornecedores; algumas ferramentas usam seu próprio nome, como CLAUDE.md. É onde você escreve o que o modelo não consegue inferir do código: qual comando roda os testes, e quais diretórios são gerados e não devem ser editados à mão. Qualquer coisa que o agente teria que adivinhar — e adivinhar errado — entra aqui.
Muitos agentes também leem arquivos de instrução em subdiretórios, então um monorepo pode ter um arquivo na raiz mais um mais específico para cada pacote. Se um arquivo mais profundo sobrescreve o da raiz ou se soma a ele varia de ferramenta para ferramenta, então confira a documentação da que você usa.
Dez linhas nesse arquivo evitam que o agente redescubra seu comando de teste toda sessão.
Como comparar agentes de CLI para código
Quando o loop e a lista de tools são iguais em todo lugar, checklists de features param de dizer muita coisa. Estas quatro perguntas separam as ferramentas de um jeito que muda seu dia:
| Pergunta | O que significa para você |
|---|---|
| Onde ele roda: terminal, IDE ou segundo plano? | Um agente de terminal vive no seu shell e funciona junto com qualquer editor. Um agente de IDE se encaixa na diff view e no undo do seu editor. Um agente em segundo plano trabalha sem supervisão a partir de uma descrição de tarefa e te entrega um pull request, o que serve mais para trabalho de backlog bem definido do que para depuração interativa. |
| O harness é open source ou proprietário? | Um harness aberto como OpenCode ou Aider pode apontar para qualquer modelo a que você tenha acesso via API, incluindo um que você roda localmente com o Ollama, e você consegue ler exatamente o que ele faz. Um harness proprietário costuma ser afinado para os próprios modelos do fornecedor e precisa de menos configuração. |
| Como você paga: API por token ou assinatura? | Cobrança por token acompanha o uso, então sessões autônomas longas custam mais. Uma assinatura limita o que você gasta, mas adiciona limites de uso e te prende aos modelos de um fornecedor. |
| Quão fundo vai o sandbox? | Alguns agentes rodam comandos direto na sua máquina; outros sempre executam dentro de um container ou VM, o mesmo tipo de isolamento que containers Docker te dão. Execução direta não precisa de configuração e é a escolha mais arriscada para qualquer coisa deixada rodando sem supervisão. |
Classifique o modo, não a marca. Um fornecedor costuma lançar uma ferramenta de terminal, uma extensão de editor e um modo em nuvem que abre pull requests; o Claude Code e o OpenAI Codex funcionam assim. Os padrões de permissão e sandbox mudam entre esses modos, então avalie o que você vai usar de fato.
Como escolher um agente de CLI para código para o seu fluxo de trabalho
Pule os leaderboards. Pontuações de benchmark mudam a cada poucas semanas e dizem pouco sobre o seu repositório. Responda duas perguntas em vez disso: você quer o agente no terminal ou no editor, e você quer que ele trabalhe sem supervisão em segundo plano ou num loop com você aprovando cada passo? Essas respostas reduzem o campo a duas ou três opções.
Depois escreva um AGENTS.md para o seu projeto, dê a cada candidata a mesma tarefa real do seu backlog e fique com aquela cujo diff você faria merge com menos edições.