Guia Definitivo do Claude Code: Do Terminal à Produção

Por Marcelo — Desenvolvedor Sênior Full Stack
Java Spring Boot • Laravel • PostgreSQL • React
Especialista em Desenvolvimento Guiado por IA
Formado em ADS, Gestão Comercial e Pós-graduado em IA/ML/Deep Learning
Última atualização: Abril 2026

Sumário

1. O que é o Claude Code

2. Instalação e Configuração Inicial

3. CLAUDE.md — O Cérebro do Projeto

4. Comandos Essenciais (Nível 1)

5. Controle de Custo e Estratégia (Nível 2)

6. Inspeção, Segurança e Recuperação (Nível 3)

7. Automação e Paralelização (Nível 4)

8. MCP — Conexão com o Ecossistema (Nível 5)

9. Skills — Comandos Personalizados (Nível 6)

10. Hooks — Automação no Ciclo de Vida (Nível 7)

11. Subagents — Agentes Especializados (Nível 8)

12. Agent Teams — Orquestração Multi-Agente (Nível 9)

13. Integração com IDEs (VS Code e JetBrains)

14. CI/CD com GitHub Actions

15. Claude Code na Web e Desktop

16. Atalhos de Teclado

17. Modo Headless e Scripting

18. Gestão de Contexto — Evitando Context Rot

19. Modos de Permissão

20. Configuração Avançada (7 Camadas)

21. Fluxos de Trabalho Completos

22. Erros Comuns e Como Evitar

23. Tabela de Referência Rápida

24. Glossário

25. Recursos e Comunidade

26. FAQ

1. O que é o Claude Code

O Claude Code é uma ferramenta de desenvolvimento baseada em IA criada pela Anthropic que opera diretamente no terminal como um agente autônomo. Diferente de assistentes tradicionais que funcionam como chatbots isolados, o Claude Code:

• Lê e entende toda a sua codebase, não apenas o arquivo aberto

• Executa comandos — roda testes, faz builds, interage com git

• Edita múltiplos arquivos simultaneamente com raciocínio sobre impacto

• Planeja e age em sequência, sem intervenção humana a cada passo

• Conecta-se a ferramentas externas via MCP (Jira, Slack, GitHub, bancos de dados)

• Spawna sub-agentes para tarefas paralelas e especializadas

Está disponível no terminal (CLI), VS Code, JetBrains, app desktop e navegador (claude.ai/code).

A diferença fundamental

2. Instalação e Configuração Inicial

Instalação

A instalação via npm foi descontinuada. Use os métodos recomendados:

# macOS / Linux (recomendado)
brew install claude-code

# Windows
winget install Anthropic.ClaudeCode

# Ou via instalador nativo
# Baixe em: https://claude.com/product/claude-code

Importante: O Homebrew e WinGet não atualizam automaticamente. Execute brew upgrade claude-code ou winget upgrade Anthropic.ClaudeCode periodicamente.

Requisitos

• Node.js 18+ (necessário para execução)

• Git 2.23+ (para integração com repositórios)

• Conta Anthropic com assinatura Claude ou acesso API

Primeiro uso

# Navegue até o projeto
cd ~/projetos/meu-app

# Inicie o Claude Code
claude

# Na primeira vez, será solicitado login
# Siga as instruções no terminal

Verificação da instalação

# Versão instalada
claude --version

# Diagnóstico completo
claude
# Dentro do Claude Code:
/doctor

3. CLAUDE.md — O Cérebro do Projeto

O CLAUDE.md é o arquivo mais importante do seu workflow com Claude Code. É a memória persistente do projeto — carregado automaticamente no início de cada sessão.

Criação automática

claude /init

O /init analisa a codebase e gera um CLAUDE.md inicial com estrutura de pastas, stack, convenções e restrições.

Estrutura recomendada

# Projeto: API de Pagamentos

## Stack
- Java 21 + Spring Boot 3.4
- PostgreSQL 16
- Redis (cache e sessões)
- Docker + Docker Compose
- GitHub Actions (CI/CD)

## Arquitetura
/src/main/java/com/empresa/pagamentos
  /controller    → REST controllers (anotações @RestController)
  /service       → Lógica de negócio (@Service, @Transactional)
  /repository    → Data JPA repositories
  /model         → Entidades JPA
  /dto           → Records para request/response
  /config        → Spring Security, CORS, beans
  /exception     → @ControllerAdvice, handlers globais

## Convenções de Código
- Java Records para DTOs (nunca classes mutáveis)
- Early return — evitar else sempre que possível
- Injeção via construtor (nunca @Autowired em campo)
- Nomes em inglês, comentários podem ser em PT-BR
- Testes em src/test com sufixo *Test.java
- Usar Optional ao invés de null checks

## Padrões REST
- POST /api/v1/resource → criar
- GET /api/v1/resource/{id} → buscar
- PUT /api/v1/resource/{id} → atualizar completo
- PATCH /api/v1/resource/{id} → atualizar parcial
- DELETE /api/v1/resource/{id} → remover

## Segurança
- NUNCA commitar .env, application-prod.yml ou secrets
- Spring Security com JWT (access + refresh token)
- Validação com @Valid e Bean Validation
- Rate limiting via bucket4j

## Testes
- JUnit 5 + Mockito para unitários
- @SpringBootTest + Testcontainers para integração
- Cobertura mínima: 80%
- Comando: ./mvnw test

## CI/CD
- Branch principal: main
- PRs obrigatórios com review
- Pipeline: lint → test → build → deploy
- Deploy via GitHub Actions + Docker

Boas práticas para o CLAUDE.md

1. Seja conciso — Se o CLAUDE.md for longo demais, o Claude ignora metade. Regras importantes se perdem no ruído

2. Se o Claude já faz algo correto sem instrução, delete a instrução — Instrução redundante é ruído

3. Converta regras frequentes em hooks — Hooks garantem execução; CLAUDE.md é consultivo

4. Liste seus skills/commands disponíveis — Assim o Claude (e sua equipe) sabe o que está disponível

5. Versione no git — O CLAUDE.md é código, merece review via PR

Hierarquia de CLAUDE.md

O Claude Code carrega CLAUDE.md em cascata:

~/.claude/CLAUDE.md              → Global (todas as máquinas)
./CLAUDE.md                      → Projeto (raiz do repo, compartilhado via git)
./CLAUDE.local.md                → Projeto local (gitignored, preferências pessoais)
./src/module/CLAUDE.md           → Módulo específico (carregado quando acessado)

4. Comandos Essenciais (Nível 1)

/login — Autenticação

claude /login

Primeiro comando em qualquer máquina nova, container ou CI. Sem autenticação, nada funciona.

/doctor — Diagnóstico da Instalação

claude /doctor

Verifica dependências, permissões, versões e configurações. Use quando algo não funciona como esperado. É o "check-up" antes de procurar o problema manualmente.

/init — Inicialização do Projeto

claude /init

Cria o CLAUDE.md na raiz do projeto. Execute sempre ao começar um projeto novo. Sem ele, o Claude repete as mesmas perguntas toda sessão.

/help — Lista de Comandos

claude /help

Exibe todos os comandos disponíveis, incluindo skills personalizados e comandos de MCP servers conectados. Use para descobrir o que está disponível na sessão atual.

/clear — Limpar Histórico

claude /clear

Apaga todo o histórico da conversa. O contexto fica vazio, mas edições de arquivo feitas na sessão permanecem. Use ao trocar completamente de tarefa.

/exit — Sair

claude /exit

Encerra a sessão do Claude Code.

5. Controle de Custo e Estratégia (Nível 2)

/model — Escolha o Modelo

claude /model haiku    # Rápido e barato ($)
claude /model sonnet   # Equilíbrio ($$) — default
claude /model opus     # Máxima inteligência ($$$)

Estratégia de otimização de custo:

Dica profissional: Troque de modelo no meio da tarefa. Comece com Haiku para explorar a codebase, suba para Sonnet para implementar, use Opus apenas quando travar em algo complexo.

/plan — Planejamento antes da Execução

claude /plan "migrar autenticação de JWT para OAuth2 com Spring Security"

O modelo expõe o plano completo antes de agir. Você valida a estratégia antes de gastar tokens com implementação errada.

Quando usar:

• Tarefas que levam mais de 30 minutos

• Código que você não conhece

• Refatoração que mexe em múltiplos arquivos

• Sempre que o custo de errar é alto

Exemplo de output:

Plano de ação:
1. Analisar SecurityConfig.java e fluxo JWT atual
2. Adicionar dependência spring-security-oauth2-client
3. Criar OAuth2SecurityConfig com providers
4. Migrar endpoints de login/callback
5. Atualizar testes de integração
6. Rodar /security-review

Prosseguir? (y/n)

Dica: Use Shift+Tab para alternar rapidamente entre modo normal → auto-accept → plan mode.

/effort — Profundidade de Raciocínio

claude /effort low     # Rápido, superficial
claude /effort medium  # Default (padrão para Opus desde março 2026)
claude /effort high    # Máximo raciocínio

Importante: /effort e /model são independentes. /model escolhe qual IA usar. /effort define quanto ela pensa. Opus com effort low é diferente de Opus com effort high.

/compact — Compressão de Contexto

claude /compact
# Com instrução do que preservar:
claude /compact "manter o contexto sobre a migração de autenticação"

Comprime o histórico em um resumo estruturado, liberando espaço na janela de contexto sem perder o foco da sessão.

Regras práticas:

• Execute quando o uso de contexto passar de 80%

• Execute em pontos de quebra naturais (após completar uma subtarefa)

• A compactação automática dispara em 95%, mas pode descartar detalhes importantes — faça manualmente

• Desde v2.0.64, a compactação é instantânea

Diferença do /clear:

• /compact → comprime mantendo resumo (lembra o que foi feito)

• /clear → apaga tudo (recomeça do zero)

/cost e /stats — Monitoramento de Gastos

claude /cost     # Token usage da sessão atual
claude /stats    # Painel detalhado com histórico

O /stats mostra sessões, tokens consumidos, distribuição por modelo e custo total. Use semanalmente para identificar padrões de gasto.

Controle de orçamento via CLI:

# Limite rígido de gastos
claude -p "corrigir testes falhando" --max-budget-usd 2.00

# Limitar turnos do agente
claude -p "revisar este arquivo" --max-turns 3

/fast — Fast Mode (Opus acelerado)

claude /fast

Ativa respostas 2.5x mais rápidas no Opus 4.6 com configurações otimizadas de API. Não é um modelo diferente — é o mesmo Opus com velocidade priorizada. Ideal para iteração rápida e debugging interativo. Desative quando economia de custo importar.

Atenção: Ao ativar Fast Mode no meio da sessão, todo o contexto anterior é re-cobrado nas taxas do Fast Mode.

6. Inspeção, Segurança e Recuperação (Nível 3)

/diff — Review antes do Commit

claude /diff

Mostra exatamente o que foi alterado, arquivo por arquivo, em um painel interativo. Use antes de qualquer commit, especialmente após sessões longas — o Claude pode ter modificado arquivos além do escopo original.

/rewind — Desfazer Tudo

claude /rewind

Restaura código e conversa para o estado anterior ao erro. Diferente do git reset, que só volta arquivos — o /rewind volta o contexto completo da sessão.

Quando usar: O Claude tomou uma decisão errada que propagou efeitos colaterais em múltiplos arquivos.

/fork — Bifurcação Segura

claude /fork

Cria uma cópia da conversa atual em uma branch separada. O original fica intocado. É um sandbox para experimentação.

Diferença chave:

• /fork → copia a conversa, original permanece intacto (quer testar algo)

• /rewind → volta a conversa no mesmo branch (quer desfazer algo)

/security-review — Auditoria de Segurança

claude /security-review

Escaneia o código buscando:

• Senhas e secrets em texto claro

• Segredos JWT hardcoded

• Vulnerabilidades de injeção (SQL, XSS, command injection)

• Configurações inseguras

• Upload sem validação

Execute sempre antes de push ou deploy. Transforma segurança em prática sistemática, não manual e inconsistente.

/simplify — Refatoração Automática

claude /simplify

Invoca três agentes internos que trabalham em paralelo para revisar a codebase: identificam complexidade desnecessária, duplicações e oportunidades de limpeza. O resultado é código mais legível sem você precisar descrever cada ponto.

/btw — Dúvida Paralela ⭐

claude /btw "qual a diferença entre @Transactional(readOnly=true) e sem readOnly?"

Abre um contexto separado para a pergunta, sem poluir a tarefa principal. Genial para manter o foco.

Cenário típico:

Você: "refatore o módulo de pagamentos para usar Spring Data JPA Specifications"
Claude: [trabalhando na refatoração...]
Você: /btw "como funciona Criteria API vs Specifications no Spring?"
Claude: [responde no contexto paralelo]
Você: [volta à refatoração com contexto limpo]

/debug — Caçador de Bugs

claude /debug

Lê todo o log da sessão e identifica a causa raiz do erro. Melhor que grep porque entende o contexto, não apenas faz matching de strings. Especialmente útil em falhas intermitentes.

/context — Visualizar Uso de Contexto

claude /context

Mostra quanto da janela de contexto está sendo utilizado. Útil para decidir quando executar /compact.

7. Automação e Paralelização (Nível 4)

/batch — Execução em Massa

claude /batch "adicione testes unitários em todos os Services do pacote com.empresa.pagamentos.service"

Divide a tarefa e executa em paralelo. Exemplo: 40 Services → 40 arquivos de teste gerados simultaneamente.

/loop — Repetição Condicional

claude /loop "rode ./mvnw test a cada 5 min até todos os testes passarem"

Repete uma ação em intervalos regulares até que a condição seja satisfeita. Ideal para debug iterativo e fixing de testes flaky.

/batch e /loop cobrem dimensões diferentes: /batch paraleliza em espaço (múltiplos arquivos), /loop repete no tempo (até condição).

/bashes — Gerenciar Tasks em Background

claude /bashes

Lista e gerencia tarefas de background em execução.

8. MCP — Conexão com o Ecossistema (Nível 5)

O MCP (Model Context Protocol) é um protocolo aberto que permite ao Claude Code interagir com ferramentas externas.

Configuração

# Adicionar servidor MCP
claude /mcp add github
claude /mcp add slack
claude /mcp add notion
claude /mcp add postgres

Após conectar, cada servidor expõe seus prompts como slash commands no formato:

/mcp__github__list_prs
/mcp__github__create_pr
/mcp__slack__send_message
/mcp__postgres__query

Arquivo de configuração MCP

Crie .mcp.json na raiz do projeto (versionado no git para compartilhar com a equipe):

{
  "mcpServers": {
    "github": {
      "type": "url",
      "url": "https://mcp.github.com/sse"
    },
    "context7": {
      "type": "url",
      "url": "https://mcp.context7.com/sse"
    },
    "postgres": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Possibilidades com MCP

• Jira/Linear: Ler tickets, atualizar status, criar issues

• GitHub: PRs, code review, issues, actions

• Slack/Discord: Enviar mensagens, ler canais

• Notion/Google Drive: Acessar documentação

• PostgreSQL: Queries diretas no banco

• Context7: Buscar documentação atualizada de frameworks

• Browser (Playwright/Chrome): Automação web, screenshots

MCP Tool Search (Lazy Loading)

O Claude Code usa lazy loading para identificar e ativar apenas ferramentas MCP relevantes com base no contexto, em vez de carregar centenas de ferramentas no startup. Isso reduz overhead de inicialização e melhora a precisão.

9. Skills — Comandos Personalizados (Nível 6)

Skills são o sistema de comandos reutilizáveis do Claude Code. São arquivos Markdown com instruções que o Claude segue quando invocado.

Estrutura de diretórios

~/.claude/skills/            → Skills pessoais (disponíveis em todos os projetos)
.claude/skills/              → Skills do projeto (compartilhados via git)
.claude/commands/            → Formato legado (ainda funciona, mas skills é recomendado)

Criando um skill

Crie ~/.claude/skills/spring-service/SKILL.md:

---
name: spring-service
description: Cria um Service Spring Boot seguindo as convenções do projeto. Use quando o usuário pedir para criar um service, lógica de negócio ou camada de serviço.
---

Ao criar um Service Spring Boot, siga estas regras:

1. **Anotação**: Use @Service e @Transactional na classe
2. **Injeção**: Construtor com final fields (nunca @Autowired em campo)
3. **Early return**: Sempre prefira early return ao invés de else
4. **DTOs**: Use Java Records para input/output
5. **Exceções**: Lance exceções de negócio específicas, nunca genéricas
6. **Logs**: Use @Slf4j do Lombok
7. **Testes**: Crie o teste unitário junto, em src/test

Exemplo de estrutura:

```java
@Slf4j
@Service
@Transactional
public class PagamentoService {

    private final PagamentoRepository repository;
    private final NotificacaoService notificacaoService;

    public PagamentoService(PagamentoRepository repository, 
                            NotificacaoService notificacaoService) {
        this.repository = repository;
        this.notificacaoService = notificacaoService;
    }

    public PagamentoResponse processar(PagamentoRequest request) {
        var pagamentoExistente = repository.findByIdempotencyKey(request.idempotencyKey());
        if (pagamentoExistente.isPresent()) {
            log.info("Pagamento duplicado detectado: {}", request.idempotencyKey());
            return PagamentoResponse.from(pagamentoExistente.get());
        }

        var pagamento = Pagamento.criar(request);
        var salvo = repository.save(pagamento);
        notificacaoService.enviar(salvo);

        return PagamentoResponse.from(salvo);
    }
}

### Invocando

```bash
claude /spring-service
# Ou o Claude detecta automaticamente pela descrição

Frontmatter avançado

---
name: security-scan
description: Scan OWASP Top 10 no projeto
allowed-tools: Read, Grep, Glob, Bash(mvn dependency-check:*)
model: claude-opus-4-6
context: fork
agent: general-purpose
---

Opções do frontmatter:

• allowed-tools → Restringe quais ferramentas o skill pode usar

• model → Força um modelo específico (ex: haiku para tarefas simples)

• context → fork para executar em contexto separado

• agent → Define o tipo de agente

• hooks → Hooks específicos do skill

Skills Bundled (já incluídos)

O Claude Code vem com skills pré-configurados que funcionam como slash commands:

Boas práticas para skills

1. Seja diretivo, não conversacional — "Revise o código" ao invés de "Você poderia revisar?"

2. Inclua formato de output — Diga exatamente como estruturar a resposta

3. Adicione exemplos — O Claude segue exemplos de perto

4. Mantenha focado — Um skill por workflow. "Faça tudo" é menos eficaz que três skills focados

5. Máximo 500 palavras — Skills longos consomem contexto

6. A description é um trigger, não um resumo — Escreva para o modelo ("quando devo disparar?")

7. Inclua uma seção Gotchas — Adicione pontos de falha do Claude ao longo do tempo

10. Hooks — Automação no Ciclo de Vida (Nível 7)

Hooks são comandos automatizados que executam em pontos específicos do ciclo de vida do Claude Code. Transformam boas práticas (consultivas) em regras aplicadas (obrigatórias).

Eventos de Hook disponíveis

Importante: Apenas PreToolUse pode bloquear ações. Use-o para gates de segurança, proteção de arquivos e revisão obrigatória.

Configuração

Hooks vivem em .claude/settings.json (projeto) ou ~/.claude/settings.json (global):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $FILE_PATH"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"block\": true, \"message\": \"Não permitido editar branch main diretamente\"}'"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date): $CONVERSATION_SUMMARY\" >> ~/.claude/activity.log"
          }
        ]
      }
    ]
  }
}

Exemplos práticos

Auto-format após edição (Java/Spring):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "google-java-format --replace $FILE_PATH 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Proteger arquivos críticos:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if echo $FILE_PATH | grep -qE '(application-prod|docker-compose.prod|SecurityConfig)'; then echo '{\"block\": true, \"message\": \"Arquivo protegido. Use /fork para testar mudanças.\"}'; fi"
          }
        ]
      }
    ]
  }
}

Rodar testes após edição de teste:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if echo $FILE_PATH | grep -q 'Test.java'; then cd $CLAUDE_PROJECT_DIR && ./mvnw test -pl . -Dtest=$(basename $FILE_PATH .java) 2>&1 | tail -5; fi"
          }
        ]
      }
    ]
  }
}

Tipos de handlers

1. command — Executa um script shell

2. prompt — Envia um prompt ao Claude para decisão

3. agent — Delega para um subagente

Debugging de hooks

claude --debug  # Mostra execução detalhada dos hooks

11. Subagents — Agentes Especializados (Nível 8)

Subagentes são instâncias separadas do Claude que rodam com contexto, sistema prompt e permissões próprias. O Claude decide quando spawnar agentes, mas você pode definir agentes customizados.

Agentes embutidos

O Claude Code já vem com agentes internos:

• Plan — Planejamento de tarefas

• Explore — Exploração da codebase

• Task (agora Agent) — Execução de subtarefas

Criando agentes personalizados

Crie .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Revisa código para qualidade, segurança e performance
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
maxTurns: 10
skills:
  - security-scan
hooks:
  Stop:
    - type: command
      command: "echo 'Review completo' >> review.log"
---

Você é um engenheiro sênior especialista em Java/Spring Boot.

Ao revisar código, avalie:

1. **Qualidade e legibilidade**
   - Nomes significativos para classes, métodos e variáveis
   - Princípios SOLID aplicados
   - Early return ao invés de else

2. **Segurança**
   - Injeção SQL/XSS/command injection
   - Autenticação e autorização (Spring Security)
   - Secrets no código

3. **Performance**
   - N+1 queries em JPA
   - Índices faltando no PostgreSQL
   - Cache desnecessário ou ausente

4. **Testes**
   - Cobertura adequada
   - Cenários de borda testados
   - Mocks corretos

Forneça referências de linha específicas e sugestões de correção.

Invocando agentes

# O Claude decide quando usar automaticamente, mas você pode pedir:
"Use o agente code-reviewer para revisar as mudanças do módulo de pagamentos"

Frontmatter de agentes

Memória de agentes

Agentes podem ter memória persistente:

~/.claude/agent-memory/<tipo>/MEMORY.md        → Global
.claude/agent-memory/<tipo>/MEMORY.md          → Projeto (compartilhado)
.claude/agent-memory-local/<tipo>/MEMORY.md    → Local (não commitado)

Isolamento com Worktrees

"Implemente esta feature em um worktree isolado para eu revisar antes de mergear"

O agente recebe sua própria cópia do repositório via git worktree. Mudanças não afetam seu diretório de trabalho até você mergear.

12. Agent Teams — Orquestração Multi-Agente (Nível 9)

Agent Teams é a feature experimental de multi-agente do Claude Code, onde uma sessão atua como "líder" coordenando múltiplos "teammates" via uma task list compartilhada.

Habilitação

// .claude/settings.json ou ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Uso

# Dentro do Claude Code:
"crie um agent team com 3 teammates para refatorar estes módulos em paralelo"

Use Shift+Down para alternar entre teammates e enviar mensagens individuais.

Componentes

1. Lead — Sessão principal que coordena

2. Teammates — Instâncias independentes com contexto próprio

3. Task List — Lista de tarefas compartilhada

4. Messaging — Comunicação direta ou broadcast

Comunicação

• Direct message → para um teammate específico

• Broadcast → para todos (use com moderação — custo escala com tamanho do time)

• Idle notifications → alerta quando um teammate está esperando

• Shared task list → coordenação central

Quando usar Agent Teams

• Refatoração que toca API, banco, testes e documentação simultaneamente

• Code review multi-aspecto (segurança + performance + qualidade)

• Feature full-stack (frontend + backend + infra)

Quando NÃO usar

• 95% das tarefas não precisam de multi-agente

• É caro — consome tokens de todas as instâncias

• Use subagentes simples primeiro; escale para Agent Teams só quando necessário

Alternativas de orquestração

Aviso: Multi-agente é experimental. Esteja preparado para atingir limites de uso rapidamente.

13. Integração com IDEs (VS Code e JetBrains)

VS Code

Instale a extensão "Claude Code" pelo Marketplace (ou Cmd+Shift+X → buscar "Claude Code").

Funcionalidades:

• Inline diffs visuais

• @-mentions para referenciar arquivos

• Plan review com comentários no editor

• Histórico de conversas

• Gerenciamento de MCP servers via /mcp

• Sessões como abas no editor

Abrir: Cmd+Shift+P → "Claude Code" → "Open in New Tab"

JetBrains (IntelliJ, PyCharm, WebStorm)

Instale o plugin "Claude Code" pelo JetBrains Marketplace.

Funcionalidades:

• Visualização interativa de diffs

• Compartilhamento de contexto de seleção

Cursor

A extensão Claude Code também funciona no Cursor — busque "Claude Code" na aba de extensões.

14. CI/CD com GitHub Actions

Setup rápido

# Dentro do Claude Code:
claude /install-github-app

Este comando guia a instalação do GitHub App e configuração dos secrets necessários.

Workflow de Code Review Automatizado

# .github/workflows/claude-review.yml
name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]
  issue_comment:
    types: [created]

jobs:
  review:
    if: |
      (github.event_name == 'pull_request') ||
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude'))
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude_args: "--max-turns 5 --model claude-sonnet-4-6"

Workflow de Security Scan

name: Claude Security Scan

on:
  pull_request:
    branches: [main, develop]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Analise as mudanças deste PR focando em:
            1. Vulnerabilidades OWASP Top 10
            2. Secrets ou credenciais expostas
            3. Injeção SQL/XSS nos controllers
            4. Configurações inseguras do Spring Security
            5. Dependências com CVEs conhecidas
            Formate o resultado como checklist com severity.
          claude_args: "--max-turns 3 --model claude-sonnet-4-6"

Combinando Hooks + GitHub Actions

• Hooks locais → capturam problemas antes do commit (dev-time)

• GitHub Actions → capturam problemas antes do merge (CI-time)

• Juntos, formam uma dupla camada de qualidade que reduz significativamente bugs em produção

15. Claude Code na Web e Desktop

Claude Code na Web

Acesse claude.ai/code para usar sem setup local:

• Agentes cloud-hosted — processamento remoto, sem consumir recursos locais

• Assíncrono — agentes continuam trabalhando após fechar a aba

• Cross-device — acesse de qualquer dispositivo

• Paralelo — múltiplas tarefas simultâneas

App Desktop

claude /desktop

Transfere a sessão do terminal para o app desktop, preservando contexto. O app oferece:

• Diffs visuais

• Múltiplas sessões lado a lado

• Tarefas agendadas

• Sessões cloud

Controle Remoto

claude /remote-control
# Com nome personalizado:
claude /remote-control --name "Refactor Auth Module"

Expõe a sessão para controle via web/mobile. Útil para deploys noturnos ou tarefas longas que precisam supervisão eventual.

16. Atalhos de Teclado

Durante sessão interativa

Modo Bash (!)

O modo bash (!) permite executar comandos shell diretamente sem sair do Claude Code:

! git status
! ./mvnw test
! docker ps

17. Modo Headless e Scripting

O modo headless (-p ou --print) é a chave para integrar o Claude Code em scripts, CI/CD e automações.

Uso básico

# Query simples
claude -p "explique o que este projeto faz"

# Output JSON estruturado
claude -p "liste todos os endpoints da API" --output-format json

# Streaming JSON
claude -p "analise este log" --output-format stream-json

# Pipe de input
cat error.log | claude -p "qual a causa raiz deste erro?"

# Encadear com ferramentas Unix
gh pr diff 123 | claude -p "revise estas mudanças focando em segurança" > review.md

Sessão encadeada

# Iniciar sessão
session_id=$(claude -p "inicie review do módulo auth" --output-format json | jq -r '.session_id')

# Continuar na mesma sessão
claude --resume "$session_id" -p "verifique compliance com LGPD"
claude --resume "$session_id" -p "gere relatório final"

Flags úteis para CI/CD

# System prompt adicional
claude -p "analise erros" --append-system-prompt "Você é um SRE expert"

# Ferramentas permitidas
claude -p "revise segurança" --allowedTools "Read,Grep,Glob"

# Orçamento máximo
claude -p "corrigir testes" --max-budget-usd 2.00

# Máximo de turnos
claude -p "revisar arquivo" --max-turns 3

# Modelo específico para CI (econômico)
claude -p "verificar linting" --model haiku

Extended Thinking

Adicione palavras-chave ao prompt para ativar raciocínio estendido:

# Boost leve
claude -p "Think. Desenhe um plano para refatorar o módulo auth."

# Boost médio
claude -p "Think harder. Elabore uma estratégia de migração REST para gRPC."

# Boost máximo
claude -p "Ultrathink. Proponha uma estratégia passo a passo para corrigir testes flaky."

18. Gestão de Contexto — Evitando Context Rot

Context rot é a degradação da qualidade das respostas conforme a conversa cresce. O Claude começa a "esquecer" coisas importantes quando o contexto enche.

Sinais de context rot

• Claude repete perguntas já respondidas

• Perde o foco da tarefa original

• Mistura contextos de diferentes tópicos

• Respostas ficam genéricas ao invés de específicas

Estratégia anti-rot

1. Monitore: Use /context para ver o uso atual

2. Compacte preventivamente: /compact "manter foco em X" ao atingir 80%

3. Limpe ao trocar de tarefa: /clear quando o assunto muda completamente

4. Use /btw para dúvidas paralelas: Não polua o contexto principal

5. Scopes de investigação: Peça ao Claude usar subagentes para exploração, mantendo o contexto principal limpo

6. Commits frequentes: Commit antes de mudar de contexto — o git é seu safety net

Limiares práticos

19. Modos de Permissão

O Claude Code opera em diferentes modos de permissão que controlam o nível de autonomia.

Modos disponíveis

Configuração

# Via CLI
claude --permission-mode auto

# Via settings
# ~/.claude/settings.json
{
  "permissions": {
    "defaultMode": "auto"
  }
}

/sandbox — Ambiente Isolado

claude /sandbox on

Isola a execução. Se o Claude apagar algo, fica só no sandbox. Essencial para:

• Scripts de terceiros não auditados

• Automações experimentais

• Qualquer coisa que possa quebrar algo em produção

20. Configuração Avançada (7 Camadas)

O Claude Code possui 7 camadas de configuração, cada uma com propósito específico:

1. CLAUDE.md — Instruções do Projeto

./CLAUDE.md                  → Compartilhado (git)
./CLAUDE.local.md            → Local (gitignored)
~/.claude/CLAUDE.md          → Global

2. Auto Memory — Notas Aprendidas

~/.claude/projects/<projeto>/memory/    → Aprendizado automático de conversas

3. Rules — Regras Modulares

.claude/rules/
  ├── formatting.md      → Regras condicionais por glob pattern
  ├── security.md
  └── testing.md

Cada regra pode ter um paths: que define quando é carregada:

---
paths:
  - "src/**/*.java"
---
Sempre use @Transactional em métodos de service.

4. Settings — Permissões, Tools, Hooks

.claude/settings.json        → Projeto (compartilhado)
.claude/settings.local.json  → Local (gitignored)
~/.claude/settings.json      → Global

5. Hooks — Automação de Ciclo de Vida

Definidos nos arquivos de settings (veja seção 10).

6. Skills — Comandos Reutilizáveis

.claude/skills/              → Projeto
~/.claude/skills/             → Pessoal

7. Agents — Subagentes Especializados

.claude/agents/              → Projeto

Variáveis de Ambiente

# Em settings.json ou .env
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1  # Carregar CLAUDE.md de --add-dir
SLASH_COMMAND_TOOL_CHAR_BUDGET=16000             # Budget de descrição de skills

21. Fluxos de Trabalho Completos

Cenário 1: Nova Feature (Spring Boot)

# 1. Setup (uma vez por projeto)
claude /init

# 2. Planejamento
claude /plan "implementar endpoint de webhook de pagamentos com idempotency"

# 3. Execução
claude "implemente o webhook seguindo o plano"

# 4. Dúvida paralela durante execução
claude /btw "como funciona idempotency key no Stripe?"

# 5. Review
claude /diff
claude /security-review

# 6. Commit
! git add .
! git commit -m "feat: webhook de pagamentos com idempotency"

# 7. Limpeza de contexto
claude /compact "manter contexto do webhook"

Cenário 2: Debug de Produção

# 1. Diagnóstico
claude /doctor

# 2. Modelo potente + effort máximo
claude /model opus
claude /effort high

# 3. Análise do erro
claude /debug
# Ou:
cat prod-error.log | claude -p "identifique a causa raiz"

# 4. Correção
claude "corrija o erro de race condition no PagamentoService"

# 5. Validação
claude /diff
claude /security-review

# 6. Se der errado
claude /rewind

Cenário 3: Refatoração Grande

# 1. Fork para segurança
claude /fork

# 2. Plano detalhado
claude /model opus
claude /effort high
claude /plan "extrair módulo de autenticação para microsserviço Spring Boot"

# 3. Execução
claude "execute o plano"

# 4. Paralelização
claude /batch "atualize todos os imports e referências ao AuthService em todo o projeto"

# 5. Testes
claude /loop "rode ./mvnw test a cada 2 min até todos passarem"

# 6. Review final
claude /diff
claude /security-review
claude /simplify

Cenário 4: Code Review de PR

# Opção 1: No terminal
gh pr diff 42 | claude -p "revise focando em segurança, performance e qualidade de código Spring Boot"

# Opção 2: Via GitHub Actions (automatizado)
# Configure o workflow da seção 14

# Opção 3: Dentro do Claude Code
claude --from-pr https://github.com/org/repo/pull/42

Cenário 5: Onboarding em Projeto Desconhecido

# 1. Entender o projeto
claude /init
claude "explique a arquitetura deste projeto e os módulos principais"

# 2. Explorar com segurança (plan mode)
# Shift+Tab até plan mode
claude "quais são os fluxos críticos de negócio?"

# 3. Primeira contribuição
claude /plan "corrigir o bug #123 no módulo de pagamentos"

22. Erros Comuns e Como Evitar

❌ Não usar /init

Problema: Claude pergunta a mesma coisa toda sessão, perde convenções.
Solução: claude /init no primeiro dia do projeto. Mantenha o CLAUDE.md atualizado.

❌ Usar Opus para tudo

Problema: Custo 10x maior sem necessidade.
Solução: Haiku para mecânico, Sonnet para 90%, Opus apenas para complexo.

❌ CLAUDE.md gigante

Problema: Regras importantes se perdem no ruído. Claude ignora metade.
Solução: Poda agressiva. Se o Claude já faz algo certo sem a instrução, delete-a. Converta em hooks.

❌ Ignorar /security-review

Problema: Secrets vazadas em produção.
Solução: Execute sempre antes do push. Automatize com hook ou GitHub Action.

❌ Não usar /btw

Problema: Contexto poluído com dúvidas paralelas, Claude perde foco.
Solução: /btw para qualquer pergunta fora do escopo da tarefa atual.

❌ Esperar o contexto degradar

Problema: Claude "esquece" coisas importantes, respostas ficam genéricas.
Solução: /compact preventivamente a cada 80% de uso.

❌ Confiar cegamente na IA

Problema: Claude gera código plausível que não lida com edge cases.
Solução: Sempre forneça verificação (testes, scripts). Se não pode verificar, não faça deploy.

❌ Investigação sem escopo

Problema: Você pede ao Claude "investigar algo" sem limites. Ele lê centenas de arquivos e enche o contexto.
Solução: Scoping estreito ou subagentes para exploração isolada.

❌ Não aproveitar o ecossistema

Problema: Usar Claude Code como "chat turbinado" desperdiça 80% do potencial.
Solução: Aprenda skills, hooks, subagentes e MCP progressivamente.

23. Tabela de Referência Rápida

Comandos essenciais

Combinações de otimização

24. Glossário

25. Recursos e Comunidade

Documentação oficial

• Claude Code Docs: code.claude.com/docs

• Repositório GitHub: github.com/anthropics/claude-code

• Changelog: github.com/anthropics/claude-code/blob/main/CHANGELOG.md

• GitHub Actions: github.com/anthropics/claude-code-action

Guias e referências da comunidade

• awesome-claude-code: github.com/hesreallyhim/awesome-claude-code — Lista curada de skills, hooks, plugins e ferramentas

• Claude Code Ultimate Guide: github.com/FlorianBruniaux/claude-code-ultimate-guide — Guia extenso com templates e quizzes

• Claude Code Best Practice: github.com/shanraisshan/claude-code-best-practice — Patterns para skills, agentes e hooks

• Production Commands (57+): github.com/wshobson/commands — Skills prontos para produção

• Claude Code Showcase: github.com/ChrisWiles/claude-code-showcase — Exemplo completo de configuração

• ClaudeFast: claudefa.st — Kit de orquestração agêntica

Ferramentas complementares

• Context7 MCP — Documentação atualizada de frameworks em tempo real

• recall — Busca full-text nas sessões do Claude Code

• cchistory — Histórico de comandos bash executados pelo Claude

• agnix — Linter para arquivos de configuração do Claude Code

• Container Use (Dagger) — Ambientes isolados para agentes

26. FAQ

Preciso do /init em todo projeto?
Sim. É o que separa "IA genérica" de "IA que conhece seu projeto". Execute uma vez e mantenha atualizado.

Vale a pena pagar pelo Opus?
Para arquitetura, debugging complexo e refatoração grande, sim. Para 90% do dia a dia, Sonnet basta. Haiku cobre o resto.

Qual a diferença entre /compact e /clear?
/compact comprime mantendo resumo — Claude lembra o que foi feito. /clear apaga tudo — recomeça do zero. Use /compact para continuar a mesma tarefa, /clear para mudar completamente de assunto.

Qual a diferença entre /fork e /rewind?
/fork cria uma cópia (original intacto) — para experimentar. /rewind volta no tempo na mesma conversa — para desfazer.

O /sandbox protege de tudo?
Não. É uma camada extra, não substitui code review e testes.

Posso usar vários comandos juntos?
Sim. /model opus + /effort high + /plan é comum em tarefas grandes.

O /mcp funciona com qualquer ferramenta?
Sim, qualquer sistema que implemente um servidor MCP compatível, incluindo soluções internas.

O que é o /effort default para Opus?
Desde março 2026, o default para Opus 4.6 em assinantes Max/Team é medium (antes era high).

Como integrar com Spring Boot especificamente?
Crie skills que encapsulam seus padrões Spring (Services, Controllers, DTOs). Use hooks para auto-format com google-java-format e auto-test. Conecte MCP para acessar banco PostgreSQL diretamente.

Agent Teams vale a pena?
Para 95% das tarefas, não. Comece com subagentes simples. Escale para Agent Teams apenas quando precisar de coordenação real entre múltiplas instâncias trabalhando simultaneamente.

Como evitar gastos excessivos?
Use /model haiku para tarefas simples, /compact preventivamente, /stats semanalmente, e --max-budget-usd em pipelines CI/CD.

O /stickers é sério?
Absolutamente. E os adesivos são lindos.

Adoção Progressiva

Se você está começando, não tente usar tudo de uma vez. Siga esta progressão:

A diferença de produtividade entre quem usa apenas prompts e quem domina o ecossistema completo não é 2x. É 10x.

Gostou? Compartilhe com seu time. Contribua com seus próprios padrões e skills.

Marcelo — Desenvolvedor Sênior Full Stack
Java Spring Boot • Laravel • PostgreSQL • React
Especialista em Desenvolvimento Guiado por IA
Usando Claude Code em produção desde do seu lançamento