A maioria das orientações CLAUDE.md é escrita para desenvolvedores solo trabalhando em um projeto por vez. Trabalho em agência é diferente: você tem um portfólio de projetos de clientes, cada um com suas próprias convenções, e o mesmo engenheiro pode tocar seis deles em uma semana. A estratégia CLAUDE.md que funciona para um dev solo falha na escala de agência. Esta é a abordagem que estabelecemos na Seahawk Media após 18 meses de iteração em 200+ repositórios de clientes ativos.
Aprendizado principal: CLAUDE.md em escala de agência precisa de três camadas — padrões em toda a agência, sobrescrita por cliente e notas por engajamento — para que um engenheiro possa trabalhar em seis repositórios com o contexto certo.CLAUDE.md at agency scale needs three layers, agency-wide standards, client overrides, and per-engagement notes, so one engineer can move across six repos with the right context.
Se você está rodando uma agência que usa Claude Code diariamente e percebendo que engenheiros estão obtendo output radicalmente diferentes entre projetos, este post é o ajuste estrutural.
Por que aconselhamento CLAUDE.md solo-dev quebra na escala de agência
O aconselhamento padrão CLAUDE.md é: escreva uma vez, otimize para seu projeto, mantenha em menos de 500 linhas. Isso funciona quando você tem um projeto. Quando você tem 50 repositórios de clientes, três problemas emergem. O mesmo engenheiro não consegue lembrar quais convenções se aplicam a qual cliente. Novos engenheiros integrando um projeto enfrentam cinquenta arquivos CLAUDE.md diferentes. O conteúdo CLAUDE.md derivava conforme engenheiros atualizavam um projeto e esqueciam dos outros.
Resolver isso na escala de agência requer uma abordagem em camadas: padrões gerais da agência em um lugar, sobrescrita específica do cliente em outro, e contexto por engajamento em um terceiro. As camadas se empilham em vez de duplicar.
O modelo CLAUDE.md de três camadas
Camada 1: padrões da agência
Um único template CLAUDE.md vive em um repositório GitHub privado da nossa agência. Cobre: estilo de código nas linguagens que entregamos, nossos padrões proibidos, nossas convenções de testes, nossos padrões de segurança, nossa regra editorial de grafia britânica, nossos padrões de deployment. Este arquivo tem aproximadamente 400 linhas e muda algumas poucas vezes por ano.
Todo novo projeto de cliente começa com symlink ou cópia deste arquivo. Mudanças no arquivo da agência são incorporadas aos projetos em uma cadência trimestral de revisão. Engenheiros podem contar que essas convenções são idênticas independentemente de qual projeto abrem.
Camada 2: CLAUDE.md específico do cliente
Cada repositório de cliente tem seu próprio CLAUDE.md que importa o da agência e adiciona especificidades do cliente: sua stack, sua hospedagem, seus plugins, suas convenções de time, sua voz editorial, seus plugins proibidos. Este arquivo tem tipicamente 100 a 200 linhas e muda quando o engajamento com o cliente muda de forma.
Usamos uma diretiva de include simples no topo: "## Agency standards" com um link para o arquivo da agência, depois "## Client-specific" com os overrides. Claude lê ambos porque ambos estão na árvore do projeto.
Camada 3: notas por engajamento
Contexto específico e limitado no tempo: a meta do sprint atual, os achados de descoberta ativa, o log de decisões recentes, a lista de questões abertas. Vive em CLAUDE_NOTES.md ou similar, atualizado semanalmente durante o engajamento, arquivado quando o engajamento fecha.
É aqui que a maioria das agências falha na higiene de CLAUDE.md. As duas primeiras camadas se mantêm arrumadas; a terceira se desvia e fica obsoleta. Resolvemos isso com uma cadência de revisão na sexta à tarde: cada engenheiro revisa seu CLAUDE_NOTES.md ativo e o atualiza ou o arquiva.
A lista de padrões proibidos que se compõe
O elemento de maior alavancagem do nosso CLAUDE.md em toda a agência é a lista de padrões proibidos. Vinte entradas, atualizadas trimestralmente. Exemplos da lista atual:
Nunca use eval() em nenhuma linguagem que enviamos.
Nunca use query_posts() em WordPress (use WP_Query em vez disso).WordPress (use WP_Query instead).
Nunca use any em TypeScript sem um comentário explícito "// suppressed: <reason>".
Nunca use document.write() em nenhum contexto.
Nunca faça commit de secrets no git, nunca, independentemente do branch.
Nunca use travessões em nenhum conteúdo voltado ao cliente (padrão operacional para evitar detecção por IA).
Nunca desabilite RLS nas tabelas Supabase para corrigir um bug.Supabase tables to fix a bug.
Nunca faça push direto para main (sempre use PR).
Nunca crie um novo arquivo quando um existente puder ser editado.
A lista se expande porque toda vez que um engenheiro quebra uma dessas regras, adicionamos a regra. Claude lê a lista de padrões proibidos a cada sessão e se recusa a gerar código que os viole. A classe de bugs que costumávamos enviar para staging desapareceu.
O que manter fora de CLAUDE.md
Cinco coisas que explicitamente não colocamos em arquivos CLAUDE.md de agências:
Atualizações de status do projeto. Ficam obsoletas; pertencem no Linear ou Notion.
Longa justificativa arquitetônica. Pertence em design docs; CLAUDE.md deve referenciá-las, não duplicá-las.
Segredos do lado do cliente, credenciais ou qualquer coisa sensível. Até arquivos CLAUDE.md privados são muito propensos a vazamentos.
Preferências pessoais de engenheiros individuais. Os padrões têm que ser em toda a agência; preferências específicas do engenheiro pertencem ao próprio .claude/settings.json.
Cópia de marketing ou linguagem de vendas. CLAUDE.md é contexto de engenharia; deve parecer escrito por um engenheiro sênior para outros engenheiros.
Como CLAUDE.md muda a equação de contratação
Um engenheiro sênior que consegue entregar em todo o portfólio de clientes sem ter que aprender cada projeto do zero em toda visita é dramaticamente mais valioso do que um que não consegue. O sistema de três camadas CLAUDE.md é o que torna isso possível. O tempo de onboarding para novos engenheiros caiu de aproximadamente 2 semanas de ramp específico do projeto para 3 dias porque as convenções estão codificadas em vez de serem tribais.
Mesmo engenheiro, mais output, menos imposto de onboarding, menos overhead de context-switch. O processo de hiring começou a trazer menos engenheiros juniores e mais seniores uma vez que tínhamos esse sistema em lugar porque engenheiros juniores não eram mais necessários para absorver o contexto específico do projeto que antes era a única forma de as convenções serem transferidas.
Resumindo
CLAUDE.md em escala de agência é um sistema em camadas: padrões em escala de agência como a base, overrides específicos do cliente no meio, notas por engajamento no topo. A lista de padrões proibidos é a seção com maior alavancagem. Evite conteúdo obsoleto na camada por engajamento com uma cadência de revisão nas sextas-feiras.
Implemente o modelo de três camadas e seus engenheiros vão parar de entregar output inconsistente em todo o portfólio. Pule isso e você está pagando por assistência de IA que produz trabalho diferente dependendo de qual projeto o engenheiro aconteceu de abrir por último.
Perguntas frequentes
O que é um arquivo CLAUDE.md?
CLAUDE.md é um arquivo de projeto que diz ao Claude Code seus padrões, stack e convenções para que seu output se encaixe no seu codebase. Em escala de agência, um arquivo único e plano por projeto não é suficiente, é por isso que usa um modelo de três camadas em vários repositórios de clientes.
Como você escala CLAUDE.md entre muitos projetos de clientes?
Com um modelo de três camadas: padrões em toda a agência que se aplicam em qualquer lugar, sobrescrita específica do cliente por conta e notas por engajamento para um projeto dado. O mesmo engenheiro consegue se mover entre seis repositórios de clientes em uma semana e ter o contexto certo em cada um sem rescrevê-lo.
O que não deve ir em CLAUDE.md?
Segredos, qualquer coisa que muda constantemente e ruído que dilui as regras importantes. Mantenha apenas padrões e convenções duráveis. Um CLAUDE.md inchado é ignorado; um enxuto e em camadas que deixa claro os padrões proibidos é o que realmente muda o output.
CLAUDE.md muda como você contrata?
Reduz o custo de onboarding. Quando padrões vivem em um CLAUDE.md em camadas, um engenheiro novo herda as convenções da agência através da ferramenta em vez de meses de conhecimento tribal. Desloca a contratação para julgamento e afasta da memorização de estilo de casa.