O problema
Um time de oito pessoas adota Claude Code. Em duas semanas, cada engenheiro tem seu próprio CLAUDE.md local, ninguém sabe qual comando faz o quê, e um novo contratado passa o primeiro dia inteiro perguntando "isso já foi tentado?" porque nenhuma convenção do time está escrita em lugar nenhum que o agente possa ler. O problema não é o Claude Code — é que o time tratou configuração como preferência pessoal, quando na verdade é infraestrutura compartilhada.
Escalar Claude Code para um time não é dar a ferramenta pra cada pessoa e deixar cada uma configurar do seu jeito. É desenhar a mesma restrição pra todo mundo, uma vez, em um lugar que o agente sempre vai ler.
O conceito central
O CLAUDE.md tem hierarquia por design: existe um escopo de projeto (versionado, compartilhado por todo o time) e um escopo de usuário (pessoal, não versionado). A decisão de arquitetura não é "o que colocar no CLAUDE.md" — é "o que pertence a qual escopo". Uma convenção de time — como formatar commits, quais diretórios nunca devem ser tocados sem revisão, qual é o comando pra rodar os testes — pertence ao escopo de projeto, porque toda sessão de qualquer pessoa precisa dela. Uma preferência pessoal — como o engenheiro gosta de receber explicações, se prefere respostas mais curtas — pertence ao escopo de usuário, porque forçar isso pra todo o time é ruído.
Regras específicas de caminho (path-specific rules) resolvem um problema que um CLAUDE.md único não resolve bem: times grandes têm sub-áreas com convenções diferentes. O diretório de infraestrutura tem uma regra de revisão mais rígida que o diretório de componentes de UI. Um CLAUDE.md gigante tentando cobrir os dois vira ruído pra ambos. Regras com escopo de caminho carregam só quando relevantes — a pessoa mexendo em UI não carrega a política de infraestrutura, e vice-versa.
Comandos e Skills são a segunda peça de escala. Um comando de projeto (.claude/commands/) transforma um procedimento que o time repete — "revisar uma migration", "gerar changelog", "verificar se um PR está pronto pra review" — em algo que qualquer pessoa do time invoca da mesma forma, sem reconstruir o prompt do zero toda vez. Isso não é conveniência: é a diferença entre um procedimento que o time executa de forma consistente e um que cada pessoa reinterpreta.
A terceira peça é rodar Claude Code de forma não interativa, especialmente em CI. O modo -p/--print com --output-format json produz saída estruturada que outra ferramenta pode consumir — um pipeline de CI pode chamar Claude Code pra revisar um PR e decidir, com base no JSON de saída, se aprova ou bloqueia automaticamente. A armadilha comum aqui é tratar essa revisão automatizada como suficiente sozinha: o valor real está em usar essa saída como um sinal a mais, com uma revisão independente (humana ou outro passe) verificando os casos que o sinal marcou como arriscados — nunca deixar o mesmo agente que gerou a mudança ser também o único juiz de que ela está correta.
Coloque em prática
No laboratório desta lição você vai construir, em Python, uma função que decide o escopo correto (projeto, usuário, ou regra de caminho) para uma lista de convenções de time, e simular a saída estruturada que uma checagem de CI headless produziria a partir de um conjunto de resultados de revisão.