Claude Code em português: guia completo 2026

O que é o Claude Code?

Claude Code é uma ferramenta de linha de comando da Anthropic que coloca o modelo Claude dentro do seu projeto, com permissão para ler, escrever e executar. A diferença para o chat do navegador não é o modelo, é o acesso: em vez de você colar trechos de código e explicar a estrutura, o agente abre os arquivos, entende as dependências, roda o comando de teste e lê a saída. Você descreve o resultado que quer, ele faz o caminho até lá e te mostra o diff antes de aplicar, se você pedir assim.

Na prática, ele é um agente, não um autocompletar. Um autocompletar sugere a próxima linha enquanto você digita. O Claude Code recebe uma tarefa inteira, tipo "adiciona autenticação por e-mail nessa API e escreve os testes", e vai executando passo a passo, chamando ferramenta atrás de ferramenta. Ele roda no terminal, tem extensão para VS Code e JetBrains, versão no navegador e no desktop. O mesmo login serve para todas as superfícies do plano, segundo a documentação oficial da Anthropic.

Eu chamo ele de Claudinho, e uso desde os primeiros meses depois do lançamento, para site, landing page, backend em NestJS, automação e para a operação da minha própria empresa, que hoje roda dentro de um repositório. Falo por experiência: fiz site por anos em WordPress e Elementor e migrei tudo para o Claude Code, porque o resultado sai melhor e sai mais rápido. O que este guia tenta fazer é te poupar os meus tropeços iniciais.

Como o Claude Code funciona por dentro

Cada pedido seu vira um loop: o modelo lê o pedido, decide qual ferramenta usar, executa, lê o resultado e decide de novo, até considerar a tarefa concluída. As ferramentas são simples, ler arquivo, editar arquivo, rodar comando no shell, buscar texto no repositório, e é a combinação delas em sequência que faz o agente parecer inteligente. Quando ele roda o teste e o teste falha, a saída do erro volta para o contexto e ele tenta consertar, sem você colar nada.

O contexto é o recurso mais caro dessa arquitetura. Tudo que o agente leu na sessão fica na conversa e é reenviado a cada chamada, então uma sessão aberta o dia inteiro consome muito mais do que a sua atividade sugere. A própria documentação de custos explica que, com cache de prompt, o histórico é relido a preço de token em cache, e que a vida útil desse cache é de uma hora na assinatura e cai para cinco minutos com crédito extra. Por isso a regra número um de economia é limpar a sessão entre tarefas sem relação.

Em cima desse loop existem três camadas de personalização que vale conhecer desde o começo. O arquivo CLAUDE.md na raiz do projeto é a memória fixa, carregada em toda sessão, e é onde você diz stack, convenções e o que nunca fazer. As skills são instruções que só entram quando a tarefa pede, então não gastam contexto o tempo todo. E os hooks são scripts que rodam antes ou depois de uma ferramenta, tipo filtrar a saída do teste. Eu trato essas três coisas como o produto de verdade, o modelo é só o motor.

Como usar o Claude Code no dia a dia?

O passo a passo de instalação, com Windows, terminal, VS Code e a primeira tarefa rodando, eu escrevi separado em Claude Code na prática: como configurar e usar. Não vou repetir aqui, porque tutorial repetido envelhece em dois lugares ao mesmo tempo. O resumo cabe em uma linha: instala pelo npm, roda claude na pasta do projeto, faz login com a conta do plano pago e começa a pedir. O que muda o resultado não é a instalação, é o jeito de pedir.

No meu processo, o dia começa com o agente lendo o estado do repositório e o que ficou pendente, e a partir daí eu trabalho por tarefa fechada: uma coisa por vez, com critério de aceite escrito antes, e commit quando passa. Para tarefa que mexe em mais de três arquivos eu uso o modo de planejamento primeiro, ele explora o código, propõe o caminho e só executa depois que eu aprovo, o que evita descobrir no fim que a direção estava errada. Pedido vago tipo "melhora esse código" faz ele varrer o projeto inteiro à toa.

Os comandos que eu mais uso são poucos. /clear entre tarefas sem relação, /compact quando a sessão fica pesada e eu ainda preciso do fio da meada, /model para trocar de modelo no meio, /usage para ver quanto da janela do plano já foi, e Escape duas vezes para voltar a um ponto anterior quando ele saiu pela tangente. O resto é conversa, em português mesmo, porque o modelo entende e responde no idioma que você escreve, sem configurar nada.

Tutorial: a primeira tarefa de verdade em cinco passos

Tutorial de "hello world" não ensina a trabalhar com agente, então o meu primeiro exercício é uma tarefa real e pequena num projeto que já existe. Escolhe um bug conhecido ou uma melhoria que você resolveria em uma hora, porque aí você tem como julgar o resultado. Se você não tem projeto, cria uma landing page estática de uma seção, é o suficiente para sentir o fluxo sem precisar de backend.

1. Escreve o CLAUDE.md antes do primeiro pedido. Cinco linhas bastam: stack, como rodar o projeto, como rodar o teste, convenção de nome e o que ele não pode tocar. Sem isso ele adivinha, e adivinha diferente a cada sessão.
2. Pede em modo de planejamento. Descreve o resultado, não a solução, e inclui o critério de aceite, tipo "o teste X passa" ou "a página abre sem erro no console". Lê o plano que ele devolve e corrige antes de liberar.
3. Deixa ele executar e lê cada diff. No começo, aprova arquivo por arquivo. É lento, só que é aqui que você aprende a ler o código que o agente escreve, e essa leitura é a habilidade que separa quem sustenta o projeto de quem trava no primeiro bug.
4. Roda o teste ou abre a página você mesmo. O agente diz que terminou, e a palavra final é sua. Quando algo quebra, cola o erro inteiro, não um resumo, porque o stack trace é o que ele usa para achar a causa.
5. Faz o commit e limpa a sessão. Tarefa fechada, commit feito, /clear. A próxima tarefa começa com o contexto limpo e o CLAUDE.md como memória, e é assim que o custo fica previsível.

Se isso rodou uma vez, você já está na frente de muita gente que só viu vídeo. O próximo nível é transformar esse ritual em processo, com PRD, tarefas atômicas e dois agentes se revisando, e é sobre isso que os posts do fim desta página falam. Não pula etapa: quem começa pelo processo sem ter rodado a tarefa simples não sabe o que o processo está protegendo.

Dá para usar o Claude Code de graça?

Não, e é melhor saber isso antes de instalar. O plano gratuito do Claude existe, só que ele cobre o chat no navegador, e a página de preços da Anthropic diz explicitamente que o Claude Code não está incluso nele, conferido em 15/09/2026. O que dá para fazer sem pagar é testar o modelo no chat, ler a documentação, que está em português, e preparar o projeto, ou seja, escrever o CLAUDE.md e organizar o repositório, para que a primeira hora paga renda de verdade.

O Codex da OpenAI tem uma porta gratuita que o Claude Code não tem. Em 15/09/2026, a página de preços do Codex listava o plano Free do ChatGPT com a descrição "explore as capacidades do Codex em tarefas rápidas de código", e o plano Go, de US$ 8 por mês, para tarefa leve. Então se o seu orçamento é zero e você quer sentir o que é trabalhar com agente, o caminho hoje é o Codex no plano gratuito, sabendo que o limite é apertado e que a experiência completa começa nos vinte dólares, nas duas casas.

Existe uma terceira via que eu não recomendo para quem está começando: usar o Claude Code com chave de API e pagar por token. Funciona, e é o que a Anthropic mede em empresa, com média de cerca de US$ 13 por desenvolvedor por dia ativo, segundo a documentação de custos. Para quem está aprendendo, isso vira fatura imprevisível, porque a curva de aprendizado é cheia de sessão longa e pedido ruim. Assinatura tem teto, e teto é o que você quer no primeiro mês.

Quanto custa o Claude Code em 2026?

O Claude Code não tem preço próprio, ele vem dentro da assinatura do Claude, e o Codex vem dentro da assinatura do ChatGPT. Todos os valores abaixo foram lidos na página oficial de cada empresa em 15/09/2026, e se você está lendo isto muito depois dessa data, trate como ordem de grandeza e confira na fonte. As duas portas de entrada custam o mesmo, vinte dólares por mês, e é onde quase todo mundo deveria começar.

Sobre limite, a informação que mais falta nos guias em português: no Claude, o uso do Claude Code e do chat sai da mesma cota, que renova numa janela móvel de cinco horas e tem um teto semanal por cima. Quando você bate na janela, a mensagem diz a hora em que ela renova, e desde a versão 2.1.234 o agente consegue esperar sozinho e continuar a tarefa interrompida. Dá para comprar crédito extra para passar do teto, e eu só recomendo isso para quem já sabe medir o próprio consumo com o /usage.

No meu caso, eu não uso API, é muito caro para trabalho interativo, e invoco os agentes pela linha de comando aproveitando os limites das assinaturas mensais. Como eu tenho mais de uma conta, mantenho um script que monitora a janela de cada uma e troca a credencial sozinho quando um limite está acabando, sem interceptar chamada nem mandar nada para terceiro, ele só muda a chave. Não é solução para quem está começando, é para quem roda agente o dia inteiro, e cito porque "como tu aguenta o limite" é a pergunta que eu mais recebo.

Claude Code ou Codex: qual leva vantagem em quê?

Os dois fazem a mesma coisa no geral, recebem uma tarefa, leem o repositório e executam, e mesmo assim eles não são intercambiáveis no dia a dia. Eu uso os dois, no mesmo projeto, e a divisão abaixo saiu de comparar as duas ferramentas nas mesmas tarefas, não de ler documentação. Não é uma regra, é o que funciona no meu processo, e o ideal é testar no seu.

Se tiver que ficar com um só, o critério que eu dou é o tipo de trabalho. Quem faz mais site, interface e produto começa pelo Claude Code, porque a conversa sobre o que construir é melhor. Quem vive de backend, integração e código que precisa passar em teste começa pelo Codex. E quem quer os dois deveria fazer o que eu faço: um escreve, o outro revisa, e nenhum código chega no main sem a revisão cruzada, porque cada modelo tem um ponto cego diferente.

Em outubro eu publico o resultado de rodar a mesma tarefa nos dois, com tempo, tamanho do código e teste medidos, e aí esta seção ganha o link. Enquanto isso, se você quer ver os dois trabalhando juntos num fluxo real, o post Claude Code e Codex juntos: como dividir o trabalho mostra a divisão de papéis que eu uso. O post de worktrees mostra como os dois mexem no mesmo repositório sem um desfazer o trabalho do outro.

Claude Code vs Cursor: editor com IA ou agente no terminal?

A comparação com o Cursor é a que mais gera confusão, porque as duas ferramentas parecem concorrentes e não são exatamente. Cursor é um editor, um fork do VS Code com IA integrada na interface, e o Claude Code é um agente de terminal que funciona com qualquer editor, inclusive dentro do próprio Cursor. Em 15/09/2026, o Cursor Pro custava US$ 20 por mês, com um plano Hobby gratuito e limitado, então o preço de entrada é igual ao do Claude Pro e a escolha não passa por dinheiro.

O Cursor leva vantagem quando o seu trabalho depende de ver o resultado visual rapidamente e iterar dentro do arquivo, frontend com muita interação de UI por exemplo, porque a IA está a um atalho de distância do código que você está olhando. O Claude Code leva vantagem em tarefa que atravessa o repositório, tipo "roda os testes, corrige o que falhou e faz o commit", porque ele foi feito para operar em sequência sem você guiar cada passo. Muita gente usa os dois, e não é redundância, são ferramentas de momentos diferentes.

Eu escrevi uma comparação mais longa em Cursor vs Claude Code: qual usar no dia a dia, e a conclusão de lá continua valendo: a escolha depende do seu fluxo de trabalho, não de qual tem mais hype no momento. Se você está começando, escolhe um só e aprende a conversar com ele direito, porque trocar de ferramenta não conserta pedido mal escrito, e pedido mal escrito é o problema de noventa por cento das pessoas que me chamam achando que o modelo é fraco.

Skills, subagentes e worktrees: o que muda quando o projeto cresce

O Claude Code funciona bem em projeto de um arquivo com o que vem de fábrica. O que separa uso de brinquedo de uso profissional são três recursos que só fazem sentido quando o projeto passa de certo tamanho, e eu vou resumir cada um e apontar o post que aprofunda, em vez de repetir o tutorial aqui. A ordem em que eu adotei foi essa mesma: skills primeiro, depois subagentes, depois worktrees.

Skill é uma pasta com um arquivo de instruções que o agente carrega só quando a tarefa pede, então você tira do CLAUDE.md tudo que é específico de um tipo de trabalho e o contexto base fica leve. Eu tenho skill de SEO, de design, de checklist de segurança, de contrato, e elas são o motivo de o resultado sair consistente entre projetos. O que é, como criar e quais eu uso está no guia de skills do Claude Code, o tutorial conversado em Claude Code Skills: como criar uma habilidade própria, e as prontas na loja de skills.

Subagente é um Claude dentro do Claude, com contexto separado, que você usa para operação barulhenta: rodar teste, ler log gigante, vasculhar documentação. O resumo volta para a conversa principal e o ruído fica lá. Não é para tudo, e o post Subagentes no Claude Code: quando usar e quando evitar explica onde ele atrapalha. Worktree é o recurso do Git que dá uma pasta por branch, e é o que me deixa rodar Claude Code e Codex em paralelo no mesmo repositório sem conflito, explicado em Git e worktrees com dois agentes.

Quanto tempo e quanto custa construir um SaaS com Claude Code?

Régua real, do meu processo, e não estimativa de time humano. Uma aplicação simples, tipo container mais webhook mais uma tela de projetos e upload de arquivo, sai em cerca de duas horas. Noventa por cento dos sistemas que eu construo ficam abaixo de trinta dias. Software grande de verdade, com muito domínio e integração, leva de um a dois meses. Quem calcula prazo de agente com a cabeça de time de dez pessoas erra para cima por um fator enorme, e quem acha que é instantâneo erra para baixo, porque o gargalo vira revisão e decisão, não digitação.

O custo do primeiro ano cabe numa conta de três linhas: assinatura dos agentes, que fica em cerca de cem reais por mês por conta, infraestrutura, que para SaaS pequeno é uma VPS e um banco, e o seu tempo. Eu abri as faixas reais em Quanto custa criar um SaaS com IA em 2026, e a régua de prazo por tipo de projeto em Quanto tempo leva construir um SaaS com IA, os dois com o que atrasa projeto tocado por agente, que quase nunca é o código.

O processo inteiro, do PRD ao deploy, está em Como construir um SaaS com Claude Code e Codex. O método que segura o projeto quando ele passa de um arquivo, com especificação que o agente executa e tarefas atômicas, está em Spec-driven development com Claude Code e Codex. Vibe coding leva até o protótipo, e o que leva até a produção é processo, então os dois posts são a continuação natural deste guia.

Os erros que eu mais vejo em quem está começando

O primeiro é tratar o agente como chat. A pessoa cola um erro, recebe um remendo, cola o próximo erro, recebe outro remendo, e em uma hora tem um código que ninguém entende. Agente recebe tarefa com critério de aceite, não pergunta solta, e quando o critério está escrito ele diagnostica a causa em vez de tapar o sintoma. Se a sua sessão virou pingue-pongue de erro, para, limpa e reescreve o pedido com o resultado esperado.

O segundo é sessão eterna. Contexto acumulado custa caro e piora a resposta, porque o modelo carrega decisões velhas que já não valem. Uma tarefa por sessão, commit no fim, /clear e a próxima. O terceiro é pular a leitura do diff, achando que aprovar tudo economiza tempo; economiza hoje e cobra na semana que vem, quando algo quebra e você não sabe o que o agente mudou. Ler o diff é a parte do trabalho que continua sendo sua.

O quarto é escolher ferramenta pelo hype e trocar a cada vídeo novo. Cada troca zera o que você aprendeu sobre como pedir, e é o pedido que define o resultado. O quinto é não ter CLAUDE.md, ou ter um de duzentas linhas que ninguém lê, inclusive o modelo. Curto, na raiz, com o que importa, e o resto vai para skill. Quem corrige esses cinco pontos costuma dobrar o rendimento sem mudar de plano nem de modelo, isso eu vejo toda semana na mentoria.

Perguntas frequentes sobre o Claude Code

Preços e limites conferidos em 15/09/2026 nas páginas oficiais da Anthropic e da OpenAI. Página atualizada em 15/09/2026. Quando eu atualizo, a data muda junto.