Claude Code

O que é Claude Code e quando ele ganha do chat

Claude Code roda no seu terminal e mexe nos seus arquivos de verdade, em vez de você copiar e colar do chat. Ganha quando o trabalho é num projeto real, não numa pergunta solta.

Se você não sabe quando ele ganha do chat comum, vai usar pra tudo e se frustrar na metade. Ele brilha em cima de projeto real, não em pergunta avulsa.

• A diferença entre um chat que responde e um agente que lê seus arquivos, roda comando e edita código
• Onde ele roda: terminal, IDE, desktop e navegador
• Que tipo de tarefa vale mandar pra ele e qual não vale
• Que ele age no seu sistema de verdade, então erro dele tem consequência real

Abre a doc de visão geral, lê a introdução e lista 3 tarefas suas da semana que se encaixam no perfil dele (repetitivas, num projeto que já existe).

Você consegue explicar em uma frase por que usaria Claude Code em vez de colar código no chat.

Terminal, IDE ou desktop: onde rodar

Dá pra usar no terminal puro, dentro do VS Code ou no app de desktop. Comece onde você já trabalha, o resto é preferência.

Escolher o ambiente errado te faz achar a ferramenta pior do que ela é. Cada um serve um estilo de trabalho.

• Terminal (CLI): controle total, bom pra quem já vive no shell
• VS Code e JetBrains: diff visual e contexto do editor
• Desktop e web: tarefa longa e várias sessões em paralelo
• Que dá pra alternar, a conta e o login são os mesmos

Instala em pelo menos dois ambientes (por exemplo terminal e VS Code) e roda a mesma tarefa boba nos dois pra sentir a diferença.

Você sabe qual ambiente vai ser seu padrão e por quê.

Instalação e primeiro projeto

Instalar leva minutos. O primeiro "faz funcionar" é pedir uma tarefa pequena num projeto de teste, não no código que paga sua conta.

Errar a instalação trava todo mundo na largada. E o primeiro projeto ser de teste evita você quebrar código que importa enquanto aprende.

• Instalar pelo instalador nativo ou via npm
• Rodar o claude e autenticar
• Usar claude doctor quando algo parecer quebrado
• Começar num repositório de teste, não no que paga sua conta

Instala, cria uma pasta de teste com um arquivo simples e pede pro Claude explicar ou mudar esse arquivo. Observa ele agir.

O comando claude roda, você autenticou, e ele já leu um arquivo seu.

Como ele cobra: tokens e custo na prática

Cada tarefa gasta token, e projeto grande gasta rápido. Entender isso agora te salva do susto na fatura depois.

Custo de IA é problema de arquitetura, não de tabela de preço. Entender token agora evita a surpresa na conta lá na frente.

• Que cada token processado custa, e contexto grande custa mais
• Que prompt caching e auto-compactação reduzem custo sozinhos
• Usar /usage pra ver seu gasto na hora
• Que o modelo mais barato resolve a maioria das tarefas

Roda uma tarefa média e depois abre /usage pra ver quantos tokens ela consumiu. Repete com o contexto menor e compara.

Você consegue estimar de cabeça se uma tarefa vai custar centavos ou dólares.

Dar contexto certo

O Claude é tão bom quanto o contexto que você dá. Diz o que é o projeto, o que você quer e o que não pode quebrar, antes de mandar ver.

O maior gargalo do Claude Code é contexto, não inteligência. Ele só entrega bem o que você contou direito.

• Dizer o objetivo, os arquivos certos e o que não pode quebrar
• Apontar o que importa em vez de despejar o repo inteiro
• Que o desempenho cai quando o contexto enche
• Deixar o Claude buscar o que precisa em vez de você colar tudo

Pega uma tarefa e escreve o contexto em 3 linhas antes de pedir. Compara o resultado com um pedido sem contexto nenhum.

Seus pedidos incluem objetivo, arquivos relevantes e limites, sem despejar o projeto todo.

Editar, rodar, iterar

O ciclo é sempre o mesmo: ele edita, você roda, olha o resultado e ajusta. Trabalho de IA é conversa em loop, não pedido único.

Quem espera acertar de primeira desiste rápido. O valor está em iterar rápido, não em acertar de uma vez.

• O ciclo: ele edita, você roda, olha e ajusta
• Dar feedback específico do que ficou errado
• Rodar o código de verdade em vez de confiar no papel
• Ir em passos pequenos em vez de um pedido gigante

Pede uma funcionalidade pequena, roda, e faz pelo menos duas rodadas de ajuste com feedback específico até ficar do jeito que você quer.

Você trata o Claude como par de iteração, não como máquina de resposta única.

Ler erro e corrigir em loop

Deixa o Claude ler o próprio erro e tentar de novo. Boa parte do trabalho é ele se corrigindo, com você vigiando.

Se você souber fechar o loop de correção, ganha velocidade de graça. E aprende a cortar quando ele começa a piorar.

• Colar a mensagem de erro de volta pra ele
• Pedir pra ele rodar os testes e corrigir as falhas
• Deixar ele iterar sozinho no erro, com você vigiando
• Perceber quando ele entra em loop de conserto que piora tudo

Deixa um bug de propósito, cola o erro e termina o pedido com "roda os testes e corrige as falhas". Vê ele fechar o loop.

Você consegue fazer o Claude corrigir o próprio erro sem microgerenciar cada passo.

Quando ele erra e como você percebe

Ele erra com confiança. Aprender a farejar quando a resposta cheira errado vale mais que qualquer comando.

IA erra com segurança, inclusive em código que parece certo. Sem faro pra isso, você sobe bug achando que subiu solução.

• Que IA inventa com segurança, inclusive código plausível
• Desconfiar de mudança em código que você não entende
• Verificar em vez de confiar: rode e leia o diff
• Onde errar custa caro, exigir prova, não fé

Pega uma resposta que o Claude deu como certa e checa manualmente se cada afirmação se sustenta. Anota onde ele exagerou.

Você não aceita saída da IA sem uma forma de verificar.

CLAUDE.md e regras de projeto

Um arquivo de regras diz pro Claude como se comportar no seu projeto toda vez, sem você repetir. É a diferença entre ferramenta e bagunça.

Sem regras de projeto você repete as mesmas instruções toda sessão. O CLAUDE.md carrega esse contexto sozinho, toda vez.

• Rodar /init pra gerar um CLAUDE.md inicial do seu projeto
• Colocar comandos, convenções e decisões que ele não adivinha
• Manter curto (a régua da comunidade é até 200 linhas)
• Commitar no Git pra todo mundo do time herdar o mesmo setup

Roda /init num projeto real, corta o que é óbvio e deixa só o que o Claude não teria como saber sozinho.

Seu projeto tem um CLAUDE.md enxuto que para de te fazer repetir contexto.

Documentação como contexto

Doc não é burocracia aqui, é combustível. Quanto melhor o projeto se explica, melhor o Claude trabalha nele.

Documentação vira contexto que o Claude lê sozinho. Projeto que se explica reduz o retrabalho da IA.

• Que documentação vira contexto que o Claude lê sozinho
• Separar regra estável (CLAUDE.md) de doc detalhada (carrega quando precisa)
• Escrever pra máquina e pra humano ao mesmo tempo
• Que projeto bem documentado reduz o retrabalho da IA

Documenta um módulo do seu projeto e depois pede pro Claude uma tarefa nele. Compara com fazer o mesmo num módulo sem doc.

Você usa documentação como alavanca de contexto, não como obrigação chata.

Estrutura de projeto que ele entende

Projeto organizado é projeto que a IA navega. Pasta baguncada confunde o Claude tanto quanto confunde gente.

Busca por arquivo (glob e grep) funciona muito melhor num repo limpo. Bagunça de pasta vira bagunça de contexto.

• Estrutura de pastas previsível e nomes claros
• CLAUDE.md em subpastas pra contexto local sob demanda
• Manter o que muda junto, perto
• Que busca por arquivo funciona melhor num repo limpo

Olha seu projeto com olhos de quem chega agora e arruma uma parte confusa. Pede algo pro Claude nela antes e depois.

Um estranho (ou uma IA) entende a estrutura do seu projeto sem mapa.

MCP: dar ferramentas pro Claude

MCP deixa o Claude usar outras ferramentas, tipo banco de dados e API. É quando ele para de só escrever código e começa a agir.

É o pulo de assistente pra agente que age. Também é o mais pesado em contexto, então ligar tudo sai caro.

• Que MCP conecta o Claude a sistemas externos (banco, API, browser)
• Adicionar servidor com claude mcp add
• Que muitos servidores enchem o contexto rápido (custo)
• Ligar só o que você usa e desligar o resto com /mcp

Conecta um servidor MCP simples (de um sistema que você já usa) e pede uma tarefa que dependa dele.

Você conectou pelo menos um MCP e entende o custo de contexto que ele traz.

Skills e tarefa repetida

Skill é você ensinar um procedimento uma vez e reusar sempre. Bom pra tudo que você faz igual toda semana.

É como você para de reexplicar o mesmo fluxo. Barata em contexto: só carrega quando o gatilho bate.

• Que skill é uma pasta com SKILL.md: gatilho + instruções
• Que ela carrega só quando o gatilho bate (barata em contexto)
• Invocar por /nome ou deixar o Claude acionar sozinho
• Bons candidatos: revisão de PR, mensagem de commit, checklist de deploy

Pega um fluxo que você repetiu duas vezes essa semana e transforma numa skill. Testa acionando por nome.

Você tem pelo menos uma skill sua que substitui uma instrução que vivia repetindo.

Rodar tarefa longa sem segurar a mão

Dá pra soltar o Claude numa tarefa grande e deixar ele tocar. O truque é preparar o terreno pra não voltar tudo errado.

Delegar bem multiplica seu alcance. Delegar mal volta um monte de código errado que dá mais trabalho que fazer na mão.

• Usar plan mode: ele planeja, você aprova, depois ele executa
• Quebrar trabalho grande em passos verificáveis
• Pedir commits a cada etapa pra poder reverter
• Delegar a subagente o que é amplo (buscar, resumir) e ficar inline no que é profundo

Pega uma tarefa multi-arquivo, entra em plan mode, revisa o plano antes de aprovar e só então deixa executar.

Você delega uma tarefa longa com plano aprovado e checkpoints, sem babá.

Segurança: o que não deixar ele fazer

Autonomia sem limite é pedido de encrenca. Defina o que o Claude pode e não pode tocar antes de dar corda.

Um agente que roda comando e lê arquivo pode fazer estrago de verdade. Cerca antes de dar corda não é paranoia, é o básico.

• Definir allowlist e deny com /permissions
• Bloquear leitura de .env e arquivos de credencial
• Nunca colar chave ou token na conversa
• Usar sandbox ou branch isolada pra tarefa arriscada
• Que hook garante uma regra sempre, o que instrução no CLAUDE.md não garante

Configura uma regra de allow pra um comando que você aprova sempre e uma de deny pra algo que nunca pode acontecer.

O Claude tem limites explícitos e não acessa o que é sensível no seu projeto.

Revisar código de IA antes de subir

Código que a IA escreveu ainda é você que assina. Revisar antes de subir não é opcional, é o trabalho.

Código de IA muitas vezes funciona por fora e esconde bug sutil por dentro. A revisão é a única rede.

• Ler o diff antes de aprovar, sempre
• Rodar os testes e não confiar no "parece certo"
• Manter PR pequeno e focado pra revisão dar conta
• Que você é o responsável final pelo que leva seu nome

Numa mudança que o Claude fez, lê o diff linha por linha e roda os testes antes de commitar. Acha pelo menos um ponto pra questionar.

Nada sobe sem você ter lido o diff e rodado o que valida.

Custo sob controle em projeto grande

Projeto grande com IA vira caro sem você ver. Modelo certo pra cada tarefa e contexto enxuto seguram a conta.

O custo cresce mais rápido que linear quando o projeto escala. Sem disciplina, a fatura vira o motivo do projeto morrer.

• Rotear tarefa simples pro modelo barato e a difícil pro potente
• Manter CLAUDE.md e contexto enxutos
• Usar /clear e compactação pra não arrastar contexto morto
• Acompanhar o gasto com /usage por skill, subagente e MCP

Faz uma dieta de contexto num projeto seu: corta o que o Claude não precisa carregar e mede o /usage antes e depois.

Você tem uma rotina pra manter o custo sob controle em projeto que dura.

Erros que mandam projeto pro Cemitério

Os mesmos erros derrubam projeto atrás de projeto. Conheça eles antes de repetir.

A maioria dos projetos de IA morre pelos mesmos motivos. Conhecer o padrão antes te tira da estatística.

• Dar autonomia demais sem revisão
• Nunca modelar custo antes de escalar
• Fazer demo bonita que nunca vira workflow real
• Confiar na saída sem verificar

Lê os post-mortems do Cemitério e marca quais desses erros você já quase cometeu. Anota como evitar da próxima.

Você reconhece os padrões de fracasso antes de repetir eles.

Quer isso rodando no seu time?

Quer isso rodando no seu time, não só no seu terminal? É o que eu faço pra fora.