Claude Code é muito mais do que você imagina

Quando comecei a usar o Claude Code, tratei-o como um chat.

Eu pedia algo, ele respondia, e era só isso.

Funcionava, mas com o tempo comecei a perceber que não estava aproveitando todo o seu potencial.

Repetia os mesmos prompts. Executava os mesmos comandos. Não tinha clareza de como tirar o máximo proveito dele.

Então parei e me fiz uma pergunta:

Como o Claude Code realmente funciona por dentro?

Comecei a ler a documentação, experimentar e testar.

E o que descobri é o seguinte:

Ele não faz mágica. É construído sobre peças concretas, cada uma com um papel claro. E quando você as entende, todo o resto começa a fazer sentido.

→ Se você repete sempre as mesmas instruções, transforme-as em uma Skill.

→ Se ele perde o fio da meada em uma tarefa longa, delegue para um SubAgent.

→ Se há etapas manuais que você repete, automatize-as com Hooks.

Entender os fundamentos é o que permite saber o que usar, quando e por quê.

Hoje tenho mais de 100 Skills, processos automatizados que antes me tomavam horas, e agentes para revisar código e estudar tópicos que me interessam.

Escrevi este artigo para compartilhar tudo o que aprendi com você.

Vamos começar.

Agent Loop: O Coração do Claude Code

O Claude Code é um agente.

Um sistema ao qual você dá um objetivo e ele trabalha até cumpri-lo.

É diferente de um chat. Num chat, você pergunta "Como adiciono autenticação ao meu aplicativo?" e ele explica os passos.

Mas você tem que ir até o projeto, modificar o código e testar se funciona.

Você faz o trabalho.

Com o Claude Code, você diz "Adicione autenticação ao meu aplicativo" e ele cuida de tudo.

Ele lê o código, escolhe a biblioteca, escreve as alterações e avisa quando terminar.

Ele tem um objetivo: adicionar autenticação.

E trabalha até cumpri-lo.

Mas como ele sabe o que fazer após cada passo? Como sabe se algo funcionou? Ele precisa de algo para coordenar essas decisões.

Isso é o loop.

Um ciclo que se repete.

O Claude Code executa uma ação, observa o resultado, decide o que fazer a seguir e recomeça. Não para até que o objetivo seja alcançado.

Se algo falha, ele volta, corrige e continua.

O loop tem 3 fases:

Coletar contexto → Entende o que precisa fazer. Lê arquivos, analisa código, explora a estrutura do projeto.

Agir → Executa alterações. Edita arquivos, roda comandos, instala dependências.

Verificar resultados → Confirma se o que fez funciona. Executa testes, revisa erros, corrige se algo falhar.

O loop se adapta ao que você pede.

Uma pergunta simples pode exigir apenas coletar contexto. Corrigir um bug pode passar por todas as três fases várias vezes.

O Claude Code decide o que cada passo requer com base no que aprendeu no anterior. E você também faz parte desse loop.

Pode interromper a qualquer momento para redirecioná-lo, adicionar contexto ou pedir que tente outra abordagem.

Este é o coração do Claude Code.

Tudo o que vem a seguir existe para tornar esse loop mais poderoso.

Ferramentas: Como o Claude Code Age no Mundo

Um LLM, por design, apenas processa texto.

Ele recebe texto e gera texto. Não tem acesso ao seu sistema de arquivos, não pode executar comandos, não sabe o que está no seu projeto.

Ele está isolado.

Então, como o Claude Code abre um arquivo ou o modifica?

Ele usa ferramentas.

Ferramentas são funções que o Claude Code pode invocar para interagir com o mundo real.

Pense como aplicativos de celular. O telefone sozinho não faz nada: são os aplicativos que lhe dão capacidades específicas: tirar fotos, enviar mensagens, navegar.

As ferramentas são o mesmo para o Claude Code.

Cada vez que usa uma ferramenta, ele envia uma solicitação ao sistema com o que precisa. O sistema a executa e retorna o resultado.

O Claude Code usa esse resultado para decidir o que fazer a seguir.

1Sua solicitação
2    ↓
3Claude Code decide qual ferramenta usar
4    ↓
5┌─────────────────────────────────┐
6│  Read · Edit · Write · Bash     │
7│  Grep · Glob · WebFetch · WebSearch │
8└─────────────────────────────────┘
9    ↓
10Sistema executa a ferramenta
11    ↓
12Resultado retorna ao Claude Code
13    ↓
14Terminou? → Não → usar outra ferramenta
15             Sim → responder

O Claude Code vem com ferramentas nativas para as operações mais comuns:

Read / Edit / Write → Ler, modificar e criar arquivos. As mais usadas. Cada vez que o Claude Code "entende seu código" ou "faz uma alteração", está usando essas três.

Bash → Acesso total ao terminal. Se você pode fazer pela linha de comando, o Claude Code também pode: instalar dependências, executar testes, fazer commits.

Grep e Glob → Pesquisar dentro do projeto. Glob encontra arquivos por nome ou padrão. Grep pesquisa conteúdo específico dentro de arquivos.

WebFetch e WebSearch → Acesso à internet. Consultar documentação, ler uma API, investigar um erro que nunca viu antes.

Voltando ao exemplo do bug no botão de login.

Quando o Claude Code trabalha nisso, ele usa várias ferramentas juntas:

→ Usa Glob para encontrar o arquivo do componente

→ Usa Read para ler o código e entender o que está acontecendo

→ Usa Edit para corrigir o erro

→ Usa Bash para executar os testes e verificar se funcionou

Tudo isso sem você intervir. Essa é a diferença entre um chat e um agente.

Contexto e Memória: O Que o Claude Code Lembra

O Claude Code funciona, executa ações, obtém resultados e decide o que fazer a seguir.

Mas como ele sabe o que fez à medida que avança?

Tudo graças ao contexto.

O contexto é a informação que o Claude Code tem disponível naquele momento. Cada vez que executa uma ação, o resultado se acumula ali.

Não apenas seu prompt inicial, mas tudo o que ele encontra: arquivos que abriu, o que descobriu no código, as ações que executou e seus resultados.

É por isso que ele pode encadear passos, se corrigir e concluir a tarefa sozinho.

Esse contexto tem 2 problemas.

1. Tem capacidade limitada. Se a sessão for muito longa, o contexto se enche e o Claude Code começa a esquecer o que aconteceu antes. Mais adiante você verá como os SubAgents resolvem isso.

2. É esvaziado toda vez que você abre uma nova conversa. O Claude Code não sabe em qual projeto você está, como sua equipe trabalha ou quais decisões já foram tomadas. Se você não disser, ele infere ou pergunta.

A memória resolve o segundo problema.

É um sistema de arquivos markdown onde você salva tudo o que o Claude Code precisa saber: sua stack, convenções da equipe, como os projetos são estruturados.

O Claude Code os lê no início de cada sessão e injeta essa informação no contexto antes de você escrever a primeira linha.

Sem Memória: Você diz "adicione um endpoint para criar usuários" e o Claude Code pergunta: "Qual framework você usa? Tem um banco de dados configurado? Como as rotas são estruturadas?"

Com Memória: Você diz a mesma coisa e ele já sabe que você usa Express com Prisma, que as rotas vão em /src/routes e que os erros são tratados com um middleware centralizado. Ele começa a trabalhar sem perguntar.

O Claude Code tem 2 sistemas de memória:

→ CLAUDE.md - Arquivos markdown que você escreve com tudo o que o Claude Code precisa saber. Podem residir em diferentes níveis:

→ ~/.claude/CLAUDE.md - Aplica-se a todos os seus projetos. Suas preferências pessoais vão ali: como você quer que ele escreva código, convenções que você sempre usa. Instruções devem ser específicas: "use 2 espaços de indentação" é mais claro que "formate o código bem."

→ /seu-projeto/CLAUDE.md - Específico do repositório. Arquitetura, convenções da equipe e comandos importantes vão ali. Ao iniciar um novo projeto, execute /init e o Claude Code o gera automaticamente. Mantenha abaixo de 200 linhas: se crescer demais, o Claude Code começa a ignorar instruções. E se você o comitar no repositório, toda a equipe compartilha o mesmo contexto.

→ .claude/rules/ - Regras modulares que ativam de acordo com o tipo de arquivo. Útil quando o projeto cresce e você não quer colocar tudo em um único arquivo.

Auto Memory - A memória que o Claude Code constrói por conta própria. Enquanto você trabalha, ele faz anotações por si só: padrões que detecta, correções que você faz, decisões que tomaram juntos. É salvo em

~/.claude/projects/<project>/memory/ e é carregado no início de cada sessão.

Revise-a com frequência: o Claude Code pode ter salvo práticas ruins sem que você perceba.

Dica: Você pode ver e editar tudo o que o Claude Code lembra executando /memory.

Hooks e Skills: Assuma o Controle

1. Hooks

O Claude Code trabalha de forma autônoma.

Executa ações, toma decisões, avança.

Mas essa autonomia tem um lado que não é tão mencionado: o Claude Code faz o que considera correto em cada etapa.

Se algo der errado, ou ele fizer algo que você não queria, já está feito.

Como você o controla? Com hooks.

Um hook é um comando que é executado automaticamente em pontos específicos do ciclo. Antes do Claude Code usar uma ferramenta, depois de usá-la, quando a sessão termina.

Você define o que acontece em cada momento.

O ponto chave é que hooks são determinísticos.

Eles não dependem do Claude Code "lembrar" de fazer algo. São sempre executados, sem exceção.

Os quatro hooks principais são:

PreToolUse - Executa antes do Claude Code usar uma ferramenta. É o único hook que pode bloquear uma ação. Exemplo: Bloquear qualquer comando que tente modificar arquivos .env.

PostToolUse - Executa depois do Claude Code usar uma ferramenta. Exemplo: Executar Prettier automaticamente toda vez que o Claude Code editar um arquivo.

Notification - Executa quando o Claude Code precisa da sua atenção. Exemplo: Receber uma notificação no seu Mac quando o Claude Code terminar uma tarefa longa.

Stop - Executa quando o Claude Code termina de responder. Exemplo: Fazer push automaticamente para staging quando o agente terminar.

Eles são configurados em .claude/settings.json:

1{
2  "hooks": {
3    "PostToolUse": [
4      {
5        "matcher": "Edit|Write",
6        "hooks": [
7          {
8            "type": "command",
9            "command": "npx prettier --write $file_path"
10          }
11        ]
12      }
13    ]
14  }
15}

Este hook executa o Prettier automaticamente toda vez que o Claude Code edita ou cria um arquivo.

Sem você pedir. Sem o Claude Code ter que lembrar.

Sem Hook: O Claude Code edita um arquivo, o código permanece não formatado, e você percebe no próximo commit.

Com Hook: O Claude Code edita um arquivo, o PostToolUse é acionado automaticamente, o Prettier formata o arquivo e o código permanece sempre limpo.

Hooks permitem adicionar comportamento garantido ao ciclo do agente. Não sugestões, não instruções que o modelo pode ignorar. Regras que são sempre executadas.

2. Skills

Há outro problema: consistência.

Você pede a mesma tarefa duas vezes e obtém resultados diferentes. Toda vez que abre uma nova conversa, o Claude Code começa sem saber como você fez da última vez.

Como resolver? Com Skills.

Uma Skill é um arquivo markdown onde você explica o processo exato para uma tarefa ao Claude Code: o que revisar, em que ordem, qual formato usar, o que ignorar.

Toda vez que essa tarefa aparece, o Claude Code segue essas instruções.

Sem Skill: Você pede para documentar uma API e ele gera algo, mas cada vez com um formato diferente. Às vezes com exemplos, às vezes sem.

Com Skill: Você pede para documentar uma API e ele segue o processo exato que você definiu. Sempre com os mesmos passos, o mesmo formato, os mesmos critérios. Toda vez igual.

Para criar uma Skill, você define uma pasta com esta estrutura:

1minha-skill/
2├── SKILL.md          # Instruções principais (obrigatório)
3├── template.md       # Template que o Claude completa
4├── examples/
5│   └── sample.md    # Exemplo de saída esperada
6└── scripts/
7    └── validate.sh  # Script que o Claude pode executar

O único arquivo obrigatório é o SKILL.md. O resto é opcional e você adiciona conforme a necessidade da tarefa.

O SKILL.md tem 2 partes:

O frontmatter - Um bloco YAML com o nome e a descrição. O nome é o comando para invocá-lo manualmente. A descrição é o que o Claude Code lê para decidir quando ativá-lo automaticamente.

O corpo - As instruções em markdown. O fluxo de trabalho, os critérios, o formato de saída.

1---
2name: api-docs
3description: Documenta endpoints de API. Use quando o usuário
4             pedir para documentar uma API ou mencionar "swagger" ou "endpoints"
5---
6
7## Processo
81. Identificar todos os endpoints
92. Para cada um: método, caminho, parâmetros, resposta esperada
103. Incluir um exemplo de requisição e resposta
114. Finalizar com uma tabela resumo

Uma vez criada, você pode invocá-la de duas formas.

Escrevendo /api-docs diretamente no chat, ou simplesmente pedindo ao Claude Code em linguagem natural.

Se a descrição corresponder ao que você está pedindo, ela se ativa sozinha.

Você pode criá-las para qualquer tarefa que repita com um processo claro por trás: documentação de API, changelogs, resumos de reuniões, migrações de código.

SubAgents: Delegue Quando o Problema Cresce

Já vimos que o contexto tem capacidade limitada.

Quanto mais longa a sessão, mais ele se enche. E quando se enche, o Claude Code começa a perder informações sobre o que aconteceu antes.

Imagine que você pede para ele revisar todo o seu projeto em busca de problemas de segurança. Ele lê dezenas de arquivos, analisa o código, gera um relatório detalhado.

Tudo isso enche o contexto rapidamente.

E enquanto faz isso, sua conversa principal fica bloqueada.

Como resolver? Com SubAgents.

Um SubAgent é uma instância separada do Claude Code que é executada com seu próprio contexto.

O agente principal delega uma tarefa a ele, o SubAgent a executa de forma independente e, quando termina, envia um resumo com os resultados.

O contexto do agente principal não se enche com todo o processo, apenas com a conclusão.

1Agente Principal
2    ↓
3"revise o projeto em busca de problemas de segurança"
4    ↓
5┌─────────────────────────────┐
6│    SubAgent: security-reviewer    │
7│                             │
8│  Lê arquivos do projeto     │
9│  Analisa código             │
10│  Detecta vulnerabilidades   │
11│  Gera relatório             │
12└─────────────────────────────┘
13    ↓
14Retorna resumo para o agente principal
15    ↓
16Agente principal continua com o loop

E não só isso.

SubAgents podem ser executados em paralelo.

Em vez de analisar três partes do código sequencialmente, o Claude Code pode delegar todas as três ao mesmo tempo.

O que antes levava minutos pode levar segundos.

1Agente Principal
2    ↓
3Divide o trabalho em tarefas independentes
4    ↓
5┌──────────────┐  ┌──────────────┐  ┌──────────────┐
6│  SubAgent 1  │  │  SubAgent 2  │  │  SubAgent 3  │
7│              │  │              │  │              │
8│ Revisa auth  │  │ Revisa BD    │  │ Revisa APIs  │
9│              │  │              │  │  externas    │
10└──────────────┘  └──────────────┘  └──────────────┘
11        ↓                 ↓                 ↓
12        Agente principal recebe os três resumos
13                          ↓
14                Continua com o loop

O Claude Code tem 3 SubAgents nativos que usa automaticamente:

→ Explore - Um agente rápido e somente leitura, especializado em pesquisar e analisar o projeto. Os resultados ficam no contexto do SubAgent, não no seu.

→ Plan - Ativa no modo de planejamento. Antes de apresentar um plano a você, o Claude Code delega a investigação do projeto a este agente.

→ General-purpose - Para tarefas complexas que exigem exploração e modificações.

Você também pode criar os seus próprios.

SubAgents são definidos em arquivos markdown com frontmatter YAML e salvos em .claude/agents/.

1---
2name: security-reviewer
3description: Revisa código em busca de vulnerabilidades de segurança.
4             Use quando o usuário pedir uma revisão de segurança.
5tools: Read, Grep, Glob
6---
7
8Você é um especialista em segurança. Analise o código para:
9- Injeções SQL
10- Exposição de dados sensíveis
11- Vulnerabilidades de autenticação
12
13Finalize com um resumo das descobertas ordenadas por gravidade.

Observe que no frontmatter limitamos as ferramentas a Read, Grep e Glob.

Este agente pode analisar, mas nunca modificar nada.

Quando você precisa de controle refinado sobre o que cada agente pode fazer, essa restrição de ferramentas é fundamental.

Uma vez criado, o Claude Code o detecta automaticamente pela descrição e o invoca quando a tarefa se encaixa. Ou você pode chamá-lo explicitamente: "use o agente security-reviewer para revisar este PR."

Quando usar SubAgents e quando não usar?

Faz sentido quando a tarefa é longa e vai gerar muita saída, quando você pode dividir o trabalho em partes independentes que executam em paralelo, ou quando precisa de um agente especializado com ferramentas limitadas.

Não vale a pena para tarefas curtas que não enchem o contexto. Coordenar SubAgents adiciona complexidade que não faz sentido se o agente principal consegue resolver a tarefa em dois minutos.

MCP: Conectando o Agente com o Mundo Externo

As ferramentas dão ao Claude Code a capacidade de agir na sua máquina.

Mas há um limite: tudo o que acontece, acontece ali.

Ele não pode abrir um PR no GitHub, consultar um banco de dados de produção ou criar um ticket no Jira. Para fazer isso, antes você precisava sair do agente e fazer manualmente.

Como resolver? Com MCP.

MCP (Model Context Protocol) é um protocolo aberto que define como o Claude Code se conecta com serviços externos.

Funciona com uma arquitetura cliente-servidor: o Claude Code é o cliente, e cada serviço externo tem seu próprio servidor MCP que expõe o que pode fazer.

Quando você conecta um servidor MCP, o Claude Code recebe uma lista de ferramentas disponíveis com seus nomes e descrições.

A partir daí, ele as usa exatamente como ferramentas nativas. A única diferença é que a ação ocorre no serviço externo, não na sua máquina.

1Claude Code
2    ↓
3Decide usar uma ferramenta do servidor MCP do GitHub
4    ↓
5┌─────────────────────────────┐
6│    Servidor MCP do GitHub   │
7│                             │
8│   Abre o PR                 │
9│   Atribui revisores         │
10│   Retorna confirmação       │
11└─────────────────────────────┘
12    ↓
13Claude Code recebe o resultado e continua

Sem MCP: Você diz "terminei as alterações, abra o PR" e o Claude Code não consegue. Você tem que ir ao GitHub, preencher o formulário, atribuir revisores e fazer o merge você mesmo.

Com MCP: Você diz a mesma coisa e o Claude Code abre o PR, escreve a descrição, atribui os revisores e avisa quando estiver pronto. Tudo sem você sair do agente.

Alguns servidores MCP que você pode conectar hoje:

→ GitHub - PRs, revisões, issues

→ Postgres / Supabase - Consultar e modificar bancos de dados

→ Slack - Mensagens e canais

→ Jira - Tickets e projetos

Ferramentas nativas para seu ambiente local. MCP para o mundo externo.

Como Tudo Se Encai­xa

O Claude Code é um agente: um sistema que recebe um objetivo e opera em um loop autônomo até cumpri-lo.

Cada peça que você viu neste artigo existe para tornar esse loop mais poderoso. Mas a melhor forma de entender é vê-las interagindo juntas.

Caso 1: Revisar e mesclar um PR

Você pede ao Claude Code: "Revise o PR #42 e, se estiver tudo certo, faça o merge."

→ Ele usa o MCP do GitHub para ler os arquivos modificados e entender as alterações

→ Delega a análise de segurança a um SubAgent especializado, para não encher o contexto principal

→ Um Hook executa os testes localmente e verifica se tudo passa

→ Se os testes passarem, ele usa o MCP do GitHub para realizar o merge sem você tocar na interface

Você escreveu uma linha. O Claude Code coordenou quatro sistemas.

Caso 2: Documentar uma API e notificar a equipe

Você pede ao Claude Code: "Documente os novos endpoints e avise a equipe."

→ Ele ativa uma Skill de documentação que define o formato exato: o que incluir, como estruturar, quais exemplos adicionar

→ Usa Ferramentas para ler o código e extrair os endpoints

→ Um Hook formata a saída antes de salvá-la

→ Usa o MCP do Slack para enviar o resumo ao canal da equipe

Toda vez que você fizer isso, o resultado será o mesmo. Sem variações, sem você ter que explicar nada.

Tudo gira em torno do loop.

Memória para iniciar cada sessão informada. Ferramentas para agir. Hooks para controlar. Skills para padronizar. SubAgents para escalar. MCP para conectar com o mundo externo.

Quando você entende isso, entende o Claude Code.

E não apenas o Claude Code: Cursor, Copilot e qualquer agente que você usar daqui em diante opera nos mesmos fundamentos.

Os nomes mudam, a interface muda, mas o loop é o mesmo.

A IA está avançando rápido.

Toda semana há algo novo. Mas os fundamentos não mudam com tanta frequência. Tê-los claros é o que permitirá que você se adapte mais rápido e extraia mais do que está por vir.

Não use o Claude Code apenas para dar prompts. Preste atenção no que acontece por baixo. É aí que estão as oportunidades.

Alguns pontos de partida para começar hoje:

→ Revise sua Auto Memory e melhore o que o Claude Code salvou

→ Crie um CLAUDE.md para seu projeto, se ainda não tiver um

→ Conecte o MCP do GitHub

→ Construa um SubAgent para tarefas que enchem o contexto

→ Configure um Hook que execute testes após cada alteração

É isso, até amanhã.

Marcus