# Guia Definitivo: Claude Code > Domine o Claude Code — o agente de codificação CLI da Anthropic. Instalação, configuração, subagents, hooks, MCP e workflows reais. Source: https://agentify.ia.br/blog/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: - Analisa o contexto do repositório - Planeja a abordagem - Executa as mudanças (criando/editando arquivos, rodando comandos) - Verifica o resultado - 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: Plano Preço Claude Code Pro $20/mês (ou $17/mês no anual) ✅ Incluído Max 5x $100/mês ✅ 5x mais uso que Pro Max 20x $200/mês ✅ 20x mais uso que Pro Team $25/seat/mês (standard) ✅ Incluído Enterprise $20/seat + uso por API ✅ Escala com uso Para uso via API (pay-per-token), os custos dependem do modelo: Modelo Input Output Opus 4.7 $5/MTok $25/MTok Sonnet 4.6 $3/MTok $15/MTok Haiku 4.5 $1/MTok $5/MTok 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: - Instalar dependências (`npm install jsonwebtoken bcrypt`) - Criar o middleware de autenticação - Criar os endpoints de login e registro - Atualizar as rotas existentes para usar o middleware - Adicionar variáveis de ambiente necessárias - 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: Modelo Melhor para Custo relativo Opus 4.7 Tarefas complexas, refactoring multi-arquivo, arquitetura $$$ Opus 4.6 Raciocínio profundo, decisões de design $$$ Sonnet 4.6 Uso diário, melhor custo-benefício $$ Haiku 4.5 Tarefas rápidas, exploração, triagem $ 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: - Delega a exploração do código atual para um subagent Explore - Recebe um resumo condensado - Planeja a refatoração - Delega implementações paralelas para subagents de execução - 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: Hook Quando executa pre-tool-use Antes de qualquer ferramenta ser chamada post-tool-use Após uma ferramenta completar pre-commit Antes de um git commit post-commit Após um git commit session-start Ao iniciar uma sessão session-end Ao encerrar uma sessão 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](https://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](https://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. Eixo Nota Justificativa Código (qualidade) 10/10 SWE-bench Verified 87.6% (Opus 4.7), 80.9% (Opus 4.6) — líder absoluto entre agentes de codificação Contexto (compreensão) 9/10 1M tokens de context window, compreende codebases massivos com relações entre módulos Autonomia 10/10 Terminal-Bench 2.0: 68.5% (Opus 4.7), execução autônoma completa com subagents e auto-verificação Velocidade 7/10 Latência maior que IDEs (API calls), mas throughput alto em tarefas longas e complexas Custo-benefício 7/10 $20/mês (Pro) a $200/mês (Max); via API Opus 4.7 custa $5/$25 MTok — caro para uso intenso, mas qualidade justifica Especialização (skills) 9/10 CLAUDE.md hierárquico, hooks, skills, memory — sistema de personalização mais flexível do mercado Multi-agente 9/10 Subagents nativos, Task tool, paralelismo via múltiplas instâncias e GitHub Actions Ecossistema 8/10 MCP servers, GitHub Actions, VS Code, JetBrains, SDK, 122k+ stars — comunidade ativa e crescente **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.* -->