Claude Code: O Guia Definitivo do CLI da Anthropic

Por que um CLI agêntico e não só mais um autocomplete?

A primeira geração de assistentes de código (Copilot, Tabnine, Codeium) resolveu um problema limitado: sugerir a próxima linha enquanto você digita. Útil, mas passivo. Você continua sendo o operário — o assistente só empresta o braço direito.

O Claude Code parte de uma premissa diferente: o modelo opera o seu terminal como um engenheiro júnior que tem acesso real ao projeto. Ele lista arquivos, lê o que precisa, roda testes, cria branches, abre PRs e escreve migrations — sempre pedindo permissão antes de cada ação irreversível. A diferença prática: você deixa de descrever linhas e passa a descrever objetivos.

Este guia é o mapa que eu gostaria de ter recebido quando comecei a usar o Claude Code em produção. Vou cobrir os sete pilares que você precisa conhecer para tirar o CLI da "curiosidade" e colocá-lo no fluxo de trabalho diário. Se você ainda não instalou, passe rapidinho pelo quick start de instalação do Claude Code e volte — o resto deste guia assume que claude já roda no seu terminal.

Anatomia em uma frase

O Claude Code é composto por sete camadas que se encaixam:

1. Prompt livre — o que você digita, em linguagem natural.
2. Slash commands — atalhos versionáveis no repo (/commit, /review-pr).
3. Skills — capacidades empacotadas com instruções + arquivos auxiliares.
4. Subagents — agentes especializados que rodam em paralelo em contexto isolado.
5. Hooks — shell commands disparados por eventos (antes/depois de cada tool use).
6. MCP servers — ponte para ferramentas externas (Linear, Slack, seu banco).
7. Plan mode + Memory — planejamento antes de executar e persistência entre sessões.

Cada camada resolve um problema específico. Você não precisa usar todas — mas entender como se encaixam é o que separa quem "brinca" de quem efetivamente entrega.

Slash commands e skills: extensão leve do modelo

Slash commands são a forma mais barata de estender o Claude Code. Um arquivo markdown em .claude/commands/deploy.md vira o comando /deploy — quando você digita, o conteúdo é injetado no prompt. Perfeito para rituais repetitivos: revisar um PR, gerar um changelog, fazer deploy para staging, rodar a rotina de início de sprint.

Skills são a evolução: um diretório com SKILL.md + arquivos auxiliares que o próprio modelo aprende a usar quando o contexto pede. A diferença crítica é quando cada um entra em cena — slash commands exigem invocação explícita, skills são ativadas pelo modelo quando detecta o gatilho. Dediquei um artigo inteiro a desenhar essa distinção em Slash Commands e Skills: personalizando seu fluxo no Claude Code, com exemplos de quando cada um é a escolha certa.

Subagents: paralelismo real dentro de uma sessão

Subagents são a feature que mais muda a percepção de velocidade. Quando você dispara um agente via ferramenta Task, o Claude principal continua livre enquanto o subagent roda no seu próprio contexto. Você pode disparar três subagents em paralelo — cada um investigando uma parte do código — e consumir só o resumo final, protegendo a janela de contexto do agente orquestrador.

Exemplos práticos: um subagent Explore que faz a busca ampla pela codebase, um code-reviewer que relê o diff com olhos independentes, um test-writer que rascunha testes enquanto você escreve a feature. Aprofundo arquitetura, uso e anti-padrões em Subagents no Claude Code: orquestrando tarefas em paralelo.

Hooks, MCP e a ponte com o mundo externo

Se skills são como você empresta instruções ao modelo, hooks e MCP servers são como você empresta ações. Hooks são shell commands executados automaticamente pelo harness — antes ou depois de cada Edit, Bash, Write. Bom caso de uso: rodar biome format depois de toda edição, bloquear edições em arquivos sensíveis, logar todo Bash num arquivo de auditoria.

MCP servers são servidores que expõem ferramentas pelo protocolo Model Context Protocol. Com um MCP do Linear conectado, o modelo pode ler e criar issues sem sair do CLI. Com um MCP para seu Postgres local, ele consulta schemas reais antes de escrever uma migration. A combinação de hooks + MCP é o que efetivamente integra o Claude Code no seu fluxo de desenvolvimento diário — é aí que o CLI deixa de ser um brinquedo e vira infraestrutura de time.

Plan mode: porque código bom começa fora do teclado

Plan mode é o modo em que o Claude não pode editar nada — só lê, pesquisa e escreve um arquivo de plano para você aprovar. Parece trivial, mas resolve o problema mais caro do pair programming com IA: o modelo começa a implementar antes de entender. No plan mode, você força o ciclo entender → propor → aprovar → executar.

Eu ligo plan mode para qualquer tarefa que toca mais de um arquivo ou mistura domínios. Detalhamento completo, quando desligar e templates de plano em Plan Mode: planejando antes da execução.

Memory system: persistência entre sessões

A cada conversa nova, o modelo começa "amnésico" — exceto pelo que estiver em CLAUDE.md e pela memória auto-escrita do projeto. O sistema de memória do Claude Code é um diretório de arquivos markdown que o modelo lê no início de cada sessão e pode atualizar sozinho quando aprende algo durável: regras do time, preferências de estilo, histórico de decisões arquiteturais, contexto de quem é o usuário e como ele prefere trabalhar.

É a peça que torna o Claude Code seu, não apenas "um assistente que sabe a linguagem". Comparações detalhadas de como Cursor e Copilot lidam (ou não lidam) com memória estão em Claude Code vs Cursor vs Copilot: comparativo honesto.

O primeiro dia produtivo

Um fluxo razoável para sair de zero a útil:

1. Instalar e logar — siga o quick start linkado no início deste artigo.
2. Escrever um CLAUDE.md mínimo — 20 linhas sobre o projeto: stack, comandos para rodar/testar/deployar, convenções do time. Vale mais que 2000 linhas de documentação espalhada.
3. Criar 3 slash commands — /commit, /review, /deploy. Esses três cortam as fricções diárias imediatamente.
4. Conectar 1 MCP server — comece pelo que você mais usa fora do editor (Linear, Jira, o banco de desenvolvimento).
5. Ligar plan mode na primeira tarefa real de verdade. Observe o que o modelo entendeu errado antes de aprovar o plano — esse momento é o aprendizado que paga todo o resto.

Quando não usar

Claude Code não é bala de prata. Em três cenários eu ainda prefiro editar à mão: (1) hot-fix em produção onde cada segundo importa — o overhead de carregar contexto não compensa; (2) arquivos de configuração críticos (DNS, IAM, secrets) — o custo do erro é maior que o ganho de velocidade; (3) código que você está aprendendo — delegar atrofia a intuição que você está tentando construir. Conhecer os limites é tão importante quanto conhecer os superpoderes.

Próximos passos

Este guia é a porta de entrada. Os três galhos principais aprofundam cada cluster: comece por slash commands e skills se o seu objetivo é ergonomia pessoal, por subagents e orquestração se você quer velocidade em tarefas grandes, ou por integração no fluxo de desenvolvimento se o plano é adotar o Claude Code no time inteiro.