Introdução
Deixa eu te fazer uma pergunta: quantos devs na sua software house usam Claude Code hoje? Cinco? Dez? Vinte?
Agora me diz: qual é a política de uso? O que eles podem e não podem fazer com a ferramenta? Quais arquivos são protegidos? Quais hooks de auditoria estão rodando? Quem definiu essas regras?
Se a resposta pra qualquer uma dessas perguntas foi “não sei” ou “cada um faz do seu jeito”, você está no mesmo barco que 76% das organizações que já tiveram incidentes com shadow AI. Não é uma estatística inventada — é um levantamento de 2026 da Digital Applied. E o número fica pior: 45% dos devs admitem usar ferramentas de IA não autorizadas no trabalho.
Na minha experiência com 300+ software houses, o padrão é sempre o mesmo: a empresa adota Claude Code, os devs amam, a produtividade dispara, e ninguém para pra pensar em governança. Até que um dev inadvertidamente dá acesso a um .env com credenciais de produção. Ou um hook de auditoria que o DevOps configurou é sobrescrito por uma configuração de projeto. Ou pior: cada equipe tem uma configuração diferente e ninguém sabe o que vale.
A boa notícia? Desde a v2.1.83, o Claude Code tem uma solução elegante pra isso: managed-settings.d/ — um drop-in directory para policy fragments. Se você já trabalhou com systemd, nginx conf.d/ ou sudoers.d/, vai entender imediatamente. Se não, calma que eu explico.
O que é managed-settings.d/
O Claude Code já tinha o conceito de managed settings — um arquivo JSON (managed-settings.json) que o time de DevOps/IT coloca numa pasta do sistema e que tem a maior precedência de todas. Nenhum dev consegue sobrescrever. É a lei.
O problema do arquivo único é óbvio: quando você tem 3 squads diferentes, cada uma com necessidades diferentes, alguém precisa ser o “dono” desse arquivo. Squad A precisa de um hook de auditoria. Squad B precisa bloquear acesso a secrets. Squad C precisa configurar MCP servers específicos. Todas precisam editar o mesmo arquivo. Conflitos, PRs travados, e aquele clássico “quem mexeu no managed-settings e quebrou tudo?”.
O managed-settings.d/ resolve isso com um modelo que o mundo Linux já usa há décadas: drop-in directory. Em vez de um arquivo monolítico, cada equipe publica seu próprio fragmento de policy numa pasta. O Claude Code lê todos e mergeia automaticamente.
Funciona assim:
/etc/claude-code/ # Linux
├── managed-settings.json # Base (lido primeiro)
└── managed-settings.d/
├── 10-telemetry.json # Ops: OpenTelemetry + métricas
├── 20-security.json # Security: deny rules + sandbox
├── 30-hooks.json # DevOps: hooks de auditoria
└── 40-squad-fintech.json # Squad Fintech: regras específicas
O Claude Code segue a convenção systemd:
1. managed-settings.json é lido como base
2. Todos os *.json dentro de managed-settings.d/ são ordenados alfabeticamente
3. Cada arquivo é mergeado em cima do anterior
4. Arquivos começando com . são ignorados (útil pra desabilitar temporariamente)
O merge é inteligente:
| Tipo de valor | Comportamento |
|---|---|
| **Scalar** (string, number, boolean) | Último arquivo vence |
| **Array** | Concatena e deduplica |
| **Object** | Deep merge recursivo |
Isso significa que os prefixos numéricos controlam a ordem de precedência: 10-* é a base, 20-* sobrescreve scalars de 10-*, 30-* sobrescreve 20-*, e assim por diante. Arrays vão acumulando — se 10-telemetry.json tem um deny rule e 20-security.json tem outro, ambos são aplicados.
Como funciona na prática
Exemplo real: SH com 3 squads
Imagine uma software house com 20 devs divididos em 3 squads: Backend, Frontend e DevOps. Cada squad tem necessidades diferentes, mas todas precisam seguir algumas regras corporativas.
10-corporate.json — Regras corporativas (vale pra todo mundo):
{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)",
"Bash(curl *)"
]
},
"companyAnnouncements": [
"Lembrete: code review obrigatório em toda PR. Dúvidas? #dev-standards no Slack."
]
}
20-security.json — Security hardening (DevOps publica):
{
"allowManagedPermissionRulesOnly": true,
"allowManagedHooksOnly": true,
"env": {
"CLAUDE_CODE_SUBPROCESS_ENV_SCRUB": "1"
}
}
30-audit.json — Hooks de auditoria (Ops publica):
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "/usr/local/bin/audit-file-change.sh"
}
]
}
]
},
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
"OTEL_METRICS_EXPORTER": "otlp"
}
}
40-squad-fintech.json — Regras específicas da squad Fintech:
{
"permissions": {
"deny": [
"Bash(rm -rf *)",
"Bash(sudo *)",
"Edit(./migrations/**)"
]
},
"autoMode": {
"environment": [
"Source control: github.internal.com/acme-fintech",
"Database: nunca executar migrations via Claude Code"
]
}
}
O resultado final é o merge de tudo: deny rules corporativos + deny rules fintech, hooks de auditoria, telemetria, env scrub, e auto mode configurado pro contexto da squad. Cada arquivo é mantido pelo time que entende do assunto. Ninguém precisa tocar no arquivo do outro.
Onde fica em cada plataforma
| Sistema | Diretório |
|---|---|
| **macOS** | `/Library/Application Support/ClaudeCode/managed-settings.d/` |
| **Linux/WSL** | `/etc/claude-code/managed-settings.d/` |
| **Windows** | `C:\Program Files\ClaudeCode\managed-settings.d\` |
Deploy automatizado
Na prática, você não cria esses arquivos manualmente. Eles entram no seu pipeline de infraestrutura:
# Ansible, Chef, Puppet, ou simplesmente um script de onboarding
sudo cp policies/10-corporate.json /etc/claude-code/managed-settings.d/
sudo cp policies/20-security.json /etc/claude-code/managed-settings.d/
# Squad-specific — só nas máquinas da squad
if [ "$SQUAD" = "fintech" ]; then
sudo cp policies/40-squad-fintech.json /etc/claude-code/managed-settings.d/
fi
Desabilitar temporariamente? Renomeia com ponto:
# Desabilita hooks de auditoria pra debug
sudo mv /etc/claude-code/managed-settings.d/30-audit.json \
/etc/claude-code/managed-settings.d/.30-audit.json
# Reabilita
sudo mv /etc/claude-code/managed-settings.d/.30-audit.json \
/etc/claude-code/managed-settings.d/30-audit.json
Por que isso importa para sua Software House
O problema real: shadow AI sem governança
Vamos ser honestos. A maioria das SHs que conheço está nessa situação:
- Devs usando Claude Code com configuração padrão
- Nenhuma política de permissões definida
- Nenhum hook de auditoria
- Sem visibilidade do que a IA está acessando
- Cada dev com seu próprio settings.json
Isso tem nome: shadow AI. E os números são assustadores:
- 76% das organizações já tiveram incidentes com shadow AI (Digital Applied)
- 65% das ferramentas de IA operam sem aprovação de TI
- 84% dos devs usam IA para code gen diariamente
- Código gerado por IA tem 1.75x mais issues de correção e 1.57x mais vulnerabilidades de segurança (Exceeds AI)
- O custo médio de ignorar shadow AI? $412K por ano (Second Talent)
“Ah, mas minha SH é pequena, isso é problema de empresa grande.” Não. Se você tem 10 devs usando Claude Code sem governança, cada um decidindo o que o Claude pode ou não pode fazer, você tem 10 pontos de risco. E quando um deles fizer algo que exponha dados de cliente, o problema é seu.
O stack completo de governança
O managed-settings.d/ não é uma feature isolada. Ele é a camada de composição dentro de um stack completo que o Claude Code construiu para governança enterprise:
| Camada | Mecanismo | Quando usar |
|---|---|---|
| **Cloud** | [Server-managed settings](https://code.claude.com/docs/en/server-managed-settings) via Claude.ai Admin | BYOD, devs remotos, sem infra de MDM |
| **OS-level** | macOS plist, Windows registry | Máquinas corporativas com MDM (Jamf, Intune) |
| **Filesystem** | `managed-settings.json` + `managed-settings.d/` | Servidores, CI/CD, containers, infra gerenciada |
| **Projeto** | `.claude/settings.json` | Regras específicas do repositório |
A precedência é clara: Managed > CLI args > Local > Project > User. Managed settings são a lei — ninguém sobrescreve.
E o que você pode controlar via managed settings vai muito além de permissões:
allowManagedPermissionRulesOnly— só regras de permissão definidas no managed valem. Dev não pode criar allow rules própriosallowManagedHooksOnly— só hooks managed executam. Previne hooks maliciosos em projetosallowManagedMcpServersOnly— só MCP servers autorizados conectamallowedChannelPlugins— controla quais channel plugins podem receber mensagensblockedMarketplaces— bloqueia fontes de plugins não autorizadasavailableModels— restringe quais modelos o dev pode usar (controle de custo)autoMode.environment— ensina o auto mode classifier quais repos e domínios são confiáveis
Combinando managed-settings.d/ com CLAUDE_CODE_SUBPROCESS_ENV_SCRUB (que eu cobri num artigo recente) e sandbox.failIfUnavailable, você tem um stack de segurança de 3 camadas: policy enforcement + credential isolation + execution sandboxing.
A conta que importa
Vou fazer uma conta rápida. Uma SH com 20 devs, cada um usando Claude Code 4h por dia:
Sem governança:
- 1 incidente de segurança a cada 6 meses (conservador, dado que 76% das orgs já tiveram)
- Custo médio por incidente: $50K (resposta, investigação, remediação)
- Custo anual: ~$100K
Com managed-settings.d/ + stack completo:
- Setup: 4 horas de um DevOps senior
- Manutenção: 1 hora por mês (adicionar/ajustar policies)
- Custo anual: ~$5K (tempo do DevOps)
ROI: 20x. E isso sem contar o custo reputacional de um vazamento de dados de cliente.
Os dados que ninguém quer ouvir
Aqui vai o dado mais incômodo que eu encontrei pesquisando pra esse artigo: apenas 37% das organizações têm políticas de governança de IA. Isso significa que 63% estão voando no escuro.
E entre as que têm políticas, a maioria depende de “confiar no bom senso do dev”. Isso não é governança — é esperança.
O mercado de AI governance tools está explodindo justamente por causa disso. Mas a maioria das soluções é cara, complexa e genérica. O que o Claude Code fez com managed settings foi diferente: governança built-in, sem ferramenta extra, sem licença adicional, sem dashboard externo. Uma pasta com arquivos JSON que você já sabe escrever.
Para SHs que atendem clientes enterprise — bancos, governo, indústria — isso vira diferencial competitivo. Quando o CISO do cliente pergunta “como vocês governam o uso de IA no desenvolvimento?”, você mostra o stack: managed settings com policies por squad, hooks de auditoria, credential scrubbing, sandbox mandatório. É resposta concreta, não slide de PowerPoint.
O que eu penso
Eu vejo uma tendência clara: as SHs que vão sobreviver nos próximos 3 anos são as que tratam IA como infraestrutura, não como ferramenta individual. E infraestrutura precisa de governança.
O managed-settings.d/ pode parecer uma feature chata comparada com agent teams ou computer use. Mas é exatamente esse tipo de feature “chata” que separa uma SH amadora de uma SH profissional. A Anthropic entendeu isso — colocou governança enterprise no mesmo nível de prioridade que features de produtividade.
Se você tem mais de 5 devs usando Claude Code e não tem managed settings configurado, você está correndo um risco desnecessário. Não precisa fazer tudo de uma vez. Começa com o básico: um 10-security.json que protege .env e ativa env scrub. Depois adiciona hooks de auditoria. Depois policies por squad. Drop-in directory é exatamente pra isso — crescer incrementalmente sem refazer tudo.
Conclusão
Governança de IA não é burocracia — é maturidade. É a diferença entre “usamos IA” e “usamos IA com controle”.
O managed-settings.d/ do Claude Code é a resposta para quem precisa escalar o uso de IA sem perder o controle. Não é uma ferramenta nova pra comprar. Não é um dashboard pra configurar. É uma pasta com JSONs que seguem uma convenção que qualquer DevOps já conhece.
Se sua software house está crescendo e a adoção de IA está acelerando, o momento de configurar governança é agora — não depois do primeiro incidente.
Se você quer implementar esse nível de controle e maturidade na sua software house, a gente trabalha exatamente isso nos nossos treinamentos e mentorias.
Sou Thulio, mentoro 300+ SHs desde 2016.
