O que é o Claude Code? Os conceitos que você precisa entender antes da primeira sessão

Tu instala, roda o comando, e a primeira tela já joga uns termos na tua cara: diretório de trabalho, sessão, contexto, modo de permissão

E ninguém parou pra explicar nenhum deles

Fala aí, beleza? Se tu chegou no Claude Code sem referência nenhuma, esse post aqui é pra ti

Não é lista de prompt mágico (essas coisas toscas), e também não é aquele tutorial que manda tu decorar comando sem saber pra que ele serve

Comando vai aparecer aqui, sim, vários, mas sempre colado no conceito que ele representa

É o vocabulário mínimo pra tu abrir a primeira sessão sabendo o que tá acontecendo na tela: pasta de trabalho, sessão, contexto e permissão

São quatro conceitos, e eles conversam entre si o tempo todo 🙂

Para que serve o Claude Code na prática

O Claude Code é uma ferramenta agêntica de codificação: ele lê o código do projeto, edita arquivos, executa comandos e se integra com as ferramentas de desenvolvimento

Escrito assim parece pouco, mas a diferença pra uma caixa de chat comum é absurda

No chat comum, quem carrega contexto é você: copia o arquivo, cola, explica a estrutura, cola outro arquivo, explica de novo…

Aqui não

Ele lê a base sozinho, o que muda completamente tarefas como entender um código que você nunca viu

Ele edita arquivo direto no disco, em vez de te devolver um bloco pra você colar na mão

Formação Recomendada

Formação Claude Code

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

• 110 aulas
• 4 projetos
• 9h 2min

Conhecer formação

Ele roda comando

E ele alcança ferramentas externas via Model Context Protocol, os tais servidores MCP

Outra coisa que confunde bastante iniciante: ele não vive só no terminal

Ele roda em Terminal CLI, extensão de VS Code, IDEs JetBrains, app de desktop e web

O terminal é só a superfície mais famosa, não é a ferramenta inteira

Conceito 1: a pasta de trabalho é o mundo do agente

Esse é o conceito que mais gente entende errado no começo

O agente não trabalha "no seu computador"

Ele trabalha dentro de um escopo, e esse escopo tem regra clara

Por padrão, ele tem leitura e escrita no diretório de trabalho atual e nos subdiretórios dele

Mais os diretórios que você adicionar com --add-dir ou /add-dir

Mais o diretório temporário da sessão, apontado por $TMPDIR

É por isso que o fluxo de primeiro uso é esse aqui, e não outro:

cd meu-projeto
claude

O cd não é frescura de tutorial, se liga: ele é literalmente o que define o mundo que o agente enxerga naquela sessão

Abriu na pasta errada, ele vai enxergar a pasta errada

E como você confere isso? A interface mostra a versão, o modelo atual e o diretório de trabalho logo acima do campo de prompt

Criou o hábito de bater o olho ali antes de pedir qualquer coisa, você já evitou metade da confusão de iniciante

Precisou de uma pasta que tá fora do escopo (uma lib de referência, um outro repo), dá pra ampliar com /add-dir dentro da sessão ou com a flag --add-dir na hora de abrir

Conceito 2: sessão é a unidade de trabalho (e ela não some)

Sessão é a conversa: tem começo, meio e fim, e ela tá amarrada a uma pasta

Muita gente acha que fechou o terminal, perdeu tudo

Não é bem assim

As transcrições ficam salvas localmente em texto puro, em ~/.claude/projects/, por 30 dias por padrão, em arquivos .jsonl nomeados pelo UUID da sessão

E dá pra voltar pra elas de várias formas:

• claude --continue (ou -c) carrega a conversa mais recente daquele diretório
• claude --resume abre uma lista pra você escolher qual sessão retomar
• /resume faz isso de dentro de uma sessão que já tá rolando
• --fork-session cria um ID novo em vez de reusar o original

O --fork-session é aquele detalhe que parece bobo e não é: serve quando você quer partir de uma conversa antiga sem escrever por cima da linha do tempo dela

Entendeu sessão como unidade de trabalho, o próximo conceito cai sozinho na tua cabeça

Conceito 3: contexto é espaço finito, e é ele que decide a qualidade

Contexto é a memória de curto prazo da sessão

Tudo que entra na conversa ocupa espaço ali: o que você digitou, os arquivos que ele leu, a saída dos comandos que ele rodou, os erros que você colou

E aqui vai a parte que ninguém te fala no primeiro dia: contexto é finito

Quando ele lota, a qualidade cai, porque o modelo passa a trabalhar num histórico espremido em vez de trabalhar no seu problema

Aí entram os comandos de gestão, e eles são simples:

• /context mostra o que tá ocupando espaço no contexto
• /clear limpa a conversa
• /compact compacta o histórico

O /context é o mais subestimado de todos

É o teu raio-x: em vez de achar que o contexto encheu, você olha e vê o que encheu

E tem a compactação automática, que dispara quando a conversa atinge uma janela configurável

Dá pra ajustar com /autocompact (tipo /autocompact 500k ou /autocompact auto), com a flag --autocompact ou com a variável CLAUDE_CODE_AUTO_COMPACT_WINDOW, aceitando de 100K a 1M tokens

Tradução: a ferramenta tem um plano B automático pro contexto lotado

Mas plano B é plano B, o ideal é não deixar chegar lá

Como economizar contexto no dia a dia (e por que isso ficou mais importante)

Esse conceito 3 é o que mais dói no bolso, e eu falo isso por experiência recente

As minhas sessões passaram a durar menos, e a cota vem sendo consumida de forma bem mais agressiva do que antes

Não fui só eu não, muita gente reclamou disso publicamente

Eu acredito que esse limite menor veio pra ficar

E mesmo que o consumo melhore lá na frente, quem aprender a economizar token agora sai ganhando de qualquer jeito

No vídeo abaixo eu junto os conceitos que uso no dia a dia pra fazer a sessão render mais, e o mais fundamental deles é o arquivo de instruções do projeto

Sem ele, o Claude sai vasculhando arquivo atrás de arquivo só pra descobrir o padrão que você já tem na cabeça, e queima token nessas idas e voltas

Exemplo bem concreto: eu quero que todas as funções sejam comentadas

Se essa regra não tá escrita em lugar nenhum, ele vai abrir arquivos de funções pra inferir o padrão sozinho

E o mais legal é que dá pra pedir pro próprio Claude gerar esse arquivo pra você, e depois ir acrescentando o que for aparecendo

Só não deixa ele virar um monstro: arquivo de instruções gigante volta a ser o mesmo problema, porque ele entra inteiro como input e come token à toa

Meu conselho é manter bem enxuto

Outro ponto que pega gente nova: MCP instalado de forma global viaja de projeto em projeto

Ele acaba sendo usado sem necessidade, e ainda entra no contexto

No vídeo eu mostro na tela a lista de MCPs ativos do meu projeto, e o hábito que eu recomendo é esse: checar isso no início de cada projeto e desconectar o que você não vai usar

Eu prefiro instalar MCP por projeto, não global

Tem também um hábito bobo que queima contexto todo santo dia: colar o log de erro inteiro no chat

Na maioria das vezes, a primeira linha do erro, com o arquivo, já basta

Stack trace completo raramente é necessário, e colar tudo obriga o modelo a interpretar dado demais pra chegar na mesma conclusão

Vai no console, acha o erro, cola só o trecho relevante

E mais uma: pedir "inicia o projeto pra mim" faz o modelo interpretar contexto só pra acabar digitando o comando de dev que você já sabe de cor

Dá pra rodar comando de terminal direto, sem passar pela LLM

Se você assistir, sai de lá com os hábitos que fazem a sua cota durar mais na prática, não na teoria

Conceito 4: permissão é você decidindo o que ele pode fazer sozinho

O agente pede autorização antes de agir

E o quanto ele pede é ajustável, esse é o conceito

Dentro da sessão, o Shift+Tab alterna os modos: do modo normal pro auto-accept, que a tela mostra como ⏵⏵ accept edits on, e depois pro plan mode (indicador ⏸ plan mode on)

Só pra não te confundir: esse auto-accept e o accept edits do indicador são o MESMO modo, beleza? Daqui pra frente eu chamo ele de accept edits, que é o nome que aparece na tua tela

Ele e o plan mode merecem atenção porque fazem coisas bem diferentes

O que o plan mode faz:

No plan mode ele explora o código e produz um plano, sem editar arquivos-fonte

E edições nunca são auto-aprovadas nesse modo

É o modo mais confortável pra quem tá começando: você deixa ele entender o projeto e te contar o que pretende fazer antes de qualquer coisa acontecer no disco

O que o accept edits libera:

O accept edits auto-aprova duas coisas: as edições de arquivo e um conjunto fixo de comandos Bash de sistema de arquivos, que são mkdir, touch, rm, mv, cp e sed

E isso vale só pra caminhos dentro do diretório de trabalho

Outros comandos Bash e caminhos fora do escopo continuam pedindo permissão, um por um

Repara como o conceito 1 volta aqui: o escopo da permissão é o escopo da pasta de trabalho 😀

Tome cuidado com um detalhe: comandos de rede como curl e wget não são auto-aprovados por padrão

E tem outra coisa que pega muita gente de surpresa

Quando você aprova algo marcando "não perguntar de novo", isso vira uma regra allow gravada em .claude/settings.local.json

Se você iniciou numa subpasta de um repositório git, esse arquivo é lido e gravado na raiz do repositório, valendo pro repositório inteiro

Ou seja: aquele "tá, pode" que você deu com pressa não morre quando a sessão acaba

É o mesmo tipo de decisão de quando você vai deixar o agente commitar por você: não é sobre confiar ou não confiar, é sobre saber exatamente o que ficou liberado

Na linha de comando, o mesmo controle aparece na flag --permission-mode, que aceita default, acceptEdits, plan, auto, dontAsk, bypassPermissions ou manual (o manual exige Claude Code v2.1.200 ou superior)

A rede de segurança: checkpoints e rewind

Agora o medo natural: "e se ele fizer besteira nos meus arquivos?"

Pergunta justa, e existe uma rede embaixo de você

A ferramenta cria checkpoints automáticos das edições

Pra voltar atrás, você usa /rewind, ou aperta Esc duas vezes com o campo de prompt vazio, e o menu de rewind abre

As opções são: restaurar código e conversa, restaurar só a conversa ou restaurar só o código

Ele guarda snapshots dos 100 checkpoints mais recentes da sessão

Essa separação entre código e conversa é mto massa, viu?

Dá pra desfazer o que ele escreveu sem perder o raciocínio da conversa, e vice-versa

Memória: o que o Claude Code lembra entre uma sessão e outra

Lembra que sessão tem fim? Pois é, mas nem tudo termina com ela

O CLAUDE.md é o arquivo de instruções persistentes, lido no início de cada sessão

É markdown puro, nada de sintaxe esquisita

Os escopos são estes:

• ~/.claude/CLAUDE.md para o usuário
• ./CLAUDE.md ou ./.claude/CLAUDE.md para o projeto
• CLAUDE.local.md para o local

Não precisa escrever do zero: o /init gera um CLAUDE.md inicial, e o /context lista os arquivos de memória que foram carregados

Sacou por que o /context é tão útil? Ele te mostra contexto e memória na mesma olhada

Além do CLAUDE.md, existe a auto memory, que é o Claude anotando sozinho

Ela acumula notas entre sessões em quatro tipos: user, feedback, project e reference

Na interface aparecem mensagens tipo Saved 2 memories ou Recalled 2 memories, e é isso que elas significam

E tudo isso é markdown legível e editável, então você pode abrir e ajustar o que ele anotou

Quanto custa e o que você precisa para começar

Antes de instalar, vale saber o pré-requisito de acesso:

Com o acesso resolvido, vem a instalação

A via npm é esta:

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

Ela exige Node.js 18 ou mais novo

Mas se liga nisso: a documentação oficial recomenda o instalador nativo (macOS, Linux e Windows) e desaconselha o sudo npm install -g

Erro comum desse passo: bater de frente com erro de permissão no npm global e sair resolvendo no sudo, que é justo o caminho que a documentação pede pra evitar

E aí é aquele fluxo do começo do post:

cd meu-projeto
claude

No primeiro uso ele vai te pedir login

O que fazer antes da sua primeira sessão

Recapitulando os quatro conceitos, um em cada frase:

1. Pasta de trabalho: por padrão ele lê e escreve no diretório atual e nos subdiretórios, mais o que você adicionar com --add-dir ou /add-dir, mais o temporário da sessão em $TMPDIR
2. Sessão: é a conversa amarrada a uma pasta, salva em ~/.claude/projects/ por 30 dias por padrão e retomável com claude --continue, claude --resume ou /resume
3. Contexto: é espaço finito, e você administra ele com /context, /clear e /compact, com a auto-compactação como plano B
4. Permissão: é você decidindo o que ele faz sozinho, alternando com Shift+Tab entre normal, accept edits e plan mode

O próximo passo concreto? Escolhe um projeto pequeno, de preferência um que você já conhece

Entra na pasta dele, abre a ferramenta e começa em plan mode, só pra ver ele explorar e te devolver um plano sem tocar nos teus arquivos

Leu o plano, gostou, aí sim você libera as edições

É um jeito bem tranquilo de conhecer a ferramenta sem aquele frio na barriga de largar um agente solto no teu código 🙂

Até o próximo post!