Claude Code: Guia COMPLETO que todo desenvolvedor precisa saber

O Claude Code, um agente de desenvolvimento de software criado pela Anthropic, funciona como uma interface de linha de comando (CLI) e está transformando a maneira como os desenvolvedores trabalham. Este agente já se tornou uma ferramenta essencial para o desenvolvimento de softwares, inclusive projetos de grande escala, superando em muitos aspectos algumas IDEs amplamente utilizadas. A chave para maximizar sua eficácia é entender como integrá-lo com ferramentas existentes como Cursor, Windsurf, VS Code e GitHub Copilot, utilizando a ferramenta certa no momento ideal. Este guia completo explorará dicas e truques que podem otimizar o fluxo de trabalho e, inclusive, gerar economia, evitando gastos excessivos com a utilização inadequada de APIs, como o gasto de $500 mencionado em exemplos reais.

A Full Cycle oferece um MBA em Engenharia de Software com IA, projetado para capacitar desenvolvedores a assumir o novo perfil profissional da era da IA. O programa foca em tornar os desenvolvedores mais produtivos e preparados para criar as próximas gerações de aplicações integradas com IA e agentes de IA verdadeiros, que vão além de pequenas automações ou instâncias de SDKs para code completion. É um MBA transformador, repleto de conteúdo de qualidade e convidados especiais, feito sob medida para desenvolvedores, sem se aprofundar em machine learning ou treinamento de modelos. Recomenda-se verificar o link na descrição do vídeo para mais detalhes.

O Claude Code se posiciona como um colaborador essencial na programação. Inicialmente, o preconceito era de que agentes CLI não se integrariam com IDEs, limitando a colaboração. No entanto, a proposta do Claude Code é diferente, permitindo um trabalho conjunto com IDEs, o que será demonstrado neste guia.

A instalação do Claude Code é um processo simples, geralmente envolvendo alguns comandos no terminal. O agente foi projetado para ser um colaborador eficaz, especialmente quando integrado à sua IDE de preferência. A documentação oficial é direta e fácil de seguir, garantindo que mesmo desenvolvedores menos experientes possam configurar a ferramenta rapidamente. A principal vantagem é a capacidade de combinar a interação via linha de comando com a rica interface gráfica de IDEs como Cursor, Windsurf e VS Code, otimizando o fluxo de trabalho.

Na primeira utilização, um login será necessário. Este é um ponto crítico para a gestão de custos, pois a escolha do plano impacta diretamente as despesas. É fundamental entender as opções de assinatura para evitar cobranças elevadas por tokens via API.

Ao fazer o login pela primeira vez no Claude Code, um aspecto crucial é a escolha do método de pagamento. Utilizar a API Key da Anthropic diretamente pode resultar em custos elevados baseados no consumo de tokens, com relatos de usuários gastando até $500 devido à falta de atenção a pequenos detalhes. A alternativa mais econômica e recomendada é assinar um dos planos da Anthropic, que oferecem limites de uso mais favoráveis e previsíveis.

O plano de $100, por exemplo, oferece cinco vezes mais capacidade de utilização do que o plano Pro, e inclui acesso ao modelo Opus do Claude, considerado o mais poderoso, em contraste com o modelo Sonnet padrão. Isso permite um trabalho praticamente ilimitado no dia a dia, evitando os limites de taxa. Embora o modelo Opus consuma mais recursos, um plano de $200 por mês oferece vinte vezes mais utilização, mitigando os limites de taxa mesmo com uso intensivo do Opus. Recomenda-se iniciar com o plano Pro para testar e, se necessário, fazer um upgrade, considerando também alternativas como o Google Gemini que oferecem grande utilização gratuita.

"Eu recomendo que você teste, né, se você for utilizar utilizando o plano pro e depois eventualmente faça o upgrade ou não."

Ao configurar o Claude, selecione a opção `cloud account with subscription` para realizar o login e evitar o uso de API Keys que podem gerar custos inesperados.

A integração do Claude Code com ambientes de desenvolvimento integrados (IDEs) é uma das suas maiores vantagens. Diferente de uma ferramenta puramente de linha de comando, o Claude Code permite que o desenvolvedor trabalhe colaborativamente dentro de sua IDE preferida. Por exemplo, ao usar o Cursor, é possível abrir o terminal na parte inferior da tela, digitar `claude`, e interagir com o agente. Ele exibirá e permitirá a alteração de arquivos, proporcionando uma experiência de desenvolvimento integrada e fluida.

Para uma integração ainda mais profunda e eficiente, é recomendável instalar a extensão do Claude Code em sua IDE, como VS Code ou Cursor. Esta extensão conecta a IDE diretamente ao Claude Code, permitindo uma comunicação mais contextualizada e um fluxo de trabalho aprimorado. Por exemplo, ao abrir um arquivo como `README.md`, um botão "Run Claude Code" aparece, abrindo uma interface lateral para interação. Essa interface pode ser fixada, transformando a IDE em um ambiente colaborativo com IA, similar à experiência nativa do Cursor.

Uma vez conectado, o Claude Code utilizará um arquivo chave chamado `cloud.md` para armazenar regras e "memórias", garantindo que ele siga instruções específicas de forma consistente.

O arquivo `cloud.md` é fundamental para o Claude Code, pois ele atua como um repositório de regras e memórias que o agente deve sempre seguir. Similar a conceitos como "cursor rules", esse arquivo pode ser criado manualmente com as instruções desejadas. No entanto, para projetos existentes ou para iniciar rapidamente, o comando `/init` oferece uma solução automatizada. Ao executar `/init`, o Claude Code analisa o codebase do seu projeto, incluindo o `README.md` e a estrutura de código, e gera um arquivo `cloud.md` inicial baseado nessa análise. Essa funcionalidade é especialmente útil para novos projetos, eliminando a necessidade de começar do zero na definição das regras e contexto para o agente.

O comando `/init` é uma ferramenta poderosa para agilizar a configuração inicial do Claude Code em um novo projeto. Ao executá-lo, o agente escaneia o diretório do projeto e gera automaticamente um arquivo `cloud.md` preenchido com as informações contextuais relevantes. É possível, inclusive, passar comandos adicionais ao `/init` para refinar a análise. Por exemplo, pode-se instruir o Claude a ler todo o projeto, mas ignorar pastas específicas, como um repositório oficial de SDKs (`MCP SDK repo`), fornecendo uma base inicial mais precisa para o agente trabalhar. Após a análise, o Claude sempre apresentará um plano de ação, que é uma lista de tarefas que ele pretende executar para cumprir a instrução. Esse planejamento é um diferencial, embora outras ferramentas como Cursor e Windsurf também ofereçam recursos semelhantes.

"Uma das coisas que o Cloud Code ele sempre vai fazer, ele vai querer, no final das contas criar, né, um plano de ação dele do que ele vai ter que fazer. Ou seja, ele tem uma list, uma tesque, e ele vai matando essas tesques até ele terminar todo o processo."

Durante a geração do `cloud.md`, o Claude Code pode apresentar um `diff` na IDE, mostrando as alterações propostas. Como ele não tem permissão para gravar arquivos por padrão, ele sempre perguntará se o usuário deseja permitir a edição. É possível optar por permitir a edição apenas uma vez, sempre permitir (com a opção "sim e nunca mais pergunte"), ou negar. Ao permitir, o Claude pode gerar uma pasta oculta `.cloud` para configurações internas. A opção "sim e não pergunte mais nessa sessão" agiliza o processo, permitindo que o Claude finalize a criação do `cloud.md` sem interrupções.

O arquivo `cloud.md` serve como um guia essencial para o Claude Code, contendo comandos, informações arquiteturais e conceitos principais extraídos da análise do projeto. Após a inicialização com `/init`, o Claude preenche este arquivo com detalhes como a execução de testes, exemplos, arquitetura (Protocolo de Contexto do Modelo - MCP), sistema de gerenciamento de sessão, meio de transporte, área de ferramentas, armazenamento de eventos, estrutura de diretórios, e notas de desenvolvimento. Ele pode identificar que o projeto usa TypeScript, que o servidor roda na porta 3.000, e detalhes sobre health checks e endpoints MCP. Além disso, pode reconhecer a utilização de Jest para testes e que cada cliente usa uma sessão. Essencialmente, o Claude Code analisa o código-fonte e cria um guia que ele mesmo pode consultar para futuras interações, permitindo que o desenvolvedor refine e melhore continuamente esse guia para fornecer um contexto cada vez mais rico ao agente.

A funcionalidade de memória do Claude Code é crucial para garantir que o agente retenha instruções específicas e comportamentos desejados ao longo do tempo, mesmo entre diferentes sessões. Utilizando o comando `/memory`, é possível adicionar novas informações à memória do Claude, as quais serão incorporadas ao arquivo `cloud.md` ou a um arquivo de memória do usuário. Isso é particularmente útil para estabelecer regras permanentes que o Claude deve seguir, evitando que ele "esqueça" diretrizes importantes durante o desenvolvimento de um projeto.

Para adicionar uma instrução à memória, basta digitar `/memory` e, ao ser solicitado, inserir o conteúdo. Por exemplo, para evitar que o Claude utilize emojis, pode-se adicionar a regra: "Nunca use emojis no projeto, nem para logs, outputs e etc." Após salvar no `Project Memory`, essa instrução será refletida no `cloud.md`, e o Claude tentará aderir a essa diretriz em todas as interações futuras. Isso proporciona um controle mais granular sobre o comportamento do agente, permitindo ajustes conforme a necessidade do projeto ou as preferências do desenvolvedor.

A integração de servidores do Protocolo de Contexto do Modelo (MCP) é uma funcionalidade avançada do Claude Code, que permite ao agente interagir com ambientes externos, como contêineres Docker. Ao digitar `/mcp` na interface do Claude, ele pode listar os servidores MCP conectados. Esta configuração pode ser global, afetando todos os projetos, ou específica da sessão. É essencial entender como configurar esses servidores para estender as capacidades do Claude e permitir que ele execute ações em seu ambiente de desenvolvimento.

Para gerenciar os servidores MCP, utiliza-se o CLI do Claude, digitando `cloud mcp`. Com a flag `-H`, é possível visualizar todas as opções disponíveis, incluindo remover, listar, adicionar e importar servidores MCP. Se o usuário já utiliza o Claude Desktop, é possível importar servidores MCP de lá. A capacidade de adicionar um servidor MCP, como o `MCP Docker` que utiliza o comando `Docker MCP gateway run`, permite ao Claude interagir com seus contêineres Docker, possibilitando consultas e execuções em seu ambiente de orquestração. Após adicionar um servidor, ele aparecerá na lista de servidores MCP conectados, e o Claude poderá utilizá-lo para suas operações.

Para demonstrar, é possível remover um servidor MCP existente com `cloud mcp remove MCP Docker` e depois adicioná-lo novamente com `cloud mcp add MCP Docker "Docker MCP gateway run"`. Uma vez adicionado, o Claude pode ser instruído a usar esse servidor. Por exemplo, ao perguntar "Use o MCP Docker para ver os contêiners rodando", o Claude, após a permissão do usuário, acessará o servidor MCP e exibirá a lista de contêineres em execução, validando a integração. Essa funcionalidade permite que o Claude execute tarefas complexas que exigem interação com o ambiente de contêineres, como listar contêineres, gerenciar serviços, entre outros.

Ao utilizar o Claude Code, ele cria um arquivo `.cloud` que contém um `settings.local.json`. É crucial compreender a diferença entre `settings.local.json` e `settings.json` para gerenciar as configurações do Claude de forma eficaz, especialmente em projetos colaborativos. O `settings.local.json` é um arquivo de configuração local, específico para o usuário no projeto, e não deve ser commitado no controle de versão. Seu objetivo é armazenar configurações pessoais que não devem afetar outros desenvolvedores. Em contraste, o `settings.json` (sem o `.local`) é um arquivo de configuração de projeto que deve ser commitado, pois ele define o comportamento do Claude para todos os membros da equipe, garantindo consistência no fluxo de trabalho. No `settings.local.json`, por exemplo, podem ser adicionadas permissões para que o Claude execute o `MCP Docker` automaticamente.

A seção `permissions` dentro desses arquivos é onde se define quais ações o Claude Code pode executar sem pedir confirmação. Essa lista de permissões tende a crescer com o tempo, à medida que o desenvolvedor concede mais autonomia ao agente para tarefas rotineiras. Entender essa distinção entre configurações locais, de projeto e, por extensão, as configurações globais (da máquina do usuário) é fundamental para um controle preciso sobre o comportamento do Claude, otimizando a produtividade individual e a colaboração em equipe.

A forma como o Claude Code interage com o usuário pode ser controlada por dois modos principais: o modo de escrita direta (auto-accept edits) e o modo de planejamento (plan mode). No modo de escrita direta, o Claude Code, ao receber uma instrução, processa-a, formula um plano e imediatamente começa a alterar os arquivos. Embora seja rápido, essa abordagem pode ser arriscada se o desenvolvedor precisar revisar o plano antes que as modificações sejam aplicadas. O "plan mode", por outro lado, permite que o Claude crie um plano de ação que o usuário pode analisar, discutir e refinar antes de conceder permissão para a execução das tarefas, garantindo maior controle e precisão no desenvolvimento.

Para ativar o "plan mode", o desenvolvedor pode usar o atalho `shift + tab` e selecionar `plan mode on`. Este modo é ideal para tarefas mais complexas ou críticas, onde a revisão do plano de ação é essencial. Por exemplo, ao solicitar: "Preciso criar uma listagem de usuários fake nesse servidor MCP. Ou seja, quando a LLM pedir uma listagem de usuários, teremos que trazer alguns usuários de exemplo com nome e e-mail", o Claude Code, no modo de planejamento, analisará a solicitação e apresentará um plano detalhado de como pretende implementar a funcionalidade. Este plano inclui a identificação de ferramentas existentes, a proposta de melhorias (como expandir o banco de dados de usuários falsos) e a manutenção da funcionalidade atual, permitindo que o usuário revise e aceite ou negue a proposta.

A grande vantagem do "plan mode" é a capacidade de dialogar com o Claude Code para refinar o plano de ação. Se o plano inicial não for satisfatório, o desenvolvedor pode recusá-lo e fornecer feedback adicional. Por exemplo, ao sugerir: "Já que você já tem o recurso de listar usuários, vamos fazer com que nós tenhamos uma funcionalidade de remover o usuário utilizando o e-mail. Então, crie um plano para isso." O Claude gerará um novo plano, detalhando a criação de uma nova ferramenta (`remove user por e-mail`), sua estrutura, parâmetros, retorno e lógica de implementação. Esse processo iterativo garante que o agente execute as tarefas exatamente como desejado. Após a revisão e aprovação do plano, o desenvolvedor pode instruir o Claude a iniciar o desenvolvimento, optando por aprovar automaticamente as edições ou revisá-las uma a uma, dependendo do nível de controle desejado.

"Se você perceber, galera, esse flow aqui com o com o cloud Code é muito bom, porque eu consigo ir discutindo com ele, tá? E ele vai cada vez mais refinando esse plano conforme eu vou pedindo."

Durante a execução de tarefas, o Claude Code frequentemente precisa rodar comandos no terminal, como `npm run build` para testar funcionalidades. Por padrão, ele solicitará permissão para cada execução. No entanto, é possível automatizar essas permissões para evitar interrupções constantes. O arquivo `settings.local.json` é o local ideal para configurar essas permissões, permitindo que o Claude execute comandos específicos sem solicitar aprovação a cada vez, o que agiliza significativamente o fluxo de trabalho do desenvolvedor.

Ao conceder permissão para um comando, como `npm run build`, o Claude Code adiciona uma entrada no `settings.local.json`, permitindo a execução desse comando (ex: `bash - npm run build`). Para comandos mais genéricos, pode-se usar curingas, como `npm run **`, que permitiria ao Claude executar qualquer script npm. Contudo, é importante notar que o Claude pode não reavaliar essas permissões instantaneamente, exigindo uma reexecução ou reinício para que as novas regras sejam aplicadas. Quando o Claude solicita a execução de comandos como `npm start`, que travam o terminal, é fundamental instruí-lo a rodar o comando em background (adicionando `&` no final) para que ele possa continuar suas operações.

Outra permissão comum é para `pkill`, utilizada para reiniciar servidores. Conceder essa permissão permite que o Claude Code gerencie o ciclo de vida dos processos. Para comandos de teste ou limpeza, como `rm` para remover arquivos temporários, o desenvolvedor pode escolher conceder permissão apenas uma vez ou supervisionar de perto, dependendo do nível de controle desejado. O Claude Code, através dessas interações e pedidos de permissão, revela uma série de chamadas de ferramentas que ele executa. Ao final de uma tarefa, ele informa sobre a conclusão, tendo programado e executado os passos definidos, sempre com a possibilidade de revisão passo a passo pelo usuário.

A janela de contexto do Claude Code é um aspecto crucial para entender seu comportamento. Com uma capacidade de aproximadamente 200.000 tokens, o Claude armazena o histórico da conversação e as informações do projeto nessa janela. Conforme o uso se intensifica e a janela de contexto se enche, o Claude começa a "esquecer" informações mais antigas devido à perda de histórico. Para mitigar isso, ele realiza uma "compactação", criando um resumo do que já foi feito para não perder informações essenciais e, em seguida, limpando parte da janela. No entanto, mesmo com a compactação, o resultado não será o mesmo que ter uma janela de contexto completa. Portanto, gerenciar proativamente a janela de contexto é vital para manter a eficácia do agente.

Se o desenvolvedor desejar compactar o histórico da conversação manualmente, pode usar o comando `/compact`. Este comando limpa o histórico, mas gera um resumo para manter o contexto principal. Embora o Claude Code faça isso automaticamente quando a janela de contexto se torna muito grande, a intervenção manual pode ser útil para otimizar o desempenho em momentos estratégicos.

A funcionalidade de "commands" do Claude Code é um recurso extremamente poderoso e muito utilizado para automatizar ações repetitivas ou aplicar workflows padronizados. Muitas vezes, um desenvolvedor utiliza prompts extensos e complexos para instruir o agente a se comportar de uma determinada maneira, criar planos de alto e baixo nível, ou seguir um workflow específico (como os prompts baseados nas diretrizes da OpenAI). Em vez de copiar e colar esses prompts repetidamente, o Claude Code permite encapsulá-los em arquivos Markdown (.md) e executá-los como comandos personalizados.

Para criar um comando personalizado, basta criar uma pasta chamada `commands` dentro do seu projeto. Dentro dessa pasta, crie um arquivo `.md`, por exemplo, `exec_prompt.md`. O conteúdo desse arquivo Markdown pode definir um prompt estruturado. Por exemplo, uma estrutura como "Execução de tarefa: Siga as instruções do prompt passado entre instruções para executar as tarefas informadas como argumentos. Tarefas a serem executadas: {argumentos}. Instruções para execução da tarefa: {instruções detalhadas}" permite que o arquivo Markdown funcione como um script de shell dentro do Claude Code. Isso transforma um prompt complexo em um comando reutilizável e fácil de invocar.

Essa funcionalidade é incrivelmente versátil, permitindo que o desenvolvedor crie comandos para uma vasta gama de ações, como "execute um commit nesse padrão", "faça uma leitura desse arquivo para validação", ou "faça uma verificação de segurança baseada nisso". Pode-se criar diversos arquivos `.md` (ex: `/security_check.md`) para realizar verificações de segurança complexas com todas as instruções pré-definidas. Este recurso economiza um tempo considerável e garante que tarefas específicas sejam realizadas de forma consistente e padronizada, aproveitando todo o potencial do Claude Code.

Os "hooks" no Claude Code representam uma funcionalidade avançada e muito importante, que se diferencia do arquivo `cloud.md`. Enquanto o `cloud.md` atua como uma diretriz ou um guideline que o Claude tenta seguir, os hooks garantem a execução de um comando específico em determinados eventos, com uma garantia muito maior. Por exemplo, se uma regra em `cloud.md` diz "Nunca use emojis", ainda há uma pequena chance de o Claude desconsiderar. Já um hook, uma vez configurado, executará o comando escolhido (como um script) em eventos predefinidos, como "antes de usar uma ferramenta" ou "depois de usar uma ferramenta".

A configuração de hooks é feita em formato JSON e pode ser aplicada de forma global (user settings), por projeto (project settings) ou local (local settings, não commitado). Os hooks funcionam com base em eventos e "matchers". Um matcher define a condição para a execução do hook; por exemplo, "quando isso der um match, você vai executar isso aqui para mim". Existem vários tipos de matchers, como: "antes de utilizar uma tool", "depois de utilizar uma tool", "quando o agente recebe um prompt" ou "quando o agente termina completamente a tarefa". Essa flexibilidade permite automatizar diversas ações em pontos estratégicos do fluxo de trabalho do Claude Code.

Para adicionar um hook, digita-se `/hooks` no Claude Code, que apresentará as opções de evento. Escolhe-se o evento desejado, como `post tool use`, e então define-se um matcher. Por exemplo, para um matcher `task` (toda vez que uma tarefa for concluída), pode-se configurar um comando simples como `echo "Hello World"`. Ao salvar este hook como local, ele será adicionado ao `settings.local.json`, onde a instrução (`"type": "command"`, `"command": "echo "Hello World""`) garante que o comando seja executado após cada tarefa. Isso proporciona uma garantia de execução, diferentemente das guidelines do `cloud.md`. É altamente recomendável consultar a documentação oficial para explorar as diversas opções de eventos, matchers e como lidar com retornos (sucesso/erro) de scripts, permitindo criar scripts de shell que interagem com inputs e outputs do Claude, tornando-o uma ferramenta ainda mais poderosa e adaptável a qualquer padrão de desenvolvimento.

Este guia completo sobre o Claude Code buscou fornecer uma visão aprofundada sobre suas funcionalidades, desde a instalação e configuração até recursos avançados como hooks e comandos personalizados. O objetivo é capacitar desenvolvedores a testar e integrar essa poderosa ferramenta em seu dia a dia, otimizando a produtividade e a qualidade do trabalho. A compreensão das nuances do Claude Code é um passo fundamental para acompanhar a evolução da engenharia de software na era da inteligência artificial.

Para aqueles que desejam aprofundar ainda mais seus conhecimentos e se tornarem especialistas na área, o MBA em Engenharia de Software com IA da Full Cycle é uma excelente oportunidade. Este programa vai além do uso de ferramentas como o Claude Code, ensinando técnicas avançadas de prompt engineering, context engineering e, crucialmente, como criar agentes de IA autênticos. O MBA prepara os desenvolvedores para integrar IA em aplicações corporativas, resolver problemas complexos e assumir um perfil de ponta no mercado de trabalho. Recomenda-se clicar no link na descrição para explorar o curso e se especializar nessa área transformadora.