Configuração do Claude Code: escopo pessoal ou do projeto, qual escolher?

Fala aí, beleza? Sabe aquele momento em que tu monta um setup lindo no Claude Code, com subagente, skill, MCP, tudo redondo, manda pro colega e na máquina dele simplesmente não acontece NADA?

Quase sempre o problema não é a configuração, é o escopo dela

O escopo do Claude Code é o que separa o que é seu do que é do repositório: tem configuração que mora na sua máquina e te acompanha em todo projeto, e tem configuração que mora dentro do repo e viaja no git junto com o código

Escolher errado dá nos dois lados: ou tu compartilha coisa que ninguém deveria herdar, ou tu guarda pra você aquilo que o time inteiro precisava ter

Bora destrinchar isso

Os quatro escopos de configuração e onde cada arquivo vive

O Claude Code lê settings em quatro escopos de arquivo, e cada um tem um dono diferente

A regra de endereço é simples: o que é de escopo global fica em ~/.claude/ e vale pra todos os projetos, e o que é de escopo de projeto fica no repositório, dentro de .claude/

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 116 aulas
• 4 projetos
• 9h 23min

Conhecer formação

As exceções ficam na RAIZ do repositório: CLAUDE.md, .mcp.json e .worktreeinclude

E a ordem de força das settings, do mais forte pro mais fraco, é essa: managed settings, depois argumentos de linha de comando, depois .claude/settings.local.json, depois .claude/settings.json e por último ~/.claude/settings.json (a documentação oficial de settings tem a lista completa das chaves)

Um aviso de nomenclatura antes que tu se perca mais pra frente: esse nível mais alto aparece como Managed aqui nos settings, mas a documentação de skills chama o mesmo topo da fila de enterprise

Nomes diferentes, mesmo escopo: o da política da organização

Repara numa coisa que confunde muita gente: o arquivo pessoal do seu home é o MAIS FRACO da fila, não o mais forte 🙂

Managed settings não são sobrescritas por usuário, projeto, local nem por --settings, com exceções documentadas: pra algumas chaves sensíveis à segurança, um valor mais restritivo vindo de um nível inferior continua valendo

O que você precisa antes de escolher o escopo

Antes de sair criando arquivo, três coisas precisam estar claras na tua cabeça

• Repositório sob controle de versão: as project settings só alcançam o clone do colega e a sessão em nuvem se o arquivo for commitado. Sem commit, aquilo é config local com nome bonito
• Diretório confiado: configuração de projeto não passa a valer sozinha. Ao entrar num diretório ainda não confiado, o Claude Code lista no prompt de confiança as allow rules, os additional directories, os hooks e os helper commands que aquelas settings ativariam
• Saber olhar o estado atual: o comando /permissions abre um diálogo com todas as regras de permissão E de qual settings.json cada uma veio

Esse último é o mais subestimado da lista

Antes de mexer em qualquer coisa, roda /permissions e olha a origem de cada regra: boa parte dos "bugs" de configuração morre aí mesmo

Como configurar o escopo pessoal, que segue a sua máquina

Esse é o setup que é SEU: ninguém do time herda nada daqui

Quase tudo nesta lista te acompanha em todo projeto que tu abrir, e no fim tem um caso que também é só teu, porém fica preso a um repositório só (já chego nele)

1. Settings pessoais no ~/.claude/settings.json

{
  "permissions": {
    "allow": ["Bash(npm run test:*)"]
  }
}

Esse arquivo vale em todos os seus projetos, mas lembra da fila de precedência: ele perde pra project e pra local

2. Servidor MCP com escopo de usuário

claude mcp add --scope user nome-do-servidor

Com --scope user a configuração é gravada no ~/.claude.json e vale pra todos os seus projetos

O erro comum deste passo: esquecer que o escopo padrão do MCP é o local, que fica preso ao projeto onde foi adicionado. Se tu não passou a flag, aquele servidor não vai te seguir pra lugar nenhum

3. Subagentes pessoais em ~/.claude/agents/

Qualquer subagente que tu jogar aí fica disponível em todos os projetos

4. Skills pessoais em ~/.claude/skills/

Mesma lógica: skill pessoal vale em todo projeto

5. Memória pessoal no ~/.claude/CLAUDE.md

Aqui vai preferência de estilo, forma de responder, aquele jeitão que tu gosta que ele trabalhe, valendo em todos os projetos

6. Preferência privada de UM projeto no CLAUDE.local.md

Esse é o tal caso que foge da regra da seção: continua sendo só teu, mas não te segue pra lugar nenhum

Ele fica na raiz do projeto, carrega junto do CLAUDE.md e serve pras suas preferências privadas naquele repositório específico

Tome cuidado! Ele precisa ir pro .gitignore, senão a tua preferência pessoal vira preferência do time sem ninguém pedir

7. Plugin com escopo user

O escopo user instala o plugin pra você, em todos os seus projetos. Se tu quer o plugin só naquele repositório e só pra você, o escopo é o local

O erro comum desta seção inteira: achar que o .claude/settings.local.json é o "seu arquivo pessoal"

Não é. Ele é seu, mas é preso a UM repositório só. O arquivo que vale em todos os projetos é o ~/.claude/settings.json

E tem uma pegadinha boa nesse local: quando o próprio Claude Code escreve o .claude/settings.local.json pela primeira vez, ele adiciona o arquivo aos git excludes globais

Se VOCÊ criar o arquivo na mão, esse ignore automático não acontece e tu precisa botar no .gitignore por conta própria

Já pensou commitar sem querer o teu arquivo de ajustes locais no repo do time? Pois é…

Como configurar o escopo de projeto para o time inteiro herdar

Agora o outro lado: o setup que nasce junto com o repositório e que qualquer pessoa herda no git clone

Se tu tá montando isso do zero num projeto novo, vale dar uma olhada no fluxo do primeiro projeto ao deploy antes, porque escopo de projeto é uma decisão bem mais confortável quando o fluxo já tá desenhado

1. .claude/settings.json commitado

Esse é o coração do setup compartilhado. Sem commit, ele não existe pro time

2. Servidor MCP no escopo do repositório

claude mcp add --scope project nome-do-servidor

Com --scope project a configuração é gravada no .mcp.json do repositório, feito justamente pra compartilhar com o time

3. Subagentes versionados em .claude/agents/

Subagente de review, de migração, de documentação, o que o time inteiro precisa ter

O Claude Code varre .claude/agents/ recursivamente, então subpasta é permitida: agents/review/ e agents/research/ funcionam normal

O erro comum deste passo: achar que o caminho define o nome do subagente. Não define. A identidade vem do campo name do frontmatter, e a subpasta não muda como ele é invocado

4. Skills de projeto em .claude/skills/

Skill que é regra da casa mora aqui

5. Comandos custom em .claude/commands/

.claude/commands/deploy.md

Esse arquivo cria o /deploy, pelo nome do arquivo. Simples assim

6. Plugins no escopo project

Com --scope project a instalação grava em enabledPlugins no .claude/settings.json, que é o arquivo que todo colaborador do repositório recebe

{
  "enabledPlugins": {
    "nome-do-plugin@nome-do-marketplace": true
  }
}

Esse formato "plugin-name@marketplace-name": true/false também pode ser configurado no ~/.claude/settings.json, no .claude/settings.local.json e no managed-settings.json, dependendo de quem tu quer atingir

7. extraKnownMarketplaces declarada no repositório

Essa setting é tipicamente usada no nível do repositório pra garantir que os membros do time tenham acesso às fontes de plugin necessárias

Sem ela, tu ativa um plugin que o colega não consegue nem alcançar

8. CLAUDE.md do projeto como memória compartilhada

Regra de arquitetura, convenção de commit, o que não pode ser mexido: tudo isso é memória de projeto e é compartilhada com o time

O erro comum desta seção: esquecer o commit e achar que o time já recebeu

O segundo erro comum, mais sorrateiro: assumir que permissions.additionalDirectories já vale pra todo mundo só porque tá no arquivo commitado

Não vale. Isso só passa a valer depois que CADA pessoa do time confia na pasta

Quem vence quando o mesmo nome existe em dois escopos

Aqui mora a parte que mais pega gente desprevenida: a ordem de precedência NÃO é a mesma pra todo tipo de recurso

Lê a linha de skills de novo, porque ela é o oposto da de subagentes

No subagente, o projeto manda mais que você. Na skill, você manda mais que o projeto

Ou seja: se existe uma skill de mesmo nome em ~/.claude/skills/ e em .claude/skills/, a que roda é a PESSOAL, e o time inteiro pode estar rodando uma coisa enquanto tu roda outra sem perceber 😅

E a memória segue uma lógica diferente de todas: os níveis somam em vez de substituir, e em conflito direto a memória mais específica prevalece sobre a mais ampla

Qual escopo escolher em cada situação real

Dá pra decidir quase tudo com uma pergunta: isso é meu, do repositório, ou é temporário?

Atalho e estilo de trabalho seu: escopo de usuário, em ~/.claude/. Aquele jeitão de responder, o teu subagente favorito, a skill que tu usa em tudo

Regra de arquitetura, comando de deploy e subagente de review que todo mundo precisa: escopo de projeto, commitado. Isso é parte do repositório tanto quanto o package.json

Credencial, caminho de máquina e experimento que ninguém deveria herdar: escopo local, no .claude/settings.local.json, fora do git

Política que a organização não quer que ninguém sobrescreva: managed (o tal enterprise da doc de skills). É o único nível que não é sobrescrito por usuário, projeto, local nem por --settings

Marketplace de plugin que o time inteiro precisa alcançar: extraKnownMarketplaces declarada no repositório

Preferência sua dentro de um projeto do time, sem poluir o CLAUDE.md compartilhado: CLAUDE.local.md na raiz, com entrada no .gitignore

Esse último é ULTRA útil quando tu cai de paraquedas num repo que já existia e precisa anotar tuas descobertas pra você mesmo

É o mesmo espírito de quando tu usa o Claude pra entender um projeto legado: as tuas anotações de navegação são suas, o contrato de arquitetura é do time

Configurei no repositório e não funcionou para o time: o que checar

Bora pros sintomas clássicos, com causa e solução

O colega clonou e nada mudou:

Causa: o arquivo não foi commitado. Project settings só alcançam o clone do colega e a sessão em nuvem se o arquivo estiver no controle de versão

Solução: git status na pasta .claude/ e commita o que tá faltando

As allow rules e os additional directories do repo não valem pra ninguém:

Causa: o diretório ainda não foi confiado por aquela pessoa

Solução: ao entrar num diretório novo, o prompt de confiança lista as allow rules, os additional directories, os hooks e os helper commands que aquelas settings ativariam. Enquanto cada pessoa não aceitar, permissions.additionalDirectories não passa a valer pra ela

O hook do subagente de projeto não dispara:

Causa: hooks de frontmatter em subagente de projeto só rodam DEPOIS do aceite do diálogo de confiança da pasta de onde o arquivo do agente veio

Solução: aceitar o workspace trust dialog daquela pasta, que é pré-requisito

A skill do projeto é ignorada só na sua máquina:

Causa: existe uma skill pessoal de mesmo nome em ~/.claude/skills/, e a ordem é enterprise (aquele topo Managed), pessoal, projeto, plugin

Solução: renomear uma das duas, ou aceitar conscientemente que a pessoal manda

A skill custom substituiu a embutida, mas chamando pelo alias não roda:

Causa: uma skill code-review em .claude/skills/ substitui a /code-review embutida, porém digitar o alias embutido /review nunca roda a sua skill

Solução: chamar pelo nome cheio e avisar o time disso, senão vira debate de fantasma

Permissão negada mesmo com a regra de allow no lugar certo:

Causa: a ordem de avaliação é deny, depois ask, depois allow. Um deny em qualquer camada mata o teu allow

Outra causa: um hook que sai com código 2 interrompe a chamada da ferramenta ANTES das regras de permissão serem avaliadas

Solução: /permissions pra ver de qual settings.json cada regra veio, e /hooks pra navegar os hooks configurados por evento, abrindo os matchers e os detalhes de cada handler

Como prevenir tudo isso:

Três comandos resolvem a maior parte da investigação de dentro da própria sessão

• /permissions mostra todas as regras e o arquivo de origem de cada uma (e as alterações passam a valer já na próxima chamada de ferramenta, mesmo dentro do mesmo turno)
• /hooks abre um navegador somente leitura dos hooks, com a contagem por evento
• /memory abre e navega pelos arquivos de memória sem sair da sessão

E guarda essa: o claudeMdExcludes pode ser configurado em qualquer camada de settings (user, project, local e managed policy), e os arrays SOMAM entre as camadas em vez de substituir

Então se algo do CLAUDE.md sumiu misteriosamente, provavelmente tem exclusão vindo de outra camada que tu nem olhou

Conclusão: decida o escopo antes de escrever o arquivo

A regra de bolso cabe em três linhas

É seu e vale em tudo? Vai pra ~/.claude/

É do repositório e o time precisa herdar? Vai pra .claude/, commitado

É temporário, sensível ou só teu naquele projeto? Vai pro local, fora do git

O resto é detalhe de precedência, e a tabela lá de cima resolve: settings e subagentes dão força pro projeto, skills dão força pra você, MCP dá força pro local e memória soma tudo com a mais específica ganhando no conflito

Próximo passo prático: abre o projeto que tu tá tocando hoje e roda /permissions

Olha de onde vem cada regra e move o que estiver no escopo errado, principalmente aquilo que tá no teu arquivo pessoal mas devia ser do repositório inteiro

É um trampo rápido que economiza um monte de "mas na minha máquina funciona" 😀

até o próximo post!