Guia Definitivo: Claude Code

Claude Code é o agente de codificação CLI da Anthropic — e provavelmente a ferramenta que mais redefiniu o que significa “autonomia” no desenvolvimento de software. Lançado como research preview em fevereiro de 2025 e em disponibilidade geral (GA) desde maio do mesmo ano, ele vive no seu terminal, entende seu codebase inteiro e executa tarefas complexas com mínima intervenção humana.

Se você já usa agentes em IDEs e quer dar o próximo passo em produtividade, este guia cobre tudo: da instalação ao uso avançado com subagents, hooks e MCP servers.

Overview

O que é Claude Code

Claude Code é um agente de codificação que opera via linha de comando. Diferente de extensões de IDE que adicionam IA a um editor existente, ele funciona diretamente no terminal — lendo arquivos, executando comandos, editando código e gerenciando workflows de git sem precisar de interface gráfica.

O modelo de execução é fundamentalmente diferente de um assistente de chat. Quando você descreve uma tarefa, Claude Code:

1. Analisa o contexto do repositório
2. Planeja a abordagem
3. Executa as mudanças (criando/editando arquivos, rodando comandos)
4. Verifica o resultado
5. Itera se necessário

Tudo isso acontece no modo agente — ele decide quais ferramentas usar, em que ordem, sem pedir permissão a cada passo (respeitando as permissões que você configurou).

Posicionamento no mercado

Claude Code compete diretamente com o Codex (OpenAI) e o Gemini CLI (Google) no espaço de agentes CLI. Também se posiciona como alternativa ao modo agente de IDEs como Cursor e GitHub Copilot, mas com uma filosofia diferente: em vez de integrar IA numa IDE, ele traz a IDE para dentro da IA.

Em maio de 2026, o repositório oficial no GitHub já acumula mais de 122 mil estrelas — um indicador claro da adoção pela comunidade.

Plataformas disponíveis

Claude Code roda em cinco superfícies:

• Terminal CLI — a experiência mais completa e feature-rich
• VS Code extension — interface gráfica nativa dentro do VS Code
• JetBrains plugin — para quem usa IntelliJ, PyCharm, etc.
• Desktop app — aplicação standalone
• Web (claude.ai/code) — execução em infraestrutura gerenciada pela Anthropic

O CLI é a base de tudo. As outras superfícies são camadas visuais sobre o mesmo engine.

Preço e planos

Claude Code está incluído nos planos de assinatura da Anthropic:

Para uso via API (pay-per-token), os custos dependem do modelo:

A opção pay-per-use via API é ideal para times que precisam de controle granular de custos ou integração em CI/CD.

Tutorial

Instalação

Pré-requisitos:

• Node.js 18+ instalado
• Conta na Anthropic com API key (ou assinatura Pro/Max)
• Terminal com suporte a cores (qualquer terminal moderno)

Instalação via npm:

npm install -g @anthropic-ai/claude-code

Após instalar, autentique:

claude login

Isso abre o navegador para autenticação OAuth. Se preferir usar API key diretamente:

export ANTHROPIC_API_KEY=sk-ant-...

Verifique a instalação:

claude --version

Primeiro Uso

Navegue até um repositório e inicie uma sessão:

cd ~/meu-projeto
claude

Claude Code analisa automaticamente a estrutura do projeto. Agora você pode conversar em linguagem natural:

> Explique a arquitetura deste projeto

> Adicione validação de input no endpoint /users

> Crie testes unitários para o módulo de autenticação

O diferencial aqui é que ele não apenas sugere código — ele efetivamente cria arquivos, edita código existente e roda comandos. Você supervisiona e aprova (ou não) cada ação.

Para tarefas rápidas sem sessão interativa, use o modo one-shot:

claude -p "Adicione um endpoint GET /health que retorna status 200"

[IMAGEM: Terminal mostrando Claude Code em ação — sessão interativa com output de criação de arquivo]

Uso Intermediário

Vamos a um cenário real: adicionar autenticação JWT a uma API Express existente.

> Adicione autenticação JWT ao projeto. Use jsonwebtoken para gerar tokens,
> bcrypt para hash de senhas, e crie middleware de verificação.
> Os endpoints /login e /register devem ser públicos.

Claude Code vai:

1. Instalar dependências (npm install jsonwebtoken bcrypt)
2. Criar o middleware de autenticação
3. Criar os endpoints de login e registro
4. Atualizar as rotas existentes para usar o middleware
5. Adicionar variáveis de ambiente necessárias
6. Rodar os testes (se existirem)

Tudo em uma única interação. Se algo falhar, ele diagnostica e corrige.

Configuração com CLAUDE.md

O CLAUDE.md é o mecanismo central de personalização. É um arquivo markdown na raiz do projeto que funciona como “regras de projeto” — instruções persistentes que Claude Code segue em toda interação.

# CLAUDE.md

## Stack
- Node.js 20 + TypeScript 5.4
- Express com Zod para validação
- PostgreSQL via Prisma ORM
- Jest para testes

## Convenções
- Sempre use async/await (nunca callbacks)
- Nomes de variáveis em camelCase
- Commits seguem Conventional Commits
- Todo endpoint precisa de teste de integração

## Arquitetura
- src/routes/ — handlers de rota
- src/services/ — lógica de negócio
- src/middleware/ — middlewares Express
- src/lib/ — utilitários compartilhados

## Regras
- Nunca commite .env
- Sempre rode `npm test` antes de sugerir que terminei
- Use early returns para reduzir nesting

O CLAUDE.md pode existir em três níveis:

• ~/.claude/CLAUDE.md — global (preferências pessoais)
• ./CLAUDE.md — raiz do projeto (regras do time)
• ./.claude/CLAUDE.md — diretório .claude (configuração avançada)

Eles se combinam hierarquicamente: global → projeto → local.

Permissões

Claude Code opera com um sistema de permissões em camadas:

# Modo padrão — pede aprovação para ações destrutivas
claude

# Modo permissivo — aprova tudo automaticamente (cuidado!)
claude --dangerously-skip-permissions

# Modo restrito — só leitura, sem execução de comandos
claude --permission-mode read-only

Para configuração granular, use o settings.json:

{
  "permissions": {
    "allow": [
      "read:**",
      "write:src/**",
      "execute:npm test",
      "execute:npm run lint"
    ],
    "deny": [
      "write:.env*",
      "execute:rm -rf*",
      "execute:git push --force"
    ]
  }
}

Isso é especialmente importante em ambientes de CI/CD e times, onde você quer autonomia controlada.

Deep Dive

Modelos Disponíveis

Claude Code suporta múltiplos modelos da família Claude, cada um otimizado para cenários diferentes:

Para trocar de modelo durante uma sessão:

/model sonnet

Ou configure o modelo padrão:

claude config set model claude-sonnet-4-6

A estratégia recomendada é usar Sonnet 4.6 como default (melhor equilíbrio preço/performance) e escalar para Opus 4.7 em tarefas que exigem raciocínio complexo — como refactoring de arquitetura ou debugging de problemas sutis.

Para subagents, o roteamento de modelo é o principal controle de custo: envie exploração para Haiku, reviews para Sonnet, e reserve Opus para a conversa principal.

Subagents

Subagents são instâncias separadas que o agente principal pode criar para lidar com subtarefas focadas. É assim que Claude Code escala para trabalhos complexos sem poluir o contexto da conversa principal.

Claude Code vem com subagents built-in:

• Explore — investiga código, busca referências, mapeia dependências
• Plan — cria planos de implementação detalhados
• General-purpose — executa tarefas delegadas genéricas

Quando você pede algo complexo como “refatore o módulo de pagamentos para usar o padrão Strategy”, o agente principal:

1. Delega a exploração do código atual para um subagent Explore
2. Recebe um resumo condensado
3. Planeja a refatoração
4. Delega implementações paralelas para subagents de execução
5. Consolida e verifica o resultado

O ruído de exploração fica contido no subagent — apenas o resumo retorna ao contexto principal. Isso preserva a janela de contexto para o que importa.

Você também pode definir subagents customizados via arquivos markdown em .claude/agents/:

# .claude/agents/test-writer.md

## Descrição
Especialista em escrever testes. Use quando precisar criar testes
unitários ou de integração.

## Instruções
- Use Jest com TypeScript
- Siga o padrão AAA (Arrange, Act, Assert)
- Cubra edge cases e error paths
- Mock dependências externas

Hooks

Hooks são scripts que executam automaticamente em pontos específicos do ciclo de vida de uma sessão. Pense neles como git hooks, mas para o agente.

Tipos de hooks disponíveis:

Exemplo prático — rodar lint automaticamente após cada edição de arquivo:

{
  "hooks": {
    "post-tool-use": [
      {
        "when": "tool == 'write_file' && path.endsWith('.ts')",
        "run": "npx eslint --fix {{path}}"
      }
    ],
    "pre-commit": [
      {
        "run": "npm test"
      }
    ]
  }
}

Hooks são poderosos para enforçar qualidade sem intervenção manual:

• Rodar formatação após cada edição
• Executar testes antes de commits
• Validar que arquivos sensíveis não foram modificados
• Notificar sistemas externos sobre mudanças

Memory (Memória)

O sistema de memória do Claude Code opera em duas camadas:

Memória explícita (CLAUDE.md): Instruções que você escreve manualmente — stack, convenções, regras. Sempre presente no contexto.

Auto-memory: Claude Code acumula aprendizados automaticamente durante o uso. Quando ele descobre algo sobre seu projeto (ex: “testes rodam com npm run test:unit, não npm test”), ele pode salvar isso para sessões futuras.

Para ver o que está na memória:

/context

Isso mostra tudo que ocupa a janela de contexto: system prompt, memory files, skills, MCP tools e mensagens da conversa.

Para adicionar algo à memória manualmente:

/memory add "Deploy para staging usa: npm run deploy:staging"

MCP Servers

MCP (Model Context Protocol) é o padrão aberto que permite conectar Claude Code a ferramentas externas. Em vez de depender apenas de leitura de arquivos e execução de comandos, MCP servers expõem capacidades adicionais.

Configuração em .claude/mcp.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://..."
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/docs"]
    }
  }
}

Com MCP servers configurados, Claude Code pode:

• Consultar bancos de dados diretamente
• Interagir com APIs do GitHub (issues, PRs, reviews)
• Acessar documentação externa
• Conectar-se a ferramentas de observabilidade
• Integrar com sistemas internos da empresa

Isso transforma Claude Code de “agente que edita código” para “agente que opera no ecossistema completo de desenvolvimento”.

Skills

Skills são conjuntos de instruções reutilizáveis que especializam Claude Code em tarefas específicas. Ficam em .claude/skills/ e são ativados automaticamente quando relevantes.

# .claude/skills/api-design/SKILL.md

## Descrição
Use quando criar ou modificar endpoints de API REST.

## Instruções
- Siga OpenAPI 3.1 spec
- Use verbos HTTP corretamente (GET para leitura, POST para criação...)
- Retorne códigos de status apropriados
- Inclua paginação em listagens (cursor-based)
- Documente com JSDoc
- Valide input com Zod schemas

Skills são o mecanismo que permite que times compartilhem conhecimento especializado. Um arquiteto define as regras, e todo desenvolvedor do time se beneficia automaticamente.

Se você quer explorar skills prontas para diferentes cenários, o ecossistema de catalogadores como skilldev.pro oferece skills verificadas para diversos workflows — de API design a testes, deploy e segurança.

Integrações

GitHub Actions

Claude Code tem integração nativa com GitHub Actions. Com um simples @claude em um PR ou issue, ele pode:

• Analisar código e sugerir melhorias
• Implementar features descritas em issues
• Criar PRs completos a partir de descrições
• Fazer code review automatizado

Setup rápido:

claude
/install-github-app

Ou manualmente, adicionando o workflow:

# .github/workflows/claude.yml
name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

O modelo padrão no GitHub Actions é Sonnet. Para usar Opus 4.7:

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude_args: "--model claude-opus-4-7"

GitLab CI/CD

Claude Code também suporta GitLab CI/CD com configuração similar, permitindo automação em pipelines de merge requests.

VS Code Extension

A extensão para VS Code oferece interface gráfica nativa:

• Painel de chat integrado ao editor
• Diff view para mudanças propostas
• Acesso a todas as features do CLI
• Atalhos de teclado customizáveis

Instale pela marketplace do VS Code buscando “Claude Code” (extensão oficial da Anthropic).

JetBrains

Plugin disponível para toda a família JetBrains (IntelliJ, PyCharm, WebStorm, etc.) com funcionalidades equivalentes à extensão VS Code.

Uso em Times

Para times, Claude Code oferece:

Managed settings: Administradores definem políticas organizacionais que têm precedência sobre configurações locais dos desenvolvedores. Entregues via console admin, MDM ou arquivo em disco.

Controle de custos: No plano Enterprise, admins definem limites de gasto por usuário e por organização.

Audit logs: Registro de todas as ações executadas pelo agente — essencial para compliance.

SSO e SCIM: Integração com provedores de identidade corporativos.

Skills organizacionais: Deploy de skills para toda a organização de uma vez.

Se sua empresa precisa de ajuda para implementar Claude Code em escala — configurando permissões, skills customizadas e integrações com sistemas internos — a ft.ia.br oferece consultoria especializada em adoção de agentes de codificação para times.

Avaliação: Spider Chart

Notas de 1 a 10 baseadas em benchmarks públicos + avaliação prática.

Média geral: 8.6/10

Metodologia: Código baseia-se em SWE-bench Verified + SWE-bench Pro. Autonomia em Terminal-Bench 2.0 + avaliação prática. Demais eixos são avaliação prática comparativa com concorrentes diretos (Codex, Cursor, Copilot). Escala: 1-4 (fraco), 5-6 (adequado), 7-8 (bom), 9-10 (excelente/líder). Dados de maio/2026.

[IMAGEM: Spider chart radar com 8 eixos mostrando as notas do Claude Code]

Prós e Contras

Prós

• Autonomia real — Claude Code não apenas sugere: ele executa. Cria arquivos, roda comandos, faz commits. Você supervisiona em vez de copiar/colar.

• Contexto profundo — Ele lê o codebase inteiro. Entende relações entre módulos, padrões do projeto e convenções do time via CLAUDE.md.

• Arquitetura extensível — Hooks, skills, subagents e MCP servers formam um sistema de camadas que permite customização profunda sem gambiarras.

• Multi-plataforma — CLI, VS Code, JetBrains, Desktop, Web. Use onde preferir, com o mesmo engine por baixo.

• CI/CD nativo — GitHub Actions e GitLab CI integrados. O agente trabalha mesmo quando você não está olhando.

• Ecossistema de modelos — Escolha entre Haiku (rápido/barato), Sonnet (equilibrado) e Opus (máxima capacidade) conforme a tarefa.

Contras

• Custo pode escalar rápido — Em uso intenso via API, especialmente com Opus, a conta sobe. Monitoramento de tokens é essencial.

• Limites de uso nos planos de assinatura — Mesmo no Max 20x, há limites. Em períodos de alta demanda, throttling acontece. A Anthropic reportou crescimento de 80x na demanda, causando restrições de compute.

• Curva de aprendizado para configuração avançada — CLAUDE.md é simples, mas dominar hooks + MCP + subagents + permissions leva tempo.

• Dependência de conectividade — Tudo roda na nuvem. Sem internet, sem agente. Não há modo offline.

• Terminal pode intimidar — Para quem vem de IDEs visuais, a experiência CLI pura pode parecer árida (a extensão VS Code mitiga isso).

• Billing em transição — A partir de junho de 2026, a Anthropic está separando billing em dois pools: uso em ferramentas first-party vs third-party. Isso pode afetar quem usa Claude Code via integrações de terceiros.

Veredicto

Claude Code é ideal para:

• Desenvolvedores que vivem no terminal e querem máxima autonomia
• Times que precisam de automação em CI/CD (code review, implementação de issues)
• Projetos complexos onde contexto profundo do codebase faz diferença
• Quem quer customizar o agente com skills, hooks e MCP servers

Claude Code NÃO é ideal para:

• Iniciantes absolutos que ainda estão aprendendo a programar (a autonomia pode ser confusa)
• Quem precisa de interface visual rica com previews em tempo real (Cursor é melhor aqui)
• Projetos com orçamento muito restrito e uso intenso (o custo por token pode surpreender)
• Ambientes sem conectividade confiável

Se você busca o agente de codificação mais autônomo e extensível disponível hoje, Claude Code é a referência. A combinação de CLAUDE.md + skills + hooks + MCP + subagents cria um sistema que se adapta ao seu workflow — não o contrário.

Versão testada: Claude Code v2.x (maio 2026). Modelos: Sonnet 4.6, Opus 4.7. Preços e features sujeitos a alteração pela Anthropic.