Claude Code em codebases gigantes: o playbook da Anthropic para legacy e monorepos

Li o último artigo da Anthropic sobre como o Claude Code funciona em codebases grandes — monorepos com milhões de linhas, legacy de décadas, dezenas de microserviços — e a tese principal me bateu forte: o harness importa tanto quanto o modelo. Quem está esperando que o próximo Sonnet ou Opus resolva sozinho um monorepo de 5 milhões de linhas vai continuar travado. O que separa os times que escalaram dos que não escalaram é a infra ao redor do modelo — CLAUDE.md, hooks, skills, plugins e MCP servers — e a disciplina de manter essa infra viva.

O que mudou: o harness pesa tanto quanto o modelo

A Anthropic descreve cinco pontos de extensão que formam o harness: CLAUDE.md (contexto carregado automaticamente), hooks (scripts que disparam em momentos-chave), skills (expertise empacotada e carregada sob demanda), plugins (bundles de tudo isso distribuíveis pela organização) e MCP servers (conexões com ferramentas internas). Cada um resolve uma classe diferente de problema. Eu venho montando esse stack no meu fluxo há meses e a diferença é absurda — uma skill bem escrita transforma uma tarefa que exigia 20 minutos de prompt engineering em uma chamada de uma linha.

Por onde começar: a sequência que a Anthropic recomenda

A ordem proposta é: CLAUDE.md primeiro (fundação contextual), hooks em seguida (automação e captura de aprendizados), skills depois (expertise reutilizável), plugins para distribuir, LSP para precisão a nível de símbolo e MCP para integrar tooling interno. Subagents entram só depois que o básico está rodando, separando exploração (read-only) de edição (write). Eu vejo muita gente querendo começar pelo MCP — montando integrações com Jira, Notion, banco — antes de ter um CLAUDE.md decente. É a ordem errada. O fundamento é o contexto que o modelo carrega sem você pedir, e quem pula essa parte fica reescrevendo o mesmo prompt todo dia.

CLAUDE.md sem bloat: a regra das revisões periódicas

O conselho mais subestimado do artigo, na minha visão: revisar o CLAUDE.md a cada três ou seis meses e aposentar instruções que existiam só para compensar limitações de modelos antigos. Regras tipo "sempre quebre refatorações em mudanças de um arquivo só" travam modelos novos que conseguem fazer edições cross-file com qualidade. CLAUDE.md inchado degrada performance porque competir por contexto em toda sessão é caro. A separação prática que adotei: convenções específicas do projeto vão pro CLAUDE.md, expertise reutilizável vai pra skills (como o Caveman Mode que documentei aqui), e tudo que é orquestração inter-projetos vira plugin. Sem essa hierarquia, qualquer arquivo cresce sem freio.

Por que RAG perde para agentic search em escala

Esse é o ponto que eu acho que vai dividir águas. A Anthropic é categórica: pipelines de embedding não conseguem acompanhar o ritmo de um time ativo. O índice fica desatualizado em horas — retorna funções que foram renomeadas, módulos que foram deletados, e pior, sem nenhum indicador de que a resposta está velha. Agentic search resolve isso porque navega o filesystem do jeito que um engenheiro humano navegaria: lê arquivos, faz grep, abre o que faz sentido. Não precisa de índice mantido, não precisa de pipeline de ingestão. Quem ainda está investindo pesado em RAG sobre código fonte está construindo dívida — não diferencial.

A camada organizacional que ninguém quer assumir

A parte mais incômoda do artigo é a que fala sobre organização. A Anthropic insiste: alguém precisa ser o DRI do Claude Code dentro da empresa. Sem dono, configurações boas ficam isoladas em quatro ou cinco devs, e o resto do time reinventa a mesma roda. Plugins existem exatamente para isso — empacotar setup que funciona e distribuir via marketplace gerenciado, com política de skills/plugins aprovados, requisitos de code review e limite inicial de acesso. É menos sexy do que falar de modelo novo, mas é o que separa empresa que adota IA em produção da empresa que tem uma horda de devs usando Cursor por conta própria sem ninguém saber.

Por que isso importa pra você

Três coisas que tirei na leitura para aplicar amanhã: (1) se você ainda não tem CLAUDE.md no projeto, esse é o seu próximo PR — se ainda nem instalou o Claude Code, comece pelo guia que escrevi aqui; (2) revise CLAUDE.md a cada três meses, sem dó — instrução que existia pra Sonnet 4.0 provavelmente atrapalha o Opus 4.7; (3) se o time é maior que três pessoas, escolha um DRI para harness antes do hype virar bagunça, porque a alternativa é cada um ter o seu fork de prompt e ninguém compartilhar nada que funciona.

Conclusão

A leitura completa do post está no blog oficial da Anthropic e vale o investimento — mas o ponto que mais me marcou eu reforço aqui: você não compra produtividade com IA, você constrói. CLAUDE.md, hooks, skills, plugins e MCP são tijolos. O modelo é o cimento. Sem o trabalho de erguer parede, o cimento escorre — e o time inteiro acaba lutando contra o próprio harness que ninguém manteve.