Primeiros passos com o Claude Code

Usar IA numa janela de chat te dá um papel que ninguém nomeia: o de entregador. Você descreve o problema, ela devolve o código, você copia, cola, roda, copia o erro de volta, cola de novo. O código sai em três segundos. A ida e volta é que custa a tarde.

O Claude Code corta o entregador. É o mesmo modelo, só que com permissão de abrir os arquivos do seu projeto, ler, editar e rodar comando. Você deixa de colar e passa a revisar.

O outro guia deste módulo é sobre pedir bem e conferir o que volta: stack, contrato, restrições, estados, e as sete perguntas de revisão. Nada disso muda aqui. O que muda é que agora você revisa arquivo em vez de bloco de texto, e quem abre o arquivo é ele.

As três coisas que quebram o primeiro uso

Antes de qualquer passo, porque as três acontecem antes de você escrever a primeira frase:

. precisa de plano pago. Assinatura Claude (Pro, Max, Team ou Enterprise) ou uma conta do Claude Console com crédito. Não tem versão de graça . é a aba Code, não a Chat. O app tem três abas, e só uma delas enxerga arquivo. Essa é a que mais pega gente, e a próxima seção é só sobre ela . no Windows, precisa do Git instalado. Sem ele a aba Code não abre na primeira vez. Instala o Git for Windows e reinicia o app, senão ele não percebe

A aba certa

Essa é a armadilha silenciosa, e vale entender por que ela é silenciosa.

O app do Claude tem três abas: Chat, Cowork e Code. Você abre o app, cai na Chat, que é a conversa de sempre, pede pra ele olhar seu projeto e ele não olha. Nada dá erro. Nenhuma mensagem diz "você está no lugar errado". A conclusão óbvia, e errada, é que a ferramenta não enxerga arquivo.

Enxerga. É a aba Code que faz isso, e ela é a única das três que abre uma pasta do seu computador.

Então o caminho inteiro é: baixa o app no claude.ai, instala, entra na sua conta, e clica em Code. Se você está no Windows e a aba não abre, é o Git faltando: instala e reinicia o app.

A primeira sessão

Antes de digitar, a aba Code te pede quatro escolhas. Só duas importam agora:

A pasta é a decisão que mais importa. Ele trabalha dentro dela e não sai dela, então apontar pra pasta certa não é detalhe, é o escopo do que ele pode tocar.

Daí você escreve em português, como escreveria pra uma pessoa:

o que esse projeto faz?

onde fica o componente de botão?

me explica esse arquivo linha por linha, como se eu nunca tivesse visto React

Repare que você não anexou nada. Ele procura, abre e lê o que precisar. Essa é a diferença que faz a conta fechar: descrever o arquivo pra IA custava mais tempo que ler o arquivo.

Quando você quiser apontar, tem dois jeitos. @ seguido do nome do arquivo joga ele na conversa, e arrastar uma imagem pra caixa de mensagem funciona: print de bug, referência, ou o seu próprio mockup. Ele lê tela.

Permissões, ou "ele vai mexer nos meus arquivos sem perguntar?"

Não, e essa é a parte que dá pra configurar. O seletor de modo fica do lado do botão de enviar, e muda a qualquer momento no meio da sessão.

Começa em Manual. É mais lento e é o ponto: cada mudança passa pela sua frente antes de existir. Quando cansar de aprovar, aí sim vale soltar.

O Plan é o modo mais subestimado. Ele lê o projeto inteiro, monta a proposta e para: você lê o que ele ia fazer antes de qualquer arquivo ser tocado. É a diferença entre revisar um design antes e depois de ele ir pra produção.

E vale a rede de segurança que não é dele: commita antes de soltar. Com o Git em dia, "desfazer tudo" é um comando. Sem ele, não é nada.

Comentar no diff, que é comentário de Figma com outro material

Essa é a parte que ninguém conta, e é a que mais parece com o seu trabalho.

Quando ele mexe nos arquivos, aparece um contador de linhas mudadas, tipo +12 -1. Clicando nele abre o diff: a lista de arquivos de um lado, as mudanças do outro. Até aí é o que qualquer ferramenta de código faz.

O que muda é que você pode clicar em uma linha do diff e comentar nela. Escreve o que está errado, dá Enter, comenta em outra linha, comenta numa terceira. Quando terminar, Cmd+Enter no Mac ou Ctrl+Enter no Windows envia tudo de uma vez. Ele lê os seus comentários e refaz, e o resultado volta como um diff novo pra você revisar de novo.

Para e olha o que isso é. Você abriu o trabalho de outra pessoa, apontou o dedo em três pontos específicos, escreveu o porquê em cada um, e mandou de volta pra segunda rodada. Isso é comentário de Figma. É exatamente o ritual que você já faz todo dia, no mesmo formato, com o mesmo tipo de frase. Só que o material é código e a segunda rodada chega em segundos.

Tem também o Review code, no canto do diff, que pede pra ele revisar as próprias mudanças antes de você commitar. Ele deixa os comentários no diff, no mesmo lugar onde você deixaria os seus, e você responde ou pede pra refazer. Ele mira erro de compilação, erro de lógica e falha de segurança, e de propósito não fala de estilo nem de formatação. A revisão de interface continua sendo sua, o que é a boa notícia dessa história inteira.

CLAUDE.md, a memória do projeto

Toda sessão nova começa do zero. O CLAUDE.md é o arquivo que resolve isso: ele é lido no começo de toda conversa, e é onde moram as coisas que você não quer repetir nunca mais.

Pra criar o primeiro, digita na conversa:

/init

Ele lê o projeto e escreve uma versão inicial com o que descobriu sozinho: como rodar, como testar, que convenções existem. O seu trabalho é acrescentar o que ele não tinha como adivinhar.

Onde o arquivo mora muda quem enxerga ele:

Pensa nele como a documentação do design system, só que escrita pro agente. Aquele comentário que você deixa em toda revisão, o "isso aí é token, não hex", você escreve uma vez:

# Regras do projeto
 
- espaçamento e cor vêm dos tokens em `src/estilos/tokens.css`,
  nunca valor cravado
- botão é `<button>`, mesmo quando parece link
- todo componente novo entrega os quatro estados: vazio,
  carregando, erro e sucesso
- nada de biblioteca de componente pronta sem conversar antes

Duas regras pra ele funcionar: menos de 200 linhas (arquivo grande é lido pior, não melhor) e instrução verificável. "Use espaçamento de 8 em 8" funciona. "Capriche no layout" não quer dizer nada, nem pra ele nem pra pessoa nova do time.

O que isso destrava pra quem é designer

Cinco coisas ao alcance no primeiro dia, todas do lado que já é seu:

Entender o que já existe. Aponta pro componente que ninguém sabe explicar e pede a tradução: quais props ele recebe, quais estados ele tem, onde ele é usado. É arqueologia de design system, feita em minutos.

Trocar valor cravado por token. "Procura todo #3b82f6 e padding: 17px no projeto e me diz onde estão." Ele varre tudo e devolve a lista. Essa é uma auditoria que ninguém faz porque dá trabalho, e agora não dá mais.

Completar os estados que faltam. O caso feliz sempre existe. Vazio, carregando e erro é o que some no caminho, e pedir os três de uma vez custa uma frase.

Passar o pente de acessibilidade. Foco visível, ordem de tabulação, contraste, semântica. Você sabe o que procurar, e agora tem quem abra os arquivos junto.

Colocar no ar. Do arquivo em branco até o deploy com link funcionando, acompanhando cada passo. Atravessar isso uma vez muda pra sempre como você conversa com engenharia.

Onde ele erra

O mesmo lugar de sempre, e vale repetir: ele soa seguro quando está errado. Inventa propriedade, usa versão antiga de biblioteca com toda a confiança do mundo, e entrega o caso feliz achando que terminou. As sete perguntas do outro guia continuam sendo o seu trabalho.

E o CLAUDE.md é contexto, não lei: ele orienta muito bem e não garante nada. Regra que precisa valer sempre é regra que pertence ao código, não ao markdown.

O que fazer hoje

Abre o app, clica em Code, aponta pra um projeto seu de verdade, escolhe o modo Plan e pede uma coisa só:

lê o componente de botão e me diz quais estados ele tem e quais faltam

Você vai ler a resposta e reconhecer tudo, porque é a sua lista. É esse o ponto: o Claude Code não te transforma em desenvolvedor. Ele tira o que atrapalhava você usar o que já sabe.

Existe também a versão de terminal, que é a mesma ferramenta com outra porta de entrada, e ela rende umas coisas que o app não faz. Mas isso é assunto do próximo guia. Comece por aqui.