Claude Code: o que é e como funciona na prática, do pedido até o código no arquivo?

Fala aí, beleza? "Ferramenta de codificação agentica que lê o codebase, edita arquivos e executa comandos"

É essa a definição oficial do Claude Code na documentação da Anthropic, e ela é correta, mas ela não responde a pergunta que provavelmente te trouxe aqui: o que acontece ENTRE você digitar um pedido e o arquivo do seu projeto mudar? 🙂

Então bora fazer diferente

Em vez de repetir a lista de features, este post segue uma tarefa do começo ao fim: o que você escreve, o que ele lê no projeto, o que ele propõe alterar, onde entra a sua aprovação e o que dá pra desfazer quando o rumo desvia

E se liga num detalhe que organiza tudo: o código não muda sem passar por um ponto de aprovação, seja ele um plano que você aceita, um diff que você revisa ou uma regra de permissão que você configurou antes

O que você precisa antes da primeira tarefa

Primeiro o acesso

A maioria das superfícies exige uma assinatura Claude ou uma conta do Console da Anthropic

A CLI do terminal, o VS Code e o JetBrains também aceitam provedores terceiros, então dá pra plugar outra fonte de modelo nessas três

Instalando:

Em macOS, Linux ou WSL, a recomendação é o instalador nativo:

curl -fsSL https://claude.ai/install.sh | bash

E tem a alternativa via npm global, familiar pra quem já vive no ecossistema Node:

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

npm install -g @anthropic-ai/claude-code

Depois de instalar, você entra na pasta do projeto e roda:

claude

Ele pede o login na sua conta Anthropic e pronto, tá de pé

Preparando o projeto com /init:

Antes de mandar a primeira tarefa de verdade, roda o /init

Ele analisa o codebase e gera um CLAUDE.md inicial com comandos de build, instruções de teste e convenções do projeto

E se liga: caso já exista um CLAUDE.md na pasta, o /init não passa por cima, ele sugere melhorias

Analogia rápida pra quem nunca viu: o CLAUDE.md é tipo o README que você escreveria pro dev novo do time, só que esse dev lê ele TODA vez que senta na cadeira

O caminho de uma tarefa: do pedido até o código no arquivo

Aqui é o coração do post

Quando o Claude Code recebe uma tarefa, ele trabalha em três fases que se misturam o tempo todo: reunir contexto, agir e verificar o resultado

Vamos abrir isso em seis passos

1. Você escreve o pedido

Parece o passo bobo, mas ele carrega uma regra importante: cada sessão começa com uma janela de contexto NOVA, sem o histórico das sessões anteriores

O que atravessa de uma sessão pra outra são os arquivos CLAUDE.md e a auto memory

O CLAUDE.md de projeto pode ficar em ./CLAUDE.md ou em ./.claude/CLAUDE.md, e ele é lido no início de cada sessão

Quer conferir o que entrou? Roda /context e olha a lista Memory files

O erro comum deste passo: achar que ele "lembra" do que vocês combinaram ontem

Não lembra, beleza? Se a regra importa, ela mora no CLAUDE.md, não na sua memória afetiva da conversa passada. E se a sua sessão morreu porque você bateu o limite de uso no meio da tarefa, esse ponto fica ainda mais óbvio

2. Ele reúne contexto

Agora ele vai ler o teu projeto, e isso não é mágica: são ferramentas com nome e função

• Read: lê arquivos do sistema local, incluindo texto, imagens, PDFs e notebooks Jupyter
• Glob: encontra arquivos por padrão de nome, com ** recursivo
• Grep: busca construída sobre o ripgrep, com suporte a regex

E tem um detalhe de engenharia que explica a sensação de velocidade: ferramentas somente leitura (Read, Glob, Grep e ferramentas MCP marcadas como read-only) podem rodar em PARALELO

O erro comum deste passo: mandar um pedido vago tipo "melhora isso aqui" sem apontar arquivo, pasta ou sintoma

Quanto mais cego o pedido, mais tempo ele gasta procurando onde você já sabia que era

3. Ele propõe antes de mexer

Esse é o passo que muita gente pula e depois se arrepende

No modo plano, o Claude pesquisa e propõe mudanças SEM aplicá-las: ele lê o projeto com as ferramentas de leitura e escreve um plano, mas não edita o código-fonte

Três formas de ligar:

claude --permission-mode plan

Ou o prefixo /plan dentro da sessão

Ou Shift+Tab até a barra de status indicar o modo plano

O erro comum deste passo: pular o plano numa tarefa grande

Em mudança pequena, tudo bem ir direto. Em refactor que encosta em vários arquivos, o plano é o teu ponto de leitura antes do estrago

4. Você aprova

Quando o plano tá pronto, ele te pergunta o que fazer em seguida

São três opções: aprovar e usar o modo auto, aprovar e revisar cada edição manualmente, ou continuar planejando

Ao aprovar, a sessão SAI do modo plano e passa pro modo de permissão da opção que você escolheu

O erro comum deste passo: apertar a primeira opção no piloto automático

Essa escolha define se você vai ver cada diff ou se vai só acompanhar o resultado, então lê antes de clicar 😀

5. Ele age

Agora sim entram as ferramentas que mudam estado:

• Edit: faz substituições exatas de string em arquivos
• Write: escreve arquivo
• Bash: executa comandos em uma sessão de shell persistente

E aqui a regra vira o contrário do passo 2: ferramentas que modificam estado rodam em SEQUÊNCIA, pra evitar conflito

Faz sentido, né? Duas edições simultâneas no mesmo arquivo seria pedir pra dar ruim

O erro comum deste passo: liberar tudo de Bash sem pensar

Os rm -rf da vida existem, e o shell é persistente

6. Ele verifica e se corrige

O Claude decide cada passo com base no que aprendeu no passo anterior

Isso significa que ele encadeia dezenas de ações e se corrige no caminho, em vez de executar uma receita fixa decidida lá no começo

E você pode interromper a QUALQUER momento pra redirecionar

O erro comum deste passo: ficar assistindo caladinho enquanto ele vai pro lado errado

Interromper cedo custa um prompt. Deixar rolar custa uma sessão inteira e um diff que ninguém quer revisar

O que só acontece com sua aprovação: os modos de permissão

Todo esse fluxo passa por uma camada de permissão, e são seis modos disponíveis

Sobre o auto, vale detalhar, e tome cuidado com a ordem das coisas aqui: ele só aparece quando a organização permite e quando o modelo selecionado suporta, exigindo Claude Opus 4.6 ou posterior, Sonnet 4.6 ou posterior, ou um modelo Fable

Estando disponível, ele é o modo de permissão padrão pra sessões novas nos planos Pro, Max e Team, a menos que as configurações do usuário ou da organização mudem isso

O que acontece por baixo é interessante: um SEGUNDO modelo, o classificador, revisa as ações antes de rodarem

Ele bloqueia o que escala além do pedido, o que mira infraestrutura não reconhecida e o que parece dirigido por conteúdo hostil que o Claude leu

E as regras de permissão?

Aqui é onde você manda de verdade

São três tipos: allow libera a ferramenta sem aprovação manual, ask pede confirmação e deny impede o uso

A avaliação segue a ordem deny, ask, allow, e a PRIMEIRA correspondência decide

Ou seja: o que você negou fica negado, não adianta ter um allow mais permissivo depois

E tem um detalhe que explica aquele "por que ele parou de perguntar isso?": quando você escolhe a opção de não perguntar de novo num pedido de permissão de comando Bash, o Claude Code salva a aprovação como regra allow em .claude/settings.local.json

Pra ver tudo que tá valendo, roda /permissions: ele lista todas as regras e o arquivo settings.json de onde cada regra vem

E se ele mudar algo que você não queria?

O sintoma: a edição saiu diferente do combinado, ou a conversa foi por um caminho ruim e agora o projeto tá num estado que você não reconhece

A causa: lembra do passo 6? O agente decide passo a passo e encadeia ações

Então o desvio raramente aparece no primeiro turno, ele aparece depois de alguns, quando uma decisão pequena virou base pra três decisões seguintes. É o mesmo mecanismo por trás daquele caso clássico de correção que quebra outra parte do código

A solução: checkpointing

O Claude Code captura automaticamente o estado do código antes de cada prompt que inicia um turno

Pra voltar, você abre o menu de rewind com /rewind ou apertando Esc duas vezes com o campo de prompt vazio

O menu oferece quatro ações:

• restaurar código e conversa
• restaurar só a conversa
• restaurar só o código
• resumir a conversa daquele ponto em diante

Ele guarda snapshots de arquivo dos 100 checkpoints mais recentes de uma sessão

E tem uma coisa que sustenta isso tudo: a conversa é salva localmente em arquivo JSONL de texto puro em ~/.claude/projects/, o que permite rewind, resume e fork de sessões

Como prevenir:

• começar em modo plano nas tarefas que encostam em muita coisa
• escolher revisar cada edição manualmente quando o código é sensível
• usar deny pro que NUNCA pode rodar no teu projeto

Onde esse fluxo roda: terminal, IDE, desktop e web

O percurso é o mesmo em todo lugar, o que muda é onde você vê acontecer

Terminal: a CLI, o formato mais direto, e uma das superfícies que aceita provedores terceiros

VS Code: a extensão traz diffs inline, menções com @, revisão de plano e histórico de conversa dentro do editor

JetBrains: tem plugin com visualização interativa de diff e compartilhamento de seleção como contexto, ou seja, você seleciona o trecho e ele vira parte do pedido

App de desktop: dá pra revisar diffs visualmente, rodar várias sessões lado a lado, agendar tarefas recorrentes e iniciar sessões na nuvem

Web: as sessões na nuvem suportam Accept edits, Plan e Auto, mas não têm Bypass permissions

Tô vindo de outra ferramenta, perco minhas regras?

Não necessariamente, e esse é um ponto massa

Quando você roda /init, o Claude lê regras do Cursor (em .cursor/rules/ ou .cursorrules) e do Copilot (em .github/copilot-instructions.md) e incorpora as partes relevantes no CLAUDE.md gerado

O que esse fluxo parece na prática, rodando aqui

No vídeo abaixo eu rodo esse caminho inteiro num projeto começando do zero

Entrei em modo de planejamento com Shift+Tab ANTES de escrever o pedido, descrevi em linguagem natural um app de resenhas de livros com likes e página inicial com cards mostrando capa, título, autor e nota, e deixei a ferramenta virar isso num plano

No fim do plano veio exatamente a pergunta que descrevi lá em cima: aceitar as edições automaticamente, aprovar manualmente ou continuar refinando

E aí duas coisas do mundo real que valem mais que qualquer screenshot bonito

A primeira: o ciclo completo de execução desse projeto inicial levou quase meia hora na minha máquina

Não botei a culpa no modelo, não: era o INÍCIO de um projeto, e comparando com as dezenas de projetos que já criei, começar do zero é sempre o pedaço mais caro

A segunda: 2 tarefas apareciam como pendentes na lista de progresso quando na verdade já estavam concluídas

Perguntei e constatei que estavam prontas mesmo

Ou seja: a lista de progresso é INDICAÇÃO, não verdade final

Quem diz se a tarefa acabou é o diff e o estado do código, e isso conecta direto com a terceira fase do fluxo, a de verificar o resultado

Eu fui até o fim: rodei o projeto, tomei um erro de Next.js na cara, voltei pro chat e pedi a correção com um prompt curto

Depois da primeira correção o servidor ainda deu problema, e eu mesmo tive que pedir o reinício manualmente, além de sugerir o caminho da correção pro troço andar

Trabalhoso? Foi

Mas no fim validei usando o app de verdade: criei um livro, publiquei uma resenha, dei like, a contagem subiu e os dados persistiram 🙂

É por isso que aprovação e revisão existem no fluxo: o agente se corrige no caminho, e quem confere se a correção chegou onde devia é você

Veja o fluxo rodando em vídeo

No vídeo você vê a tela inteira: o modo de planejamento ligado antes do pedido, o plano sendo escrito, a pergunta de aprovação no fim dele, a execução rodando e a hora em que o projeto sobe e quebra

Conclusão

Resumindo o percurso todo numa linha: pedido, contexto, plano, aprovação, edição, verificação

É isso que tá acontecendo entre você digitar uma frase e o arquivo mudar, e é por isso que a definição seca de "ferramenta agentica" nunca explicou nada pra ninguém haha

O próximo passo concreto, se você ainda não rodou:

1. instala pelo instalador nativo ou pelo npm
2. entra na pasta do projeto e roda claude
3. roda /init pra deixar o CLAUDE.md pronto ANTES da primeira tarefa de verdade
4. começa em modo plano, lê o plano com calma e só depois aprova

Faça o teste e compara com o que você esperava, porque ver o fluxo é bem diferente de ler sobre ele…

Até o próximo post!