Claude Code: como funciona o agente de programação

O Claude Code é a ferramenta de programação com agente da Anthropic. Em vez de apenas completar a linha que você está digitando, ele recebe uma tarefa, decide quais arquivos ler, edita código, roda comandos no terminal e verifica se o resultado funcionou.

Este texto explica a arquitetura e o funcionamento com base exclusivamente na documentação oficial da Anthropic, consultada em 8 de outubro de 2026. O produto recebe atualizações frequentes, então nomes de modos, versões e números citados aqui podem mudar. Quando um detalhe depende de versão, indicamos.

Se o conceito de agente ainda é novo para você, vale ler antes o que são agentes de IA.

O que é o Claude Code

A visão geral da documentação define o Claude Code como uma ferramenta de programação com agente que lê a base de código, edita arquivos, executa comandos e se integra às ferramentas de desenvolvimento.

Ele roda em várias superfícies, que a documentação chama de surfaces: o terminal (a interface de linha de comando, ou CLI), extensões para VS Code e IDEs da JetBrains, um aplicativo de desktop e a versão web em claude.ai/code. Segundo a mesma página, todas se conectam ao mesmo motor, de modo que arquivos de instrução, configurações e servidores MCP do repositório valem em qualquer uma delas.

Para usar, a maioria das superfícies exige uma assinatura do Claude ou uma conta no Anthropic Console. A CLI, o VS Code e a JetBrains também aceitam provedores de nuvem de terceiros, conforme a documentação.

A arquitetura: modelo, ferramentas e o “arnês”

A página How Claude Code works descreve duas peças. A primeira é o modelo, um modelo Claude que raciocina sobre a tarefa. A segunda são as ferramentas, que permitem agir.

O Claude Code em si é a camada em volta do modelo. Ele fornece as ferramentas e administra o contexto que o modelo enxerga. A documentação dá a essa camada o nome de arnês de agente (agentic harness, em inglês): a estrutura que conecta o modelo ao seu computador.

O contexto, ou janela de contexto, é tudo o que o modelo tem diante de si em cada momento: a conversa, o conteúdo dos arquivos lidos, a saída dos comandos e as instruções do projeto. Para entender por que esse espaço é limitado, veja contexto e memória em IA.

A documentação agrupa as ferramentas nativas em cinco categorias:

• Operações de arquivo: ler, editar, criar e renomear arquivos.
• Busca: encontrar arquivos por padrão e pesquisar conteúdo com expressões regulares.
• Execução: rodar comandos de shell, iniciar servidores, executar testes e usar o git.
• Web: pesquisar na internet e buscar documentação.
• Inteligência de código: ver erros de tipo após edições e saltar para definições, o que exige plugins específicos.

O ciclo de trabalho do agente

Quando você passa uma tarefa, o Claude Code trabalha em três fases que se misturam, segundo a documentação: reunir contexto, agir e verificar resultados. Cada uso de ferramenta devolve uma informação que orienta o passo seguinte.

A própria documentação dá um exemplo para o pedido “corrija os testes que estão falhando”. O agente pode rodar a suíte de testes, ler o erro, buscar os arquivos relevantes, lê-los, editar o código e rodar os testes de novo para confirmar.

O ciclo se adapta ao pedido. Uma pergunta sobre o código talvez só precise da fase de leitura. Uma correção de bug pode passar pelas três fases várias vezes. Você pode interromper a qualquer momento com a tecla Esc ou digitar uma correção enquanto o agente trabalha.

O que o agente enxerga

Ao rodar o comando claude em uma pasta, o agente passa a ter acesso, segundo a documentação, a:

• arquivos da pasta e subpastas (e de outros lugares, com sua permissão);
• qualquer comando que você mesmo poderia rodar no terminal;
• o estado do git, como branch atual e alterações não salvas;
• o arquivo CLAUDE.md, um texto em Markdown com regras e convenções do projeto que o agente lê no início de cada sessão;
• uma memória automática, em que o agente guarda aprendizados entre sessões;
• extensões configuradas, como servidores MCP e subagentes.

Cada sessão nova começa com a janela de contexto vazia. Quando ela se aproxima do limite, o Claude Code apaga saídas antigas de ferramentas e resume a conversa. A documentação avisa que instruções dadas no começo da conversa podem se perder nesse resumo e recomenda colocar regras permanentes no CLAUDE.md.

Extensões: MCP, hooks e subagentes

As ferramentas nativas são a base. Sobre elas, a documentação descreve camadas de extensão.

MCP (Model Context Protocol) é um padrão aberto para conectar ferramentas de IA a fontes de dados e serviços externos. Segundo a página sobre MCP, servidores MCP dão ao Claude Code acesso a ferramentas, bancos de dados e APIs. A configuração pode ser local, de projeto (num arquivo .mcp.json versionado com o código) ou do usuário. A mesma página alerta: confirme que você confia em cada servidor, porque servidores que buscam conteúdo externo expõem você a risco de injeção de prompt.

Hooks são comandos de shell definidos por você que rodam em pontos fixos do funcionamento do agente. O guia de hooks explica a diferença central: as instruções do CLAUDE.md são orientações que o modelo pode seguir ou não, enquanto um hook sempre roda. Exemplos da documentação: formatar o arquivo depois de cada edição, avisar quando o agente espera sua resposta e bloquear edições em arquivos sensíveis, como .env. Um hook do tipo PreToolUse roda antes de uma ferramenta e pode impedir a ação.

Subagentes são assistentes especializados para os quais o agente principal delega tarefas. Segundo a página de subagentes, cada um roda em sua própria janela de contexto, com instruções próprias, acesso restrito a ferramentas e permissões independentes. Só um resumo volta para a conversa principal. A documentação lista subagentes nativos, como o Explore, voltado a busca somente leitura, e o Plan, usado no modo de planejamento.

Há ainda as skills, pacotes de instruções e fluxos reutilizáveis que só entram no contexto quando são usados.

Permissões e segurança

A documentação de segurança afirma que o produto tem arquitetura baseada em permissões. O modo de permissão define o que o agente faz sem perguntar. A página de modos, consultada em 8/10/2026, lista seis:

Modo	O que roda sem perguntar	Indicação da documentação
Manual (default)	Apenas leituras	Revisar cada ação, trabalho sensível
acceptEdits	Leituras, edições e comandos comuns de arquivo	Iterar em código que você revisa
plan	Leituras (e comandos aprovados pelo classificador, quando disponível)	Explorar antes de mudar
auto	Tudo, com verificações de segurança em segundo plano	Tarefas longas
dontAsk	Leituras e ferramentas pré-aprovadas; o resto é negado	CI e scripts travados
bypassPermissions	Tudo	Só contêineres e máquinas virtuais isoladas

No modo auto, um segundo modelo, chamado classificador, revisa as ações no seu lugar e bloqueia as que julgar arriscadas. Segundo a documentação, a partir da versão 2.1.283 ele é o modo inicial nas sessões interativas de terminal e VS Code; em versões anteriores, só nos planos Pro, Max e Team.

Sobre os modos, você pode criar regras de permissão que liberam ou bloqueiam ferramentas e comandos específicos. A documentação diz que regras de bloqueio valem em todos os modos, inclusive bypassPermissions.

Outras proteções descritas:

• Sandbox: isolamento de sistema de arquivos e de rede para comandos de terminal. Em texto de engenharia de outubro de 2025, a Anthropic informou que, internamente, o sandbox reduziu em 84% os pedidos de permissão. É um número da própria empresa, sem auditoria externa.
• Checkpoints: antes de editar, o agente guarda uma cópia do arquivo, e você pode voltar atrás. A documentação ressalva que isso só cobre edições feitas pelas ferramentas de arquivo, não ações em sistemas remotos (bancos de dados, APIs, deploys) nem, segundo o guia de boas práticas, mudanças feitas por comandos de terminal. Não substitui o git.
• Confiança na pasta: em sessões interativas, o Claude Code pergunta se você confia numa pasta nova antes de trabalhar nela.

A documentação é explícita sobre o limite dessas defesas. Injeção de prompt é a técnica em que um atacante insere texto malicioso (num arquivo, numa página, num ticket) para manipular as instruções do agente. A página de segurança diz que as proteções reduzem bastante o risco, mas que nenhum sistema é imune a todos os ataques. Ela também atribui ao usuário a responsabilidade de revisar código e comandos antes de aprovar.

Casos de uso descritos pela Anthropic

A visão geral e o guia de boas práticas citam usos como:

• escrever testes para código sem cobertura, corrigir erros de lint (verificação automática de estilo) e resolver conflitos de merge;
• implementar funcionalidades descritas em linguagem comum e investigar bugs a partir de uma mensagem de erro;
• criar commits, branches e pull requests;
• revisar código e triar issues em pipelines de CI, como GitHub Actions;
• responder perguntas sobre uma base de código desconhecida, o que a documentação apresenta como forma de integração de novos membros;
• rodar sem interação com claude -p em scripts, inclusive em migrações de muitos arquivos.

Esses são os usos que o fabricante descreve, não resultados medidos pela redação. Para um caminho prático de uso em produto, veja nosso roteiro de como construir um MVP com agentes de IA.

Limites que a própria documentação aponta

O guia de boas práticas parte de uma restrição: a janela de contexto enche rápido, e o desempenho cai à medida que ela enche. O agente pode “esquecer” instruções iniciais ou errar mais.

Outros limites e alertas do mesmo guia:

• O agente para quando o trabalho “parece pronto”. Sem um teste ou verificação que ele possa rodar, a checagem fica com você.
• Implementações plausíveis podem falhar em casos-limite. A recomendação é direta: se você não consegue verificar, não publique.
• Corrigir o agente repetidas vezes na mesma sessão polui o contexto. Depois de duas correções sem sucesso, o guia sugere recomeçar com um pedido melhor.

O guia também sugere separar exploração, planejamento e implementação, e usar uma segunda sessão ou subagente para revisar o código, já que um contexto novo não fica enviesado pelo que acabou de escrever. Sobre os erros de modelos de linguagem em geral, veja alucinações de IA.

Quanto custa

A página de custos informa que o Claude Code cobra por consumo de tokens de API, e remete os preços dos planos de assinatura a claude.com/pricing. Token é a unidade de texto que o modelo processa; veja tokens em modelos de IA.

Na data da consulta (8/10/2026), a documentação dizia que, em implantações corporativas, o custo médio fica em torno de US$ 13 por desenvolvedor por dia ativo e US$ 150 a 250 por desenvolvedor por mês, com 90% dos usuários abaixo de US$ 30 por dia ativo. São médias divulgadas pela Anthropic; a própria página diz que o custo varia muito conforme modelo, tamanho do código e padrão de uso, e recomenda começar com um grupo-piloto.

O que mais pesa, segundo a documentação: sessões longas sem limpeza (cada pedido reenvia o histórico), modelos maiores usados como padrão, subagentes e equipes de agentes, que consomem tokens próprios. O comando /usage mostra uma estimativa de consumo da sessão; a cobrança oficial fica no painel da conta.

O que levar deste texto

• O Claude Code é uma camada que dá ferramentas a um modelo Claude e administra o contexto; o trabalho segue um ciclo de ler, agir e verificar.
• MCP conecta serviços externos, hooks impõem regras que sempre rodam e subagentes isolam tarefas em contextos separados.
• Modos de permissão, regras de bloqueio, sandbox e checkpoints reduzem riscos, mas a documentação deixa claro que não os eliminam e que a revisão continua sendo sua.
• Testes e outras verificações automáticas são o que separa um resultado plausível de um resultado confirmado.
• Custos e recursos mudam com frequência. Confira a documentação oficial antes de decidir.