Claude Code na prática: CLAUDE.md, Skills, Subagents, Hooks, MCP e outros recursos

Todo dia, milhares de desenvolvedores abrem o Claude Code e repetem exatamente os mesmos erros.

O fluxo normalmente é assim:

1. Abre o Claude Code;
2. Cola um prompt enorme;
3. Pede uma funcionalidade;
4. Corrige tudo manualmente;
5. Repete o processo no dia seguinte.

No começo parece funcionar.

E, sinceramente, às vezes realmente funciona.

O problema aparece quando o projeto começa a crescer.

Depois de algumas semanas surgem sintomas clássicos:

• prompts gigantes;
• regras repetidas;
• instruções contraditórias;
• IA esquecendo padrões do projeto;
• código inconsistente;
• retrabalho em tarefas simples.

E é exatamente nesse ponto que muita gente conclui:

IA ainda não serve para projetos grandes.

Só que, muitas vezes, o problema não é a IA. O problema é tentar usar IA sem organizar o contexto.

E isso muda completamente a forma como o Claude trabalha.

Porque existe uma diferença enorme entre:

conversar com uma IA

e:

criar um ambiente organizado de desenvolvimento assistido por IA

A maioria das pessoas conhece apenas o CLAUDE.md, outras nem isso.

Mas o Claude Code possui um ecossistema muito maior.

Você pode separar regras, modularizar contexto, criar comandos reutilizáveis, organizar documentação, construir workflows, delegar tarefas para especialistas separados, automatizar verificações e conectar o Claude às ferramentas que você já usa no dia a dia.

Ao longo do tempo, isso transforma completamente a experiência de desenvolvimento.

O projeto deixa de depender de prompts improvisados e passa a ter:

• contexto organizado;
• padrões definidos;
• documentação estruturada;
• memória que cresce entre sessões;
• processos reutilizáveis;
• especialistas dedicados;
• automações que funcionam independente da IA.

Neste artigo, vamos entender de forma prática e sem complicação:

• o que é CLAUDE.md;
• o que é CLAUDE.local.md;
• como funciona o Auto Memory;
• como funcionam imports com @;
• para que serve docs/;
• como funcionam rules;
• o que são slash commands e skills;
• o que são subagents;
• o que são hooks;
• o que é MCP;
• quando usar cada recurso;
• o que deve ou não ir para o Git.

Mais importante do que decorar nomes de pastas ou comandos é entender a lógica por trás do Claude Code.

Porque no final, a grande mudança não está na ferramenta. Está na forma de organizar o conhecimento, o contexto e os processos do projeto.

E é exatamente isso que separa:

Vibe Coding

de:

desenvolvimento assistido por IA

O que é Claude Code?

Claude Code é uma ferramenta da Anthropic para desenvolvimento de software assistido por IA.

A diferença para um chat comum é simples, no Claude Code, a IA pode:

• trabalhar dentro da pasta do projeto;
• ler, criar e editar arquivos;
• entender a estrutura;
• seguir padrões;
• e executar fluxos de desenvolvimento com mais contexto.

Em vez de você explicar tudo novamente a cada conversa, você cria arquivos que ensinam ao Claude como aquele projeto funciona.

A lógica é:

Você organiza o contexto e o Claude trabalha seguindo esse contexto.

Isso evita repetir instruções como:

Use PHP 8.3.
Use MySQL.
Use Bootstrap.
Siga MVC.
Não misture SQL na view.

Você escreve isso uma vez no lugar certo, depois o Claude Code usa essas informações durante o desenvolvimento.

Como instalar o Claude Code

Antes de criar arquivos como CLAUDE.md, rules, skills ou subagents, você precisa instalar o Claude Code.

Hoje existem cinco formas de usar o Claude Code:

1. Pelo terminal do computador, também chamado de CLI
2. Pelo aplicativo desktop
3. Pelo navegador, sem instalar nada
4. Pela extensão do VS Code
5. Pela extensão do JetBrains

Se você ainda não tem familiaridade com terminal, o aplicativo desktop ou o navegador podem ser um caminho mais confortável para começar.

Instalando pelo aplicativo desktop

A Anthropic possui uma área oficial de downloads do Claude.

Você pode acessar:

👉 https://claude.ai/downloads

Nessa página, baixe a versão Desktop do Claude que já inclui o Claude Code.

A vantagem do aplicativo desktop é que ele oferece uma interface visual, mais parecida com os programas que você já usa no dia a dia. Além disso, é possível revisar alterações de código visualmente, rodar várias sessões ao mesmo tempo e configurar tarefas agendadas.

Instalando pela CLI

A CLI é a versão de linha de comando do Claude Code.

Ela é muito usada por desenvolvedores porque permite abrir o projeto no terminal e trabalhar diretamente nos arquivos do sistema.

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Se aparecer a mensagem The token '&&' is not a valid statement separator, você está no PowerShell, não no CMD. Use o comando do PowerShell acima.

Atenção: No Windows, às vezes é necessário reiniciar o computador após a instalação.

A instalação pela CLI se atualiza automaticamente em segundo plano, então você sempre fica na versão mais recente sem precisar fazer nada.

macOS, Linux ou WSL:

curl -fsSL https://claude.ai/install.sh | bash

Instalação pelo Homebrew (macOS):

brew install --cask claude-code

Diferente da instalação direta, o Homebrew não atualiza automaticamente. Para atualizar manualmente, execute brew upgrade claude-code.

Instalação pelo WinGet (Windows):

winget install Anthropic.ClaudeCode

Assim como o Homebrew, o WinGet não atualiza automaticamente. Execute winget upgrade Anthropic.ClaudeCode para atualizar.

Usando pelo navegador

Se você não quer instalar nada, pode usar o Claude Code diretamente pelo navegador em:

👉 claude.ai/code

Essa opção é útil para trabalhar em repositórios que você não tem salvos no computador, para iniciar tarefas longas e verificar o resultado depois, ou para rodar várias tarefas em paralelo.

Instalando no VS Code ou JetBrains

Se você usa o VS Code, procure por “Claude Code” na aba de extensões (Ctrl+Shift+X no Windows ou Cmd+Shift+X no Mac) e instale. A extensão oferece visualização de diferenças no código, menções com @, revisão de planos e histórico de conversas diretamente no editor.

Para usuários do IntelliJ, PyCharm, WebStorm e outros IDEs da JetBrains, instale o plugin disponível no JetBrains Marketplace.

Depois de instalar

Na primeira execução, o Claude Code vai pedir autenticação com sua conta. Segundo a documentação oficial, o Claude Code exige uma conta Pro, Max, Team, Enterprise ou Console. O plano gratuito do Claude.ai não inclui acesso ao Claude Code. O terminal e o VS Code também aceitam provedores terceiros.

Aplicativo desktop

1. Procure e abra o aplicativo Claude.
2. Clique na opção Code para ter acesso ao Claude Code.
3. Escolha a pasta do seu projeto.

Versão CLI

Abra o terminal dentro da pasta do seu projeto e execute:

claude

Esse comando inicia o Claude Code naquele projeto.

Para verificar se a instalação funcionou:

claude --version

Qual opção escolher?

Se você está começando e prefere uma interface visual, comece pelo aplicativo desktop ou pelo navegador.

Se você já usa terminal no desenvolvimento, instale a CLI.

Se você trabalha dentro do VS Code ou JetBrains, instale a extensão e ganhe a experiência integrada ao editor.

Na prática, os diferentes formatos levam ao mesmo objetivo: permitir que o Claude Code trabalhe com mais contexto dentro do seu projeto.

Preparando o ambiente para usar todo o potencial do Claude Code

Se você chegou até aqui, já consegue instalar e começar a usar o Claude Code. Mas existe um ponto importante que faz toda a diferença na prática.

Para aproveitar todos os recursos da ferramenta, especialmente aqueles ligados à execução de tarefas automáticas, é recomendado ter algumas ferramentas instaladas no seu computador.

As principais são:

• Git
• Node.js (com NPX)

Por que isso é importante

O Claude Code não funciona apenas como um chat com IA dentro do projeto.

Ele permite que o agente:

• execute comandos no terminal
• manipule arquivos
• rode scripts
• interaja com o sistema operacional
• automatize tarefas de desenvolvimento

E é aqui que o Git e o Node.js entram.

O papel do Git e do Node.js

Git

O Git é a ferramenta de versionamento de código mais usada no mundo. Para o Claude Code, ele vai além de versionar: é através do Git que o agente consegue usar o terminal de forma completa.

A documentação oficial menciona especificamente que no Windows, ter o Git instalado é altamente recomendado. Sem ele, o Claude Code substitui o terminal Bash pelo PowerShell, o que limita o que o agente consegue executar.

No macOS e no Linux o Git normalmente já vem instalado. No Windows, você pode baixar em git-scm.com.

Node.js e NPX

O Node.js é importante principalmente para quem quer usar servidores MCP, que são as conexões do Claude Code com ferramentas externas como Google Drive, Jira, Slack e outras.

Boa parte desses servidores é instalada e executada via NPX, que vem junto com o Node.js e permite rodar pacotes diretamente, sem precisar instalar tudo manualmente. Se precisar de um guia completo para instalar o Node.js, preparei um passo a passo detalhado, o guia usa o Antigravity como referência, mas o processo de instalação do Node.js é o mesmo independente da ferramenta:

👉 Node.js e NPX — Guia completo para iniciantes

O que acontece se você não instalar

Sem essas ferramentas, o Claude Code ainda funciona, mas com limitações.

Você pode:

• conversar com a IA;
• gerar e editar código;
• criar e organizar arquivos.

Mas pode ter dificuldades quando o agente precisar:

• executar comandos no terminal;
• conectar com serviços externos via MCP;
• rodar scripts e automatizar tarefas mais completas;
• realizar operações que dependem do Git.

Resumo

• Git e Node.js não são obrigatórios para instalar o Claude Code.
• mas são altamente recomendados para uso completo.
• o Git libera o terminal Bash, especialmente no Windows.
• o Node.js e NPX são necessários para a maioria dos servidores MCP.

Antes de começar: sobre comandos e interfaces

O Claude Code está disponível em quatro formatos: versão web, aplicativo desktop, CLI (pelo terminal do computador) e extensões para VS Code e JetBrains. A grande maioria dos recursos e comandos descritos neste artigo funciona em qualquer um desses ambientes.

Mas existem exceções. Alguns comandos que começam com / funcionam apenas no terminal. Outros recursos, como gerenciar plugins, podem aparecer diretamente como botões ou menus na interface do aplicativo desktop, sem precisar digitar nenhum comando.

O artigo não se preocupou em identificar cada caso porque as interfaces de IA estão mudando muito rápido, o que era exclusivo do terminal hoje pode estar no desktop amanhã, e vice-versa. Até você ler este artigo, algumas coisas já podem ter mudado.

Se você não encontrar algum recurso na interface que está usando, a forma mais rápida de resolver é perguntar diretamente no chat.

O próprio Claude te orienta para o caminho certo no ambiente em que você está.

Arquivos locais e globais do Claude Code

Antes de entender CLAUDE.md, rules, skills ou subagents, existe um conceito importante que costuma confundir iniciantes: local vs global.

Essa diferença é mais simples do que parece.

Pense assim

• Arquivos locais: Pertencem apenas ao projeto atual.
• Arquivos globais: Ficam disponíveis para qualquer projeto do seu computador.

O que significa ~?

Ao longo da documentação do Claude Code, você verá caminhos como:

~/.claude/

O símbolo:

~

representa a pasta do usuário no sistema operacional.

Por exemplo:

Windows

C:\Users\SeuUsuario\

Linux

/home/seu-usuario/

macOS

/Users/seu-usuario/

Então:

~/.claude/

significa: a pasta global do Claude Code no seu computador.

Estrutura local do projeto

Quando algo pertence apenas ao projeto atual, normalmente fica dentro da pasta:

.claude/

Exemplo:

meu-sistema/
├── .claude/
│   ├── rules/
│   ├── skills/
│   ├── agents/
│   └── commands/
├── CLAUDE.md

Tudo isso pertence apenas àquele sistema.

Estrutura global do Claude Code

O Claude Code também possui uma estrutura global no computador do usuário.

Exemplo:

~/.claude/

Dentro dela podem existir:

~/.claude/rules/
~/.claude/skills/
~/.claude/agents/
~/.claude/commands/

Esses recursos ficam disponíveis em qualquer projeto da máquina.

Quando usar arquivos globais?

Arquivos globais funcionam muito bem para coisas que você reutiliza constantemente.

Por exemplo:

• regras pessoais;
• comandos favoritos;
• skills reutilizáveis;
• especialistas genéricos.

Exemplo:

~/.claude/skills/revisar-codigo/

Essa skill pode funcionar em vários projetos diferentes.

Quando usar arquivos locais?

Arquivos locais fazem sentido quando o conteúdo depende daquele projeto específico.

Por exemplo:

• regras do ERP da empresa;
• arquitetura do projeto;
• padrões internos;
• regras do módulo financeiro.

Exemplo:

.claude/rules/financeiro.md

Essa rule provavelmente não faz sentido fora daquele sistema.

Regra simples para não se perder

Uma pergunta ajuda bastante:

Isso pertence ao projeto ou pertence à minha máquina?

• Se pertence ao projeto: use estrutura local do projeto.
• Se pertence apenas ao seu computador (pode ser usado em vários projetos): use estrutura global.

Essa separação parece pequena no começo, mas em projetos grandes ela faz muita diferença na organização do contexto e da equipe.

Você não precisa escrever tudo sozinho

Depois de conhecer recursos como:

CLAUDE.md
rules
skills
subagents
commands

é normal pensar:

Isso parece complicado demais para criar manualmente.

Mas existe um detalhe importante:

• Você pode usar a própria IA para criar praticamente tudo isso.
• Na prática, é exatamente isso que quase todo mundo faz.

Pense assim

Você não precisa sentar e escrever um CLAUDE.md perfeito do zero.

Também não precisa decorar:

• estrutura de skills;
• organização de rules;
• formato de subagents;
• padrões de documentação.

A IA pode ajudar em praticamente todo esse processo e isso reduz muito a barreira de entrada.

Exemplo simples

Você pode pedir:

Crie rules para um projeto PHP focadas em segurança e boas práticas.

E a IA pode gerar algo parecido com:

- usar prepared statements
- validar uploads
- nunca misturar SQL na view
- seguir PSR-12

O mais importante

Você não precisa acertar tudo na primeira versão, esse talvez seja o maior erro de iniciantes.

Muita gente imagina que precisa construir uma estrutura perfeita antes de começar.

Na prática, quase ninguém trabalha assim.

O normal é:

1. criar algo simples;
2. usar no projeto;
3. perceber problemas;
4. ajustar aos poucos.

Com o tempo, a estrutura evolui naturalmente.

A IA também ajuda a melhorar a estrutura

Existe outro detalhe interessante, além de criar os arquivos, a própria IA pode ajudar a melhorar sua organização.

Por exemplo:

Analise meu CLAUDE.md e sugira melhorias.

ou:

Transforme este prompt repetitivo em uma skill reutilizável.

E conforme o projeto cresce, você evolui a organização junto com ele.

O que é o CLAUDE.md?

O CLAUDE.md é o principal arquivo de contexto do projeto.

Pense nele como o “manual principal” que ensina ao Claude como aquele sistema funciona.

É normalmente o primeiro lugar onde você organiza:

• objetivo do projeto;
• tecnologias utilizadas;
• arquitetura;
• padrões principais;
• estrutura do sistema;
• regras importantes.

Na prática, ele funciona como o ponto de partida do projeto dentro do Claude Code.

O problema que o CLAUDE.md resolve

Quando as pessoas usam IA sem organização, normalmente acontece algo assim:

Todo dia elas repetem:

Use PHP 8.3.
Use MySQL.
Siga MVC.
Use Bootstrap.
Nunca misture SQL na view.

Com o tempo:

• os prompts ficam enormes;
• regras começam a se contradizer;
• partes importantes são esquecidas;
• o projeto perde consistência.

O CLAUDE.md existe justamente para evitar isso.

Em vez de explicar tudo em cada conversa, você ensina uma vez no arquivo principal do projeto.

Depois o Claude usa essas informações como referência durante o desenvolvimento.

Pense no CLAUDE.md como a “porta de entrada” do projeto

Uma forma simples de entender é imaginar alguém entrando na equipe pela primeira vez.

Essa pessoa precisaria de um documento inicial explicando:

• o que é o sistema;
• como ele funciona;
• quais tecnologias usa;
• quais padrões seguir;
• quais cuidados são importantes.

O CLAUDE.md faz exatamente esse papel.

Ele apresenta o projeto para o Claude.

Onde o CLAUDE.md fica?

O arquivo normalmente fica na raiz do projeto, que é a pasta principal do sistema.

Exemplo:

financeiro-app/
├── CLAUDE.md
├── app/
├── public/
├── database/
├── docs/
├── .claude/

Ele também pode ficar dentro da pasta .claude/, se você preferir manter os arquivos de configuração separados do restante:

financeiro-app/
├── .claude/
│   └── CLAUDE.md
├── app/
├── public/

As duas localizações funcionam da mesma forma. Escolha a que fizer mais sentido para a organização do seu projeto.

Os quatro níveis do CLAUDE.md

O Claude Code carrega instruções de quatro lugares diferentes, do mais geral para o mais específico:

1. Nível da organização → configurado pelo time de TI ou DevOps diretamente no sistema operacional dos computadores da empresa. Se aplica a todos os colaboradores e não pode ser sobrescrito por ninguém. Útil para padrões e políticas que valem para toda a equipe, como regras de segurança obrigatórias ou convenções de código da empresa.

O arquivo fica num caminho fixo que depende do sistema operacional:

• macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
• Linux e WSL: /etc/claude-code/CLAUDE.md
• Windows: C:\Program Files\ClaudeCode\CLAUDE.md

Na prática, esse nível só é relevante para empresas que querem padronizar o uso do Claude Code em toda a equipe via configuração centralizada. Para uso individual ou em times pequenos, os outros três níveis já dão conta.

2. Nível do usuário → fica em ~/.claude/CLAUDE.md, no computador do desenvolvedor. Aplica preferências pessoais em todos os projetos da máquina.

3. Nível do projeto → é o CLAUDE.md na raiz do projeto, compartilhado com toda a equipe via Git. O mais comum e o que este artigo aborda principalmente.

4. Nível local → é o CLAUDE.local.md, que guarda configurações pessoais daquele projeto específico, sem compartilhar com ninguém.

Quando existem instruções em mais de um nível, o Claude carrega todos e os combina. Instruções do nível do projeto aparecem no contexto depois das do nível do usuário, então regras mais próximas do projeto têm mais peso.

Exemplo simples de CLAUDE.md

# Sistema Financeiro

Este projeto é um sistema de contas a pagar e contas a receber.

Tecnologias utilizadas:

- PHP 8.3
- MySQL 8
- Bootstrap 5

Arquitetura:

- MVC
- Repository Pattern
- Service Layer

Regras importantes:

- Nunca misturar SQL nas views.
- Sempre usar prepared statements.
- Controllers devem ser leves.
- Validar uploads de arquivos.

Imports:

@docs/regras-negocio.md
@docs/interface.md

Perceba uma coisa importante:

O CLAUDE.md não precisa carregar tudo sozinho.

Ele também pode organizar e importar outros arquivos. Entenderemos como importar arquivos no CLAUDE.md ainda neste artigo.

Gerando o CLAUDE.md automaticamente

Se você já tem um projeto com código escrito, não precisa criar o CLAUDE.md do zero.

Dentro do Claude Code, execute:

/init

O Claude analisa o codebase, identifica os comandos de build, convenções e padrões do projeto e cria um CLAUDE.md inicial automaticamente. Se o arquivo já existir, o /init sugere melhorias em vez de sobrescrever.

É um bom ponto de partida para refinar depois com informações que o Claude não conseguiria descobrir sozinho, como regras de negócio e decisões de arquitetura.

Quanto deve ter no CLAUDE.md?

A documentação oficial recomenda manter cada CLAUDE.md abaixo de 200 linhas.

O motivo é simples: o arquivo é carregado inteiro no início de cada sessão, ocupando espaço no contexto da conversa. Arquivos muito longos consomem mais espaço e fazem com que o Claude siga as instruções com menos precisão.

Se o seu CLAUDE.md estiver crescendo demais, é sinal de que parte do conteúdo deveria ir para outros lugares, como rules, skills ou a pasta docs/.

O maior erro com CLAUDE.md

Esse talvez seja o erro mais comum de todos.

Muita gente transforma o CLAUDE.md em um “super prompt gigante“.

Misturando:

• arquitetura;
• segurança;
• deploy;
• frontend;
• backend;
• testes;
• prompts;
• exemplos;
• integrações;
• documentação;
• checklists.

No começo parece funcionar, mas com o tempo vira bagunça.

• Arquivo enorme.
• Difícil de manter.
• Difícil de atualizar.
• Cheio de informações repetidas.

É exatamente por isso que existem:

• imports;
• rules;
• skills;
• subagents;
• docs/

Projetos organizados usam o CLAUDE.md como:

visão geral
+
direcionamento principal
+
organização do restante do contexto

E não como um arquivo infinito.

O que normalmente fica no CLAUDE.md?

O CLAUDE.md funciona melhor quando guarda informações mais gerais do projeto.

Por exemplo:

• objetivo do sistema;
• stack principal;
• arquitetura;
• padrões gerais;
• estrutura das pastas;
• convenções importantes;
• imports principais.

Ele é excelente para explicar:

Como este projeto funciona no geral?

O que NÃO deveria ficar no CLAUDE.md?

Algumas coisas ficam melhores em outros lugares.

Regras permanentes muito específicas

Exemplo:

• regras de segurança;
• padrões de banco;
• regras de testes.

Isso normalmente vai melhor em:

.claude/rules/

Processos operacionais grandes

Exemplo:

• revisar release;
• auditar segurança;
• gerar changelog.

Isso combina melhor com:

.claude/skills/

Especialistas técnicos

Exemplo:

• especialista em segurança;
• especialista em MySQL;
• especialista em performance.

Isso pertence aos:

.claude/agents/

Documentação detalhada

Exemplo:

• escopo;
• regras de negócio;
• documentação de API;
• fluxos do sistema.

Isso normalmente fica em:

docs/

Quando usar imports no CLAUDE.md?

Quando o projeto começa a crescer.

Imports ajudam a dividir o contexto em partes menores e organizadas.

Exemplo:

@docs/arquitetura.md
@docs/regras-negocio.md

Isso evita transformar o CLAUDE.md em um bloco gigantesco difícil de manter.

CLAUDE.md local e global

Na maioria dos casos, o CLAUDE.md pertence ao projeto atual.

Ele normalmente vai para o Git junto com o restante do sistema.

Porque faz parte da documentação e da organização do projeto.

Mas existe também o:

CLAUDE.local.md

Esse arquivo é diferente, ele guarda informações locais da máquina do desenvolvedor.

Por exemplo:

• caminhos locais;
• senhas;
• URLs de teste;
• banco local;
• configurações pessoais.

Exemplo do CLAUDE.local.md:

# Minhas configurações locais

Caminho do projeto:
C:\xampp\htdocs\financeiro-app

Banco local:
Host: localhost
Database: financeiro_app
User: root
Password: vazio no XAMPP local

URL local:
http://localhost/financeiro-app/public/

Esse arquivo não deve ir para o Git, pois pode conter:

• caminhos locais;
• senhas;
• usuário do banco;
• configurações pessoais;
• informações que só fazem sentido na sua máquina.

Benefícios do CLAUDE.md

O maior benefício não é apenas “dar contexto“. É criar consistência.

• Sem um CLAUDE.md, cada conversa começa praticamente do zero.
• Com ele, o projeto passa a ter uma identidade técnica organizada.

O Claude começa a entender:

• como o sistema funciona;
• quais padrões seguir;
• quais decisões já foram tomadas;
• como a equipe trabalha.

E isso reduz muito:

• retrabalho;
• inconsistência;
• prompts gigantes;
• instruções repetidas;
• confusão no projeto.

No começo parece apenas um arquivo, depois você percebe que ele virou a base de organização de todo o desenvolvimento assistido por IA.

Auto Memory: o Claude que aprende sozinho

Existe um recurso do Claude Code que muita gente não conhece e que muda bastante a experiência de uso: a memória automática, chamada de Auto Memory.

A ideia é simples.

Normalmente, cada sessão do Claude Code começa do zero. Ele não lembra do que você discutiu ontem, dos comandos que você usa com mais frequência ou dos padrões que já explicou antes.

O CLAUDE.md resolve parte disso, porque você mesmo escreve as instruções que devem persistir.

Mas o Auto Memory vai um passo além:

O próprio Claude escreve anotações para si mesmo enquanto trabalha com você.

Sem você precisar fazer nada.

O que o Claude anota?

Ele guarda coisas práticas que seriam úteis em conversas futuras. Por exemplo:

• comandos para rodar o projeto ou os testes;
• caminhos importantes do codebase;
• padrões de código que você prefere;
• decisões de arquitetura que apareceram na conversa;
• insights de debugging que foram úteis;
• convenções que você corrigiu durante o trabalho.

O Claude não anota tudo. Ele decide o que vale a pena guardar com base no que provavelmente seria útil de novo no futuro.

Como a memória é carregada?

No início de cada sessão, o Claude carrega automaticamente as anotações que foram acumuladas. Para não sobrecarregar o contexto, ele lê até 200 linhas ou 25KB de memória por sessão. Se as anotações crescerem além disso, ele prioriza as mais recentes e relevantes.

Essa memória fica no seu computador e não é compartilhada com ninguém. Todos os worktrees do mesmo repositório — que são cópias separadas do mesmo projeto usadas para trabalhar em paralelo — compartilham a mesma memória.

Como ver e editar a memória

Você pode ver tudo que o Claude guardou rodando o comando:

/memory

Esse comando lista os arquivos de instruções carregados na sessão atual, incluindo os arquivos de Auto Memory. Como são arquivos de texto simples, você pode abri-los diretamente no seu editor para ler, ajustar ou apagar o que não faz mais sentido.

Se quiser pedir ao Claude para guardar algo específico, basta falar:

Lembre que neste projeto usamos sempre pnpm, nunca npm.

Ele salva automaticamente na memória.

Se quiser que algo vá para o CLAUDE.md em vez da memória automática, é só pedir:

Adicione isso ao CLAUDE.md.

Ativando e desativando

O Auto Memory vem ativado por padrão.

Para desativar, use o comando /config dentro do Claude Code e procure pela opção de memória automática. Você também pode pedir diretamente ao Claude:

Desative o Auto Memory para este projeto.

Qual a diferença entre CLAUDE.md e Auto Memory?

São dois sistemas que se complementam:

	CLAUDE.md	Auto Memory
Quem escreve	Você	O próprio Claude
O que contém	Instruções e regras	Aprendizados e padrões descobertos
Uso ideal	Padrões do projeto, arquitetura, convenções da equipe	Comandos de build, insights de debugging, preferências que o Claude observou

Use o CLAUDE.md para o que você quer garantir que o Claude sempre saiba. Deixe o Auto Memory cuidar das coisas que ele vai aprendendo naturalmente ao longo do tempo.

Por que isso importa?

Sem Auto Memory, toda vez que o Claude descobre algo útil sobre o seu projeto, esse aprendizado some no final da sessão.

Com Auto Memory ativo, ele vai ficando mais familiarizado com o projeto com o passar do tempo. Cada sessão deixa rastros que tornam as próximas um pouco mais produtivas.

É a diferença entre trabalhar com alguém que esquece tudo de um dia para o outro e trabalhar com alguém que vai acumulando experiência no projeto.

O que são imports com @?

Imports servem para dividir o contexto do projeto em vários arquivos menores e organizados.

Na prática, o símbolo:

@

diz ao Claude Code:

Leia este outro arquivo também.

Exemplo:

@docs/arquitetura.md
@docs/regras-negocio.md

Quando o Claude encontra essas linhas, ele carrega esses arquivos como parte do contexto do projeto.

O problema que os imports resolvem

Quando as pessoas começam a usar IA para programar, normalmente colocam tudo dentro do CLAUDE.md.

Exemplo:

• arquitetura;
• regras de segurança;
• estrutura do banco;
• interface;
• prompts;
• deploy;
• testes;
• integrações;
• regras de negócio.

No início parece funcionar, depois o arquivo cresce sem controle.

• Vira um bloco gigantesco difícil de manter.
• Com regras duplicadas.
• Informações contraditórias.
• Trechos antigos misturados com novos.

Os imports existem justamente para evitar isso.

Pense como um livro

Uma forma simples de entender imports é imaginar um livro.

Você poderia colocar tudo em um único capítulo enorme, mas isso seria horrível de ler. Então o livro é dividido em capítulos.

Imports fazem exatamente isso com o contexto do projeto.

Em vez de um arquivo gigante, você separa por assunto.

Por exemplo:

• arquitetura;
• segurança;
• regras de negócio;
• testes;
• deploy;
• interface.

Isso deixa tudo mais organizado e muito mais fácil de manter.

Exemplo simples de import

Imagine este arquivo:

CLAUDE.md

Conteúdo:

# Sistema Financeiro

@docs/arquitetura.md
@docs/regras-negocio.md
@docs/interface.md

Agora o CLAUDE.md ficou limpo e organizado.

Cada assunto vive no seu próprio arquivo.

O que acontece quando usamos @?

Um detalhe importante: o import não “busca o arquivo quando precisa“.

Quando o Claude Code inicia a sessão, ele já carrega todos os arquivos marcados com @ de uma vez, junto com o próprio CLAUDE.md. Pense como se o conteúdo de todos eles fosse reunido no começo da conversa.

Isso significa que imports ajudam na organização, mas não reduzem o quanto de informação é carregada. Se você importar dez arquivos enormes, tudo isso entra no contexto de uma vez.

Importante: imports são para organizar o conteúdo em arquivos menores e mais fáceis de manter. Se o objetivo é carregar algo só quando necessário, existem outros recursos para isso, como as skills.

Como os caminhos funcionam

Quando você escreve um import como:

@docs/arquitetura.md

O caminho é calculado a partir do arquivo que contém o import, não da pasta onde o Claude Code foi aberto.

Por exemplo, se o import está em .claude/CLAUDE.md, o arquivo docs/arquitetura.md será procurado a partir da pasta .claude/, e não da raiz do projeto.

Na maioria dos casos isso não causa problemas, mas é um detalhe importante quando os arquivos ficam em pastas diferentes.

Imports também podem referenciar arquivos que importam outros arquivos. Essa cadeia pode ter no máximo 5 níveis de profundidade. Na prática, raramente alguém chega perto desse limite.

Arquivos fora do projeto

Se você importar um arquivo que fica fora da pasta do projeto, por exemplo um arquivo na pasta pessoal do usuário:

@~/.claude/meus-padroes.md

Na primeira vez que o Claude Code encontrar esse tipo de import externo, ele exibe uma tela pedindo sua aprovação antes de carregar o arquivo. Se você recusar, o import fica desativado e a pergunta não aparece novamente.

Onde esses arquivos normalmente ficam?

Os imports podem apontar para qualquer arquivo relevante do projeto.

Os lugares mais comuns são:

Pasta de documentação

docs/

Outros arquivos Markdown

.md

Exemplo completo:

meu-sistema/
├── CLAUDE.md
├── docs/
│   ├── arquitetura.md
│   ├── regras-negocio.md
│   └── interface.md
├── .claude/
│   └── rules/
│       ├── security.md
│       └── database.md

Por que isso ajuda tanto?

Porque projetos crescem e projetos grandes sofrem quando o contexto vira bagunça.

Sem imports, o CLAUDE.md tende a ficar muito grande.

Com imports você separa responsabilidades. Cada arquivo cuida de um assunto específico.

Isso deixa o projeto:

• mais organizado;
• mais fácil de atualizar;
• mais fácil de revisar;
• mais fácil de compartilhar;
• mais fácil de manter.

Quando usar imports?

Imports são excelentes quando o projeto começa a crescer.

Eles funcionam muito bem para separar:

• arquitetura;
• regras de negócio;
• segurança;
• interface;
• banco de dados;
• testes;
• deploy;
• integrações.

Uma boa regra prática é:

Se um assunto ficou grande demais, talvez ele devesse virar um arquivo separado.

Quando NÃO usar imports?

Projetos pequenos

Não existe motivo para criar dezenas de arquivos minúsculos sem necessidade.

Se o projeto for muito simples, com poucas regras e poucos arquivos, um CLAUDE.md pequeno pode ser suficiente.

Fragmentar demais

Outro erro comum é exagerar na fragmentação. Criar muitos arquivos com poucas linhas em cada um.

• Isso dificulta a manutenção.
• O objetivo dos imports é organizar.
• Não transformar o projeto em um quebra-cabeça impossível de navegar.

Confundir organização com economia de contexto

Como explicado acima, todos os arquivos importados são carregados de uma vez no início da sessão. Dividir o CLAUDE.md em vários arquivos menores ajuda na organização, mas não faz a sessão ficar mais leve automaticamente.

Imports ajudam a evitar repetição

Sem imports, muitas pessoas acabam copiando as mesmas informações em vários lugares.

Com imports, você centraliza cada assunto em um único arquivo.

Exemplo:

security.md

Agora todas as regras de segurança vivem ali. Se precisar atualizar algo, você muda em apenas um lugar.

Benefícios dos imports

O maior benefício é organização. Eles ajudam a transformar o projeto em algo modular.

Em vez de um contexto gigante e desorganizado, você passa a ter:

• documentação separada;
• regras separadas;
• arquitetura separada;
• fluxos separados.

E isso faz uma diferença enorme quando o projeto cresce. Principalmente em equipes.

Porque o conhecimento deixa de ficar espalhado em prompts aleatórios. Ele passa a existir de forma estruturada dentro do projeto.

O que é a pasta docs/?

A pasta docs/ é usada para guardar a documentação do projeto.

Pense nela como a “biblioteca” do sistema.

É o lugar onde você explica como o projeto funciona.

Por exemplo:

• regras de negócio;
• fluxo do sistema;
• estrutura dos módulos;
• funcionamento das telas;
• integrações;
• APIs;
• documentação técnica;
• decisões importantes do projeto.

Muita gente acha que documentação serve apenas para humanos, no Claude Code, ela também ajuda a IA a entender o sistema.

Observação importante

A pasta docs/ serve como a “biblioteca central” do seu sistema. É o lugar perfeito para você criar arquivos de texto simples (no formato Markdown, com a extensão .md) para explicar as regras de negócio do projeto, como funcionam as telas, as integrações de APIs ou os fluxos que o usuário faz no seu site.

Mas aqui vai uma “observação técnica importante” que pouca gente percebe: a pasta docs/ não é um recurso de fábrica ou uma ferramenta nativa da IA. Diferente das pastas de skills ou de subagentes (que precisam ter nomes exatos e específicos para a IA encontrar), a pasta docs/ é apenas uma convenção de organização. Os desenvolvedores, costumam usar esse padrão no mercado para deixar manuais e papéis arrumados dentro de qualquer projeto.

A IA não tem nenhuma linha de código secreta que diz “procure uma pasta chamada docs”. O que ela faz, na verdade, é ter a capacidade de ler e indexar os arquivos de texto do seu projeto para usá-los como base de conhecimento (contexto).

Ao criar uma pasta docs/ e colocar seus manuais ali dentro, você não está ativando um botão oculto da IA; você está apenas aplicando uma boa prática de mercado que facilita a vida da IA na hora de encontrar e ler os seus arquivos de documentação.

O problema que a pasta docs/ resolve

Quando não existe documentação organizada, começam a surgir problemas:

• ninguém lembra como o sistema funciona;
• regras de negócio ficam espalhadas;
• cada pessoa explica de um jeito;
• decisões importantes se perdem;
• a IA começa a responder de forma inconsistente.

E isso piora muito conforme o projeto cresce, no começo, todo mundo “ainda lembra”.

Depois de alguns meses:

• o sistema muda;
• novos módulos aparecem;
• regras ficam mais complexas;
• novas pessoas entram na equipe.

Sem documentação, o conhecimento começa a ficar preso apenas na cabeça das pessoas.

A pasta docs/ ajuda justamente a organizar esse conhecimento.

Pense na pasta docs/ como o manual do sistema

Imagine um sistema financeiro.

Ele pode possuir regras como:

• quando uma cobrança vence;
• como funciona multa;
• como calcular juros;
• quais permissões cada usuário possui;
• como funciona o fluxo de aprovação.

Essas informações são importantes, mas elas não são “rules” do Claude, são regras do negócio.

Onde a pasta docs/ fica?

Ela normalmente fica na raiz do projeto.

Exemplo:

meu-sistema/
├── CLAUDE.md
├── docs/
├── app/
├── public/
├── database/
├── .claude/

Dentro dela, você pode organizar os assuntos em vários arquivos.

Exemplo:

docs/
├── arquitetura.md
├── regras-negocio.md
├── fluxo-financeiro.md
├── api.md
├── integracoes.md
└── deploy.md

Exemplo simples de documentação

Arquivo:

docs/regras-negocio.md

Conteúdo:

# Regras de negócio

- Toda cobrança possui data de vencimento.
- Cobranças vencidas geram multa após 5 dias.
- Apenas administradores podem cancelar pagamentos.
- Relatórios financeiros devem considerar fuso horário UTC-3.

Agora o projeto possui um lugar centralizado explicando essas regras. Isso ajuda tanto a equipe quanto o Claude.

docs/ NÃO é a mesma coisa que rules

Essa diferença é extremamente importante. Muita gente mistura os dois.

docs/

Explica como o sistema funciona.

Exemplo:

• fluxo financeiro;
• regras de comissão;
• funcionamento do ERP;
• integração com API.

rules

Explica como o Claude deve trabalhar.

Exemplo:

• usar prepared statements;
• nunca misturar SQL na view;
• seguir MVC;
• validar uploads.

Uma forma simples de pensar é:

• docs/ – conhecimento sobre o sistema;
• rules – padrões técnicos do projeto.

docs/ NÃO é a mesma coisa que skills

Outro erro comum.

• docs/ – explica informações.
• skills – explicam procedimentos.

Exemplo:

• docs/ – como funciona o módulo financeiro.
• skill – como revisar uma release financeira.

A documentação descreve o sistema. A skill descreve um fluxo de trabalho.

O Claude também usa a documentação

Esse ponto é importante. No Claude Code, a documentação não serve apenas para consulta humana.

Ela também ajuda a IA a entender o projeto.

Por exemplo:

@docs/regras-negocio.md

Quando esse arquivo é importado no contexto, o Claude passa a considerar essas informações durante o desenvolvimento.

Quanto melhor a documentação, mais contexto útil o Claude possui.

Quando usar a pasta docs/?

A pasta docs/ funciona muito bem para:

• regras de negócio;
• documentação de APIs;
• fluxos do sistema;
• integrações;
• arquitetura;
• decisões importantes;
• padrões funcionais;
• documentação técnica.

Uma boa pergunta é:

Isso explica como o sistema funciona?

Se a resposta for sim, provavelmente pertence ao docs/.

Quando NÃO usar docs/?

Não use docs/ para tudo.

Regras técnicas permanentes

Exemplo:

Nunca misturar SQL nas views.

Isso pertence a:

.claude/rules/

Procedimentos operacionais

Exemplo:

Revisar release antes da publicação.

Isso combina melhor com:

skills

Comandos rápidos

Exemplo:

Gerar mensagem de commit.

Isso faz mais sentido como:

slash command

Benefícios da pasta docs/

O maior benefício é preservar conhecimento. Sem documentação, o projeto depende da memória das pessoas.

Com documentação organizada:

• a equipe entende melhor o sistema;
• novos desenvolvedores aprendem mais rápido;
• a IA recebe contexto melhor;
• regras importantes não se perdem;
• o projeto fica mais sustentável.

No começo, documentação parece “extra”, depois de alguns meses, você percebe que ela virou uma das partes mais importantes do projeto.

O que é .claude/rules/?

A pasta .claude/rules/ serve para guardar regras permanentes do projeto.

Essas regras funcionam como instruções que o Claude deve seguir sempre durante o desenvolvimento.

Pense nelas como os padrões oficiais do sistema.

Por exemplo:

• nunca misturar SQL na view;
• sempre usar prepared statements;
• validar uploads de arquivos;
• controllers devem ser leves;
• seguir padrão MVC.

Essas instruções não deveriam ficar sendo repetidas em prompts o tempo inteiro.

E esse é justamente um dos maiores erros de quem começa a usar IA para programar.

A pessoa escreve algo assim todos os dias:

Use PHP 8.3.
Use MVC.
Nunca misture SQL na view.
Use prepared statements.
Valide uploads.
Siga PSR-12.

No começo parece normal. Depois vira caos.

• Cada prompt fica gigante.
• As instruções começam a mudar sem querer.
• Uma conversa fala uma coisa.
• Outra fala diferente.
• O projeto perde consistência.

As rules existem para resolver exatamente isso.

Pense nas rules como as “leis do projeto”

Uma forma simples de entender é imaginar uma empresa.

Toda empresa possui regras internas:

• padrão visual;
• regras de segurança;
• processos internos;
• forma correta de trabalhar.

As rules fazem o mesmo papel dentro do projeto.

Elas dizem ao Claude:

Independentemente da tarefa, estas regras devem ser respeitadas.

Onde as rules ficam?

As rules normalmente ficam dentro da pasta:

.claude/rules/

Exemplo:

.claude/rules/backend.md
.claude/rules/database.md
.claude/rules/security.md
.claude/rules/testing.md

Cada arquivo pode guardar um conjunto específico de regras.

Isso ajuda a organizar melhor o contexto.

Em vez de colocar tudo em um único CLAUDE.md gigante, você separa por assunto.

O Claude carrega automaticamente as rules. Você não precisa importar no CLAUDE.md.

Por que separar em vários arquivos?

Porque projetos crescem. No início, o sistema parece pequeno.

Depois aparecem:

• frontend;
• backend;
• APIs;
• autenticação;
• banco de dados;
• testes;
• deploy;
• integrações.

Se tudo ficar dentro de um único arquivo enorme, o contexto vira bagunça.

Separar as rules ajuda a manter organização e clareza.

Por exemplo:

Regras de banco

.claude/rules/database.md

Regras de segurança

.claude/rules/security.md

Regras de testes

.claude/rules/testing.md

Isso deixa o projeto muito mais fácil de manter.

Exemplo simples de rule

Arquivo:

.claude/rules/database.md

Conteúdo:

# Regras de banco de dados

- Nunca usar SQL diretamente nas views.
- Sempre utilizar prepared statements.
- Nunca concatenar dados do usuário em queries.
- Toda migration deve possuir rollback.
- Evitar SELECT * em queries do sistema.
- Criar índices para colunas usadas em filtros frequentes.

Agora essas regras ficam centralizadas em um único lugar.

Você não precisa repetir isso em toda conversa.

Rules condicionais por tipo de arquivo

Existe um recurso poderoso que muita gente não conhece: rules que só entram em ação quando o Claude está trabalhando com determinados arquivos.

Funciona assim: você adiciona um bloco de configuração no topo do arquivo de rule indicando para quais arquivos ela deve ser aplicada.

Exemplo:

---
paths:
  - "src/api/**/*.ts"
---

# Regras para endpoints de API

- Todo endpoint deve incluir validação de entrada.
- Use o formato padrão de resposta de erro.
- Inclua comentários de documentação OpenAPI.

Nesse caso, essas regras só entram no contexto quando o Claude estiver trabalhando com arquivos TypeScript dentro da pasta src/api/. Para o restante do projeto, essas regras simplesmente não existem.

Isso é muito útil em projetos maiores, onde diferentes partes do sistema seguem padrões diferentes. Em vez de carregar todas as regras o tempo inteiro, você carrega apenas o que é relevante para o momento.

Alguns exemplos de padrões que você pode usar:

Padrão	O que cobre
**/*.ts	Todos os arquivos TypeScript
src/**/*	Tudo dentro da pasta src/
*.md	Arquivos Markdown na raiz
src/components/*.tsx	Componentes React em uma pasta específica

Rules sem essa configuração de caminho continuam funcionando como sempre: carregam no início da sessão e se aplicam ao projeto inteiro.

Compartilhando rules entre projetos com symlinks

Se você tem regras que fazem sentido em mais de um projeto, não precisa copiar os arquivos. A pasta .claude/rules/ aceita atalhos do sistema operacional (chamados de symlinks) que apontam para arquivos em outro lugar.

Exemplo:

ln -s ~/padroes-empresa/security.md .claude/rules/security.md

Assim, vários projetos podem apontar para o mesmo arquivo. Quando você atualiza esse arquivo, a mudança vale para todos os projetos de uma vez.

O comando que cria esse atalho é diferente dependendo do seu sistema operacional:

macOS e Linux:

ln -s ~/padroes-empresa/security.md .claude/rules/security.md

Windows PowerShell (executar como Administrador):

New-Item -ItemType SymbolicLink -Path ".claude\rules\security.md" -Target "$HOME\padroes-empresa\security.md"

Windows CMD (executar como Administrador):

mklink .claude\rules\security.md %USERPROFILE%\padroes-empresa\security.md

No Windows, criar atalhos desse tipo exige que o terminal seja aberto como Administrador, ou que o Modo Desenvolvedor esteja ativado nas configurações do sistema.

O que esses comandos fazem é simples: criam um atalho dentro da pasta .claude/rules/ que aponta para um arquivo que existe em outro lugar no seu computador. O Claude enxerga esse atalho como se fosse o arquivo de verdade.

Assim, vários projetos podem apontar para o mesmo arquivo. Quando você atualiza esse arquivo, a mudança vale para todos os projetos de uma vez.

Rules locais e globais

Assim como outros recursos do Claude Code, as rules podem ser locais ou globais.

Rules locais

Ficam dentro do projeto atual.

Exemplo:

meu-sistema/
├── .claude/
│   └── rules/
│       └── security.md

Use rules locais quando as regras fazem sentido apenas para aquele sistema.

Exemplo:

• usar Repository Pattern;
• seguir padrão financeiro da empresa;
• usar nomenclatura específica;
• seguir arquitetura definida pelo time.

Essas regras normalmente vão para o Git junto com o projeto.

Porque toda a equipe deve seguir os mesmos padrões.

Rules globais

Rules globais ficam disponíveis em vários projetos.

Exemplo:

~/.claude/rules/

Rules globais funcionam bem para preferências pessoais ou padrões que você usa em praticamente qualquer projeto.

Exemplo:

• evitar código duplicado;
• escrever código legível;
• priorizar segurança;
• documentar funções complexas.

Um detalhe importante: as rules globais carregam antes das rules do projeto. Isso significa que, se houver alguma contradição entre uma rule global e uma rule do projeto, a rule do projeto prevalece.

Quando usar rules?

Rules são perfeitas para comportamentos que devem acontecer sempre.

Elas funcionam muito bem para:

• padrões de arquitetura;
• segurança;
• convenções de código;
• organização de arquivos;
• padrões de banco;
• regras de testes;
• boas práticas;
• estrutura do projeto.

Uma boa pergunta para fazer é:

Isso deve valer sempre, independentemente da tarefa?

Se a resposta for sim, provavelmente isso deveria virar uma rule.

Quando NÃO usar rules?

Muita gente tenta transformar tudo em rule e isso também vira problema.

Rules não servem para tarefas operacionais.

Por exemplo:

Revise esta release e gere um changelog.

Isso não é uma regra permanente, é apenas um procedimento.

Nesse caso, o melhor recurso é uma Skill.

Outro exemplo ruim para rules:

Gere uma mensagem de commit.

Isso é um comando rápido. Um slash command faz mais sentido.

E existe outro caso importante:

Investigue gargalos de performance no banco.

Isso exige um especialista focado. Nesse caso, subagents funcionam melhor.

Rule não é prompt

Esse é um ponto muito importante.

Rules existem para tirar instruções repetitivas de dentro dos prompts.

Sem rules, os prompts ficam assim:

Use MVC.
Não misture SQL na view.
Use prepared statements.
Valide uploads.
Crie testes.
Siga PSR-12.

Depois de alguns meses, o projeto vira um “prompt Frankenstein“.

• As mesmas instruções aparecem em lugares diferentes.
• Às vezes contraditórias.
• Às vezes desatualizadas.

Rules resolvem isso centralizando as decisões permanentes do projeto.

Benefícios das rules

O maior benefício não é apenas organização. É consistência.

• Sem rules, cada conversa pode seguir um padrão diferente.
• Com rules, o Claude passa a trabalhar seguindo um conjunto fixo de decisões.
• Isso reduz retrabalho, evita inconsistências e ajuda muito quando o projeto começa a crescer, principalmente em equipes.
• Porque o padrão deixa de depender da memória das pessoas.
• O padrão passa a existir dentro do projeto.

O que vai para o Git e o que não vai?

Git é o sistema usado para versionar projetos e compartilhar código entre desenvolvedores.

Pense nele como um histórico compartilhado do sistema.

Tudo que vai para o Git pode parar na máquina de outras pessoas da equipe.

Por isso, uma das decisões mais importantes em qualquer projeto é definir: o que deve ser compartilhado e o que deve permanecer local.

No começo, muita gente simplesmente envia tudo para o repositório.

Depois começam os problemas:

• senhas expostas;
• arquivos temporários no Git;
• configurações pessoais misturadas;
• conflitos desnecessários;
• bagunça no projeto.

É exatamente por isso que existe essa separação.

O que normalmente vai para o Git?

Vai para o Git tudo aquilo que faz parte do projeto e precisa ser compartilhado com a equipe.

Por exemplo:

• código-fonte;
• documentação;
• rules;
• skills;
• estrutura do sistema;
• configurações compartilhadas.

Exemplo:

CLAUDE.md
docs/
.claude/rules/
.claude/skills/
.claude/agents/
app/
database/
public/

Esses arquivos ajudam outras pessoas a entender, executar e continuar o projeto.

Também ajudam o Claude a trabalhar seguindo os mesmos padrões para toda a equipe.

O que normalmente NÃO vai para o Git?

Arquivos locais, temporários, pessoais ou sensíveis normalmente não devem ser compartilhados.

Exemplo:

CLAUDE.local.md
.env
logs/
tmp/
node_modules/
vendor/

Esses arquivos costumam conter:

• senhas;
• tokens;
• caminhos locais;
• arquivos temporários;
• dependências instaladas;
• configurações pessoais;

E muitas vezes fazem sentido apenas na máquina daquele desenvolvedor.

Por que isso é tão importante?

Imagine duas pessoas trabalhando no mesmo projeto.

Uma usa Windows, outra usa Linux.

Uma roda o sistema em:

C:\xampp\htdocs\

Outra usa:

/home/projeto/

Uma utiliza porta:

localhost:8080

Outra:

localhost:8000

Essas configurações não deveriam ficar misturadas no contexto compartilhado do projeto.

Por isso existe o:

CLAUDE.local.md

Ele guarda informações específicas da máquina local.

Enquanto:

CLAUDE.md

guarda informações compartilhadas do projeto.

O papel do .gitignore

O arquivo:

.gitignore

serve para dizer ao Git quais arquivos não devem ser enviados para o repositório.

Pense nele como uma lista de exclusão.

Exemplo:

.env
node_modules/
vendor/
CLAUDE.local.md
logs/
tmp/

Assim, mesmo que esses arquivos existam no projeto, eles não serão compartilhados automaticamente.

Um erro muito perigoso

Um dos erros mais comuns de iniciantes é enviar arquivos sensíveis para o Git sem perceber.

Exemplo:

• senha do banco;
• token de API;
• chave da OpenAI;
• credenciais de produção.

Isso pode virar um problema enorme, principalmente em repositórios públicos.

Por isso, arquivos locais e sensíveis normalmente ficam fora do Git.

Regra simples para não se perder

Uma pergunta ajuda bastante:

Isso precisa existir na máquina de toda a equipe?

• Se a resposta for sim: provavelmente vai para o Git.
• Se a resposta for: “isso é pessoal, temporário ou sensível“, então provavelmente não deve ir.

Benefícios dessa separação

O maior benefício é organização. Sem essa separação, o projeto mistura:

• contexto compartilhado;
• arquivos pessoais;
• dados sensíveis;
• configurações locais;
• arquivos temporários.

E isso vira bagunça rapidamente.

Quando a separação é bem feita:

• o projeto fica mais limpo;
• a equipe trabalha melhor;
• o contexto fica mais consistente;
• riscos de segurança diminuem;
• a manutenção fica mais simples.

Em projetos pequenos isso já ajuda.

Em projetos grandes, isso vira obrigatório.

O que são slash commands?

Quando começamos a usar IA para programar, é comum repetir as mesmas instruções várias vezes.

Por exemplo:

Revise meu código.
Verifique riscos de segurança.
Sugira melhorias.
Gere uma mensagem de commit.

No primeiro dia isso parece normal, mas depois de alguns dias começa a ficar cansativo.

Você copia o mesmo prompt dezenas de vezes. Às vezes esquece um detalhe. Em outros momentos escreve diferente e recebe respostas inconsistentes.

Foi exatamente para resolver esse problema que surgiram os slash commands.

Um slash command é apenas um comando rápido que começa com /.

Exemplo:

/review

ou:

/gerar-commit

Em vez de escrever um prompt enorme toda vez, você cria um “atalho inteligente“.

Pense como os comandos do terminal do Windows ou Linux, mas voltados para conversar com a IA.

Você digita:

/gerar-commit

e o Claude já sabe o que precisa fazer.

Na prática, é como transformar prompts repetitivos em botões de ação.

Slash commands oficiais do Claude Code

O próprio Claude Code já possui vários comandos prontos. É útil entender que eles se dividem em dois grupos com comportamentos diferentes.

Comandos de controle executam ações fixas dentro da ferramenta, como limpar a conversa ou abrir uma interface. Skills embutidas são comandos que funcionam como skills, elas dão instruções ao Claude e deixam ele decidir como executar o trabalho usando suas ferramentas.

Comandos de controle

Comando	O que faz	Quando usar
/help	Mostra ajuda e lista de comandos disponíveis	Quando quiser ver o que existe
/clear	Limpa a conversa atual	Quando a sessão ficou confusa ou longa demais
/compact	Resume a conversa para economizar contexto	Quando a sessão está muito longa
/memory	Lista e permite editar os arquivos de instruções carregados	Para revisar o que o Claude está usando como referência
/init	Gera um CLAUDE.md analisando o projeto automaticamente	Na configuração inicial de um projeto
/agents	Abre a interface para gerenciar subagents	Para criar, editar ou verificar subagents disponíveis
/hooks	Abre o visualizador de hooks configurados	Para conferir quais automações estão ativas
/config	Abre as configurações do Claude Code	Para ajustar preferências, memória e outros comportamentos
/effort	Ajusta o nível de esforço do Claude na sessão	Quando quiser respostas mais rápidas ou mais profundas

Skills embutidas

Essas skills já vêm instaladas e funcionam como qualquer skill personalizada: você as chama com /nome ou o Claude as usa automaticamente quando acha relevante.

Skill	O que faz
/debug	Ajuda a investigar erros e comportamentos inesperados
/simplify	Sugere formas de simplificar o código atual
/batch	Executa uma mesma tarefa em vários arquivos de uma vez
/loop	Repete uma tarefa até que uma condição seja satisfeita
/run	Inicia o projeto e verifica se uma mudança está funcionando na prática
/verify	Compila e roda o projeto para confirmar que uma alteração faz o que deveria
/run-skill-generator	Ensina ao /run e ao /verify como iniciar o seu projeto específico
/claude-api	Ajuda a trabalhar com a API da Anthropic diretamente no projeto

Nota sobre /run e /verify: esses dois comandos tentam descobrir como iniciar o projeto automaticamente. Para projetos que precisam de banco de dados, variáveis de ambiente ou passos de build específicos, vale rodar /run-skill-generator primeiro. Ele registra a receita certa e os próximos usos ficam muito mais confiáveis.

Commands e skills: a mesma coisa

Esse é um ponto importante que muita documentação ainda não explica claramente.

Na versão atual do Claude Code, slash commands e skills foram unificados.

Na prática, isso significa que um arquivo em:

.claude/commands/gerar-commit.md

e um arquivo em:

.claude/skills/gerar-commit/SKILL.md

fazem exatamente a mesma coisa: criam o comando /gerar-commit.

Se você já tem arquivos na pasta .claude/commands/, eles continuam funcionando normalmente. Mas hoje a recomendação oficial é usar a estrutura de skills, que oferece mais recursos.

Vamos entender melhor isso na seção de skills mais adiante.

Onde os slash commands ficam?

Os slash commands personalizados podem ficar em dois lugares:

Formato antigo (ainda funciona):

.claude/commands/

Formato atual recomendado:

.claude/skills/

Em ambos os casos, o nome do arquivo ou da pasta vira o nome do comando.

Por exemplo:

.claude/commands/gerar-commit.md

vira:

/gerar-commit

Slash commands locais e globais

Os comandos podem existir em dois níveis diferentes:

Commands locais

São comandos criados dentro do projeto atual.

Exemplo:

meu-sistema/
├── .claude/
│   └── commands/
│       └── gerar-commit.md

Esses comandos fazem sentido apenas para aquele sistema.

Você normalmente coloca no Git para compartilhar com a equipe.

Use commands locais quando:

• o projeto possui regras próprias;
• o fluxo depende da arquitetura daquele sistema;
• o time inteiro deve usar os mesmos comandos;
• o comando está ligado ao negócio do projeto.

Exemplo:

/criar-migration-financeira

Esse comando poderia seguir um padrão específico do sistema financeiro da empresa.

Commands globais

Commands globais ficam fora do projeto e podem ser usados em vários sistemas diferentes.

Eles funcionam mais como ferramentas pessoais.

Exemplo:

~/.claude/commands/

Use commands globais quando:

• você repete o mesmo fluxo em vários projetos;
• o comando não depende de uma arquitetura específica;
• o uso é mais pessoal do que do time;
• você quer reutilizar o mesmo comando em qualquer projeto.

Exemplo:

/revisar-codigo

Esse comando poderia funcionar em PHP, Python, Node.js ou qualquer outra linguagem.

Criando seu primeiro slash command

Imagine que você sempre pede para o Claude gerar mensagens de commit.

Você pode transformar isso em um comando simples.

Crie o arquivo:

.claude/commands/gerar-commit.md

Dentro dele:

Analise as alterações atuais do projeto.

Depois:

1. Resuma o que mudou.
2. Identifique riscos importantes.
3. Sugira uma mensagem de commit clara.
4. Use o padrão Conventional Commits.
5. Não execute o commit automaticamente.

Agora basta usar:

/gerar-commit

E pronto.

Você economizou um prompt repetitivo.

Slash commands podem receber argumentos

Os slash commands e skills também podem receber informações digitadas depois do nome. Isso os torna muito mais flexíveis do que prompts estáticos.

Existem duas formas de capturar esses argumentos dentro do arquivo:

$ARGUMENTS → Captura tudo que foi digitado após o comando, como uma string única.

Exemplo de arquivo .claude/commands/teacher.md:

Explique o assunto abaixo como um professor experiente:
$ARGUMENTS

Uso:

/teacher Docker

O Claude Code substitui $ARGUMENTS por Docker antes de enviar o prompt, que vira:

Explique o assunto abaixo como um professor experiente:
Docker

Argumentos posicionais $0, $1, $2… → Quando você precisa separar os argumentos em posições específicas. O $0 é o primeiro argumento, o $1 é o segundo, e assim por diante.

Exemplo:

Compare as tecnologias abaixo:
Tecnologia 1: $0
Tecnologia 2: $1

Uso:

/compare React Vue

O Claude Code substitui automaticamente:

Compare as tecnologias abaixo:
Tecnologia 1: React
Tecnologia 2: Vue

Atenção: se o argumento tiver mais de uma palavra, coloque entre aspas. Por exemplo: /compare "React Native" Vue — o $0 vira React Native (com espaço) e o $1 vira Vue.

Se você não incluir $ARGUMENTS nem variáveis posicionais no arquivo, o Claude Code adiciona o argumento automaticamente no final do prompt.

Quando um comando vira uma skill?

Essa é uma dúvida comum.

A resposta simples é: quando o procedimento começa a crescer.

Um bom sinal é este:

• Se o comando tem uma ou duas instruções diretas, ele pode continuar sendo um arquivo simples na pasta commands/.
• Se ele começa a ter várias etapas, condições, arquivos de apoio ou comportamentos diferentes, vale migrar para a estrutura de skills.

Na próxima seção vamos entender melhor o que são skills e por que elas são mais poderosas.

O que são skills?

Skills são instruções reutilizáveis que ensinam o Claude a executar um tipo de tarefa de forma mais organizada.

Pense em uma skill como um pequeno manual de trabalho.

Ela explica:

quando usar
o que fazer
em qual ordem fazer
quais cuidados tomar
qual resultado entregar

A diferença para um prompt comum é simples.

• No prompt comum, você explica tudo na hora.
• Na skill, você explica uma vez e reutiliza sempre.

Por exemplo, em vez de escrever toda vez:

Revise a release, verifique os arquivos alterados, procure riscos de segurança, confira migrations, gere um resumo das mudanças e monte uma checklist final.

Você pode criar uma skill chamada:

revisar-release

Depois, quando precisar, basta digitar /revisar-release ou simplesmente pedir ao Claude para revisar a release. Ele encontra a skill e segue o procedimento que você definiu.

Onde as skills ficam?

Uma skill fica dentro de uma pasta própria, e dentro dessa pasta existe um arquivo principal chamado:

SKILL.md

Esse arquivo é o coração da skill. É nele que você escreve as instruções.

Exemplo:

.claude/skills/revisar-release/SKILL.md

Nesse caso, revisar-release é o nome da skill, e SKILL.md é o arquivo com as instruções.

Cada skill fica na sua própria pasta.

Como o Claude sabe quando usar uma skill?

Existem duas formas:

1. Você chama diretamente:

/revisar-release

2. O Claude identifica sozinho:

Quando você faz um pedido, o Claude lê as descrições de todas as skills disponíveis e decide se alguma delas é relevante para o que você pediu.

Por isso, escrever uma boa descrição na skill é importante. Quanto mais claro você deixar o propósito da skill, mais fácil fica para o Claude usá-la no momento certo.

A estrutura completa de uma skill

Uma skill bem configurada tem duas partes: uma seção de configuração no topo e as instruções em si.

A seção de configuração fica entre duas linhas com --- e usa um formato chamado YAML, que é basicamente um conjunto de chaves e valores:

---
description: Use esta skill para revisar uma release antes de publicar.
---

## Revisar release

Siga estas etapas:

1. Verifique quais arquivos foram alterados.
2. Procure mudanças arriscadas.
3. Confira se existem migrations novas.
4. Veja se há testes relacionados.
5. Aponte possíveis problemas de segurança.
6. Gere um resumo claro.
7. Monte uma checklist final antes da publicação.

A seção de configuração é opcional para skills simples, mas se torna muito útil à medida que o projeto cresce.

O que você pode configurar em uma skill

Esses são os principais campos disponíveis na seção de configuração:

description → Explica o que a skill faz e quando deve ser usada. O Claude usa esse texto para decidir se a skill é relevante para um pedido. Quanto mais específico e direto você for aqui, mais o Claude acerta na hora de usá-la automaticamente.

disable-model-invocation: true → Impede que o Claude chame a skill por conta própria. Com isso, só você pode acioná-la digitando /nome-da-skill. Útil para procedimentos com consequências, como fazer deploy ou enviar mensagens, onde você quer decidir manualmente quando rodar.

user-invocable: false → O oposto do campo anterior: esconde a skill do menu de comandos e deixa apenas o Claude chamá-la, quando achar relevante. Útil para skills que funcionam como contexto de fundo, não como ação direta do usuário.

allowed-tools → Lista de ferramentas que o Claude pode usar sem pedir sua permissão enquanto essa skill estiver ativa. Por exemplo, se a skill envolve rodar testes, você pode pré-autorizar o uso do terminal para não precisar confirmar cada execução.

paths → Assim como nas rules condicionais, você pode fazer uma skill aparecer apenas quando o Claude estiver trabalhando com determinados tipos de arquivo ou pastas. Útil em projetos grandes onde diferentes partes seguem padrões diferentes.

model → Define qual versão do Claude será usada quando essa skill rodar. Útil quando você quer uma skill mais poderosa para tarefas complexas ou mais rápida e econômica para tarefas simples.

effort → Controla o quanto o Claude “pensa” antes de responder. As opções low, medium e high afetam a profundidade da análise e o tempo de resposta. Para revisões rápidas, low já resolve. Para análises críticas, high vale o tempo extra.

Injetando informações dinâmicas na skill

Existe um recurso muito útil chamado injeção dinâmica de contexto.

Funciona assim: dentro do SKILL.md, você pode escrever um comando entre acentos graves com ! na frente. Antes de o Claude ler a skill, o Claude Code executa esse comando e substitui a linha pelo resultado.

Exemplo:

---
description: Resumir as alterações não commitadas do projeto.
---

## Alterações atuais

!`git diff HEAD`

## Instruções

Resuma as alterações acima em dois ou três pontos e liste qualquer risco que você identificar.

Quando essa skill for usada, o Claude Code roda git diff HEAD automaticamente e coloca o resultado no lugar da linha com !. O Claude então recebe a skill já com o conteúdo real do diff, sem precisar buscar essa informação por conta própria.

Isso é especialmente útil para skills que trabalham com dados do momento, como estado atual do repositório, versão do sistema, arquivos recentes, entre outros.

Arquivos de apoio dentro da skill

Uma skill não precisa ter apenas o SKILL.md. Você pode adicionar outros arquivos dentro da mesma pasta para deixar a skill mais completa.

Exemplo de estrutura:

.claude/skills/revisar-release/
├── SKILL.md           (instruções principais — obrigatório)
├── checklist.md       (checklist detalhada para o Claude seguir)
├── exemplos/
│   └── exemplo-bom.md (exemplo de como deve ser o resultado)
└── scripts/
    └── verificar.sh   (script que o Claude pode executar)

No SKILL.md você menciona esses arquivos para que o Claude saiba que eles existem e quando usá-los:

## Recursos adicionais

- Para a checklist completa, consulte [checklist.md](checklist.md)
- Para ver um exemplo de resultado esperado, veja [exemplos/exemplo-bom.md](exemplos/exemplo-bom.md)

Isso evita que o SKILL.md fique longo demais. O conteúdo detalhado fica nos arquivos de apoio e só é carregado quando necessário.

A recomendação da documentação é manter o SKILL.md abaixo de 500 linhas, movendo detalhes para arquivos separados quando necessário.

Skills locais e skills globais

Assim como acontece com outros recursos do Claude Code, uma skill pode ficar no projeto atual ou na pasta global do usuário.

Skills locais

Skills locais ficam dentro do próprio projeto.

Exemplo:

meu-sistema/
├── .claude/
│   └── skills/
│       └── revisar-release/
│           └── SKILL.md

Use uma skill local quando ela faz sentido apenas para aquele sistema.

Por exemplo:

.claude/skills/revisar-modulo-financeiro/SKILL.md

Skills locais podem ir para o Git, porque fazem parte da organização do projeto e podem ser úteis para toda a equipe.

Skills globais

Skills globais ficam na pasta pessoal do usuário.

Exemplo:

~/.claude/skills/

Use skills globais quando você quer reaproveitar o mesmo procedimento em vários projetos.

Exemplo:

~/.claude/skills/revisar-codigo/SKILL.md

Essa skill poderia funcionar em qualquer projeto, independentemente da linguagem usada.

Exemplo simples de skill

Imagine que você sempre precisa revisar uma release antes de publicar.

Arquivo:

.claude/skills/revisar-release/SKILL.md

Conteúdo:

---
description: Use quando o usuário pedir para revisar uma release antes da publicação.
disable-model-invocation: true
---

# Revisar release

Siga estas etapas:

1. Verifique quais arquivos foram alterados.
2. Procure mudanças arriscadas.
3. Confira se existem migrations novas.
4. Veja se há testes relacionados.
5. Aponte possíveis problemas de segurança.
6. Gere um resumo claro para o usuário.
7. Monte uma checklist final antes da publicação.

Não publique nada automaticamente.
Sempre peça confirmação antes de executar qualquer ação irreversível.

Agora o Claude tem um procedimento claro para seguir.

A skill não é apenas um comando rápido. Ela descreve um fluxo de trabalho completo.

Quando usar skills?

Use skills quando a tarefa tem várias etapas e precisa ser repetida com consistência.

Elas funcionam muito bem para:

• revisar release;
• gerar documentação;
• auditar segurança;
• criar plano de testes;
• padronizar revisão de código;
• preparar descrição de pull request;
• analisar performance;
• montar changelog.

Uma boa pista é esta:

Se o prompt começou a ficar grande demais, talvez ele devesse virar uma skill.

Por exemplo, este pedido é simples:

Gere uma mensagem de commit.

Isso pode ser um slash command.

Mas este pedido já é maior:

Revise todos os arquivos alterados, identifique riscos, confira testes, valide migrations, gere um changelog, monte uma checklist e só depois sugira a publicação.

Isso tem cara de skill.

Quando NÃO usar skills?

Não use skills para tudo. Se a tarefa for muito curta, uma skill pode ser exagero.

Por exemplo:

Limpe a conversa.

ou:

Gere uma mensagem de commit.

Esses casos combinam melhor com slash commands.

Também não use skill para uma regra que precisa valer o tempo todo.

Exemplo:

Nunca misturar SQL dentro das views.

Isso não é skill, isso é uma regra permanente do projeto.

Nesse caso, faz mais sentido colocar no CLAUDE.md ou em .claude/rules/.

Outro caso: se você precisa de um especialista separado para investigar algo com profundidade, talvez o melhor recurso seja um subagent.

• A skill ensina um processo.
• O subagent funciona mais como um especialista chamado para uma tarefa específica.

Skill não é mágica

• Uma skill não torna o Claude perfeito. Ela apenas reduz improviso.
• Sem skill, o Claude depende muito do que você explicou naquela conversa.
• Com skill, ele recebe um procedimento pronto.

É como entregar uma receita para alguém cozinhar. A pessoa ainda precisa executar bem, mas agora ela sabe os ingredientes, a ordem e os cuidados principais.

O que são subagents?

Subagents são assistentes especializados que trabalham separadamente da conversa principal.

A documentação do Claude Code define subagents como assistentes especializados criados para tarefas específicas e para melhorar o gerenciamento de contexto.

Na prática, eles funcionam como “especialistas da equipe“.

Por exemplo:

• especialista em segurança;
• especialista em MySQL;
• especialista em testes;
• especialista em debugging;
• especialista em arquitetura.

Mas existe um detalhe muito importante:

O principal objetivo dos subagents não é apenas especialização. É separação de contexto.

E isso muda tudo em projetos grandes.

O problema que os subagents resolvem

Imagine esta situação.

Você está desenvolvendo uma funcionalidade nova.

Ao mesmo tempo, quer:

• revisar segurança;
• analisar performance;
• investigar bugs;
• revisar arquitetura;
• validar testes.

Se tudo acontecer na mesma conversa, o contexto começa a ficar enorme e bagunçado.

A sessão mistura:

• código;
• logs;
• regras de negócio;
• erros;
• testes;
• arquitetura;
• análises.

Com o tempo, o Claude pode começar a perder foco.

É exatamente aqui que entram os subagents.

Em vez de fazer tudo na conversa principal, o Claude cria um “assistente separado” para executar aquela tarefa específica. Esse assistente trabalha na própria janela de contexto, sem poluir a conversa principal. Quando termina, devolve apenas o resultado relevante.

Na prática, funciona mais ou menos assim:

Conversa principal:
"Crie o módulo financeiro."

Enquanto isso, um subagent pode investigar separadamente:

"Analise possíveis riscos de segurança nesse módulo."

Outro pode verificar:

"Procure gargalos de performance."

E outro:

"Revise os testes automatizados."

Cada um trabalha separado, sem poluir a conversa principal.

Depois, apenas os resultados importantes voltam.

Pense como uma equipe real

Uma forma fácil de entender subagents é imaginar uma equipe de especialistas.

Você continua falando com o “líder principal“.

Mas ele pode chamar especialistas para tarefas específicas.

Exemplo:

Você → gerente do projeto
Subagent → especialista técnico

• Você não precisa acompanhar cada detalhe interno da investigação.
• Recebe apenas o resumo relevante.
• Isso deixa a conversa principal muito mais limpa e organizada.

Por que isso é tão importante?

Porque IA também sofre com excesso de contexto.

Quando uma conversa fica gigantesca, misturando dezenas de assuntos diferentes, o desempenho pode cair.

Subagents ajudam a manter o contexto principal limpo e focado.

Em projetos pequenos, talvez isso não faça tanta diferença.

Mas em projetos grandes, faz muita diferença.

Principalmente quando existem:

• muitos arquivos;
• muitas regras;
• logs grandes;
• testes extensos;
• análises técnicas;
• múltiplas investigações paralelas.

Os subagents que já vêm prontos

O Claude Code já inclui alguns subagents prontos que ele usa automaticamente quando acha adequado. Você não precisa criar nada para usá-los.

Explore → Um assistente rápido e focado em leitura. Ele só pode ler arquivos, não pode alterá-los. É usado quando o Claude precisa pesquisar e entender o código sem fazer mudanças. Por ser mais leve, responde mais rápido e com menor custo.

Plan → Usado quando você ativa o modo de planejamento. Antes de propor um plano de ação, o Claude delega a pesquisa do codebase para esse assistente, que coleta o contexto necessário sem fazer alterações.

General-purpose → Um assistente completo, com acesso a todas as ferramentas, usado para tarefas mais complexas que envolvem tanto pesquisa quanto modificações.

Conhecer esses assistentes embutidos ajuda a entender melhor o que acontece por baixo dos panos quando o Claude Code trabalha em tarefas maiores.

Onde os subagents ficam?

Os subagents ficam em arquivos dentro da pasta:

.claude/agents/

Exemplo:

.claude/agents/security-reviewer.md
.claude/agents/mysql-optimizer.md
.claude/agents/test-writer.md

Também podem existir globalmente, disponíveis em qualquer projeto:

~/.claude/agents/

Como criar um subagent

Cada subagent é um arquivo de texto com uma seção de configuração no topo e as instruções do especialista no corpo.

Exemplo:

---
name: security-reviewer
description: Especialista em segurança PHP. Use quando precisar revisar riscos de segurança no código.
tools: Read, Grep, Glob
model: sonnet
---

Você é um especialista em segurança PHP.

Sua função é:

- procurar SQL Injection;
- identificar falta de validação;
- encontrar senhas expostas;
- revisar uploads inseguros;
- analisar permissões;
- procurar riscos comuns em aplicações web.

Sempre entregue:

- resumo dos riscos;
- arquivos afetados;
- nível de prioridade;
- sugestões de correção.

Nunca altere arquivos automaticamente.

Os campos da seção de configuração mais importantes são:

name → O identificador único do subagent. Use letras minúsculas e hífens.

description → Explica para o Claude quando ele deve acionar esse especialista. Quanto mais específico, melhor.

tools → Lista de ferramentas que o subagent pode usar. Se omitir, ele herda todas as ferramentas da conversa principal. Para um especialista somente de leitura, por exemplo, você listaria apenas Read, Grep, Glob.

model → Define qual versão do Claude esse subagent usa. Você pode escolher um modelo mais rápido e barato para tarefas simples (haiku) ou um mais poderoso para análises complexas (opus). Se não definir, ele usa o mesmo modelo da conversa principal.

Memória persistente para subagents

Um recurso muito útil é a memória persistente.

Por padrão, cada vez que um subagent é chamado, ele começa do zero, sem lembrar de conversas anteriores.

Mas você pode mudar isso adicionando o campo memory na configuração:

---
name: code-reviewer
description: Revisão de código com aprendizado contínuo.
memory: user
---

Com isso, o subagent passa a guardar anotações entre sessões. Conforme ele trabalha no projeto, vai acumulando conhecimento sobre padrões do código, problemas recorrentes e decisões de arquitetura.

As opções disponíveis são:

• user → A memória fica no computador do usuário e vale para todos os projetos.
• project → A memória fica na pasta do projeto e pode ser compartilhada via Git com a equipe.
• local → A memória fica na pasta do projeto, mas não vai para o Git.

Subagents locais e globais

Subagents locais

Ficam dentro do projeto atual.

Exemplo:

meu-sistema/
├── .claude/
│   └── agents/
│       └── security-reviewer.md

Use quando o especialista depende das regras daquele sistema.

Subagents locais normalmente vão para o Git junto com o projeto.

Subagents globais

Ficam disponíveis para qualquer projeto.

Exemplo:

~/.claude/agents/

Use quando o especialista pode funcionar em vários sistemas diferentes.

Como chamar um subagent?

Existem três formas:

1. Pedindo em linguagem natural:

Use o subagent security-reviewer para analisar este módulo.

O Claude decide se delega ou não com base na descrição do subagent.

2. Usando @-mention:

Digite @ e escolha o subagent na lista que aparecer. Isso garante que aquele especialista específico seja chamado, sem deixar a decisão para o Claude.

@security-reviewer analise os arquivos de autenticação

3. Deixando o Claude decidir:

Faça uma análise profunda de segurança neste sistema.

Se o Claude identificar que existe um subagent adequado para isso, ele o aciona automaticamente.

Gerenciando subagents com /agents

O Claude Code tem um comando dedicado para gerenciar subagents:

/agents

Ao executar esse comando, você vê uma interface com duas abas:

• Running → Mostra os subagents que estão rodando no momento. Você pode acompanhar o progresso ou interromper um subagent por aqui.
• Library → Lista todos os subagents disponíveis. Permite criar novos, editar os existentes e excluir os que não usa mais.

Pelo /agents você também pode gerar um subagent com ajuda do próprio Claude, descrevendo o que você precisa e deixando ele montar a configuração inicial para você.

Subagents em segundo plano

Subagents podem rodar de duas formas:

Em primeiro plano → A conversa principal fica pausada enquanto o subagent trabalha. Qualquer pedido de permissão aparece para você responder normalmente.

Em segundo plano → O subagent trabalha enquanto você continua usando o Claude normalmente. Útil para tarefas longas que não precisam da sua atenção o tempo todo.

O Claude decide como rodar o subagent com base na tarefa. Você também pode pedir explicitamente:

Rode essa análise em segundo plano.

Quando usar subagents?

Subagents são excelentes quando:

• a tarefa é muito especializada;
• a investigação pode gerar muito contexto;
• você quer separar análises da conversa principal;
• existem tarefas paralelas;
• o projeto é grande;
• você quer especialistas dedicados.

Exemplos muito bons:

• análise de segurança;
• investigação de bugs;
• revisão de arquitetura;
• análise de performance;
• otimização de banco;
• revisão de testes.

Quando NÃO usar subagents?

Não use subagents para tarefas simples.

Por exemplo:

Gerar mensagem de commit

Isso é simples demais. Um slash command resolve melhor.

Também não use subagents para regras permanentes do projeto.

Exemplo:

Nunca misturar SQL na view

Isso pertence ao CLAUDE.md ou ao .claude/rules/.

Outro erro comum é usar subagents para processos operacionais completos.

Exemplo:

Revisar release inteira com checklist, documentação e changelog

Isso normalmente combina mais com uma Skill.

• A Skill define o processo.
• O Subagent define o especialista.

Skill e Subagent NÃO são a mesma coisa

Isso costuma confundir muita gente.

• Uma Skill é um procedimento.
• Um Subagent é um especialista.

Exemplo simples:

Skill

Procedimento para revisar release

Subagent

Especialista em segurança

A Skill ensina um fluxo.

O Subagent executa uma função especializada.

Inclusive, uma Skill pode usar Subagents internamente.

Benefícios dos subagents

• O maior benefício não é “ter vários agentes“.
• É manter o projeto organizado.
• Sem subagents, tudo acontece na mesma conversa.
• Com subagents, cada investigação fica isolada.

Isso reduz bagunça, evita excesso de contexto e ajuda o Claude a manter foco mesmo em projetos grandes e complexos.

Hooks: automatizando ações ao redor do Claude

Existe um recurso do Claude Code chamado hooks que permite executar ações automáticas antes ou depois de o Claude fazer alguma coisa.

A ideia é simples: você define um gatilho e um comando. Quando o gatilho acontece, o comando roda automaticamente, sem depender de o Claude lembrar ou decidir fazê-lo.

Por que isso é útil?

O CLAUDE.md e as rules ensinam o Claude a seguir padrões. Mas o Claude ainda é uma IA tomando decisões. Em alguns momentos, especialmente em projetos com regras críticas, você não quer depender da decisão dele.

Hooks resolvem isso de forma determinística. Ou seja, eles simplesmente acontecem, independentemente do que o Claude decidiu fazer.

Exemplo prático: você quer que o código seja formatado automaticamente toda vez que o Claude editar um arquivo. Sem hook, você precisaria confiar que o Claude vai lembrar de formatar. Com hook, a formatação roda automaticamente após cada edição, sem exceção.

Exemplos de uso

Alguns casos onde hooks fazem diferença:

• Formatar código automaticamente após cada arquivo editado pelo Claude;
• Rodar o linter antes de cada commit para garantir que o código está limpo;
• Registrar em log quais arquivos o Claude modificou durante a sessão;
• Validar comandos antes de o Claude executá-los no terminal, bloqueando operações perigosas;
• Notificar quando o Claude terminar uma tarefa longa.

Quando o hook é acionado?

Os hooks podem ser configurados para disparar em momentos específicos da sessão:

Antes de usar uma ferramenta → Roda antes do Claude executar algo, como abrir um arquivo ou rodar um comando. Útil para validações e bloqueios.

Depois de usar uma ferramenta → Roda após o Claude terminar uma ação. Útil para formatação, linting e logs.

Quando o Claude termina de responder → Roda ao final de cada resposta. Útil para notificações ou verificações finais.

Quando o Claude precisa de input → Avisa você quando ele está esperando uma resposta sua. Útil para não ficar olhando o terminal o tempo todo.

Onde os hooks ficam?

Diferente das skills e das rules, hooks não ficam em arquivos Markdown. Eles são configurados dentro do arquivo settings.json, que fica na pasta .claude/ do projeto ou em ~/.claude/ para configurações globais.

Um exemplo simples de hook que formata automaticamente os arquivos editados pelo Claude:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $FILE"
          }
        ]
      }
    ]
  }
}

Você não precisa escrever esse JSON do zero. Pode simplesmente pedir ao Claude:

Crie um hook que formate automaticamente os arquivos que você editar.

Ele escreve a configuração para você.

Visualizando os hooks ativos

Para ver todos os hooks configurados no projeto, use o comando:

/hooks

Ele mostra uma lista de todos os eventos disponíveis e quantos hooks estão configurados em cada um. Você pode navegar para ver os detalhes de cada hook: o evento, a condição de disparo, o tipo e o comando que será executado.

O /hooks é somente leitura. Para adicionar, editar ou remover hooks, você edita o settings.json diretamente ou pede ao Claude para fazer isso.

Como hooks se encaixam no ecossistema

Até aqui, você viu recursos que orientam o comportamento do Claude:

• CLAUDE.md explica o projeto;
• rules definem padrões permanentes;
• skills descrevem procedimentos;
• subagents especializam tarefas.

Todos esses recursos influenciam o Claude, mas ainda dependem dele para agir.

Hooks são diferentes. Eles executam comandos do sistema operacional diretamente, fora do controle do Claude. É como ter um assistente que, independentemente do que o Claude fizer, garante que certas ações sempre acontecem.

Para quem os hooks são recomendados?

Hooks são um recurso mais avançado. Para a maioria dos projetos e para quem está começando, o CLAUDE.md, as rules e as skills já resolvem bem.

Hooks começam a fazer sentido quando:

• você precisa de garantias que não dependam da decisão do Claude;
• o projeto tem regras críticas de segurança ou qualidade;
• você quer automatizar verificações que hoje faz manualmente;
• a equipe precisa de consistência absoluta em determinados processos.

Se você chegou até aqui no artigo e ainda não sente necessidade de hooks, tudo bem. É um recurso para quando o projeto ou o time crescer e as necessidades ficarem mais exigentes.

MCP: conectando o Claude às suas ferramentas

Por padrão, o Claude Code trabalha dentro do seu projeto. Ele lê arquivos, edita código, roda comandos no terminal e entende a estrutura do sistema.

Mas e se você quiser que ele também acesse o Jira para atualizar um ticket? Ou leia um documento no Google Drive? Ou busque informações no Slack?

É para isso que existe o MCP.

O que é MCP?

MCP é a sigla para Model Context Protocol, que em português significa Protocolo de Contexto de Modelo.

O nome técnico pode assustar, mas a ideia é simples:

MCP é um padrão que permite conectar o Claude Code a serviços externos.

Pense como uma tomada universal. Em vez de cada ferramenta criar uma integração diferente do zero, o MCP define um formato padrão que qualquer serviço pode usar para se conectar ao Claude Code.

A Anthropic criou esse padrão e o disponibilizou abertamente. Isso significa que qualquer empresa pode criar um conector para o seu serviço seguindo esse padrão.

O que você pode conectar?

Já existem conectores prontos para muitos serviços populares. Alguns exemplos:

• Google Drive → O Claude acessa documentos, planilhas e apresentações diretamente;
• Jira → O Claude lê e atualiza tickets sem você precisar abrir o navegador;
• Slack → O Claude busca mensagens e contexto de conversas recentes;
• GitHub → O Claude acessa issues, pull requests e informações do repositório;
• Notion → O Claude lê páginas e bases de dados do seu workspace;
• Banco de dados → O Claude consulta dados diretamente com permissões controladas.

E a lista cresce constantemente, porque qualquer desenvolvedor pode criar um conector para qualquer serviço seguindo o padrão MCP.

Como isso muda o trabalho na prática?

Sem MCP, um fluxo comum é assim:

1. Você abre o Jira, copia a descrição do ticket;
2. Cola no Claude Code;
3. O Claude gera o código;
4. Você volta ao Jira para atualizar o status manualmente.

Com MCP conectado ao Jira:

1. Você diz “implemente o ticket JRA-234”;
2. O Claude lê a descrição direto do Jira, gera o código e atualiza o ticket.

O Claude para de depender de você copiar e colar informações de um lugar para outro.

MCP em subagents

Um uso interessante do MCP é dentro de subagents. Você pode criar um especialista que só tem acesso a um serviço específico.

Por exemplo, um subagent de banco de dados que acessa apenas um servidor de leitura, sem permissão para modificar nada. Quando o Claude termina de usar esse subagent, a conexão com o serviço encerra automaticamente.

Isso é útil porque limita o acesso de cada especialista apenas ao que ele realmente precisa para fazer o trabalho.

Para quem o MCP é recomendado?

Assim como os hooks, o MCP é um recurso mais avançado. Você não precisa dele para começar a usar o Claude Code de forma produtiva.

Faz sentido explorar o MCP quando:

• você repete com frequência o processo de copiar informações de outras ferramentas para o Claude;
• o seu time trabalha com ferramentas de gestão como Jira, Linear ou Notion e quer integrar o fluxo de desenvolvimento;
• você quer que o Claude acesse dados em tempo real que ficam fora do repositório.

Para quem está começando, o mais importante é entender que o recurso existe. Quando você sentir que o fluxo de trabalho poderia ser mais automatizado, o MCP provavelmente é o caminho.

Plugins: instalando extensões prontas

Ao longo deste artigo você viu como criar skills, subagents, hooks e conexões MCP para o seu projeto. Cada um desses recursos pode ser construído do zero, mas existe uma forma mais rápida de começar: usando plugins.

Um plugin é um pacote pronto que agrupa skills, subagents, hooks e conexões com serviços externos em uma única instalação. Em vez de configurar tudo manualmente, você instala o plugin e esses recursos já ficam disponíveis no seu projeto.

Pense como as extensões de um editor de código. Você não precisa escrever um tema escuro do zero, você instala um.

O que um plugin pode incluir?

Um plugin pode conter qualquer combinação de:

• skills prontas para uso;
• subagents especializados;
• hooks configurados;
• conexões com serviços externos via MCP.

Tudo empacotado junto, com um único comando de instalação.

Como os plugins evitam conflitos de nomes?

Se dois plugins diferentes tiverem uma skill chamada /deploy, eles não se misturam. Cada plugin usa um namespace próprio, que é basicamente um prefixo com o nome do plugin.

Por exemplo:

/meu-plugin:deploy
/outro-plugin:deploy

Os dois convivem no mesmo projeto sem problema.

Onde encontrar plugins prontos?

O Claude Code possui um marketplace onde você pode descobrir e instalar plugins criados pela comunidade e por empresas. Para acessar, use o comando:

/plugin

Ele abre uma interface onde você navega pelos plugins disponíveis, vê o que cada um faz e instala com um clique.

Posso criar meu próprio plugin?

Sim. Se você já tem um conjunto de skills, subagents e hooks que funcionam bem em um projeto, pode empacotá-los como plugin e reutilizar em outros repositórios ou compartilhar com a equipe.

Isso é especialmente útil em empresas que têm vários projetos seguindo os mesmos padrões. Em vez de copiar os arquivos de configuração de um projeto para o outro, você mantém um único plugin e instala onde precisar.

Quando vale a pena usar plugins?

Plugins fazem sentido quando:

• você quer começar rápido sem configurar tudo do zero;
• existe um plugin pronto que já resolve o que você precisa;
• você quer compartilhar sua configuração com outros projetos ou pessoas;
• sua equipe usa os mesmos padrões em vários repositórios.

Para projetos únicos e configurações muito específicas, criar seus próprios arquivos diretamente ainda é o caminho mais simples.

Para quem está começando, vale pelo menos dar uma olhada no marketplace antes de criar tudo manualmente. É bem provável que alguém já tenha resolvido o mesmo problema.

Qual o melhor recurso para cada situação?

Depois de conhecer todos os recursos do Claude Code, muita gente fica com a mesma dúvida:

Mas afinal… quando eu uso cada um?

Essa dúvida é normal. Porque vários recursos são parecidos no começo.

A melhor forma de entender é pensar que cada recurso resolve um tipo diferente de problema.

Visão rápida de todos os recursos

Recurso	O que é	Quando usar
CLAUDE.md	Arquivo principal de contexto do projeto	Explicar visão geral, arquitetura e padrões principais
CLAUDE.local.md	Configuração local da máquina	Guardar dados pessoais, caminhos locais e configurações sensíveis
Auto Memory	Anotações que o próprio Claude escreve entre sessões	Acumular aprendizados do projeto sem esforço manual
@imports	Forma de carregar outros arquivos no contexto	Modularizar informações e evitar arquivos gigantes
docs/	Documentação do sistema	Explicar regras de negócio, fluxos e funcionamento do projeto
.claude/rules/	Regras permanentes do projeto	Definir padrões técnicos e comportamentos obrigatórios
.claude/skills/	Skills e slash commands reutilizáveis	Atalhos rápidos e workflows com várias etapas
.claude/agents/	Subagents especializados	Delegar análises e investigações para especialistas separados
Hooks	Comandos automáticos disparados por eventos	Garantir ações que não dependem da decisão do Claude
MCP	Conexão com serviços externos	Integrar o Claude com Jira, Google Drive, Slack e outros
Plugins	Pacotes prontos com skills, hooks, subagents e MCP	Instalar configurações completas sem montar tudo do zero

Pense assim

Uma analogia simples ajuda bastante:

• CLAUDE.md → é a visão geral do projeto;
• Auto Memory → é o caderno de anotações que o Claude mantém sozinho;
• docs/ → são os manuais do sistema;
• rules → são as leis técnicas;
• slash commands e skills → são procedimentos e atalhos operacionais;
• subagents → são especialistas separados;
• hooks → são as regras que executam automaticamente, sem depender do Claude;
• MCP → são as pontes para o mundo fora do projeto;
• plugins → são extensões prontas que empacotam tudo isso junto.

Quando você entende essa separação, o Claude Code começa a fazer muito mais sentido.

O objetivo não é usar tudo

Outro ponto importante: você não precisa usar todos os recursos em projetos pequenos. Muita gente exagera.

Cria:

• dezenas de rules;
• centenas de arquivos;
• skills para tudo;
• subagents desnecessários;
• hooks para casos que não precisam deles.

Isso também vira bagunça. O objetivo é organização, não complexidade artificial.

Projetos pequenos

Talvez precisem apenas de:

CLAUDE.md
+
algumas rules

Projetos médios

Talvez já façam sentido:

docs/
skills
commands
Auto Memory

Projetos grandes

Aí sim começam a aparecer benefícios enormes com:

subagents
hooks
MCP
plugins
contexto modular
documentação extensa
processos especializados

A regra mais importante

Se existir uma regra que resume tudo, talvez seja esta:

Não tente resolver organização com prompts maiores.

Quanto mais o projeto cresce, mais importante fica separar:

• contexto;
• documentação;
• regras;
• processos;
• especialistas;
• automações.

Essa separação é justamente o que transforma IA de:

chat improvisado

em:

ambiente real de desenvolvimento assistido por IA

Outros recursos que valem explorar

O Claude Code tem ainda mais recursos que não aprofundamos neste artigo por serem mais técnicos ou voltados para usos específicos. Se você chegar num ponto onde o básico já não resolve, vale pesquisar cada um deles na documentação oficial em code.claude.com/docs.

Agent Teams → Coordenação de múltiplas sessões do Claude Code trabalhando em paralelo, cada uma com seu contexto próprio e se comunicando entre si. Útil quando uma tarefa grande pode ser dividida em frentes independentes. Uma equipe revisando segurança, outra testando performance, outra implementando features, tudo ao mesmo tempo.

Tarefas agendadas (Scheduled Tasks) → Permite programar prompts para rodar automaticamente em horários definidos. Você pode, por exemplo, agendar uma análise de segurança toda madrugada ou um resumo de alterações toda sexta-feira, sem precisar estar presente.

Output Styles → Arquivos que customizam a forma como o Claude formata as respostas. Se você precisa que ele sempre responda num estilo específico, mais formal, mais resumido, seguindo um padrão da empresa, output styles guardam essa preferência de forma permanente.

Worktrees → Forma de isolar sessões do Claude usando cópias separadas do repositório. Especialmente útil quando você quer que o Claude trabalhe em uma funcionalidade nova sem misturar com o código principal em desenvolvimento.

Goals → Um recurso para definir objetivos de longo prazo que o Claude acompanha ao longo de múltiplas sessões. Ainda experimental, mas interessante para projetos com metas contínuas.

Channels → Permite que sistemas externos enviem eventos e informações diretamente para uma sessão ativa do Claude Code. Útil em fluxos de automação mais complexos, como acionar o Claude automaticamente quando um build falha no servidor.

Remote Control → Possibilita controlar o Claude Code de outro dispositivo, como um celular ou tablet, enquanto ele roda no computador. Útil para acompanhar tarefas longas sem precisar estar na frente do computador.

Esses recursos estão todos documentados em code.claude.com/docs e a documentação oficial é bem acessível. Vale uma explorada quando você já tiver o básico funcionando bem no projeto.

Conclusão

Muita gente ainda usa IA para programar como se estivesse apenas conversando com um chatbot.

Os recursos do Claude Code apresentados neste artigo mudam justamente essa lógica.

Em vez de depender apenas da conversa atual, você passa a construir um ambiente organizado para a IA trabalhar.

O projeto começa a possuir:

• contexto estruturado;
• documentação;
• regras permanentes;
• memória que cresce com o tempo;
• workflows reutilizáveis;
• especialistas separados;
• automações que independem da decisão da IA;
• integração com as ferramentas que você já usa.

E isso muda completamente a qualidade do desenvolvimento.

• O Claude deixa de trabalhar “no improviso“.
• Ele passa a trabalhar seguindo uma estrutura.

Essa talvez seja a principal ideia do artigo:

Desenvolvimento assistido por IA não é sobre criar prompts gigantes. É sobre organizar contexto.

Quando você organiza tudo corretamente, o projeto começa a ficar muito mais previsível, mais consistente e mais sustentável.

Principalmente em projetos longos e em equipes. E isso vale não apenas para Claude Code.

Essa forma de pensar provavelmente vai se tornar cada vez mais importante em qualquer ambiente de desenvolvimento com IA.

Porque no futuro, a diferença não será apenas sobre “quem usa IA“. A diferença será sobre “quem sabe estruturar contexto para IA“.

No primeiro caso, você apenas conversa com a ferramenta. Isso é puro Vibe Coding.

No segundo, você constrói um ambiente real de desenvolvimento com contexto, regras, processos, memória e organização. Isso é desenvolvimento assistido por IA.