Esta nota é uma aula sobre gestão de configuração no Claude Code e nas aplicações que usam Claude. A pergunta que ela responde é simples de enunciar e trabalhosa de cumprir: como fazer com que o comportamento do Claude seja previsível, versionado e igual para todas as pessoas do time? Ao terminar, você consegue dizer onde cada instrução mora, por que algumas configurações entram no git e outras não, como uma mudança chega a produção sem surpresas e o que revisar num pull request que mexe em configuração.

A aula parte do zero. Não pressupõe que você já saiba o que é um arquivo de instrução nem como o Claude Code lê configurações. Os caminhos de arquivo e os nomes de campos vêm da documentação oficial do Claude Code, consultada em 18 de outubro de 2026. Essa ferramenta muda com frequência, então confira a documentação antes de copiar um campo. Onde a documentação não diz algo, a aula avisa.

Esta aula cobre a gestão de configuração do Claude Code e das aplicações. O peso é baixo, mas as perguntas costumam ser objetivas: qual arquivo carrega qual instrução, o que vai no git e o que fica local, e o que muda entre ambientes. Quem entende o mecanismo acerta sem decorar.

Mapa da aula

Pré-requisito: saber o que é um arquivo de configuração e usar git no dia a dia. Ajuda ter lido Agents, porque subagents são um dos tipos de arquivo que esta aula coloca sob controle de versão.

Parte 1: instruções e configurações

1. O que é gestão de configuração

Pense em uma cozinha de restaurante. O chef não cozinha sozinho, e cada cozinheiro tem o próprio jeito de temperar. Para que o prato saia igual de um turno para outro, o restaurante escreve a receita, guarda a receita num lugar que todo mundo consulta e troca a receita com registro quando muda um ingrediente. Se cada cozinheiro seguisse a própria memória, o cliente que volta na terça teria um prato diferente do que comeu na segunda, e ninguém saberia dizer por quê.

Gestão de configuração é essa disciplina aplicada ao comportamento de um sistema. Em vez de receitas, temos instruções e parâmetros: o que o Claude deve saber sobre o projeto, quais ações ele pode executar sem perguntar, qual modelo usar, quais ferramentas externas estão conectadas. Gerenciar isso significa três coisas. Primeiro, saber onde cada parâmetro está escrito. Segundo, guardar a versão escrita no mesmo lugar que o código, para que mudanças tenham histórico e dono. Terceiro, garantir que a mesma versão rode em cada máquina e em cada ambiente, ou que as diferenças sejam deliberadas e visíveis.

O porquê é prático. Um modelo de linguagem não tem memória entre sessões. Cada conversa do Claude Code começa com uma janela de contexto vazia, e tudo o que o Claude precisa saber sobre o projeto tem de chegar por algum arquivo ou pela própria conversa. Se essa informação estiver só na cabeça de uma pessoa, ou só no histórico de um chat, o comportamento do Claude depende de quem abriu a sessão. A configuração versionada transforma esse conhecimento em algo que o time compartilha, revisa e reverte.

A figura mostra as camadas de instrução e configuração que um time encontra, do que a empresa impõe até o que fica só na sua máquina. Cada caixa indica se o arquivo entra no git.

2. Onde o Claude Code guarda instruções: o CLAUDE.md

O CLAUDE.md é um arquivo Markdown com instruções persistentes. Você escreve o texto, e o Claude Code o lê no início de cada sessão. Não há compilação nem esquema: o conteúdo é texto livre, em linguagem natural, como a receita da cozinha. Por ser texto, a qualidade depende de quem escreve. Instruções vagas são seguidas de forma vaga.

A documentação oficial lista quatro lugares possíveis para esse arquivo, cada um com um alcance diferente. Eles estão nesta tabela, conferida na página de memória do Claude Code.

O escopo gerenciado é o de instruções que a organização impõe a todos, como normas de segurança e requisitos de compliance. O usuário é o seu CLAUDE.md pessoal, com preferências que valem para qualquer projeto. O de projeto é o que o time escreve: arquitetura, comandos de build e teste, convenções de nomes. O local do projeto é para o que é seu e não deve ir para o git, como a URL do seu ambiente de testes pessoal.

Esse é o ponto que mais costuma gerar dúvida: o que cabe em cada arquivo. Uma regra prática separa os casos. Se a instrução vale para o time inteiro e faz parte do projeto, ela vai no CLAUDE.md do projeto, porque assim ela chega ao colega que clona o repositório. Se é uma preferência sua que valeria em qualquer repositório, como “sempre responda em português” ou “prefira rg a grep”, ela vai no CLAUDE.md do usuário. Se é uma preferência sua que vale só aqui, como um apontamento para um banco de dados local, ela vai no CLAUDE.local.md. E se é uma regra que a empresa não quer ver contornada, ela vai no arquivo gerenciado. O erro mais comum é colocar preferência pessoal no arquivo do projeto, porque aí ela passa a valer para todo o time sem que ninguém tenha decidido isso.

Como o arquivo é carregado

Um detalhe de funcionamento muda a forma de organizar esses arquivos. Ao iniciar, o Claude Code carrega os arquivos CLAUDE.md e CLAUDE.local.md do diretório em que você abriu a sessão e de todos os diretórios acima dele, até a raiz do sistema. Os arquivos das pastas de nível mais alto entram primeiro, e os da pasta atual entram por último. Dentro da mesma pasta, o CLAUDE.local.md vem depois do CLAUDE.md. Esse conteúdo não substitui nada: tudo é concatenado no contexto. Por isso uma instrução de um nível não apaga a de outro, e um conflito entre duas instruções pode levar o Claude a escolher uma delas sem critério claro.

Arquivos em subpastas seguem outra regra. Eles não entram no início. O Claude Code os carrega quando o Claude lê, escreve ou edita algum arquivo naquela subpasta. Essa é a forma de colocar regras específicas de um módulo, como as de pagamentos, sem pesar o contexto de todas as sessões. A figura abaixo mostra os dois momentos.

A figura mostra três caminhos que chegam ao contexto no início, marcados com “pacotes”, e um caminho pontilhado que só se ativa quando a sessão toca a pasta de pagamentos. O arquivo pessoal do usuário também entra no início, à direita, porque vale para toda sessão. O hexágono no centro é o ponto em que tudo se junta. A cor de cada arquivo segue o mapa desta aula: verde para o que o time versiona e laranja para o que é só local.

Há um limite prático que a documentação recomenda: manter cada CLAUDE.md abaixo de cerca de 200 linhas. O motivo é que o arquivo consome contexto em toda sessão, e um arquivo longo tende a ser seguido com menos consistência. Quando um arquivo cresce, a saída é separar em partes. Os arquivos podem importar outros com a sintaxe @caminho/do/arquivo.md, e as regras podem ficar em .claude/rules/, com um campo paths que as limita a certos arquivos. A própria documentação avisa que importar não reduz o custo de contexto, porque o arquivo importado também é carregado no início. Dividir em arquivos ajuda a manter a leitura, não o orçamento.

O que o CLAUDE.md não faz

O CLAUDE.md é contexto, não é uma regra que o sistema obriga. A documentação diz isso com todas as letras: o Claude trata essas instruções como contexto, e não como configuração imposta. Uma instrução do tipo “nunca rode migrações em produção” é um pedido que o modelo tende a respeitar, mas não é uma garantia. Quando a regra precisa ser cumprida sempre, a ferramenta certa é a configuração de permissões ou um hook do tipo PreToolUse, que roda antes da ação e pode bloqueá-la. A aula sobre operação do Claude Code (6.1) detalha essa diferença. Aqui, o que importa é não confundir os dois mecanismos: instrução explica o que se espera, e configuração garante o que é permitido.

Vale mencionar um arquivo vizinho. O Claude Code também lê arquivos AGENTS.md, usados por outras ferramentas de programação, quando não existe nenhum CLAUDE.md no diretório atual ou acima dele. Se o repositório já tem um AGENTS.md e você adiciona um CLAUDE.md, o Claude passa a ler o CLAUDE.md e ignora o AGENTS.md, a menos que a configuração de instruções seja alterada. Esse detalhe causa confusão quando a equipe muda de ferramenta e não percebe que o arquivo lido mudou.

3. Configurações que o git carrega e as que ficam na máquina

Instruções são uma parte da configuração. A outra parte são os arquivos JSON de settings, que dizem o que o Claude pode fazer, quais ferramentas estão ligadas, quais variáveis de ambiente existem e quais hooks rodam. Esses arquivos também têm escopos, e a documentação mostra a relação entre eles nesta tabela.

O arquivo compartilhado é o que o time versiona. Ele contém permissões, hooks, plugins e variáveis de ambiente que o projeto precisa. Quem clona o repositório recebe esse arquivo, e isso dá a todo o time o mesmo comportamento sem que cada um configure a mão. O arquivo local existe para exceções pessoais. A documentação mostra um exemplo: se o time usa um modelo no arquivo compartilhado e você prefere outro, você coloca o seu modelo no arquivo local, e só as suas sessões mudam. Os colegas não percebem nada, e o arquivo compartilhado não recebe um commit só para atender a sua preferência.

Dois detalhes importantes para a prática. O primeiro: o Claude Code cria o .claude/settings.local.json com uma proteção automática. Quando ele grava o arquivo pela primeira vez, adiciona a regra **/.claude/settings.local.json aos excludes globais do git, então o arquivo fica fora dos commits em todos os repositórios. Se você criar o arquivo à mão, precisa colocá-lo no .gitignore por conta própria. O segundo: o CLAUDE.local.md não tem essa proteção automática. A documentação diz para adicioná-lo ao .gitignore. Esquecer essa linha é um erro simples que expõe preferências pessoais no repositório.

A figura abaixo coloca os arquivos dessas tabelas lado a lado, com a mesma divisão de cores. Os quatro verdes do repositório são o que o time compartilha. Os dois laranjas são os overrides que ficam na sua máquina. Os azuis são os seus arquivos pessoais, que valem em todos os projetos. A seta entre o arquivo local e o compartilhado mostra o caso mais comum de sobreposição: o seu override sobrepõe, chave a chave, o que o time definiu.

Precedência entre os arquivos

Quando a mesma chave aparece em mais de um arquivo, a documentação define uma ordem. Do mais forte para o mais fraco, a ordem é: gerenciado, linha de comando (a flag --settings, válida só para a sessão), .claude/settings.local.json, .claude/settings.json e, por último, ~/.claude/settings.json. Uma chave definida num nível mais alto sobrepõe a mesma chave definida num nível mais baixo.

A figura seguinte mostra essa escada.

Leia a figura de cima para baixo. O arquivo gerenciado está no topo e não pode ser derrubado por nenhum arquivo local. Logo abaixo vem a linha de comando, que vale só para a sessão aberta. Depois vem o seu arquivo local, que sobrepõe o do time. O arquivo compartilhado sobrepõe o pessoal, e o pessoal é a base de tudo. A seta “sobrepõe” entre cada par indica quem vence quando a mesma chave está nos dois. O hexágono é o valor que o Claude de fato usa.

Essa regra vale para chaves escalares, como o modelo padrão. Listas se comportam de outro jeito. Quando a mesma lista, como permissions.allow, aparece em mais de um arquivo, o Claude Code combina as listas em vez de escolher uma delas. Cada arquivo acrescenta entradas sem apagar as dos outros. Essa diferença explica muitos casos de “eu coloquei a regra e ela não surtiu efeito”, porque uma regra de deny de outro arquivo continua valendo mesmo quando o seu allow local existe.

Há ainda uma exceção que vale a pena decorar. Algumas variáveis de ambiente do shell ganham do arquivo de settings. A documentação dá o exemplo de ANTHROPIC_MODEL: se ela está exportada no seu shell, ela sobrepõe a chave model de qualquer arquivo, e a flag --model sobrepõe as duas. Quando um modelo parece errado, a primeira pergunta a fazer é se alguma variável de ambiente está definida, antes de procurar no JSON.

4. Permissões: a ordem das regras

As permissões são parte das settings, mas merecem atenção separada porque é onde a configuração decide o que o Claude pode fazer sem pedir licença. 6.1 Operação do Claude Code cobre a operação em detalhe. Aqui basta entender a ordem de avaliação, porque ela determina o efeito de qualquer regra que você escreve.

As regras têm três tipos: allow, que libera sem perguntar, ask, que sempre pergunta, e deny, que bloqueia. A documentação define a ordem de avaliação: deny primeiro, depois ask, depois allow. A primeira regra que casa com a ação decide o resultado, e a especificidade da regra não muda essa ordem. Por isso uma regra deny ampla ganha de uma allow mais específica. Se você proíbe Bash(aws *) e libera Bash(aws s3 ls), a chamada aws s3 ls continua bloqueada, porque o deny foi avaliado antes.

A figura abaixo mostra o caminho de uma ação pelas três regras.

Uma ação como npm publish chega ao topo. Se alguma regra deny casa com ela, o caminho termina no bloqueio, e nenhuma regra allow pode reverter isso. Se não casa, o caminho segue para a regra ask, que transforma a ação em pergunta. Se também não casa, a regra allow decide: se ela casa, a ação roda sem perguntar. Se nenhuma casa, vale o modo de permissão atual. Repare que o ramo de bloqueio fica à esquerda e é o único que termina com um ✕, porque é o único que não tem volta por configuração local.

Essa ordem tem consequência direta para a gestão de configuração. Um allow no seu arquivo local não derruba um deny do arquivo compartilhado. Um hook PreToolUse também não derruba um deny, porque a documentação diz que as regras de deny e ask são avaliadas mesmo quando um hook devolve allow. Assim, a regra mais restritiva do time pode ser escrita no arquivo compartilhado, e nenhum colega consegue contorná-la com uma linha no arquivo local.

Parte 2: o que o time versiona

5. Subagents, comandos, skills e servidores MCP

Além de instruções e settings, o projeto pode carregar outros arquivos que mudam o comportamento do Claude. Quatro tipos merecem atenção, e todos seguem a mesma lógica: moram no repositório, passam por revisão e valem para quem clona.

Subagents são agentes especializados, definidos em arquivos Markdown com um cabeçalho YAML. Quando o projeto os coloca em .claude/agents/, o time inteiro usa a mesma definição. A documentação lista os campos aceitos. Só name e description são obrigatórios. Os demais, como tools, model e permissionMode, restringem ou configuram o agente. O campo model aceita um apelido (sonnet, opus, haiku), inherit ou um identificador completo de modelo. Usar o identificador completo fixa a versão, e essa é uma escolha de gestão de configuração: o agente se comporta igual no mês seguinte, mesmo que o apelido passe a apontar para outro modelo. O caminho do usuário é ~/.claude/agents/, e o agente pessoal não é versionado.

Há um detalhe que pede cuidado na revisão. A documentação diz que o Claude Code ignora em silêncio campos que não reconhece. Se você escreve tool: no lugar de tools:, o arquivo continua válido, o agente sobe, e a restrição que você queria não existe. Nenhum erro aparece. Essa é uma das razões para revisar o arquivo como código e para checar se os nomes dos campos batem com a documentação.

Comandos são atalhos que o time chama com barra, como /deploy. A documentação mostra que um arquivo em .claude/commands/deploy.md cria o comando /deploy, e que comandos em subpastas ganham nome com dois pontos, como /frontend:component. Comandos e skills se fundiram: o caminho recomendado para trabalho novo é .claude/skills/<nome>/SKILL.md, que cria o mesmo comando e acrescenta a possibilidade de carregar arquivos de apoio e de o Claude usar a skill sozinho quando ela for relevante. A documentação recomenda versionar .claude/skills/ para que o time receba as skills do projeto. Se o mesmo nome aparece em mais de um escopo, a ordem é: empresa sobre pessoal, e pessoal sobre projeto. Isso significa que a skill pessoal deploy pode esconder a do projeto na sua máquina, e o time não vê o problema. Evite nomes que colidam.

Servidores MCP são conexões com ferramentas externas, e são o item mais sensível desta lista. A documentação diz que a configuração de projeto fica em .mcp.json na raiz do repositório, e que esse arquivo deve ser versionado para que todos tenham as mesmas ferramentas. Na primeira vez, o Claude Code pede aprovação de cada servidor do arquivo, em sessões interativas. Essa aprovação é uma decisão de segurança: um servidor MCP pode trazer dados para fora da máquina e executar comandos. A documentação também avisa um caso que pega equipes desprevenidas. Em claude -p, no Agent SDK e nas sessões na nuvem, o pedido de aprovação não pode ser exibido, e os servidores do projeto carregam sem perguntar. Se o seu pipeline roda claude -p num repositório que tem .mcp.json, esses servidores estão ativos sem revisão humana naquele momento. Para bloqueá-los nesses modos, a documentação indica a chave disabledMcpjsonServers. Para refazer as aprovações de uma máquina, o comando é claude mcp reset-project-choices.

Por fim, o arquivo .mcp.json aceita expansão de variáveis no formato ${VAR} e ${VAR:-padrão}. Isso permite que o arquivo versionado mencione ${API_KEY} sem conter a chave. O princípio é o mesmo de qualquer projeto: o que é segredo fica no ambiente de quem roda, e o arquivo versionado só diz onde buscá-lo. Um segredo colado diretamente no .mcp.json vai parar no histórico do git, e a remoção depois do commit não o apaga do histórico.

6. Ambientes: desenvolvimento, teste e produção

Ambientes são o lugar onde a mesma configuração roda com dados e riscos diferentes. A documentação do Claude Code não define um modelo de três ambientes, porque ela descreve a ferramenta e não o seu fluxo de entrega. O que segue é a prática recomendada que se aplica às duas situações: o Claude Code que o time usa para programar, e a aplicação que chama o modelo em produção.

No primeiro caso, o ambiente é a máquina de cada pessoa, e o que separa um ambiente do outro é o que está fora do git. Cada desenvolvedor tem as próprias preferências em CLAUDE.local.md e settings.local.json, e o time compartilha o resto. Quando alguém quer testar uma mudança de configuração antes de todos, a forma segura é colocá-la no arquivo local, usar a sessão por algum tempo e só então abrir o pull request.

No segundo caso, a aplicação com Claude tem três ambientes clássicos: desenvolvimento, teste e produção. A regra central é que o código e a configuração são os mesmos em todos eles, e o que muda entre ambientes são os valores que chegam por variável de ambiente. A chave de API é o exemplo mais claro: cada ambiente tem a própria, para que um teste mal feito não consuma o orçamento de produção e para que uma chave vazada num ambiente não dê acesso aos outros. O modelo também deve estar fixado no código de configuração, com identificador completo, e não lido de um apelido que pode mudar sem aviso. Assim, dev, teste e produção usam o mesmo modelo, e uma troca de modelo passa pelo mesmo caminho dos outros ambientes.

A figura abaixo mostra como uma mudança chega a produção. A configuração sai do repositório, passa pela revisão, roda primeiro em desenvolvimento e depois em teste, e só segue para produção se a avaliação passar.

O caminho principal desce pela coluna central, com as cores que indicam o que é versionado (verde), o que muda por ambiente (roxo do claude), a decisão humana (laranja) e a falha (rosa). A parte importante está no losango “Avaliação passou?”. Ele separa a mudança que segue para produção da que volta. O ramo de falha termina num hexágono de reversão, porque a forma de desfazer uma mudança de configuração é reverter o commit, e não corrigir uma máquina à mão. Essa é a vantagem de manter a configuração no git: a versão anterior está a um comando de distância.

Isolar uma mudança é o que impede que uma alteração pequena derrube o sistema inteiro. A técnica básica é nunca mudar a configuração de produção direto. A mudança entra no repositório, passa pela revisão e chega aos ambientes na mesma ordem. Quando a mudança é arriscada, como trocar o modelo ou ativar uma ferramenta nova, a equipe pode colocá-la atrás de uma flag, que liga o comportamento só em certos ambientes ou para uma parte dos usuários. Isso permite testar em teste, depois ativar em uma fração da produção, e só então ampliar. Cada passo é uma decisão registrada, e cada passo pode ser revertido sem novo deploy.

Um erro comum é tratar a variável de ambiente como se fosse configuração versionada. Ela não é. A variável fica no ambiente de execução, na plataforma de deploy ou no cofre de segredos, e não no repositório. Por isso ela não aparece no histórico do git e não passa pelo pull request. Se uma mudança depende de variável nova, o pull request deve dizer isso na descrição, e a variável deve ser criada no ambiente antes do merge. Caso contrário, o deploy quebra por falta de um valor que o código espera.

7. Revisão no pull request

Configuração é código, e deve passar pela mesma revisão. Esse é o ponto em que muitas equipes escorregam: revisam com rigor a função de cálculo e aprovam o arquivo de permissões com um “ok” de passagem. Um arquivo de configuração pode ampliar o que o Claude faz sem que nenhuma linha de lógica mude, e isso o torna especialmente perigoso de revisar mal.

A figura seguinte mostra o caminho de um pull request que mexe em .claude/settings.json e as perguntas que o revisor precisa responder antes do merge.

O autor propõe a mudança e descreve o motivo. Uma checagem automática roda antes da revisão humana, e aqui entra o claude doctor, que reporta problemas de configuração, além dos testes do repositório. Só depois a revisão olha o conteúdo, e o revisor tem três perguntas de rotina. A primeira é se alguma regra de deny ficou mais ampla, ou se um allow novo foi aberto. A segunda é se a mudança traz um servidor MCP novo, porque ele pode enviar dados para fora da máquina. A terceira é se os campos têm a grafia que a documentação exige, porque campos com erro são ignorados sem aviso. A seta tracejada da última pergunta mostra que o revisor não precisa parar de procurar só porque achou um problema antes, mas o resultado final é o mesmo: qualquer resposta que aponte risco volta ao autor com o motivo, em rosa.

Há um detalhe de implantação que vale o conhecimento. Uma regra allow em .claude/settings.json só passa a valer para cada colega depois que ele confia na pasta do projeto, pelo diálogo de confiança do workspace. Enquanto isso, o colega ainda vê os pedidos de permissão. Já as regras deny e ask valem imediatamente. Portanto, uma mudança que amplia permissões tem efeito gradual, e uma que restringe tem efeito imediato. O revisor deve saber disso ao avaliar a urgência.

Para quem mantém o repositório, duas práticas do GitHub ajudam. A primeira é colocar os arquivos de configuração sob um dono, com CODEOWNERS, para que nenhuma mudança em .claude/ ou .mcp.json entre sem a aprovação de quem responde pela segurança. A segunda é tratar managed-settings.json como um caso à parte, porque ele não vai no repositório do projeto. Ele é entregue pela infraestrutura da organização, e um pull request de projeto não consegue mudá-lo. Essa separação é intencional: quem escreve o código não define a política que o próprio código deve obedecer.

A figura mostra o caminho de uma mudança de configuração, do autor até a branch main. Quando uma checagem falha, a mudança volta ao autor.

Parte 3: prática

8. Erros comuns e boas práticas

O primeiro erro é guardar preferência pessoal no arquivo do projeto. A instrução “sempre use tabs” parece inofensiva, mas quando entra no CLAUDE.md compartilhado, passa a valer para o time inteiro, e a discussão sobre tabs volta de outro jeito. A regra é perguntar, antes de cada instrução, quem decidiu que ela vale para todos.

O segundo erro é o CLAUDE.md longo e contraditório. Um arquivo com quatrocentas linhas, com duas regras que dizem coisas opostas, faz o Claude escolher uma delas. A documentação recomenda revisar periodicamente os arquivos e as regras, e há o comando /doctor prompt-audit para ajudar nessa revisão. O motivo é simples: instrução velha continua sendo lida e continua competindo com a nova.

O terceiro erro é achar que o CLAUDE.md garante comportamento. Ele orienta. Para uma restrição que não pode falhar, a configuração de permissões ou um hook são a ferramenta certa. Se o time escreveu “nunca apague o banco” no CLAUDE.md e nada mais, a garantia é só a expectativa de que o modelo leia e obedeça.

O quarto erro é segredo no arquivo versionado. Chave de API colada em settings.json, em .mcp.json ou no CLAUDE.md entra no histórico do git. Mesmo que o arquivo seja corrigido depois, a chave continua no histórico e deve ser considerada comprometida. A prática é usar variável de ambiente e referenciá-la no arquivo.

O quinto erro é o desencontro entre o que o arquivo diz e o que está valendo. Uma variável no shell sobrepõe o model do arquivo, e uma regra de outro arquivo continua valendo mesmo quando a sua regra local diz o contrário. Antes de concluir que a configuração “não funciona”, verifique qual valor está de fato em uso. O comando /status mostra qual fonte de configuração se aplica, e /context lista os arquivos de memória carregados na sessão.

Algumas boas práticas resumem o que foi dito. Versione o que o time precisa para trabalhar igual: CLAUDE.md do projeto, .claude/settings.json, .claude/agents/, .claude/skills/ e .mcp.json. Mantenha fora do git o que é pessoal: CLAUDE.local.md, settings.local.json e o seu CLAUDE.md de usuário. Fixe o modelo com identificador completo no que é de produção. Revise configuração como código, com a mesma atenção a permissões e a segredos. E escreva instruções curtas e específicas, porque a documentação recomenda isso e a experiência confirma.

9. Exercícios

Estes exercícios podem ser feitos num repositório de teste, sem tocar em projetos reais.

Primeiro exercício: crie um CLAUDE.md na raiz de um projeto com três instruções de projeto, e um CLAUDE.local.md com uma preferência sua. Abra uma sessão e use o comando /context para confirmar que os dois arquivos foram carregados. Depois adicione o CLAUDE.local.md ao .gitignore e confira com git status que ele não aparece como novo arquivo.

Segundo exercício: escreva uma regra deny para Read(./.env) em .claude/settings.json e uma regra allow para o mesmo caminho em .claude/settings.local.json. Peça ao Claude que leia o arquivo .env e observe o resultado. Explique com a ordem de avaliação por que o resultado é esse, e não o que o allow local sugeriria.

Terceiro exercício: crie um subagent em .claude/agents/revisor.md com o campo tools escrito errado, como tool:. Rode uma delegação e verifique se o agente recebeu as ferramentas que você queria. Depois corrija o nome do campo e compare. O objetivo é sentir o comportamento de campo ignorado em silêncio.

Quarto exercício: escreva uma lista de cinco mudanças de configuração que você faria num pull request e, para cada uma, responda à pergunta do revisor. A mudança amplia alguma permissão? Traz servidor MCP novo? Os campos estão escritos como a documentação pede?

10. Glossário

Gestão de configuração: disciplina de manter o comportamento de um sistema descrito em arquivos versionados, revisados e com valores por ambiente.

CLAUDE.md: arquivo Markdown de instruções persistentes, lido pelo Claude Code no início da sessão. É contexto, não uma regra imposta.

CLAUDE.local.md: versão do CLAUDE.md para uso pessoal num projeto, que deve ficar fora do git.

Settings: arquivos JSON que configuram o Claude Code, como permissões, hooks e variáveis de ambiente, em vários escopos.

Precedência: ordem em que um valor de um arquivo sobrepõe o mesmo valor de outro. Vale para chaves escalares. Listas são combinadas.

Subagent: agente especializado definido em um arquivo Markdown com cabeçalho YAML, em .claude/agents/ ou ~/.claude/agents/.

Skill: pasta com um SKILL.md que cria um comando com barra e pode ser usada pelo Claude quando for relevante.

Servidor MCP: conexão com uma ferramenta externa, declarada em .mcp.json para o projeto.

Ambiente: contexto de execução, como desenvolvimento, teste ou produção, que muda valores como chaves e flags sem mudar o código.

Promoção: passagem de uma mudança por ambientes em ordem, com verificação em cada um.

Fixação de modelo: escrever o identificador completo do modelo, para que o comportamento não mude quando um apelido mudar de destino.

Fontes

Consultadas em 18 de outubro de 2026, na documentação oficial do Claude Code:

• Página de memória e CLAUDE.md: https://code.claude.com/docs/en/memory
• Configurações e precedência: https://code.claude.com/docs/en/settings
• Permissões: https://code.claude.com/docs/en/permissions
• Implantação de configurações gerenciadas: https://code.claude.com/docs/en/managed-settings
• Subagents: https://code.claude.com/docs/en/sub-agents
• Skills: https://code.claude.com/docs/en/skills
• Comandos de barra: https://code.claude.com/docs/en/slash-commands
• Servidores MCP: https://code.claude.com/docs/en/mcp

Não foi verificado, nesta consulta, o detalhe de quais chaves de env são ignoradas em arquivos de projeto. A aula cita apenas o que a página de configurações afirma sobre o tema. A ordem exata de carregamento de comandos com o mesmo nome em escopos diferentes também não está clara na página de comandos, e a aula não a afirma.

Relacionados

• Agents
• Spec-driven development