CLAUDE.md em equipe: 7 padrões e 3 armadilhas

Meu “time” tem um humano (eu) e uma agente IA que roda no Claude Code CLI. Não sou o time da PLAID. Vou admitir isso antes de começar, porque é a única forma de esse texto não virar mais um “10 dicas de CLAUDE.md” escrito por quem nunca operou o arquivo em cenário real.

O que eu tenho, verificável na minha máquina agora, são 48 arquivos CLAUDE.md espalhados pelos meus repos. Vão do pessoal (~/.claude/CLAUDE.md, 64 linhas) ao mais inchado (sns-operations/CLAUDE.md, 559 linhas, que já está na fila para ser reescrito). Esses padrões vêm de operar esses 48 arquivos, cruzados com o que o time da PLAID e a Anthropic publicaram em texto. Onde a fonte é minha, é minha máquina. Onde é externa, tem link.

A tese não é minha: CLAUDE.md é constituição, não instrução

Em fevereiro de 2026, a PLAID (empresa listada em bolsa que faz o KARTE) publicou “PR数4倍でも破綻しない、Claude Codeをチーム運用する仕組み”. Depois de adotar o Claude Code no time, o número de PRs quadruplicou (150 → 600 por mês, para ser exato). E nada desabou. O que mudou não foi o modelo. Foi como o arquivo compartilhado do time (no caso deles, AGENTS.md, com CLAUDE.md apontando pra ele via @) passou a ser tratado: como política do time, não como prompt.

A Anthropic reforça esse frame no próprio guia oficial de boas práticas do Claude Code: “Check CLAUDE.md into git so your team can contribute. The file compounds in value over time.” E: “Bloated CLAUDE.md files cause Claude to ignore your actual instructions.”

A palavra “constituição” pega porque significa duas coisas ao mesmo tempo. Primeiro, o humano e a IA seguem as mesmas regras. Segundo, mudar regra pede review. Se você não consegue defender uma linha no PR, ela é preferência sua, não regra do time. Preferência sua vai no ~/.claude/CLAUDE.md, e não no arquivo compartilhado.

7 padrões que funcionam

1. Só entra o que aparece em 80%+ das tarefas

A Anthropic é explícita no guia oficial: para cada linha, pergunte “se eu remover, o Claude passa a errar?”. Se a resposta for não, corta. O tamanho não é virtude. O meu sns-operations/CLAUDE.md inflado foi o único caso, entre os 48 arquivos, em que eu vi o agente pular regra que existia. O modelo não ficou pior. Nada mantém 500 linhas de convenção viva ao mesmo tempo.

2. Dois níveis: repositório + pessoal

CLAUDE.md compartilhado entra no Git do repo. ~/.claude/CLAUDE.md fica na home e cuida de preferência pessoal. O meu tem 64 linhas, quase só idioma, ferramentas locais e atalhos que não interessam ao repo. O harness-ops/CLAUDE.md tem 128 linhas, só o que a Iris precisa aplicar dentro daquele projeto específico.

Sem essa separação, você acaba brigando por regras que são gosto (“prefiro let em vez de const”) num arquivo que deveria decidir política.

3. Níveis de colaboração explícitos (L1-L4)

Delegation Poker é uma prática do Management 3.0 (Jurgen Appelo). Aplicada ao Claude Code, o que eu uso, vindo do capítulo 6 do claude-code-mastery, fica assim:

• L1 (Consult): humano lidera, IA consulta. Decisões de arquitetura.
• L2 (Agree): acordar plano antes de executar. Implementação.
• L3 (Inquire): IA executa, pergunta só quando há dúvida. Testes, docs.
• L4 (Delegate): totalmente delegado. Formatação, lint.

Documentar no CLAUDE.md qual tipo de tarefa cai em qual nível evita o sintoma mais chato do Claude Code: agente que aprova o próprio plano em silêncio quando você queria discutir arquitetura primeiro.

4. Proibições vindas de falha real, não de medo

## Prohibited só ganha item depois que a IA errou daquele jeito. Regra hipotética (“não use eval”) lota o arquivo e é ignorada. Regra vinda de post-mortem tem peso porque tem cicatriz. Eu perdi 24 horas para aprender isso na prática. Regra sem “por que” não sobrevive ao primeiro conflito de opinião no time.

5. Referenciar arquivos externos em vez de inflar

A Anthropic documenta o @path/to/import no guia oficial: CLAUDE.md pode incluir outros arquivos por referência. Meu iris-hub/CLAUDE.md (250 linhas) só continua legível porque cada seção linka docs/apps/*.md (e docs/tools/*.md, playbooks/*.md) em vez de colar o conteúdo. O CLAUDE.md vira índice, não manual.

Regra prática: se o exemplo passa de 20 linhas, ele vai para outro arquivo e o CLAUDE.md linka.

6. CLAUDE.md entra no PR review

Mudar regra é mudar CLAUDE.md, então mudar CLAUDE.md pede PR. CODEOWNERS com dois humanos exigidos quando CLAUDE.md é alterado é o mínimo. Regras que passam nesse review são regras que o time defende. Regras que não passam nunca deveriam ter virado regra.

7. Review automatizado via GitHub Actions

O claude-code-action@v1 deixa você mencionar @claude num PR e disparar review automático. O que controla a qualidade do review não é o modelo. É a seção ## Code Review Criteria do CLAUDE.md, dividida em Must / Should / Nit. Sem essa divisão explícita, o review devolve lista genérica sem hierarquia, e o time ignora.

3 armadilhas que quebram o time

1. Copiar template sem cicatriz própria

Templates são úteis como ponto de partida. Copiados sem adaptar, viram documentação genérica que ninguém consulta e nada aplica. O CLAUDE.md do meu slide-anti-slop começou como template genérico de projeto TS e não sobreviveu à segunda semana. Cortei 80% dele. O que ficou foi só o que o repo real precisava.

2. Confundir CLAUDE.md com documentação do projeto

CLAUDE.md não faz o papel de README. Nem de ADR. Nem de design doc. Quando eu misturei os três, o arquivo virou o lugar onde ninguém encontra nada. Documentação de arquitetura vai em docs/. Decisão de biblioteca vai em ADR. O CLAUDE.md diz como a IA deve trabalhar dentro dessas decisões, e nada mais.

3. Ignorar o custo de contexto de cada linha

Cada linha do CLAUDE.md entra no contexto de toda invocação. O sintoma disso aparece antes do custo em dólar: a Anthropic escreve que “bloated CLAUDE.md files cause Claude to ignore your actual instructions”. Foi o que eu vi no sns-operations, não muito diferente do que o Claude Code faz quando o spec fica ambíguo. Adicionar regra é fácil. Remover exige coragem.

Para checar isso na prática, o próprio Claude Code oferece /context (confirma o que foi carregado) e, para arquivos versionados, /doctor (o próprio agente propõe cortes de conteúdo que já dá para inferir do código).

Como eu opero isso hoje

Meu time é um humano e uma agente IA. Não temos os 4x PRs da PLAID. Mesmo assim, o mesmo shape se aplica:

Os quatro seguem o padrão 2 (dois níveis, pessoal e repo). Três seguem o padrão 5 (referência a docs/). Só o de sns-operations quebra o padrão 1 (progressive disclosure) e paga o custo do anti-padrão 3 (custo de contexto). Reescrevê-lo está na fila desde que eu comecei este texto.

Onde eu paro de me comparar com a PLAID

Isso importa. Constituição do time só funciona se o time inteiro concorda em rever. Comigo e a Iris, “review” quer dizer que eu leio o diff antes de aceitar. Num time humano-humano-IA, precisa de gente concordando de verdade, e o CLAUDE.md, sozinho, não faz esse trabalho. Ele documenta o consenso. Ele não fabrica consenso.

Os 7 padrões funcionam. Os 3 anti-padrões quebram. Mas a constituição só pesa tanto quanto o review que a defende.

Aprofundei esses padrões (mais os 15 templates de CLAUDE.md por caso de uso e o caso PLAID completo) no claude-code-mastery, capítulos 6 e 7.