O Que Vive na Sua Pasta .claude

Sua pasta .claude guarda dois tipos diferentes de coisas: instruções que são carregadas no contexto do Claude no início de cada sessão (CLAUDE.md, rules/, skills/, agents/) e configurações que governam como a ferramenta se comporta (settings.json, hooks, servidores MCP). Ambos os tipos estão divididos entre um diretório de projeto que você versiona e um diretório ~/.claude na sua pasta home que você nunca versiona.

A pasta também tende a crescer sozinha. Aprovar um prompt de permissão grava um arquivo que você não criou, o /init deixa um CLAUDE.md, e um pull request pode acabar carregando um .claude/settings.local.json cheio de regras de permissão de um único desenvolvedor.

Este é um tour arquivo por arquivo: o que cada caminho faz, qual arquivo prevalece quando dois deles definem a mesma coisa, e um veredito por arquivo sobre se ele pertence ou não ao repositório.

Onde Ficam os Dois Locais .claude?

O Claude Code lê duas raízes .claude. Uma fica no projeto, viaja com o repositório e é destinada a toda a equipe; a outra, ~/.claude na sua pasta home, é só sua e o acompanha em todos os projetos da máquina. Essa divisão é a coisa mais útil a se internalizar. A referência de diretórios do Claude Code traça a mesma linha: versione os arquivos do projeto, deixe os da pasta home onde estão. No Windows, a raiz home fica em %USERPROFILE%\.claude, e apontar CLAUDE_CONFIG_DIR para outro lugar move tudo isso.

my-project/
├── CLAUDE.md                    # instructions loaded every session
├── CLAUDE.local.md              # private preferences, gitignored
├── .mcp.json                    # team-shared MCP servers
└── .claude/
    ├── settings.json            # permissions, hooks, env, model defaults
    ├── settings.local.json      # your personal overrides, gitignored
    ├── rules/*.md               # topic-scoped instructions, optionally path-gated
    ├── skills/<name>/SKILL.md   # reusable prompts invoked with /name
    ├── commands/*.md            # single-file prompts, same mechanism as skills
    ├── agents/*.md              # subagent definitions with their own prompt and tools
    ├── workflows/*.js           # workflow scripts saved from /workflows
    ├── output-styles/*.md       # instruction sets that adjust how Claude works
    └── agent-memory/<name>/     # persistent memory for subagents

~/.claude.json                   # app state, OAuth, personal MCP servers
~/.claude/
├── CLAUDE.md                    # your instructions, across every project
├── settings.json                # personal defaults
├── rules/*.md                   # user-level rules, applied to every project
├── keybindings.json             # custom keyboard shortcuts
├── themes/*.json                # custom colour themes
├── plugins/                     # cloned marketplaces and per-plugin data
├── projects/<project>/memory/   # auto memory Claude writes itself
└── .credentials.json            # login credentials

Na prática, dois arquivos absorvem quase toda a edição: CLAUDE.md e settings.json. Todo o resto é opcional.

CLAUDE.md, Imports e Regras Restritas por Caminho

CLAUDE.md é o arquivo que o Claude Code carrega no contexto no início de cada sessão, e ele é lido a partir de quatro locais: política gerenciada (managed policy), ~/.claude/CLAUDE.md, o projeto (./CLAUDE.md ou ./.claude/CLAUDE.md) e ./CLAUDE.local.md para anotações pessoais. A documentação de memória deixa claro que esses arquivos se empilham em vez de competir: cada arquivo que o Claude Code encontra é adicionado ao contexto em sequência, começando na raiz do sistema de arquivos e descendo até o seu diretório de trabalho, e dentro de um mesmo diretório o CLAUDE.local.md entra depois do CLAUDE.md. Um arquivo em um diretório pai é carregado na inicialização; um em um subdiretório espera até que o Claude abra um arquivo lá.

A sintaxe @path/to/file traz outro arquivo, resolvido em relação ao arquivo que o importa, com até quatro níveis de profundidade. Quebrar um arquivo longo em imports organiza tudo sem recuperar nenhum contexto, já que tudo o que ele importa também é expandido na inicialização. O parsing de imports ignora qualquer coisa dentro de crases ou de um bloco delimitado, que é como você cita um caminho nas suas instruções sem trazer o arquivo junto.

Dois limites importam. O número de 200 linhas é uma meta e não um teto: acima disso, um arquivo consome mais contexto e o Claude o segue de forma menos confiável. O teto real é de 4 MiB. O Claude Code carrega um CLAUDE.md até esse tamanho por inteiro e ignora um que ultrapasse.

.claude/rules/*.md é a alternativa modular. Arquivos de regra são descobertos recursivamente, um tópico cada. Dê a uma regra nenhum frontmatter e ela carrega na inicialização, com o mesmo peso de .claude/CLAUDE.md; dê a ela um campo paths e ela fica fora do contexto até o Claude tocar em um arquivo que corresponda ao glob.

---
paths:
  - "src/components/**/*.tsx"
---

Prefer function components with explicitly typed props.
Co-locate the test file beside the component it covers.

Instruções contraditórias entre arquivos são resolvidas arbitrariamente, então não há regra a memorizar aí. Execute /context ou /memory para ver o que realmente foi carregado, e se uma instrução realmente precisa rodar em um ponto fixo, escreva-a como um hook PreToolUse. Um hook roda como um comando de shell em um ponto fixo da sessão, tendo o Claude escolhido fazê-lo ou não.

Onde o AGENTS.md se Encaixa?

Um repositório que já carrega AGENTS.md para outros agentes de codificação não precisa de nada extra: o Claude Code lê esses arquivos por conta própria, sozinhos ou ao lado do CLAUDE.md. Onde o diretório de trabalho e seus pais não têm nenhum CLAUDE.md, é o AGENTS.md que carrega. Quais arquivos carregam é definido em “Project instructions” no /config, e essa configuração só aparece em sessões que conseguem buscar as feature flags da Anthropic, então ela está ausente no Bedrock, Vertex e Foundry.

Para uma sessão que não consegue carregar AGENTS.md, ou quando você quer manter um CLAUDE.md existente, adicione um CLAUDE.md ao lado do AGENTS.md que o importe:

@AGENTS.md

## Claude Code

Run `pnpm typecheck` before proposing any change under `packages/api/`.

Um symlink também funciona quando você não precisa de conteúdo específico para o Claude: ln -s AGENTS.md CLAUDE.md. O Windows não cria um sem privilégios de Administrador ou o Modo de Desenvolvedor, então o import é o caminho mais seguro por lá. Um AGENTS.md lido diretamente não aparece em Memory files no /context ou /memory. Em vez disso, a sessão imprime uma linha “AGENTS.md loaded”.

Não confunda AGENTS.md com CLAUDE.local.md. Este último é o companheiro pessoal e gitignored do CLAUDE.md e não tem nada a ver com interoperabilidade entre ferramentas.

Qual é a Diferença Entre skills/, commands/ e agents/?

Commands e skills rodam sobre o mesmo mecanismo e ambos respondem a /name. A referência de diretórios direciona trabalhos novos para skills/<name>/SKILL.md, porque um diretório de skill pode agrupar arquivos de apoio junto das instruções, enquanto um command é um único arquivo markdown. Um diretório commands/*.md existente continua funcionando. Para saber como estruturar uma skill para trabalho de frontend, veja nosso guia sobre Claude Code skills para fluxos de trabalho de frontend.

agents/*.md guarda definições de subagentes, cada uma com seu próprio prompt e lista de ferramentas. Ambos os diretórios existem no escopo de projeto e sob ~/.claude, e ambos são detectados pela sua localização em vez de por registro em um arquivo de configuração.

Precedência de Configuração do Claude Code: settings.json Contra settings.local.json

settings.json é o arquivo compartilhado do projeto e settings.local.json é sua sobrescrita pessoal por projeto, e quando ambos definem a mesma chave o arquivo local vence. A referência de settings apresenta cinco níveis de precedência, do mais alto para o mais baixo: managed settings, argumentos de linha de comando, .claude/settings.local.json, .claude/settings.json e ~/.claude/settings.json. O JSON que você passa para --settings se encaixa logo abaixo dos managed settings e acima dos seus três arquivos próprios.

A parte que pega as pessoas de surpresa é que nem toda chave segue essa pilha. Chaves de lista como permissions.allow, permissions.ask e permissions.deny se combinam entre escopos em vez de se substituírem, então uma regra de deny no settings.json compartilhado de um colega ainda morde mesmo quando seu arquivo local permite a mesma ferramenta. Quatro chaves de modelo são a exceção a essa combinação. fallbackModel é uma cadeia ordenada, então o arquivo de maior precedência que a define fornece o valor inteiro. modelPicker funciona da mesma forma, exceto que lê apenas managed settings, --settings e user settings, ignorando a chave em arquivos de projeto e locais (Claude Code v2.1.242 e posterior). Uma lista availableModels gerenciada se aplica como está e seus próprios acréscimos são descartados, embora entre arquivos de usuário, projeto e local esses arrays ainda se combinem. modelSettings é resolvido um modelo de cada vez.

Arquivo compartilhado:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "cleanupPeriodDays": 30,
  "permissions": {
    "deny": ["Read(./.env)"]
  }
}

Arquivo local:

{
  "cleanupPeriodDays": 7,
  "permissions": {
    "allow": ["Bash(npm run lint)"]
  }
}

A sessão resolvida usa cleanupPeriodDays: 7, porque o arquivo local supera o compartilhado em uma chave escalar. Ambas as regras de permissão permanecem ativas: npm run lint roda sem prompt e a leitura de .env continua bloqueada. Arquivos de settings são JSON estrito: adicione um comentário // ou uma vírgula final e o arquivo falha ao ser interpretado. A linha $schema te dá autocomplete no editor, e como o schema publicado às vezes fica atrás dos lançamentos mais recentes da CLI, um aviso sobre uma chave documentada na semana passada diz mais sobre o schema do que sobre o seu arquivo. Execute /status para confirmar quais arquivos de settings foram carregados.

Onde Ficam os Hooks e os Servidores MCP?

Hooks não são arquivos separados. Eles vivem sob a chave hooks no settings.json, em qualquer escopo em que você queira que se apliquem, e uma edição entra em vigor sem reiniciar a sessão. Servidores MCP se dividem por público: .mcp.json fica na raiz do projeto, acompanha o repositório e é a lista compartilhada da equipe. Servidores MCP pessoais vivem em ~/.claude.json, que também armazena estado da aplicação, dados OAuth e servidores de escopo local indexados por caminho de projeto, então trate-o como estado de máquina e não como um arquivo de configuração que você edita à mão.

O Que Versionar e o Que Colocar no gitignore

Na primeira vez que o Claude Code escreve esse arquivo local em um repositório que ainda não o ignora, ele acrescenta **/.claude/settings.local.json aos seus global git excludes. Essa escrita é o que acontece quando você responde “Yes, and don’t ask again” a um prompt de permissão. Crie o arquivo à mão e nada é adicionado por você, então torne a entrada explícita:

# Claude Code personal config
# settings.local.json is usually auto-excluded already; this covers hand-created files
.claude/settings.local.json
CLAUDE.local.md

As configurações compartilhadas também são o que as sessões na nuvem enxergam, já que essas rodam contra um clone novo. Arquivos de usuário e locais ficam na sua máquina e nunca chegam até elas.

Tudo Sob ~/.claude É Texto Puro

Transcrições de sessão, saída de ferramentas, texto colado e o log de prompts history.jsonl vão todos parar no disco como texto puro, com as permissões de arquivo sendo a única coisa à frente deles. Se um comando imprimiu um token durante uma sessão, esse token está guardado em uma transcrição. O .credentials.json guarda suas credenciais de login e sobrevive à limpeza de retenção, que de outra forma remove arquivos elegíveis assim que ultrapassam o cleanupPeriodDays: 30 dias por padrão, 1 no mínimo, e 0 recusado como valor inválido.

A pasta é menor do que parece depois que você a organiza: instruções se concatenam, settings obedecem à precedência, permissões se combinam, e o diretório home nunca entra no controle de versão. Abra o seu próprio .claude/ e compare com a árvore acima, apague os arquivos que ninguém escreveu de propósito, e adicione o bloco de duas linhas no .gitignore antes que o próximo pull request faça isso por você.

Perguntas Frequentes

Preciso aprovar servidores MCP que chegam em um .mcp.json versionado por um colega?

Sim. Em uma sessão interativa, o Claude Code pergunta antes de usar qualquer servidor de escopo de projeto declarado em um .mcp.json, e cada desenvolvedor responde por si em vez de uma única resposta valer para todo o repositório. Execute claude mcp reset-project-choices para limpar essas respostas. Contextos não interativos não conseguem exibir o prompt: execuções de claude -p, sessões do Agent SDK e sessões na nuvem carregam servidores de escopo de projeto sem perguntar, então use disabledMcpjsonServers para bloquear um servidor em todos os modos de permissão.

Como sobrescrevo uma configuração do Claude Code para uma única sessão sem editar um arquivo?

Passe --settings com o caminho para um arquivo JSON ou uma string JSON inline. Ele fica abaixo dos managed settings e acima dos seus arquivos de usuário, projeto e local. Algumas chaves também têm sua própria flag ou variável de ambiente, e qual delas vence é decidido chave a chave: --model e /model superam ANTHROPIC_MODEL, enquanto CLAUDE_CODE_EFFORT_LEVEL supera /effort.

Editar o settings.json no meio da sessão tem efeito imediato?

Algumas chaves recarregam na hora e outras são lidas apenas uma vez no início da sessão, então uma edição pode parecer ignorada até a próxima inicialização. Permissões e hooks recarregam sem reiniciar, enquanto model, effortLevel e modelSettings são lidos uma vez no início. Uma mudança de outputStyle se aplica a partir da sua próxima mensagem desde a v2.1.251, embora no terminal um arquivo de estilo que você cria ou edita no meio da sessão só seja detectado após um reinício. Se um valor ainda parecer errado depois de reiniciar, execute /status e verifique a precedência: um arquivo de escopo mais alto como .claude/settings.local.json pode estar definindo a mesma chave.

O que eu perco se apagar a pasta projects sob ~/.claude?

Apagar projects/ remove transcrições retidas e pode impedir que você retome sessões passadas, embora novas sessões não sejam afetadas. O comando claude project purge é a alternativa direcionada: ele apaga as transcrições, a memória automática, as tarefas e as entradas de histórico de arquivos de um projeto, as linhas de prompt correspondentes em history.jsonl e a entrada desse projeto em ~/.claude.json. Tanto shell-snapshots/ quanto backups/ são mantidos onde estão. Passe -i para percorrer o plano de exclusão passo a passo.