Claude Code em equipe: como padronizar o agente entre vários devs do mesmo repositório

Já abriu um pull request e sentiu que aquele mesmo repositório recebeu código com cara de cinco pessoas diferentes? 🙂

Cada dev configurou o agente do seu jeito, e o resultado sai inconsistente: um commita teste, o outro não, um usa uma lib, o outro usa outra

O Claude Code lê configuração em CAMADAS: uma parte vem do repositório (e chega em todo mundo que clona), outra parte vem da máquina do dev (e vale só pra ele)

Padronizar não é escrever manual gigante, é decidir o que mora em cada camada

Então bora montar isso na prática, arquivo por arquivo, porque aqui é passo a passo e não teoria

O que versionar no repositório e o que cada dev mantém na própria máquina

A divisão oficial é simples: os arquivos do projeto (a pasta .claude/ do repo mais CLAUDE.md, .mcp.json e .worktreeinclude na raiz) vão pro git pra compartilhar com o time

Com uma ressalva que mora DENTRO dessa mesma pasta: o .claude/settings.json é o arquivo compartilhado do time, mas o .claude/settings.local.json é preferência pessoal daquele dev e não é pra chegar em todo mundo

O que está em ~/.claude é configuração pessoal do dev e vale pra todos os projetos dele

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Nota pra galera do Windows: aquele ~/.claude que aparece na documentação é o %USERPROFILE%\.claude aqui

E tem ainda uma ordem de precedência entre as camadas: as configurações gerenciadas pela organização (managed) têm a MAIOR precedência e não podem ser sobrescritas por nenhum outro escopo, fora as exceções documentadas

Depois vem o projeto, e por último as de usuário, que só valem quando nada mais define aquele item

O critério de decisão é esse, e cabe em uma linha: se a regra é do PROJETO, vai pro git; se é gosto ou ambiente do dev, fica local

O que você precisa antes de padronizar o agente do time

Antes de sair criando arquivo, checa essa listinha:

• Claude Code instalado na máquina de cada dev do time (se o time ainda está decidindo isso, vale entender qual plano do Claude Code compensa antes de padronizar)
• Repositório git com permissão de commit pra quem vai subir a configuração
• Um acordo MÍNIMO do time sobre comandos de build e de teste, porque isso vira conteúdo direto do CLAUDE.md
• Ciência de que o que já está em ~/.claude é pessoal e continua ali, nada some quando o repositório passa a ter configuração própria

E um aviso de segurança antes de alguém sair "limpando" pasta: NÃO apague ~/.claude.json, ~/.claude/settings.json e ~/.claude/plugins/

Esses guardam autenticação, preferências e os plugins instalados

Já me ferrei uma vez apagando pasta de config achando que ia "resetar" e resolver, então tome cuidado aqui

Passo a passo: padronizando o Claude Code entre vários devs

O alvo final é um repositório com essa cara:

<pre><code>repo/ CLAUDE.md .mcp.json .claude/ settings.json settings.local.json skills/ agents/ rules/ </code></pre>

Bora montar isso na ordem

1. Gere a base com /init

O comando /init cria um CLAUDE.md inicial a partir da estrutura atual do projeto, pra você refinar depois

<pre><code>/init </code></pre>

O erro comum deste passo: aceitar o que saiu e commitar direto, sem cortar nada

O gerado é ponto de partida, não entrega

2. Enxugue o CLAUDE.md linha a linha

A boa prática oficial é olhar cada linha e perguntar: se eu tirar isso, o Claude erra?

Se a resposta é não, corta

Arquivo inchado faz o Claude ignorar justamente a instrução que importava

O que a documentação manda INCLUIR: comandos de terminal que o Claude não tem como adivinhar, regras de estilo que divergem do padrão da linguagem, instruções de teste e o test runner preferido, etiqueta do repositório, decisões de arquitetura específicas do projeto e peculiaridades do ambiente de desenvolvimento

O que deixar de FORA: o que o Claude descobre lendo o código, convenções padrão da linguagem, documentação detalhada de API, informação que muda com frequência, explicações longas e descrição arquivo por arquivo

O erro comum deste passo: transformar o CLAUDE.md em documentação de API

Um detalhe que muda o jogo: o CLAUDE.md vira parte do prompt do Claude, então trate ele como prompt de uso frequente e itere na eficácia

Na própria Anthropic é comum passar o arquivo pelo prompt improver e ajustar a ênfase (com IMPORTANT ou YOU MUST, por exemplo) pra melhorar a aderência

3. Commite o CLAUDE.md na raiz

A recomendação oficial é chamar o arquivo de CLAUDE.md e commitar no git, pra compartilhar entre sessões e com o time

A alternativa é chamar de CLAUDE.local.md e jogar no .gitignore

<pre><code>git add CLAUDE.md git commit -m "config: contexto compartilhado do Claude Code" </code></pre>

O erro comum deste passo: usar CLAUDE.local.md achando que o time recebe

Não recebe, esse é o arquivo que fica de fora do git por definição

4. Crie o .claude/settings.json compartilhado

Aqui é onde mora a configuração do TIME

O que é preferência individual do dev vai pro .claude/settings.local.json, e o que vale pra todos os projetos daquela pessoa vai pro ~/.claude/settings.json

Garanta que o .claude/settings.local.json está listado no .gitignore do projeto

O erro comum deste passo: subir preferência individual no arquivo do time e todo mundo herdar o gosto de uma pessoa só

5. Defina as permissões e entenda a ordem

Existem três tipos de regra: allow (usa a ferramenta sem aprovação manual), ask (pede confirmação) e deny (impede o uso)

E elas são avaliadas nessa ordem: deny, depois ask, depois allow

A PRIMEIRA regra que casar decide, e a especificidade da regra não muda essa ordem

Ou seja: uma regra super específica não "ganha" de uma genérica, quem manda é a ordem de avaliação

O erro comum deste passo: escrever regra pensando que a mais detalhada vence

6. Compartilhe as ferramentas com .mcp.json versionado

Servidores MCP com escopo de projeto ficam no .mcp.json na raiz, e esse arquivo foi feito justamente pra colaboração em equipe

A documentação orienta versionar ele, assim todo mundo tem as mesmas ferramentas MCP

O erro comum deste passo: achar que "commitei, então já está funcionando pra todos"

Por segurança, na primeira vez que o Claude Code vê um servidor MCP com escopo de projeto, ele pede aprovação daquele dev antes de conectar

Avisa o time que essa confirmação vai aparecer, senão vira chamado de suporte interno 😀

7. Padronize comandos e subagentes

Comandos personalizados e skills foram unificados: .claude/commands/deploy.md e .claude/skills/deploy/SKILL.md criam o mesmo /deploy e funcionam igual

O formato .claude/commands/ é considerado LEGADO (os arquivos existentes continuam funcionando), e a recomendação é usar .claude/skills/<nome>/SKILL.md

Skills de projeto podem ser commitadas em .claude/skills/ no controle de versão, e as pessoais ficam em ~/.claude/skills/

Pra subagentes, o Claude Code observa .claude/agents/ (projeto) e ~/.claude/agents/ (pessoal)

Quando alguém adiciona ou edita um arquivo de subagente, a mudança é detectada em alguns segundos e a próxima delegação já usa a definição atualizada, sem reiniciar nada

Isso ajuda demais quando o time começa a usar subagents no Claude Code pra dividir tarefa, porque a definição do papel deixa de ser combinado de boca e passa a ser arquivo revisado em PR

8. Escape do CLAUDE.md gigante em repositório grande

Em base de código grande, um CLAUDE.md único na raiz sempre cai num de dois buracos: ou cresce até cobrir a convenção de todo subsistema (gastando contexto com instrução que não tem nada a ver com a tarefa) ou fica genérico demais e não ajuda ninguém

A saída é dividir: CLAUDE.md por diretório e regras modulares em .claude/rules/

As regras de .claude/rules/ carregam junto do CLAUDE.md, e com o frontmatter YAML paths: elas viram escopadas por caminho

<pre><code>— paths: src/api/** —

Toda rota nova precisa de teste de contrato </code></pre>

Assim a regra só carrega quando o Claude lê um arquivo que casa com o glob

Regra sem paths: carrega no início da sessão, sempre

O resultado é o Claude carregando as regras do repositório inteiro MAIS só as convenções do código em que ele está mexendo agora

9. Transforme o que é inegociável em hook

Aqui está a diferença que quase todo time demora pra sacar: instrução não é imposição

Se uma regra precisa valer TODAS as vezes, ela tem que ser um hook, não uma frase no prompt

O PreToolUse dispara antes da chamada de ferramenta e pode BLOQUEAR a execução

O PostToolUse dispara depois que a ferramenta teve sucesso

O exemplo oficial roda o script de lint apenas quando o Claude escreve ou edita arquivo, via PostToolUse com o matcher Edit|Write

O erro comum deste passo: escrever no CLAUDE.md "sempre rode o lint depois de editar" e ficar bravo quando não roda

10. Escale pro time inteiro com plugins e marketplace

Quando a padronização passa de um repositório e vira coisa da organização, dá pra distribuir extensões criando um marketplace

O arquivo .claude-plugin/marketplace.json fica na raiz do repositório e define nome, dono e a lista de plugins com suas origens

O time adiciona assim:

<pre><code>/plugin marketplace add owner/repo </code></pre>

Qualquer serviço de hospedagem git serve (GitHub, GitLab, Bitbucket ou servidor próprio)

E dá pra declarar marketplaces adicionais nas settings com extraKnownMarketplaces, sendo que o .claude/settings.json de projeto permite plugins específicos do projeto compartilhados com o time

Um plugin com escopo de projeto é versionado no repositório e chega em todo colaborador que clona

Padronizou e continua inconsistente? Cinco causas comuns

É aqui que a configuração ENGANA, porque tudo parece certo no arquivo e o comportamento não bate

O dev liberou a ferramenta no local e nada mudou:

Se uma ferramenta é negada em QUALQUER nível de configuração, nenhum outro nível consegue liberar

O allow local do dev não desfaz o deny do projeto

Como prevenir: antes de sair criando allow pessoal, olhe o deny do time, porque a discussão é lá e não na máquina de ninguém

O hook do projeto não substituiu o do dev:

As entradas de hooks SOMAM entre as camadas em vez de substituir

Usuário, projeto e local adicionam os próprios hooks sem remover os gerenciados

Como prevenir: assuma merge, não sobrescrita, e escreva hook que seja idempotente e não brigue com o do vizinho

A instrução do CLAUDE.md às vezes é seguida e às vezes não:

Regras em .claude/rules/ (e o próprio CLAUDE.md) são ORIENTAÇÃO que o Claude lê, não configuração que o Claude Code aplica à força

Como prevenir: se o comportamento tem que acontecer 10 em 10 vezes, ele é hook

Se é convenção que o modelo deve considerar, aí sim é rule ou CLAUDE.md

O hook funciona na máquina e some na sessão em nuvem:

Sessões na nuvem do Claude Code na web NÃO leem o ~/.claude/settings.json local do dev

Os hooks nessas sessões vêm do repositório e das configurações gerenciadas pelo servidor da organização

Como prevenir: se o time usa a web, o hook precisa estar versionado no repositório, ponto

Quebrou o CLAUDE.md em imports pra economizar contexto:

Os arquivos CLAUDE.md são carregados na janela de contexto no início de TODA sessão e consomem tokens junto com a conversa

Quebrar em imports com a sintaxe @caminho/do/arquivo ajuda MUITO na organização, mas não reduz contexto, porque os importados carregam no start do mesmo jeito

Como prevenir: pra economizar contexto de verdade, o caminho é cortar linha (passo 2) e escopar por caminho com .claude/rules/ (passo 8)

Quanta padronização o seu time precisa

Não é pra sair aplicando os 10 passos numa dupla, isso vira burocracia e ninguém mantém

Dupla ou squad pequeno: CLAUDE.md versionado e .mcp.json na raiz, e olhe lá

O resto resolve no acordo verbal mesmo, porque vocês revisam o código um do outro toda semana

Time médio: aí entra o .claude/settings.json com as permissões acordadas, skills e subagentes de projeto commitados, e rules escopadas por caminho pra cada área do sistema ter a sua convenção sem inflar o contexto de todo mundo

Empresa que precisa IMPOR e não combinar: existem as configurações gerenciadas pela organização

Elas podem vir do console de administração da Claude, de um sistema de MDM ou de um arquivo em disco, e incluem opções como allowManagedHooksOnly (que bloqueia hooks de usuário, projeto e plugin), allowManagedPermissionRulesOnly e disableBypassPermissionsMode

Tem também o claudeMdExcludes, que pode ser definido em qualquer camada (usuário, projeto, local ou managed policy) e faz merge entre elas

O detalhe importante: arquivos CLAUDE.md de managed policy NÃO podem ser excluídos, o que garante que a instrução da organização sempre valha

Como isso se comporta quando são muitos agentes no mesmo projeto

Essa régua de "projeto no git, pessoal na máquina" fica muito mais visível quando você para de rodar um agente e passa a rodar vários

No vídeo abaixo eu monto uma "empresa" de agentes com o Paperclip, onde o agente individual é o funcionário e o Paperclip é a camada que organiza o time

E os funcionários podem ser adaptadores diferentes, incluindo o Claude Code, sem ficar preso numa ferramenta só

Um ponto que conecta direto com padronização: quando testei, o teste de ambiente do agente FALHOU na primeira tentativa porque o CLI do Claude não estava instalado no servidor

Resolvi abrindo outra conexão com o servidor, instalando o CLI e fazendo login pela conta, e aí o teste de conexão passou

Olha o que isso ensina: o ambiente de execução é máquina, não repositório

Por isso configuração pessoal e login não viajam no git, e é exatamente por isso que a documentação separa ~/.claude do que está versionado

Eu defendo rodar o Paperclip em VPS e não no PC pessoal, pra o time de agentes seguir funcionando sem depender da minha máquina estar ligada (na demonstração eu conectei por SSH com encaminhamento de porta e abri a dashboard pelo localhost do navegador)

Fiz a instalação no meu próprio computador durante o vídeo pra mostrar que dá, mas o caminho que eu indico é VPS mesmo

O cenário que eu montei foi uma empresa de conteúdo: defini a meta principal e a primeira tarefa do agente diretor, que era montar a equipe e produzir o primeiro material

Aí veio a parte que eu mais gostei: o agente PAROU sozinho e devolveu a decisão pra mim

Ele ficou bloqueado pedindo aprovação pra contratar novos agentes, e essas pendências caíram na inbox, onde eu podia aprovar, rejeitar ou pedir revisão de cada uma

Aprovei todas pra seguir, o time cresceu e o fluxo continuou sozinho, com o agente definindo o próximo passo

E os agentes acordam sozinhos por horário agendado ou por gatilho de evento, sem eu precisar iniciar o processo

Dois controles me deixaram tranquilo ali: o orçamento por agente, com parada automática ao atingir o limite (previsibilidade de custo), e a dashboard como painel de governança, mostrando agentes ativos, tarefa em progresso, gasto do mês, metas e o que estava rodando em tempo real

O cenário de uso que eu aponto é quem já mantém MAIS DE UM Claude Code aberto ao mesmo tempo e se perde alternando entre janelas e projetos

Porque o ganho principal não é velocidade, é contexto compartilhado e governança, pra todos os agentes trabalharem em conjunto sob a mesma direção

E é a mesma lógica do post: contexto compartilhado versionado é o que faz N executores produzirem uma coisa só, em vez de cinco estilos no mesmo repo

Sendo honesto sobre quando NÃO usar: quem trabalha com um agente por vez, tarefas pontuais sem continuidade, setup simples que já resolve ou uso casual e exploratório não precisa disso

Conclusão

Padronizar Claude Code em equipe não é escrever mais regra, é colocar cada coisa na camada certa

A régua de decisão cabe em três linhas:

• Se é do PROJETO, vai pro git (CLAUDE.md, .claude/settings.json, .mcp.json)
• Se é gosto ou ambiente do DEV, fica local (.claude/settings.local.json e ~/.claude/)
• Se é INEGOCIÁVEL, vira hook, porque instrução é orientação e hook é imposição

O próximo passo concreto pra hoje: roda o /init no repositório, corta o CLAUDE.md linha a linha com aquela pergunta ("se eu tirar, o Claude erra?"), usa o /memory pra revisar os arquivos de memória nos escopos de usuário e de projeto

E só DEPOIS disso senta com o time pra acordar as permissões, porque discutir deny antes de ter contexto compartilhado é discussão perdida

Faça o teste no seu repo e me conta o que sobrou do CLAUDE.md depois do corte 😀

até o próximo post!