12 recursos do Claude Code: explicação detalhada com exemplos

1. Visão geral

Claude Code é um coding agent que roda no terminal, capaz de ler, modificar, executar comandos e testar automaticamente o código no seu projeto. O problema é: um agent poderoso, mas se usar a configuração padrão, ele facilmente se “perde” — modifica os arquivos errados, consome a context window inteira, ou executa comandos perigosos. Este artigo explica 12 recursos que ajudam você a controlar esse agent de forma deliberada. Após ler, você saberá como configurar CLAUDE.md, permissions, hooks, MCP… para que Claude Code trabalhe seguindo as convenções da sua equipe, em um projeto Spring Boot de exemplo que contém Order, Customer, PaymentService.

2. CLAUDE.md

CLAUDE.md é um arquivo de memória que Claude Code lê automaticamente no início de cada sessão. É o lugar onde você declara convenções de código, estrutura de diretórios, comandos de build, style guide — para que o agent não precise perguntar a cada vez.

# CLAUDE.md

## Arquitetura
- Package `com.nonladev.order`: domain Order, Customer
- Package `com.nonladev.payment`: PaymentService, PaymentGateway (interface)

## Convenções
- Sempre escrever testes JUnit 5 + AssertJ para novos métodos públicos
- Nunca usar `@Autowired` field injection, apenas constructor injection
- Executar `mvn verify` antes de informar "pronto"

## Comandos frequentes
- Build: `mvn -q clean verify`
- Rodar local: `mvn spring-boot:run`

Claude lê esse arquivo antes de executar qualquer task na sessão. Se você pedir “adicione um método de reembolso para PaymentService”, o agent saberá automaticamente usar constructor injection e escrever o teste incluído — sem necessidade de repetir as instruções.

Aviso: não coloque muitos detalhes no CLAUDE.md. Um arquivo longo consome a context window desde o início da sessão, enquanto a maioria do conteúdo pode não ser relevante para a task atual.

3. Permissions

Permissions controlam quais tools Claude pode usar e quais ficam bloqueados — importante porque o agent tem permissão para executar comandos shell reais.

{
  "permissions": {
    "allow": [
      "Bash(mvn *)",
      "Edit(src/main/java/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Edit(src/main/resources/application-prod.properties)"
    ]
  }
}

Esse arquivo settings.json fica dentro do diretório .claude/. A linha allow autoriza o agent a executar mvn e editar arquivos em src/main/java, mas a linha deny bloqueia absolutamente o comando de remoção recursiva e impede a edição do arquivo de configuração de produção. Quando Claude quer ultrapassar uma permissão, ele pedirá sua confirmação antes de executar.

Erro comum: deixar permissions muito amplas (allow: ["*"]) permite ao agent executar qualquer comando sem pedir — perigoso com arquivos de config sensíveis ou secrets.

4. Plan Mode

Plan Mode força Claude a apresentar um plano antes de mexer no código. Você revisa o plano, faz ajustes se necessário, e depois autoriza a execução.

> Adicione o recurso de reembolso parcial para PaymentService

[PLAN MODE]
1. Adicionar método refundPartial(Order order, BigDecimal amount) a PaymentService
2. Validar que amount <= order.getTotalPaid()
3. Chamar PaymentGateway.refund(...)
4. Escrever PaymentServiceTest para 2 casos: válido, amount acima do limite

Deseja que eu execute esse plano? [y/n/edit]

Quando você responde edit, Claude ajustará o plano de acordo com suas sugestões (por exemplo, adicionar logging de auditoria) antes de tocar no código-fonte real. Isso é especialmente útil para tasks que modificam vários arquivos, pois você detecta uma direção errada no estágio de planejamento, ao invés de após o código já estar bagunçado.

5. Checkpoints

Checkpoints são snapshots automáticos do projeto em momentos importantes da sessão, permitindo você “rebobinar” se o agent bagunçar algo.

# Ver histórico de checkpoints na sessão
/rewind

# Saída
Checkpoint 1 - 10:02 - antes de modificar PaymentService
Checkpoint 2 - 10:05 - após adicionar refundPartial
Checkpoint 3 - 10:09 - após modificar teste (com erro)

# Voltar ao checkpoint 2
/rewind 2

Diferente de git commits, checkpoints não exigem que você os crie manualmente — Claude Code salva automaticamente antes de cada mudança importante. Se o agent modificar o teste de forma incorreta (por exemplo, comentar assertions para o teste “passar”), você rebobina para o estado anterior sem precisar fazer git reset manualmente.

Nota: checkpoints existem apenas dentro da sessão atual, não substituem git. Você ainda deve fazer commits reais quando alcançar um milestone.

6. Skills

Skills são arquivos de instruções reutilizáveis que Claude aplica automaticamente quando detecta uma task apropriada — sem precisar você chamar pelo nome a cada vez.

---
name: spring-boot-test-writer
description: Use quando precisar escrever testes para service layer em projetos Spring Boot
---

Ao escrever testes para uma classe Service:
1. Use JUnit 5 + AssertJ, não use Hamcrest
2. Mock dependências com Mockito, nomeie as variáveis como `mock<Dependência>`
3. Nomeie métodos de teste seguindo `should_<esperado>_when_<condição>`

Esse arquivo fica em .claude/skills/spring-boot-test-writer.md. Quando você pede “escreva testes para PaymentService”, Claude reconhece a skill apropriada e aplica a convenção lá, resultando em:

class PaymentServiceTest {

    private final PaymentGateway mockGateway = mock(PaymentGateway.class);
    private final PaymentService paymentService = new PaymentService(mockGateway);

    @Test
    void should_refundAmount_when_amountIsWithinPaidTotal() {
        Order order = new Order("ORD-1", BigDecimal.valueOf(200));

        paymentService.refundPartial(order, BigDecimal.valueOf(50));

        verify(mockGateway).refund(order.getId(), BigDecimal.valueOf(50));
    }

    @Test
    void should_throwException_when_amountExceedsPaidTotal() {
        Order order = new Order("ORD-2", BigDecimal.valueOf(100));

        assertThatThrownBy(() -> paymentService.refundPartial(order, BigDecimal.valueOf(150)))
            .isInstanceOf(IllegalArgumentException.class);
    }
}

Skills diferem de CLAUDE.md em um ponto: CLAUDE.md sempre é carregado, mas uma skill só carrega quando o contexto precisa — economizando context window em projetos com muitas convenções especializadas.

7. Hooks

Hooks executam scripts shell seus em pontos específicos do lifecycle do agent, por exemplo PreToolUse (antes de chamar uma tool) ou PostToolUse (após chamar uma tool).

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "mvn -q -pl . checkstyle:check"
      }
    ]
  }
}

Toda vez que Claude termina uma edição (Edit tool), o hook executa checkstyle:check automaticamente. Se o comando falhar, o output é retornado para Claude, o agent corrige o código conforme o erro de estilo antes de informar a conclusão da task — você não precisa rodar a verificação manualmente.

[PostToolUse] mvn checkstyle:check
ERROR: PaymentService.java:42: Linha maior que 120 caracteres
→ Claude encurta automaticamente a linha 42 e executa check novamente

Quando não usar: hooks executam toda vez que a tool é chamada, então se o script é pesado (build de projeto inteiro), a sessão ficará lenta. Só coloque hooks em eventos de lifecycle que precisam de verificação rápida.

8. MCP

MCP (Model Context Protocol) conecta Claude a sistemas externos — database, APIs internas, issue tracker — como uma tool padronizada.

{
  "mcpServers": {
    "postgres-orders": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://localhost:5432/orders_db"]
    }
  }
}

Após registrar esse servidor em .claude/settings.json, você pode perguntar diretamente:

> Quantos Orders estão com status PENDING na tabela orders?

[MCP: postgres-orders] SELECT COUNT(*) FROM orders WHERE status = 'PENDING';
→ 37 pedidos estão PENDING

Claude gera a SQL automaticamente, chama via servidor MCP, e retorna o resultado real do banco — sem você precisar copiar queries manualmente em outro terminal.

9. Plugins

Plugin é um pacote que agrupa skills, servidor MCP e hooks relacionados, permitindo você instalar tudo de uma vez ao invés de configurar cada parte separadamente.

/plugin install spring-boot-toolkit

Esse comando instala um plugin (hipotético) que contém: skill para escrever testes Spring Boot, hook para rodar mvn verify após cada edição, e servidor MCP que conecta ao endpoint do Spring Boot Actuator para o agent verificar automaticamente health checks. Ao invés de você escrever 3 arquivos de configuração separados (skill, hook, mcp) como nos tópicos 6–8, o plugin empacota tudo numa única instalação que pode ser compartilhada com toda a equipe em um único comando.

10. Context

Context é a context window atual da sessão — todos os arquivos lidos, histórico de conversas, outputs de comandos. O comando /context mostra quanto está usando.

/context

Context usage: 48,200 / 200,000 tokens (24%)
- CLAUDE.md: 1,200 tokens
- Arquivos lidos: PaymentService.java, Order.java, PaymentServiceTest.java (6,400 tokens)
- Histórico de conversas: 38,000 tokens
- Outputs de tools: 2,600 tokens

Quando vê o histórico de conversas ocupando a maior parte, você sabe que deveria fazer compactação ou iniciar uma nova sessão, evitando que Claude “esqueça” detalhes importantes mencionados no início devido ao context estar cheio.

11. Slash Commands

Slash command é um atalho para tasks que você repete — digite / seguido do nome, sem precisar escrever o prompt completo toda vez.

---
name: review-pr
description: Revise o diff atual seguindo um checklist padrão
---

Revise o código diff atual com esse checklist:
1. Há testes para a nova lógica?
2. Há logging de informações sensíveis (números de cartão, senhas)?
3. Viola a convenção de constructor injection?

Responda no formato: PASS/FAIL para cada item, com justificativa.

Salve esse arquivo em .claude/commands/review-pr.md, depois chame:

/review-pr

1. PASS - há PaymentServiceTest para refundPartial
2. FAIL - log.info contém order.getCardNumber() na linha 58
3. PASS - usa constructor injection

Slash commands diferem de skills: skills se ativam automaticamente por contexto, enquanto slash commands precisam ser chamados explicitamente pelo nome — ideal para checklists fixos como revisão de PR, release notes.

12. Compaction

Compaction compacta um histórico de conversas longo em um resumo, liberando tokens sem perder informações importantes.

/compact

Antes do compact: 182,000 / 200,000 tokens
Após compact:     24,000 / 200,000 tokens

Resumo mantido:
- Em andamento: adicionar refundPartial a PaymentService
- Concluído: PaymentServiceTest (2 test cases passaram)
- Falta fazer: atualizar especificação OpenAPI para endpoint /refund

Ao invés de o agent esquecer completamente o histórico quando o context enche, compaction mantém os pontos importantes (task em andamento, concluída, faltando) em forma de resumo curto, depois continua a sessão com a maior parte do context livre. Você deveria chamar /compact manualmente após concluir uma sub-task grande, antes de mudar para a próxima.

13. Subagents

Subagents permitem Claude Code gerar múltiplos agentes filhos rodando em paralelo, cada um responsável por uma parte independente do trabalho em um fluxo maior.

---
name: test-writer
description: Especializado em escrever testes unitários para a classe especificada
tools: Read, Edit, Bash
---

Você só escreve testes, não modifica lógica de negócio. Use JUnit 5 + AssertJ.

Com esse arquivo subagent em .claude/agents/test-writer.md, você pode passar uma task grande para o agent principal, que automaticamente distribui entre subagents:

> Complete o módulo de reembolso: adicione lógica, escreva testes, atualize docs

[Agent principal] Distribuindo em 3 subagents em paralelo:
  → subagent "code-writer": adicionar refundPartial a PaymentService
  → subagent "test-writer": escrever PaymentServiceTest
  → subagent "doc-writer": atualizar README.md

[3 subagents rodando em paralelo] ... completado em 42s

Ao invés de o agent principal processar sequencialmente cada passo (código → testes → docs, potencialmente 3 vezes mais tempo), subagents processam simultaneamente partes independentes — útil em fluxos com múltiplas etapas que não dependem fortemente umas das outras.

Quando não usar: se as etapas dependem sequencialmente (por exemplo, escrever testes precisa que o código já exista para conhecer a interface), executar em paralelo causará erros porque o subagent de testes rodará antes do código existir. Use subagents apenas para tarefas verdadeiramente separáveis.

14. Conclusão

Os 12 recursos acima se dividem em três grupos claros: grupo de orientação do agent (CLAUDE.md, Skills, Plan Mode), grupo de controle de segurança (Permissions, Checkpoints, Hooks), e grupo de extensão de capacidades (MCP, Plugins, Subagents). Context, Slash Commands e Compaction são a camada de infraestrutura que ajuda o agent rodar eficientemente em uma sessão longa. Você não precisa usar todos os 12 ao mesmo tempo — comece com CLAUDE.md e Permissions para seu projeto atual, depois adicione Hooks ou MCP quando seu fluxo de trabalho realmente precisar.