Como o Claude Code Funciona
📚 Navegação da Série: O artigo anterior 02 · Instalação e Uso te guiou para instalar e rodar o Claude Code. Este artigo levanta a tampa para ver claramente como ele realmente trabalha — por que ele consegue ler código, alterar arquivos e executar comandos por conta própria, e não apenas bater papo.
Na primeira vez que usar o Claude Code, é comum deparar-se com um diálogo como este...
Você: "Por que este teste falhou?" Claude: "Vou rodar a suíte de testes primeiro para dar uma olhada." (começa a rodar o comando) Claude: "O erro diz que
validateEmailretornou undefined, vou olhar essa função." (leu o arquivo) Claude: "Achei, faltou um return aqui. Vou corrigir e depois rodar o teste novamente para confirmar." (corrigiu, e rodou de novo) Claude: "O teste passou."
Ao ver isso você facilmente fica confuso: Eu só fiz uma pergunta, como ele mesmo roda o comando, mesmo lê o arquivo, mesmo altera e mesmo verifica?
Francamente, esta é a maior diferença entre o Claude Code e uma caixa de bate-papo de IA comum. A caixa de bate-papo só "te responde com um texto", enquanto o Claude Code coloca a mão na massa. Por trás disso, há um mecanismo de trabalho fixo que hoje explicaremos a fundo.
Ao terminar de ler este artigo, você terá:
- Um diagrama para entender o "Loop do Agente" do Claude Code — as três ações que ele repete para fazer qualquer coisa
- Entender quais são as 5 categorias de "ferramentas" que ele tem e para que servem, e como ele decide qual usar
- Saber o que ele realmente pode ver no seu computador e o que não pode (relacionado à segurança)
- Um pequeno experimento para você reproduzir e ver com os próprios olhos todo o ciclo acontecer
01 Loop do Agente: Pensar → Agir → Observar
Primeiro a conclusão: Para qualquer tarefa que o Claude Code faz, ele repete três ações — coleta de contexto, tomada de ação e verificação de resultados. Oficialmente, este mecanismo é chamado de "Loop do Agente (agentic loop)".
Falando num modo mais simples: Pensar → Agir → Observar.
- Pensar (coletar contexto): Entender a situação primeiro — ler os arquivos relevantes, ver mensagens de erro, verificar o status do git
- Agir (tomar ação): Mão na massa — alterar código, rodar comandos, criar novos arquivos
- Observar (verificar resultados): Checar se o que foi feito está correto — rodar testes, ver a saída, e se não estiver, iniciar o ciclo novamente
Analogia: Um mecânico experiente. Você leva o carro e diz "o volante está tremendo". O mecânico não vai logo desmontando. Ele dá uma olhada, dá uma volta (Pensar), depois usa a chave inglesa (Agir), e quando termina dirige para confirmar se parou de tremer (Observar). Se ainda tremer, volta ao primeiro passo. O Claude Code é como esse mecânico, só que conserta o seu código.
Voltando à conversa no início do texto, faça o paralelo:
| Claude diz | Qual etapa do loop |
|---|---|
| "Vou rodar a suíte de testes primeiro" | Pensar (coletar contexto) |
| "O erro diz undefined, vou olhar a função" | Pensar (continuar a coleta) |
| "Faltou um return, vou corrigir" | Agir (tomar ação) |
| "Rodar o teste novamente para confirmar" | Observar (verificar o resultado) |
| "O teste passou" | Fim do Loop |
Ele encadeia esses três passos, e o resultado de um decide o que fazer no próximo. Consertar um bug pode levar várias rodadas do ciclo; perguntar "o que esse trecho faz" pode precisar apenas do passo de "Pensar". O número de rodadas é decidido pela complexidade da tarefa, não é algo fixo.
A imagem acima é a roda que o Claude Code gira a cada tarefa: Do "Pensar" para "Agir" para "Observar", e se não estiver bom, volta do "Observar" para o "Pensar" para mais uma rodada — e você pode apertar Esc para pará-lo a qualquer momento.
Há um ponto crucial aqui que muitos não percebem: Você também faz parte deste loop. Se ele se desviar, você pode intervir a qualquer momento para corrigi-lo — explicaremos mais na próxima seção.
Duas coisas impulsionam este ciclo: O modelo fica encarregado de "Pensar", as ferramentas ficam encarregadas de "Agir" e "Observar".
O modelo é o cérebro do Claude — o Sonnet é suficiente para a programação diária, o Opus tem um raciocínio mais forte, adequado para arquiteturas complexas. Na sessão você pode digitar /model para trocar a qualquer momento, ou iniciá-lo com claude --model sonnet.
💡 Resumo em uma frase: O Claude Code não "responde um texto", ele gira no "Pensar→Agir→Observar" até que a tarefa termine, essa é a diferença fundamental entre ele e uma caixa de bate-papo.
02 Você também está no loop: Pode interromper a qualquer momento
Eu mencionei no final da seção anterior: você também faz parte deste loop. Vamos detalhar isso. O bate-papo de IA comum é "você pergunta uma vez, ele responde uma vez, o turno acaba". O Claude Code é diferente — enquanto ele está executando no loop, você não precisa ficar esperando, você pode intervir a qualquer momento.
Por exemplo, ao pedir para refatorar um módulo, você vê que ele se desviou e está prestes a modificar um monte de arquivos; você pressiona Esc e ele para imediatamente, cancelando o comando que estava rodando. Você adiciona "Não toque naquele arquivo, mude apenas esta função", e ele continua seguindo a nova instrução.
Há dois modos de interrupção, certifique-se de diferenciar:
| Operação | Efeito | Quando usar |
|---|---|---|
Pressionar Esc | Para imediatamente, a ferramenta em execução é cancelada, e ele aguarda seu próximo comando | Ele errou o caminho, ou ia fazer a coisa errada, você o impede rapidamente |
Digitar + Enter | Não interrompe a operação atual, você envia um complemento e ele lerá quando terminar o que está fazendo | Só quer dar um contexto ou um aviso, sem pressa para parar |
Você não precisa preparar o "prompt perfeito". Dê a ideia geral e observe ele trabalhar; corrija se ele errar — Isto é um diálogo, não um comando de vez única.
Essa frase vem da documentação oficial, e vale muito a pena lembrar. Quando somos iniciantes, sempre queremos "colocar todos os requisitos em uma frase", sofrendo por horas. Não precisa: dê a direção, e se ele fizer errado você grita para parar, iterar é muito mais rápido do que tentar um super poder de uma vez.
💡 Resumo em uma frase: Ele trabalha sozinho, mas escuta seus comandos a todo instante — parada imediata com
Esc, complementos digitados, a direção está sempre na sua mão.
03 Ferramentas: O motivo pelo qual ele consegue botar a mão na massa
A seção anterior disse que o modelo fica a cargo do "Pensar". O "Agir" e "Observar" contam com o quê? Ferramentas.
Esta é a frase mais importante a se lembrar sobre o Claude Code: Sem ferramentas, o Claude apenas responde com texto; com ferramentas, ele consegue realmente ler seu código, alterar seus arquivos e rodar seus comandos.
Analogia: Um assistente de voz com dispositivos inteligentes. Um assistente que só sabe falar só te dá ideias; mas, dê a ele as ferramentas para abrir a porta, digitar e procurar dados, e ele poderá realmente resolver as coisas para você. As ferramentas são as "mãos" do Claude Code.
A documentação oficial divide as ferramentas nativas em 5 grandes categorias. Aqui está em linguagem simples:
| Categoria da Ferramenta | O que ela pode fazer | Qual ação equivalente no seu dia a dia |
|---|---|---|
| Operação de Arquivo | Lida com arquivos, código, cria novos, renomeia, reorganiza | Você abrindo, digitando e salvando no editor |
| Pesquisa | Acha arquivos por nome, pesquisa conteúdo por Regex, vasculha a base de código | Você usando Ctrl+F ou grep |
| Execução | Roda comandos shell, liga servidores, executa testes, usa git | Você teclando Enter no terminal |
| Rede | Busca páginas da web, captura documentos, consulta erros | Você abrindo o navegador para procurar uma mensagem de erro |
| Inteligência de Código | Verifica erros e avisos de tipos, pula para a definição, encontra referências | O "ir para definição" e "achar referências" do IDE |
⚠️ Nota: A 5ª categoria, "Inteligência de Código", precisa que você instale os plugins de inteligência de código separadamente, enquanto as primeiras 4 estão prontas para usar. Verifique a documentação oficial.
Mas como ele decide qual ferramenta usar? Não é você quem manda, é o modelo que decide por conta própria com base no que você disse e no progresso.
Veja um exemplo oficial. Quando você diz "Corrija os testes que falharam", internamente a rotação será mais ou menos assim:
- Executa a suíte de testes para ver qual falhou —— Usa Execução
- Lê a saída do erro —— Execução
- Busca arquivos-fonte relacionados —— Pesquisa
- Lê esses arquivos para entender a lógica —— Operação de Arquivo
- Altera os arquivos para consertar o erro —— Operação de Arquivo
- Roda os testes de novo para verificar —— Execução
Viu isso? Esses 6 passos são a expansão do loop "Pensar→Agir→Observar" ao nível das ferramentas. Toda vez que uma ferramenta é usada, um pedaço novo de informação é recuperado, que é alimentado ao modelo para decidir o que fazer a seguir — é assim que o ciclo gira.
Um cenário bem típico: pedir a ele para "organizar a estrutura de pastas" de um projeto legado sem documentação. Você não precisa passar nenhum arquivo, ele mesmo usa ls, usa grep para buscar palavras-chave, lê sete ou oito arquivos e por fim desenha um fluxograma com a estrutura. Não definimos nenhum arquivo no processo todo — este é o "delegue, não dê ordens" oficial: dê o objetivo, os detalhes ele procura por si.
Já para Skill, MCP, Hook, Subagent e afins — são camadas de expansão criadas sobre essas 5 ferramentas nativas, que servem para conectar o Claude a mais dados e a serviços externos. Trataremos deles mais para frente; por ora apenas saiba que existem.
💡 Resumo em uma frase: Ferramentas são as "mãos" do Claude Code, divididas em 5 categorias; qual usar, e quantas vezes usar, ele mesmo escolhe, você só define o destino.
04 O que ele consegue ver no seu computador
Isto tem a ver com segurança e precisa ficar bem claro. Muitos ficam na dúvida na primeira vez: Ele vasculhou o meu HD inteiro e mandou os dados embora? Não.
Guarde uma frase: A "visão" do Claude Code é basicamente igual ao que o seu terminal nesse diretório pode acessar. Da pasta onde você chama o claude, seu alcance tem aquilo como centro.
Segundo a documentação, quando você executa o claude numa pasta, ele pode acessar:
- Seu projeto: Arquivos na pasta atual e subpastas (arquivos fora dali só são tocados se você autorizar).
- Seu terminal: Qualquer comando que você pode rodar — ferramentas de compilação, git, gerenciadores de pacotes, scripts. Se a linha de comando consegue rodar, ele consegue.
- Seu estado do git: Branch atual, mudanças não consolidadas, histórico de commits recente.
- Seu
CLAUDE.md: Seu manual dedicado do projeto, lido a cada nova sessão (falaremos mais disso depois). - Extensões configuradas: Seu MCP, Skills, Subagents e outros.
Como ele pode ver o projeto inteiro e não apenas o arquivo que você tem aberto, ele consegue coordenar entre arquivos — você diz "conserta o bug de login", ele vai procurar os múltiplos arquivos conectados, alterá-los todos, e então executar um teste para confirmar. Isto é bem diferente de um plugin de autocomplete inline que enxerga o código do arquivo.
E como garantimos a segurança? Com duas barreiras —
Barreira 1: Checkpoint (ponto de verificação), funciona como salvar o jogo. Antes de alterar qualquer arquivo, ele cria uma captura. Se algo der errado, enquanto a entrada de texto estiver vazia, aperte Esc duas vezes (ou use /rewind), e um "Menu de Retorno" irá surgir. Escolha "Restore code" para voltar ao estado de antes; ou diga simplesmente "desfaça as últimas alterações".
Checkpoints só cuidam dos arquivos modificados por ferramentas de edição — coisas rodadas em bash, ou outros efeitos colaterais externos não são garantidos. Bancos de dados, APIs e envios de ambiente ao vivo "jogam a água fora da bacia sem voltar", e não conseguem dar save. Sendo assim, antes de executar tarefas que geram alterações externas severas, o Claude vai sempre perguntar primeiro.
Aqui está um buraco típico: à vezes ele altera cinco ou seis arquivos e você acha que a direção toda está errada. Antes, precisaríamos de git checkout manual por um tempo, hoje em dia apenas apertamos Esc duas vezes e pegamos a opção "Restore code" — os cinco arquivos voltam juntos ao momento antes da alteração, limpinhos. Com esse recurso na manga, deixá-lo mexer em códigos não dá mais calafrios.
Barreira 2: Modos de Permissão, igual estagiário que sempre te pergunta antes de agir. Aperte Shift+Tab para pular e trocar:
| Modos de Permissão | Como o Claude age |
|---|---|
| Padrão | Pergunta antes de modificar arquivos e rodar comandos |
| Aceitar edições automaticamente | Não pergunta sobre mudanças nos arquivos e comandos normais (como mkdir, mv), mas pergunta para o resto |
| Plan Mode (Modo de Planejamento) | Lê arquivos, manda comandos para explorar, mas não altera fonte; ele faz o plano, e você autoriza o serviço a iniciar |
| Modo Automático | Roda a checagem de fundo base de avaliação (em avaliação experimental com preview, pode mudar) |
A opção melhor a se acostumar é o Plan Mode: Desafios complexos precisam que você aperte duas vezes o Shift+Tab, deixando a IA "apenas ler, montar a ideia, sem tocar no teclado". Analise o esquema, mude os pedaços, confirme, e em seguida deixe que ele aja. Isso evitará retrabalhos das vezes em que as modificações tomam a direção incorreta. Verifique os croquis antes das construções e ganhe bastante tempo de ajuste.
Abominar ficar recebendo perguntas? É só liberar no arquivo settings.json na sua pasta de projeto, adicionando os processos livres aprovados lá (como npm test, git status). As configurações de detalhes chegam mais para frente.
💡 Resumo em uma frase: A visão dele ≈ a restrição no mesmo endereço do terminal; os pontos de retorno cuidam do retrocesso (undo) da escrita, e as portas de entrada de comandos cuidam se você responde "sim" ou se ele assume de vez — Use ambos, e sinta segurança nas operações sem temor.
05 Mão na massa: Veja com seus próprios olhos um ciclo inteiro
Apenas ler princípios sem reproduzir os passos não traz memorização. O uso do loop "Pensar→Agir→Observar" acontece diante dos seus olhos em minutos. Isto independe de ferramentas já carregadas locais de projeto, você só precisará de criar arquivos vazios em novas pastas do PC.
Passo 1: Crie o diretório em vazio local e ative os inícios proativos no terminal.
No terminal faça o comando (Mac / Linux; em Windows via PowerShell substitua o termo mkdir -p pelo formato simples e fácil de local original de linha no terminal e mkdir):
mkdir -p ~/cc-demo && cd ~/cc-demo
claudePasso 2: Após os usos logados abertos em entrada, primeiro vá às opções e troque para Modo de Planejamento.
As teclas Shift+Tab acionam 2 toques rápidos, o menu visual da base indicará no app na base Plan Mode (Modo de Planejamento). Passe ao projeto original a chamada de linha em instrução:
Ajude-me a escrever um script Python add.py, contendo dentro a função add(a, b) que retorne a soma,
crie testes na sequência para verificar isso, por último faça uma rodagem neles. Dê o plano primeiro, não vá diretamente metendo a mão na massa.Expectativa: Ele não criará o caminho nativo de arquivos locais diretos no terminal e limitará na base do terminal o acesso a aprovações mostrando respostas prévias nos guias na leitura, no qual relatará opções assim ——
Plano:
1. Criar add.py, e o teste add(a, b)
2. Escrever o teste (usando de assert ou pytest)
3. Rodar as verificações ativadas originais testadas limitadas no fluxo
Deseja que eu comece?Nesta altura ele se encaixa no "Pensar" — As estruturas são guiadas por passos de fluxos do terminal em formato nativo na máquina de linhas ativadas de testes de leitura originais proativos locais no formato testados de limites. Perceba, que sua autorização foca a ação no plano; este é a diferença foca de modo planejamento original local.
Passo 3: Aprove o plano local de execução nativa do limite base nativa original "Agir" + "Observar".
Aprove respondendo "Pode, inicie aí" locais proativos e de aplicativo originais nas ferramentas originais de linha. A ação passará o roteiro focando na execução em limites no terminal base:
- Operação no arquivo limite testado (ferramentas ativadas no projeto) —— A opção no terminal originais proativas requer aceite de arquivos nativos, pressione sim no fluxo proativo testado
- Ação limpa focada testada na sequência os comandos originais da ferramenta local testada nas rotinas de fluxo de teste base proativo ativado original em
python add.pylocais proativospyteste ativadas originais - Os testes mostram limitados originais testados proativos no projeto no terminal e no fluxo ativado original as saídas proativas nativos testadas:
Teste de verificações testadas passou: add(2, 3) == 5 ✓ add(-1, 1) == 0 ✓ add(0, 0) == 0 ✓As operações de sistema no projeto original "Pensar→Agir→Observar" de sistema nativos de execução fluiram: Pensar (As funções guiadas pelo plano) → Agir (Arquivo escrito em código nativo de fluxos originais) → Observar (Comando testado na via terminal do resultado nativo).
Passo 4 (Opcional): Force no formato proposital de retorno da estrutura em "novo ciclo loop".
Acesso originais locais no limitados de linha locais na instrução originais na instrução de aplicativo no sistema de comandos "Altere o formato da ferramenta original no limitados testados locais originais ativados, use diminuição (subtração) sem modificar testes testados nativos e nome das rotinas locais nativos, em originais base limitadas no aplicativo na linha de fluxo".
Ele ativará na máquina o fluxo "Agir testadas de sistema e Observar de terminal". As opções nativas no terminal e de comandos locais de linha com foco ativados em limite nativas de soma falham; o acesso aos testes ativados percebe limitados proativos nativos originais de sistema "Agir novamente e Pensar" nativo de verificação. Esse limite de sistema originais de ciclo ativados é: Achou o erro original no uso nativas na execução, refaz ciclos ativados na rodada testadas.
Os iniciantes merecem na leitura original o fluxo prático proativo local ativados testados. O ver e executar as linhas originais testados na rotina e ler 10 limites nativos ativados em páginas, ativa testadas locais na visão nativas na parada ativadas e ativadas proativos originais no projeto no modo nativos no momento e formato proativo local ativados de limite nativos de sistema de compreensão de leitura rápida testada nativa da mente nativos.
💡 Resumo em uma frase: Uma rápida operação na máquina nas funções nas verificações testadas nos ambientes de vazio ativados em terminal e fluxo trará originais de execução testada locais na visão "Pensar→Agir→Observar" nas voltas ativadas no processo de fluxo —— o fluxo na máquina original testa a rotina nativos e entende erros nativas originais e faz repetida rotina originais e refaz testados e testadas de limites nativos no momento na frente ativados originais na experiência ativados limitadas originais.
06 Conclusão
Este espaço e as opções nativas no projeto foca em limite na máquina testada nas ações proativas nativos no núcleo ativados de instrução limpos originais proativos: Claude Code nas verificações originais no projeto na autonomia ativados no trabalho no fluxo originais nativos locais de aplicativo testadas de instrução nativas no terminal.
Relembrando o limite central originais de execução:
| Os Tópicos testadas de limite de projeto na instrução | Um resumo para base de leitura |
|---|---|
| Loop do Agente | Pensar→Agir→Observar, o percurso na máquina ativadas nas verificações nativos locais de ativados; e essa na máquina originais na instrução nativos no sistema de limpas originais de limite locais testados em diferenças de chat nativos originais de terminal. |
| Modelos testadas originais no terminal e limitados locais originais de sistema de ferramentas | Os testes locais de opções proativas no modelo de Pensar, originais nas máquinas ativadas nas execuções de teste das ferramentas em Agir nativos proativos locais e Observar. |
| 5 regras de instrução proativas nativas no terminal | Sistema locais de Arquivos / Procura na instrução locais proativos / Execuções originais na máquina ativadas / Rede ativadas locais testados proativos / Limitados originais proativos locais na máquina inteligentes de código de limites, as opções locais no terminal o uso nativas no aplicativo escolhe originais locais proativas. |
| O que ele consegue ler originais locais proativas no terminal | ≈ as limitações no terminal locais no terminal originais; consegue e sabe fazer leitura entre arquivos nativos de máquina. |
| Os sistemas locais originais de projeto ativadas de portas de segurança | Ponto de retorno Checkpoint (retrocesso de uso testado) + Os Modos proativos de permissão originais nas máquinas (limitados originais na instrução e escolhas e aprovação). |
Neste passo ativados no projeto no sistema limitados locais e de limitados ativados originais de uso nativas em fluxo locais originais de uso no projeto de projeto, a sua leitura originais e entendimento no aplicativo no terminal as opções locais na linha originais locais de limitados no terminal e de arquivo e opções originais na máquina nas execuções proativas em tela no aplicativo no terminal — as verificações de sistema locais de linha originais de arquivo e os locais nativos proativos de limite locais de projeto e opções locais nas opções nativos de comandos Esc locais de limitados proativos e ativadas originais no sistema de parada proativos locais no uso no projeto e o acesso locais na linha originais de limite nas etapas ativadas proativas nativos locais no projeto; a base nativas locais de projeto locais.
Ao limite proativo locais originais na máquina no projeto e o aplicativo no terminal e de aplicativo e limites no terminal, a sua mente limitados proativos no projeto originais de limite locais no projeto de comandos nativos no projeto, de opções locais nas execuções no terminal no uso de linha nas rotinas originais testados no terminal locais de aplicativo nativas no projeto e o uso locais proativos no projeto de diretrizes no uso nativos de terminal e de sistema no terminal originais. As opções locais no projeto originais e nativas no aplicativo locais na instrução e de comandos no uso nativas na rotina de aplicativo — as edições de sistema originais de limitados no terminal de leitura locais de sistema originais de limites de linha locais de projeto originais testados nativos locais.
A etapa no uso de opções locais de sistema 04 · API de configurações nativas no terminal de sistema nativos de opções locais: O Claude Code os limites no aplicativo proativos nativos de uso originais e a base nativas de ferramentas, originais de projeto no terminal e no uso de aplicativo no terminal originais locais na linha nativos locais de modelo originais e de uso proativos locais de aplicativo no terminal. Esta na instrução originais locais proativos no terminal e locais de projeto nativas no terminal a leitura locais de linha no terminal e opções locais no aplicativo — de opções locais no sistema no aplicativo originais de opções locais na instrução.