Estrutura do Projeto: O que o Claude Code coloca no seu projeto

📚 Navegação da Série: O artigo anterior 12 Inicialização do Projeto mostrou como executar /init para gerar o primeiro CLAUDE.md do seu projeto. Este artigo continua a partir daí — após o /init, o que exatamente há na pasta .claude/ que apareceu silenciosamente no seu projeto, quem a gerencia e se ela deve ir para o git.

Todos dizem que a pasta .claude "não precisa de atenção, ele mesmo cuida", mas para falar a verdade, entender isso é o que faz você realmente saber usar o Claude Code.

Por que digo isso? Porque quase todos os "recursos avançados" desta ferramenta — comandos personalizados, controle de permissões, subagentes, habilidades — quando chegam ao disco, são apenas alguns arquivos e diretórios dentro de .claude/. Se você não entende a estrutura, quando encontrar problemas como "por que as permissões que configurei não funcionaram" ou "os colegas de equipe puxaram o código, mas não têm meus comandos", você não saberá o que fazer.

Eu mesmo fiz uma bobagem quando comecei: por conveniência, escrevi uma configuração com a senha do banco de dados diretamente no .claude/settings.json e a enviei com git push. Quando percebi, a senha já estava no histórico do repositório — no final, só pude mudar a senha, reescrever o histórico e perder mais de meia hora. Mais tarde, entendi que essas coisas deveriam ir para o settings.local.json, um arquivo que o Claude Code ignora no git por padrão. Colocar um arquivo no lugar errado faz tanta diferença.

Este artigo não ensina como configurar cada arquivo a fundo (isso fica para artigos específicos depois), mas faz apenas uma coisa: dá a você um mapa panorâmico, para que, com um olhar para um arquivo, você saiba "para que serve, onde fica, se pertence ao projeto ou a você, e se deve ser commitado".

Após ler este artigo, você terá:

• Um mapa panorâmico do diretório .claude/: o que cada arquivo/subdiretório gerencia
• A diferença fundamental entre as configurações de "nível de projeto" e "nível de usuário" (acompanha o projeto vs acompanha você)
• Uma tabela de referência rápida: o que deve ser commitado no git e o que deve ir para o .gitignore
• Um exercício prático fácil de seguir para ver com seus próprios olhos como são essas duas camadas de diretórios

---

01 Entenda primeiro uma coisa: o Claude Code tem "duas casas"

Vamos à conclusão: As configurações do Claude Code são divididas em dois lugares — um acompanha o projeto e o outro acompanha você. Entenda isso e o resto fará sentido.

Analogia: O "arquivo de projetos" da empresa e a "gaveta da sua mesa". O arquivo de projetos (nível de projeto) contém coisas que todos no projeto precisam ver — normas do projeto, quem pode realizar quais operações, para que os novatos possam se basear nesses materiais. A gaveta da sua mesa (nível de usuário) contém seus hábitos pessoais — atalhos que você prefere, preferências privadas, que continuam com você mesmo se mudar de projeto.

No disco, são dois locais:

Esse local	Onde fica	Quem afeta	Quem acompanha
Nível de Projeto (Project)	./.claude/ no projeto	Todos os colaboradores deste repositório	Acompanha o projeto (commitado no git, compartilhado com a equipe)
Nível de Usuário (User)	~/.claude/ no seu diretório home	Você, em todos os seus projetos	Acompanha você (na sua máquina, nunca é commitado)

Aqui estão dois termos para esclarecer:

Nível de Projeto (Project scope): As configurações ficam no repositório, vão para o git e são compartilhadas com a equipe. Se você alterar as regras e commitar, a equipe receberá as atualizações.

Nível de Usuário (User scope): As configurações ficam no seu diretório home ~/.claude/, afetam apenas você e nunca vão para nenhum repositório. Se você mudar para qualquer projeto da empresa, essas configurações vão com você.

Um exemplo comum de uso: coloque "respostas em português" ou "qual prefixo usar nas mensagens de commit", que são preferências estritamente pessoais, no CLAUDE.md de nível de usuário em ~/.claude/ — dessa forma, em qualquer projeto que você abrir, o Claude seguirá seus hábitos. Enquanto "este projeto usa pnpm e não npm", que é um fato do projeto, escreva no ./CLAUDE.md de nível de projeto, commitado para toda a equipe. Hábitos pessoais e normas de projeto, desde o início, vão em dois lugares diferentes, o que poupa dores de cabeça mais tarde.

💡 Resumo em uma frase: O Claude Code tem "duas casas" — ./.claude/ no projeto (acompanha o projeto, vai para o git, compartilhado com a equipe) e ~/.claude/ no diretório home (acompanha você, não vai para o git, afeta apenas você).

---

02 Abrindo o .claude/ de nível de projeto: o que há lá dentro

Agora vamos olhar o que há na pasta ./.claude/ no projeto. Um projeto em uso terá mais ou menos esta estrutura:

your-project/
├── CLAUDE.md                ← Manual do projeto (também pode ficar em .claude/CLAUDE.md)
├── CLAUDE.local.md          ← Suas preferências pessoais no projeto (vai no .gitignore)
├── .mcp.json                ← Configuração compartilhada de servidores MCP (vai no git)
└── .claude/
    ├── settings.json        ← Configuração compartilhada: permissões, hooks, modelos padrão
    ├── settings.local.json  ← Suas substituições de configuração pessoal (automaticamente no gitignore)
    ├── commands/            ← Comandos de barra personalizados, cada .md é um comando /
    ├── rules/               ← Regras modulares do projeto (separadas do CLAUDE.md)
    ├── skills/              ← Habilidades: fluxos de trabalho chamáveis por / ou automaticamente pelo Claude
    └── agents/              ← Subagentes: assistentes especializados com contextos independentes

Vou falar sobre o que cada um faz, mas este artigo apenas indica "o que é e quem o gerencia", os detalhes de uso terão artigos específicos:

CLAUDE.md —— Manual do projeto. O primeiro arquivo que o Claude lê toda vez que entra no projeto. O que é o projeto, como rodar, que convenções existem, tudo fica aqui. Ele e o .claude/settings.json têm uma diferença fundamental: o CLAUDE.md é um "guia" para o Claude ler (ele tenta seguir, mas não é uma restrição rígida), enquanto o settings.json é a "configuração" que o Claude Code impõe.

A documentação oficial menciona um detalhe: o CLAUDE.md pode ficar na raiz do projeto ou em .claude/CLAUDE.md — este último ajuda a manter a raiz mais limpa.

CLAUDE.local.md —— Suas preferências pessoais no projeto. Sobreposto ao CLAUDE.md, contém instruções relevantes apenas para você, como "meu banco de dados local está na porta 5433". Deve ser adicionado manualmente ao .gitignore (escolher a opção pessoal ao rodar /init adiciona para você).

settings.json —— Centro de configurações compartilhado da equipe. Controla se o Claude pode ou não executar certas ações (permissões), quando rodar seus scripts (hooks), e permite definir qual modelo usar como padrão neste projeto. Vai no git, é a base de segurança da equipe.

settings.local.json —— Sua substituição de configuração pessoal. No mesmo formato JSON acima, mas aplica-se apenas a você e não é commitado. Se você quiser liberar temporariamente uma permissão sem afetar os colegas de equipe, escreva aqui. Na primeira vez que o Claude Code escreve este arquivo, ele configura automaticamente o git para ignorá-lo — é o arquivo que mencionei no começo que "deveria ter sido usado".

A documentação oficial observa: ele adiciona a regra de ignorar no seu ~/.config/git/ignore global (não no .gitignore do projeto), então você não encontrará essa linha se procurar no .gitignore do projeto. Para que toda a equipe ignore, você precisa adicionar a linha no .gitignore do projeto.

commands/ —— Comandos de barra personalizados. Cada arquivo .md no diretório torna-se um comando /nome-do-arquivo. Salve os comandos que você digita com frequência em um arquivo, e da próxima vez você pode chamá-los digitando /. A equipe oficial unificou os mecanismos de commands/ e skills/, então, para novos comandos, o recomendado é usar skills/ (suporta agrupar arquivos adicionais), enquanto commands/ continua compatível, mas não é o caminho recomendado.

rules/ —— Regras modulares do projeto. Quando o CLAUDE.md ficar muito longo (a recomendação oficial é mantê-lo abaixo de 200 linhas), divida as regras por tema em vários arquivos em rules/, como testing.md, api-design.md.

skills/ —— Habilidades. Cada habilidade é um subdiretório com um SKILL.md dentro. Você pode chamá-la manualmente com /nome-da-habilidade, ou o Claude pode decidir automaticamente se deve usá-la de acordo com a tarefa.

agents/ —— Subagentes. Cada .md define um assistente especializado com uma janela de contexto independente, que não polui a conversa principal. Ideal para trabalho paralelo ou tarefas isoladas.

.mcp.json —— Configuração compartilhada de servidores MCP. Fica na raiz do projeto, ao lado de .claude/. Os servidores MCP (Model Context Protocol) podem ser configurados em dois lugares: este .mcp.json é para commitar no git e compartilhar com a equipe, como ferramentas de banco de dados ou APIs internas; e as configurações pessoais de MCP (como ferramentas que só você usa) ficam em ~/.claude.json e não vão para nenhum repositório. A diferença é: compartilhado no projeto vs uso pessoal privado.

💡 Resumo em uma frase: No .claude/ de nível de projeto, CLAUDE.md e rules/ são "guias" para o Claude, settings.json é a configuração "imposta" pelo Claude Code, e commands/, skills/ e agents/ são "extensões" que você instala nele.

---

03 O mesmo diretório, também existe no ~/.claude/

Esta é a parte que mais confunde os novatos, mas na verdade é a mais simples: os mesmos nomes de diretório acima existem quase da mesma forma no ~/.claude/ de nível de usuário.

commands/, rules/, skills/, agents/, CLAUDE.md, settings.json — todos existem no projeto, e também no ~/.claude/. Há apenas uma diferença:

(No nível de usuário ~/.claude/ também existem diretórios exclusivos que não estão no projeto — themes/, keybindings.json, output-styles/, workflows/, etc., que serão apresentados em artigos separados).

O que está em ~/.claude/ afeta todos os seus projetos; o que está no ./.claude/ do projeto, afeta apenas aquele projeto.

Dois exemplos para você entender:

• Um comando /commit-pt (para gerar mensagens de commit em português), colocado em ~/.claude/commands/ — pode ser usado em qualquer projeto, sem precisar configurar novamente em cada um.
• Mas um comando como "fazer deploy no ambiente de teste da empresa", que claramente é específico de um projeto, vai no .claude/commands/ do projeto, e é commitado para a equipe usar.

Além desses diretórios "gêmeos", há dois arquivos no diretório home ~/ que aparecem apenas no nível de usuário e que você raramente precisa tocar, apenas saiba quais são:

Arquivo / Diretório	Onde fica	O que é	Você precisa gerenciar?
~/.claude.json	Diretório home	Estado do aplicativo: sessão OAuth, temas, servidores MCP pessoais, histórico de confiança de projetos e preferências de UI	Quase nunca toca, usa /config para alterar
~/.claude/projects/	Nível de usuário	Histórico de sessões de cada projeto; a memória automática fica no subdiretório <projeto>/memory/	Não precisa escrever, ele mesmo gerencia

Vou falar mais sobre a memória automática (auto memory): ela e o CLAUDE.md são duas coisas diferentes. O CLAUDE.md contém instruções que você escreve para o Claude; a memória automática são notas que o Claude escreve para ele mesmo (como comandos de build que ele descobriu, ou problemas que ele encontrou), salvas em ~/.claude/projects/<projeto>/memory/ e reutilizadas entre sessões. Não confunda: um você escreve, o outro ele escreve.

💡 Resumo em uma frase: Os diretórios commands/ e skills/ existem em nível de projeto e de usuário, a diferença é se "gerencia um projeto" ou "gerencia todos os seus projetos"; ~/.claude.json e ~/.claude/projects/ são exclusivos de usuário e você quase não toca.

---

04 O que vai para o git, e o que nunca deve ser commitado

Esta seção é a mais prática, o problema do vazamento de chave do início aconteceu aqui. A regra de ouro: arquivos com "local" ou chaves/senhas NUNCA vão para o git.

Por que uns vão e outros não? A lógica é simples — o que for compartilhado com a equipe deve ser commitado, o que for só para você ou para sua máquina, não.

Analogia: Coisas do arquivo do projeto devem ser registradas, itens da gaveta da sua mesa não precisam ser entregues.

Vamos classificar os arquivos comuns do projeto por "deve commitar", siga esta tabela e você não errará:

Arquivo / Diretório	Vai pro git?	Por quê
CLAUDE.md	✅ Commita	Manual do projeto compartilhado
.claude/settings.json	✅ Commita	Base de permissões / configurações da equipe
.claude/commands/*.md	✅ Commita	Comandos padronizados reutilizados pela equipe
.claude/rules/*.md	✅ Commita	Regras modulares da equipe
.claude/skills/, .claude/agents/	✅ Commita	Habilidades e subagentes da equipe
.claude/settings.local.json	❌ Não commita	Substituições pessoais; o Claude Code já coloca no gitignore
CLAUDE.local.md	❌ Não commita	Preferências de projeto pessoal; você precisa adicionar no .gitignore
Qualquer arquivo com chaves / tokens / senhas	❌ NUNCA commita	Uma vez no histórico, vaza para sempre

Alguns lembretes práticos:

O settings.local.json já é ignorado automaticamente. Oficialmente, quando o Claude Code cria este arquivo, ele automaticamente configura o git para ignorá-lo. Para permitir permissões temporárias locais, este é o lugar mais seguro.

Você tem que colocar o CLAUDE.local.md no .gitignore. Diferente do settings.local.json, ele não é ignorado automaticamente — usar a opção "pessoal" no /init faz isso para você, caso contrário, não esqueça de adicionar a linha manualmente.

Senhas NUNCA devem ser colocadas como texto puro nos arquivos de configuração. A recomendação oficial é usar variáveis de ambiente, por exemplo ${GITHUB_TOKEN} no lugar do token real — quando o Claude Code inicia, ele lê do ambiente shell e o token não fica no arquivo. Cumpra essa regra à risca.

💡 Resumo em uma frase: Arquivos da equipe (CLAUDE.md, settings.json, commands/, etc.) vão para o git; arquivos com "local" e qualquer arquivo com senha nunca vão — settings.local.json é ignorado automaticamente, CLAUDE.local.md precisa que você o ignore.

---

05 Configurações conflitantes, de quem ouvir: Uma imagem esclarece a prioridade

Você já deve ter pensado: e se o settings.json do usuário e o settings.json do projeto configuram a mesma coisa, qual vale?

A prioridade oficial é assim (do mais alto para o mais baixo):

Managed (Gerenciado pela organização, mais alto, inquestionável)
  ↓
Argumentos de linha de comando (como --permission-mode, válido apenas para a sessão atual)
  ↓
Local (settings.local.json)
  ↓
Project (settings.json do projeto)
  ↓
User (usuário ~/.claude/settings.json, o mais baixo)

Dica de memorização: O mais "específico" e mais "próximo à operação atual" tem maior prioridade. A organização > linha de comando temporária > projeto local > projeto compartilhado > o seu padrão global.

Esta imagem mostra as duas árvores lado a lado: à esquerda, o nível de projeto ./.claude/ (acompanha o projeto, entra no git para compartilhar com a equipe), à direita, o nível de usuário ~/.claude/ (acompanha você e gerencia todos os seus projetos) — lembre-se de qual árvore gerencia o quê, e não terá problemas com as configurações.

Mas tem uma armadilha muito fácil de cair aqui, que deve ser destacada — nem todas as configurações seguem a lógica de "substituição" (overwrite):

Tipo de Configuração	Quando ocorre em múltiplos escopos	Exemplo
Valor escalar (um único valor)	Pega o mais específico e substitui	model: se o projeto definir, usa o do projeto
Valor array (listas)	Mesclagem (merge) entre escopos, não substitui	permissions.allow: soma dos do usuário + do projeto + locais

É muito fácil errar aqui: eu mesmo caí nessa — no settings.json de nível de usuário, eu bloqueei (deny) um comando, pensando que ele estaria globalmente desabilitado, mas quando mudei de projeto, ele continuou a executar. Não entendi nada na hora. Depois entendi que regras de permissão são mescladas, não substituídas; se o projeto permitiu (allow), ela será mesclada com a regra do usuário. Então não espere proibir tudo de uma vez pelo nível de usuário, você precisa entender a regra de mesclagem.

💡 Resumo em uma frase: A prioridade, da mais alta para a mais baixa, é Managed → Linha de comando → Local → Project → User; mas lembre-se — valores como model são "substituídos", enquanto permissions.allow são "mesclados".

---

06 Prática: Veja com seus próprios olhos as duas camadas de diretório

Olhar imagens não é tão bom quanto ver com seus próprios olhos. Os comandos abaixo apenas leem, não escrevem, são muito seguros, use-os para entender como as "duas casas" funcionam.

Passo 1: Veja seu diretório home ~/.claude/ no nível de usuário

Abra o terminal, digite (Mac / Linux):

ls -a ~/.claude

No Windows PowerShell use:

dir $HOME\.claude

Resultado Esperado: Você verá settings.json, projects e possivelmente commands, skills, etc. — dependendo do quanto você usou o Claude Code. Se algo for listado, o nível de usuário existe e está em vigor.

Passo 2: Veja o .claude/ de nível de projeto em um projeto

Use cd para entrar em qualquer projeto onde você rodou o Claude Code (se não tiver um, volte ao artigo anterior e use /init para criar um), então:

ls -a .claude

Resultado Esperado: No mínimo você verá o settings.local.json (se você aprovou permissões antes), possivelmente também settings.json. Isso é o "arquivo do projeto", separado do diretório home.

Passo 3: Confirme que settings.local.json foi realmente ignorado pelo git

No projeto (que precisa ser um repositório git), digite:

git check-ignore .claude/settings.local.json

Resultado Esperado: O terminal imprime o caminho do arquivo (.claude/settings.local.json), provando que foi ignorado — exatamente o que o Claude Code faz automaticamente. Se nada for impresso, significa que não foi ignorado e você deveria adicionar essa linha no .gitignore.

Passo 4 (Opcional): Dê uma olhada no manual do projeto

cat CLAUDE.md

(No Windows PowerShell use type CLAUDE.md)

Resultado Esperado: Imprime o conteúdo gerado com /init no artigo anterior. Esse é o primeiro arquivo que o Claude lê ao entrar no projeto, e agora você sabe onde ele fica.

⚠️ Lembrete: git check-ignore só funciona dentro de um repositório git. Se o projeto ainda não tem git init, o comando acusará fatal: not a git repository, transforme em um repositório git primeiro.

💡 Resumo em uma frase: ls -a ~/.claude para ver nível de usuário, ls -a .claude para ver nível de projeto, git check-ignore .claude/settings.local.json para verificar arquivo ignorado — três comandos de leitura fáceis.

---

07 Conclusão

Neste artigo cobrimos todo o "inventário" de pastas e arquivos do Claude Code em um projeto. Resumindo:

O que você deve lembrar	O que é
Duas casas	Projeto ./.claude/ (acompanha o projeto, vai pro git) + Home ~/.claude/ (acompanha você, não vai pro git)
Guia vs Configuração	CLAUDE.md / rules/ são guias para o Claude; settings.json são configurações aplicadas à força
Diretórios gêmeos	commands/, skills/, agents/ existem no nível de projeto e usuário, mudando se afetam um ou todos
Linha vermelha do git	Aqueles com "local" ou senhas, nunca commitam; settings.local.json é ignorado pelo sistema automaticamente
Prioridade	Managed → Linha de comando → Local → Project → User; substitui para escalares, mescla para arrays

Você agora deve ser capaz de: Abrir qualquer projeto, ver um arquivo dentro de .claude/ e saber para que serve, de quem é a responsabilidade, se deve ou não ir pro git; e também saber qual configuração vence em um conflito. Este mapa é a base para todos os artigos seguintes — quando falarmos sobre configurar o settings.json a fundo, como escrever bons CLAUDE.md, como criar habilidades ou subagentes, você já saberá exatamente onde eles devem ir.

---

O próximo artigo é o 14 "Interface e Atalhos" — agora que você entende a estrutura de pastas "estática", é hora de se familiarizar com o "painel de controle" do Claude Code. O próximo artigo o levará a conhecer cada parte da interface, além de praticar os atalhos de teclado mais úteis, para que você os digite com rapidez e confiança.

---

Leitura Recomendada

• Hooks: Acionamento automático de ações
• Gerenciamento de Contexto: Não o deixe "esquecer" nem estourar os tokens
• Integração com JetBrains