O que é Claude Code de verdade

Field Note

Segunda-feira, 9h. Você herda um repositório que ninguém do time abre há seis meses e alguém pergunta "quanto tempo pra corrigir aquele bug do login?". Você abre o terminal, entra na pasta e digita claude. Em vez de colar trecho de código numa janela de chat, você pede: "descubra onde o login quebra depois que a sessão expira". Na tela aparecem leituras de arquivo, buscas, um teste rodando e falhando. Ninguém colou nada. Ele foi atrás.

Conceito

Claude Code é um agente: um programa que recebe um objetivo, escolhe ações, executa essas ações no seu ambiente e usa o resultado para decidir o próximo passo. Isso é bem diferente das outras coisas que costumam ser chamadas de "IA para código".

• Modelo: o cérebro que raciocina (Opus, Sonnet, Haiku e companhia). Sozinho, só devolve texto.
• Chat: você conversa com o modelo e copia o resultado. O contexto é o que você colou.
• Copiloto / autocomplete: sugere a próxima linha dentro do arquivo aberto. Enxerga pouco além dele.
• Agente: o modelo ganha ferramentas e um ambiente. Lê, busca, edita, roda comando, confere e repete.

A documentação oficial descreve o funcionamento como um loop agêntico em três fases que se misturam: coletar contexto, agir e verificar resultados. Uma pergunta sobre o código pode ficar só na primeira fase. Um bug passa pelas três várias vezes. E você faz parte do loop: dá para interromper com Esc a qualquer momento, ou digitar uma correção que entra na fila e é lida assim que as ferramentas em execução terminam.

O loop tem duas peças: o modelo, que raciocina, e as ferramentas, que agem. O Claude Code é a camada em volta do modelo que entrega as ferramentas e administra o que o modelo enxerga. A doc chama essa camada de agentic harness (o "arreio" do agente). As ferramentas nativas caem em cinco grupos:

1. Arquivos: ler, editar, criar, renomear.
2. Busca: achar arquivos por padrão e conteúdo por regex.
3. Execução: rodar comandos de shell, subir servidor, rodar teste, usar git.
4. Web: buscar na internet e ler documentação.
5. Inteligência de código: erros de tipo e "ir para definição", quando você instala um plugin de code intelligence.

Cada uso de ferramenta devolve informação que alimenta a próxima decisão. Esse é o ponto. Um chat responde e espera. Um agente responde, testa, lê o erro e tenta de novo.

Efeitos reais. Rodando local, o Claude Code acessa os arquivos do diretório onde você abriu a sessão, o seu terminal (qualquer comando que você conseguiria rodar), o estado do git e as extensões que você configurar, como servidores MCP. Edição de arquivo tem rede de proteção: antes de editar, ele tira um snapshot e você volta atrás com Esc duas vezes. Mas a doc é clara: ação em sistema remoto (banco, API, deploy) não tem checkpoint. Isso fica por conta do modo de permissão e das regras que você define.

Por que o projeto importa mais que o prompt. O agente trabalha com o que encontra. Um repositório com testes que rodam, um CLAUDE.md (arquivo de instruções do projeto lido no início de toda sessão) e comandos de build claros rende mais que o prompt mais caprichado num projeto bagunçado. Cada sessão começa com a janela de contexto zerada. O que precisa sobreviver entre sessões mora no CLAUDE.md e na auto memory, não na sua memória de "eu já expliquei isso ontem".

Quando usar

• A resposta depende de ler vários arquivos do projeto, não de conhecimento geral.
• A tarefa tem um jeito de ser verificada: teste, build, lint, script que compara saída.
• Você precisa entender um código desconhecido antes de mexer nele.
• O trabalho envolve uma sequência de passos que se alimentam: rodar, ler erro, ajustar, rodar de novo.

Quando não usar

• Pergunta conceitual que não depende do seu código ("o que é idempotência?"). Chat resolve mais barato.
• Você não sabe o que quer. Um agente executa bem uma intenção clara e executa rápido uma intenção errada.
• O ambiente toca produção sem nenhuma barreira (sem branch, sem permissão configurada, credencial de produção solta no terminal).
• A tarefa é determinística e repetitiva todo dia do mesmo jeito. Isso é script ou hook, não conversa.

Faça agora

A prática desta etapa é uma leitura somente exploratória. Nada de edição.

1. Escolha um projeto simples que você conheça mais ou menos. Um repositório pessoal serve.
2. Entre na pasta e abra o Claude Code em plan mode, o modo em que ele explora e propõe sem editar seus arquivos:

cd caminho/do/projeto
claude --permission-mode plan

3. Mande este pedido:

Explique o que este projeto faz, qual é o ponto de entrada e como eu rodaria os testes. Não altere nenhum arquivo. Ao final, liste quais arquivos você leu e quais comandos rodou.

4. Observe a tela enquanto ele trabalha. Anote cada ferramenta que aparece: leitura, busca, execução.
5. Rode /context para ver o que está ocupando a janela de contexto: instruções do sistema, ferramentas, arquivos lidos, conversa.
6. Monte o Mapa do loop agêntico: para três momentos da sessão, registre contexto (o que ele sabia), ação (o que fez), resultado (o que voltou) e nova decisão (o que mudou depois disso).

Armadilhas

• Tratar como chat. Colar código na conversa quando ele pode ler o arquivo direto. Você gasta contexto e perde a parte boa.
• Achar que ele leu tudo. Ele lê o que julga necessário. Se a resposta parece genérica, pergunte quais arquivos foram lidos.
• Confiar no checkpoint para tudo. Checkpoint cobre arquivo editado pelas ferramentas de edição. Comando que apaga, publica ou altera banco não volta com Esc.
• Esquecer o modo de permissão. A partir da versão 2.1.283, a doc indica auto mode como modo inicial padrão em sessões interativas no terminal e no VS Code: um classificador revisa as ações e ele edita e roda a maioria das coisas sem perguntar. Configuração sua ou da organização pode mudar isso. Confira o modo antes de pedir qualquer coisa e use Shift+Tab para alternar.
• Prompt longo para compensar projeto ruim. Se os testes não rodam, o agente não tem como verificar. Arrume o chão antes.

Material para levar

Mapa do loop agêntico, versão de bolso:

Tarefa:
Modo de permissão usado:

Ciclo 1
  Contexto: o que ele já sabia
  Ação: ferramenta usada (ler, buscar, executar, editar, web)
  Resultado: o que voltou
  Nova decisão: o que ele fez diferente por causa disso

Ciclo 2 (idem)
Ciclo 3 (idem)

Arquivos lidos:
Comandos executados:
O que eu precisei corrigir ou interromper:

Checklist rápido antes de qualquer sessão:

• Estou na pasta certa?
• Qual modo de permissão está ativo?
• Existe um jeito de verificar o resultado (teste, build, lint)?
• O que aqui não tem volta (banco, deploy, API externa)?