SpyBara
Go Premium

how-claude-code-works.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 39 additions and 77 deletions.

2026
Wed 9 22:58 Mon 14 22:58 Fri 18 23:58 Tue 22 23:59 Fri 25 23:58

Como Claude Code funciona

Entenda o loop agentic, as ferramentas integradas e como Claude Code interage com seu projeto.

Claude Code é um assistente agentic que funciona em seu terminal. Embora se destaque em codificação, pode ajudar com qualquer coisa que você possa fazer a partir da linha de comando: escrever documentação, executar compilações, pesquisar arquivos, pesquisar tópicos e muito mais.

Este guia cobre a arquitetura principal, capacidades integradas e dicas para trabalhar efetivamente. Para instruções passo a passo, consulte Fluxos de trabalho comuns. Para recursos de extensibilidade como skills, MCP e hooks, consulte Estender Claude Code.

O loop agentic

Quando você dá uma tarefa a Claude, ele trabalha através de três fases: reunir contexto, tomar ação e verificar resultados. Essas fases se misturam. Claude usa ferramentas ao longo do processo, seja pesquisando arquivos para entender seu código, editando para fazer alterações ou executando testes para verificar seu trabalho.

Diagrama do loop agentic: Seu prompt leva Claude a reunir contexto, tomar ação, verificar resultados e repetir até que a tarefa seja concluída. Você pode interromper em qualquer ponto. Diagrama do loop agentic: Seu prompt leva Claude a reunir contexto, tomar ação, verificar resultados e repetir até que a tarefa seja concluída. Você pode interromper em qualquer ponto.

O loop se adapta ao que você pede. Uma pergunta sobre sua base de código pode precisar apenas de coleta de contexto. Uma correção de bug passa por todas as três fases repetidamente. Uma refatoração pode envolver verificação extensiva. Claude decide o que cada etapa requer com base no que aprendeu da etapa anterior, encadeando dezenas de ações e se autocorrigindo ao longo do caminho.

Você também faz parte deste loop. Você pode interromper em qualquer ponto para orientar Claude em uma direção diferente, fornecer contexto adicional ou pedir que tente uma abordagem diferente. Claude trabalha autonomamente, mas permanece responsivo à sua entrada.

O loop agentic é alimentado por dois componentes: modelos que raciocinam e ferramentas que agem. Claude Code serve como o agentic harness ao redor de Claude: fornece as ferramentas, gerenciamento de contexto e ambiente de execução que transformam um modelo de linguagem em um agente de codificação capaz.

Models

Claude Code usa modelos Claude para entender seu código e raciocinar sobre tarefas. Claude pode ler código em qualquer linguagem, entender como os componentes se conectam e descobrir o que precisa mudar para alcançar seu objetivo. Para tarefas complexas, ele divide o trabalho em etapas, as executa e se ajusta com base no que aprende.

Múltiplos modelos estão disponíveis com diferentes compensações. Sonnet lida bem com a maioria das tarefas de codificação. Opus fornece raciocínio mais forte para decisões arquitetônicas complexas. Mude com /model durante uma sessão ou comece com claude --model <name>.

Quando este guia diz "Claude escolhe" ou "Claude decide", é o modelo fazendo o raciocínio.

Tools

Ferramentas são o que tornam Claude Code agentic. Sem ferramentas, Claude pode apenas responder com texto. Com ferramentas, Claude pode agir: ler seu código, editar arquivos, executar comandos, pesquisar a web e interagir com serviços externos. Cada uso de ferramenta retorna informações que alimentam o loop, informando a próxima decisão de Claude.

As ferramentas integradas geralmente se enquadram em cinco categorias, cada uma representando um tipo diferente de agência.

Categoria O que Claude pode fazer
Operações de arquivo Ler arquivos, editar código, criar novos arquivos, renomear e reorganizar
Pesquisa Encontrar arquivos por padrão, pesquisar conteúdo com regex, explorar bases de código
Execução Executar comandos shell, iniciar servidores, executar testes, usar git
Web Pesquisar a web, buscar documentação, procurar mensagens de erro
Inteligência de código Ver erros de tipo e avisos após edições, pular para definições, encontrar referências (requer plugins de inteligência de código)

Essas são as capacidades principais. Claude também tem ferramentas para gerar subagents, fazer perguntas a você e outras tarefas de orquestração. Consulte Ferramentas disponíveis para Claude para a lista completa.

Claude escolhe quais ferramentas usar com base em seu prompt e no que aprende ao longo do caminho. Quando você diz "corrigir os testes falhando", Claude pode:

  1. Executar o conjunto de testes para ver o que está falhando
  2. Ler a saída de erro
  3. Pesquisar os arquivos de código-fonte relevantes
  4. Ler esses arquivos para entender o código
  5. Editar os arquivos para corrigir o problema
  6. Executar os testes novamente para verificar

Cada uso de ferramenta dá a Claude novas informações que informam a próxima etapa. Este é o loop agentic em ação.

Estendendo as capacidades base: As ferramentas integradas são a base. Você pode estender o que Claude sabe com skills, conectar a serviços externos com MCP, automatizar fluxos de trabalho com hooks e delegar tarefas a subagents. Essas extensões formam uma camada sobre o loop agentic principal. Consulte Estender Claude Code para orientação sobre como escolher a extensão certa para suas necessidades.

O que Claude pode acessar

Quando você executa claude em um diretório, Claude Code ganha acesso a:

  • Seu projeto. Arquivos em seu diretório e subdiretórios, além de arquivos em outro lugar com sua permissão.
  • Seu terminal. Qualquer comando que você possa executar: ferramentas de compilação, git, gerenciadores de pacotes, utilitários do sistema, scripts. Se você pode fazer a partir da linha de comando, Claude também pode.
  • Seu estado git. Branch atual, alterações não confirmadas e histórico de commits recentes.
  • Seu CLAUDE.md. Um arquivo markdown onde você armazena instruções específicas do projeto, convenções e contexto que Claude deve conhecer a cada sessão.
  • Auto memory. Aprendizados que Claude salva automaticamente conforme você trabalha, como suas preferências. As primeiras 200 linhas ou 25KB de MEMORY.md, o que vier primeiro, são carregadas no início de cada sessão.
  • Extensões que você configura. Servidores MCP para serviços externos, skills para fluxos de trabalho, subagents para trabalho delegado e Claude no Chrome para interação com navegador.

Como Claude vê seu projeto inteiro, pode trabalhar em todo ele. Quando você pede a Claude para "corrigir o bug de autenticação", ele pesquisa arquivos relevantes, lê múltiplos arquivos para entender o contexto, faz edições coordenadas entre eles, executa testes para verificar a correção e confirma as alterações se você pedir. Isso é diferente de assistentes de código inline que apenas veem o arquivo atual.

Ambientes e interfaces

O loop agentic, ferramentas e capacidades descritos acima são os mesmos em qualquer lugar que você use Claude Code. O que muda é onde o código é executado e como você interage com ele.

Ambientes de execução

Claude Code funciona em três ambientes, cada um com diferentes compensações para onde seu código é executado.

Ambiente Onde o código é executado Caso de uso
Local Sua máquina Padrão. Acesso completo aos seus arquivos, ferramentas e ambiente
Cloud VMs gerenciadas pela Anthropic, ou ambientes auto-hospedados que sua organização opera Delegar tarefas, trabalhar em repositórios que você não tem localmente
Remote Control Sua máquina, controlada a partir de um navegador Use a interface web enquanto a execução e seus arquivos permanecem locais

Interfaces

Você pode acessar Claude Code através do terminal, do aplicativo desktop, extensões IDE, claude.ai/code, Remote Control, Slack e pipelines CI/CD. A interface determina como você vê e interage com Claude, mas o loop agentic subjacente é idêntico. Consulte Use Claude Code em qualquer lugar para a lista completa.

Trabalhe com sessões

Claude Code salva sua conversa localmente conforme você trabalha. Cada mensagem, uso de ferramenta e resultado é escrito em um arquivo JSONL em texto simples sob ~/.claude/projects/, o que permite retroceder, retomar e bifurcar sessões. Antes de Claude fazer alterações de código, ele também tira um snapshot dos arquivos afetados para que você possa reverter se necessário. Para caminhos, retenção e como limpar esses dados, consulte dados de aplicação em ~/.claude.

As sessões são independentes. Cada nova sessão começa com uma janela de contexto fresca, sem o histórico de conversa de sessões anteriores. Claude pode persistir aprendizados entre sessões usando auto memory, e você pode adicionar suas próprias instruções persistentes em CLAUDE.md.

Trabalhe entre branches

Cada conversa de Claude Code é uma sessão vinculada ao seu diretório atual. O seletor /resume mostra sessões do worktree atual por padrão, com atalhos de teclado para ampliar a lista para outros worktrees ou projetos. Consulte Gerenciar sessões para a lista completa de atalhos do seletor e como funciona a resolução de nomes.

Claude vê os arquivos do seu branch atual. Quando você muda de branch, Claude vê os arquivos do novo branch, mas seu histórico de conversa permanece o mesmo. Claude se lembra do que você discutiu mesmo após mudar de branch.

Como as sessões estão vinculadas a diretórios, você pode executar sessões paralelas de Claude Code usando git worktrees, que criam diretórios separados para branches individuais.

Retome ou bifurque sessões

Retomar uma sessão com claude --continue ou claude --resume reabre-a sob o mesmo ID de sessão e anexa novas mensagens à conversa existente. Bifurcar com --fork-session ou /branch copia o histórico em um novo ID de sessão, deixando o original inalterado.

Diagrama de continuidade de sessão: retomar continua a mesma sessão, bifurcar cria um novo branch com um novo ID. Diagrama de continuidade de sessão: retomar continua a mesma sessão, bifurcar cria um novo branch com um novo ID.

Para as flags de retomada, o seletor /resume, nomeação e o que acontece quando a mesma sessão está aberta em dois terminais, consulte Gerenciar sessões.

A janela de contexto

A janela de contexto de Claude contém seu histórico de conversa, conteúdo de arquivos, saídas de comando, CLAUDE.md, auto memory, skills carregadas e instruções do sistema. Conforme você trabalha, o contexto se enche. Claude compacta automaticamente, mas instruções do início da conversa podem ser perdidas. Coloque regras persistentes em CLAUDE.md e execute /context para ver o que está usando espaço.

Para um passo a passo interativo do que é carregado e quando, consulte Explore a janela de contexto.

Quando o contexto se enche

Claude Code gerencia o contexto automaticamente conforme você se aproxima do limite. Ele limpa saídas de ferramentas mais antigas primeiro, depois resume a conversa se necessário. Suas solicitações e trechos de código-chave são preservados; instruções detalhadas do início da conversa podem ser perdidas. Coloque regras persistentes em CLAUDE.md em vez de confiar no histórico de conversa.

Para controlar o que é preservado durante a compactação, adicione uma seção "Compact Instructions" a CLAUDE.md ou execute /compact com um foco (como /compact focus on the API changes).

Se um único arquivo ou saída de ferramenta for tão grande que o contexto se reencheça imediatamente após cada resumo, Claude Code para de compactar automaticamente após algumas tentativas e mostra um erro em vez de fazer loop. Consulte Auto-compactação para com um erro de thrashing para etapas de recuperação.

Execute /context para ver o que está usando espaço. Definições de ferramentas MCP são adiadas por padrão e carregadas sob demanda via busca de ferramentas, então apenas nomes de ferramentas e instruções do servidor consomem contexto até Claude usar uma ferramenta específica.

Gerencie contexto com skills e subagents

Além da compactação, você pode usar outros recursos para controlar o que é carregado no contexto.

Skills carregam sob demanda. Claude vê descrições de skills no início da sessão, mas o conteúdo completo só carrega quando uma skill é usada. Para skills que você invoca manualmente, defina disable-model-invocation: true para manter descrições fora do contexto até que você precise delas. Para skills que você não escreveu, use skillOverrides para fazer o mesmo a partir das configurações.

Subagents trabalham em sua própria janela de contexto. Um subagent começa do zero a menos que seja um fork, que começa com uma cópia de sua conversa até agora. De qualquer forma, as chamadas de ferramenta do subagent ficam fora de seu contexto, e Claude recebe um resumo quando o subagent termina.

Consulte custos de contexto para o que cada recurso custa e reduzir uso de tokens para dicas sobre como gerenciar contexto.

Fique seguro com checkpoints e permissões

Claude tem dois mecanismos de segurança: checkpoints permitem que você desfaça alterações de arquivo e permissões controlam o que Claude pode fazer sem perguntar.

Desfaça alterações com checkpoints

Cada edição de arquivo é reversível. Antes de Claude editar qualquer arquivo, ele tira um snapshot do conteúdo atual. Se algo der errado, pressione Esc duas vezes para retroceder a um estado anterior, ou peça a Claude para desfazer.

Checkpoints são separados do git e permanecem disponíveis quando você retoma uma conversa. Eles cobrem apenas alterações de arquivo, e uma restauração ignora arquivos com links simbólicos e hard-linked. Ações que afetam sistemas remotos (bancos de dados, APIs, implantações) não podem ser checkpointed. Você controla esses com seu modo de permissão e regras de permissão.

Controle o que Claude pode fazer

Escolha um modo de permissão para definir o que Claude pode fazer sem perguntar a você. Pressione Shift+Tab para percorrer os modos de permissão:

  • Auto: um classificador revisa a maioria das ações em segundo plano e bloqueia as arriscadas em vez de perguntar a você. Nos planos Pro, Max e Team, é o modo de permissão inicial integrado para sessões interativas de terminal e VS Code
  • Manual: Claude pergunta antes de edições de arquivo e comandos shell
  • Accept edits: Claude edita arquivos e executa comandos comuns do sistema de arquivos como mkdir e mv sem perguntar, ainda pergunta por outros comandos
  • Plan: Claude explora e propõe um plano sem editar seus arquivos de origem

Você também pode permitir comandos específicos em .claude/settings.json para que Claude não pergunte cada vez. Isso é útil para comandos confiáveis como npm test ou git status. As configurações podem ser escopo de políticas em toda a organização até preferências pessoais. Consulte Permissões para detalhes.

Trabalhe efetivamente com Claude Code

Essas dicas ajudam você a obter melhores resultados de Claude Code. Para mais informações sobre prompts específicos, verificação e planejamento, consulte Melhores práticas.

Peça ajuda a Claude Code

Claude Code pode ensinar você como usá-lo. Faça perguntas como "como configuro hooks?" ou "qual é a melhor maneira de estruturar meu CLAUDE.md?" e Claude explicará.

Comandos integrados também o guiam através da configuração:

  • /init o guia através da criação de um CLAUDE.md para seu projeto
  • /doctor executa uma verificação de configuração que diagnostica problemas de instalação e configuração e pode corrigi-los

É uma conversa

Claude Code é conversacional. Você não precisa de prompts perfeitos. Comece com o que você quer, depois refine:

Corrigir o bug de login

[Claude investiga, tenta algo]

Isso não é bem certo. O problema está no tratamento de sessão.

[Claude ajusta a abordagem]

Quando a primeira tentativa não está certa, você não começa do zero. Você itera.

Interrompa e oriente

Você pode redirecionar Claude em qualquer ponto sem esperar que o turno termine ou começar do zero:

  • Pressione Esc para parar Claude imediatamente. A chamada de ferramenta em execução é cancelada e Claude aguarda sua próxima instrução. Se você tiver mensagens na fila, Claude Code as envia em seguida.
  • Digite uma correção e pressione Enter para enviá-la sem parar a ferramenta em execução. Claude a lê assim que a ação atual é concluída e se ajusta antes de decidir seu próximo passo.

Delegue, não dite

Pense em delegar a um colega capaz. Dê contexto e direção, depois confie em Claude para descobrir os detalhes:

O fluxo de checkout está quebrado para usuários com cartões expirados.
O código relevante está em src/payments/. Você pode investigar e corrigir?

Você não precisa especificar quais arquivos ler ou quais comandos executar. Claude descobre isso.

O que vem a seguir

puzzle-piece Estender com recursos

Adicione skills e conexões MCP
graduation-cap Fluxos de trabalho comuns

Guias passo a passo para tarefas típicas