Claude Code é muito mais do que você imagina

Quando comecei a usar o Claude Code, eu o tratava como um chat.

Eu pedia algo, ele respondia, e acabava por ali.

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

Eu repetia os mesmos prompts. Executava os mesmos comandos. Não tinha clareza de como aproveitá-lo ao máximo.

Então parei e me fiz uma pergunta:

Como o Claude Code funciona por dentro?

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

E o que descobri é o seguinte:

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

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

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

→ Se existem passos manuais que você repete, você automatiza 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 fazer revisões de código e estudar assuntos 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 para o 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 app?" e ele explica os passos.

Mas você precisa 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 app" e ele cuida de tudo.

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

Ele tem um objetivo: adicionar autenticação.

E ele trabalha até cumprí-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 em seguida e recomeça. Ele 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 que o que fez funciona. Roda 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 etapa exige com base no que aprendeu na anterior. E você também faz parte desse loop.

Você 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.

Tools: Como o Claude Code Age no Mundo

Um LLM, por definição, só 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 tem no seu projeto.

Ele é isolado.

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

Ele usa tools.

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

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

As tools são a mesma coisa para o Claude Code.

Toda vez que ele usa uma tool, envia uma requisição ao sistema com o que precisa. O sistema executa e retorna o resultado.

O Claude Code usa esse resultado para decidir o que fazer em seguida.

1Your request
2    ↓
3Claude Code decides which tool to use
4    ↓
5┌─────────────────────────────────┐
6│  Read · Edit · Write · Bash     │
7│  Grep · Glob · WebFetch · WebSearch │
8└─────────────────────────────────┘
9    ↓
10System executes the tool
11    ↓
12Result returns to Claude Code
13    ↓
14Finished? → No → use another tool
15             Yes → respond

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

Read / Edit / Write → Ler, modificar e criar arquivos. As mais usadas. Toda 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ê consegue fazer pela linha de comando, o Claude Code também consegue: instalar dependências, rodar testes, fazer commits.

Grep e Glob → Busca dentro do projeto. Glob encontra arquivos por nome ou padrão. Grep busca conteúdo específico dentro dos 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 tools 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 rodar os testes e verificar que 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 trabalha, executa ações, obtém resultados e decide o que fazer em seguida.

Mas como ele sabe o que fez ao longo do caminho?

Tudo graças ao contexto.

O contexto é a informação que o Claude Code tem disponível naquele momento. Cada vez que ele 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 consegue encadear passos, se corrigir e finalizar a tarefa sozinho.

Esse contexto tem 2 problemas.

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

2. Ele é esvaziado toda vez que você abre uma nova conversa. O Claude Code não sabe em que projeto você está, como seu time trabalha ou quais decisões já foram tomadas. Se você não contar, 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 do time, como os projetos são estruturados.

O Claude Code os lê no início de cada sessão e injeta essas informações 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 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 ficam 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. Eles podem estar 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 do time e comandos importantes vão ali. Quando você inicia um novo projeto, execute /init e o Claude Code gera automaticamente. Mantenha abaixo de 200 linhas: se crescer demais, o Claude Code começa a ignorar instruções. E se você commitar no repositório, todo o time compartilha o mesmo contexto.

→ .claude/rules/ - Regras modulares que se ativam conforme o tipo de arquivo. Útil quando o projeto cresce e você não quer colocar tudo num ú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 conta própria: padrões que detecta, correções que você faz, decisões que tomaram juntos. É salva em

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

Revise-a com frequência: o Claude Code pode ter salvo más práticas 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.

Ele executa ações, toma decisões, segue em frente.

Mas essa autonomia tem um lado que não é tão comentado: o Claude Code faz o que considera correto a cada passo.

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

Como você controla isso? Com hooks.

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

Você define o que acontece em cada momento.

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

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

Os quatro hooks principais são:

PreToolUse - Executa antes do Claude Code usar uma tool. É 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 tool. 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 Mac quando o Claude Code terminar uma tarefa longa.

Stop - Executa quando o Claude Code termina de responder. Exemplo: Fazer push automático 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 precisar lembrar.

Sem Hook: O Claude Code edita um arquivo, o código fica sem formatação e você percebe no próximo commit.

Com Hook: O Claude Code edita um arquivo, o PostToolUse dispara automaticamente, o Prettier formata o arquivo e o código fica 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

Existe 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 aparecer, 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:

1my-skill/
2├── SKILL.md          # Main instructions (required)
3├── template.md       # Template that Claude completes
4├── examples/
5│   └── sample.md    # Example of expected output
6└── scripts/
7    └── validate.sh  # Script that Claude can execute

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. Identifique todos os endpoints
92. Para cada um: método, caminho, parâmetros, resposta esperada
103. Inclua um exemplo de requisição e resposta
114. Finalize com uma tabela resumo

Depois de 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 repete com um processo claro por trás: documentação de API, changelogs, resumos de reunião, migrações de código.

SubAgents: Delegue Quando o Problema Crescer

Já vimos que o contexto tem capacidade limitada.

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

Imagine que você pede para ele revisar seu projeto inteiro 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 executa com seu próprio contexto.

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

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

1Main Agent
2    ↓
3"review the project for security issues"
4    ↓
5┌─────────────────────────────┐
6│    SubAgent: security-reviewer    │
7│                             │
8│  Reads project files        │
9│  Analyzes code              │
10│  Detects vulnerabilities    │
11│  Generates report           │
12└─────────────────────────────┘
13    ↓
14Returns summary to main agent
15    ↓
16Main agent continues with the loop

E não só isso.

SubAgents podem rodar 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.

1Main Agent
2    ↓
3Divides work into independent tasks
4    ↓
5┌──────────────┐  ┌──────────────┐  ┌──────────────┐
6│  SubAgent 1  │  │  SubAgent 2  │  │  SubAgent 3  │
7│              │  │              │  │              │
8│ Reviews auth │  │ Reviews DB   │  │ Reviews ext  │
9│              │  │              │  │ APIs         │
10└──────────────┘  └──────────────┘  └──────────────┘
11        ↓                 ↓                 ↓
12        Main agent receives the three summaries
13                          ↓
14                Continues with the loop

O Claude Code tem 3 SubAgents nativos que ele usa automaticamente:

→ Explore - Um agente rápido e somente leitura, especializado em buscar 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 para 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 em busca de:
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 tools a Read, Grep e Glob.

Este agente pode analisar, mas nunca modificar nada.

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

Depois de 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 rodam 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 ao Mundo Externo

As tools 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 consegue abrir um PR no GitHub, consultar um banco 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 nome e descrição.

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

1Claude Code
2    ↓
3Decides to use a tool from the GitHub MCP server
4    ↓
5┌─────────────────────────────┐
6│      GitHub MCP Server      │
7│                             │
8│   Opens the PR              │
9│   Assigns reviewers         │
10│   Returns confirmation      │
11└─────────────────────────────┘
12    ↓
13Claude Code receives the result and continues

Sem MCP: Você diz "terminei as alterações, abra o PR" e o Claude Code não consegue. Você precisa ir ao GitHub, preencher o formulário, designar 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, designa 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

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

Como Tudo se Encaixa

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 fazer merge de um PR

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

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

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

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

→ Se os testes passarem, ele usa o GitHub MCP 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 avisar o time

Você pede ao Claude Code: "Documente os novos endpoints e avise o time."

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

→ Ele usa Tools para ler o código e extrair os endpoints

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

→ Ele usa o Slack MCP para enviar o resumo ao canal do time

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

Tudo gira em torno do loop.

Memória para começar cada sessão informado. Tools 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 só o Claude Code: Cursor, Copilot e qualquer agente que você usar daqui em diante opera sobre os mesmos fundamentos.

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

A IA está avançando rápido.

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

Não use o Claude Code apenas para fazer prompts. Preste atenção no que acontece por baixo dos panos. É 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 GitHub MCP

→ Crie um SubAgent para tarefas que enchem o contexto

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

É isso, até amanhã.

Marcus