Onboarding do Claude Code: como integrar IA como um novo dev — 17 anos de lições

Se você acha que jogar um assistente de IA dentro de um codebase gigante resolve tudo magicamente, tenho uma notícia — e ela vem direto de quem esteve dos dois lados do balcão. Brendan MacLean, desenvolvedor principal do software Skyline na University of Washington, passou 17 anos construindo e mantendo um codebase de mais de 700 mil linhas de C# com 200 mil testes automatizados. Quando ele decidiu integrar o Claude Code no fluxo do laboratório, descobriu algo surpreendente: o problema é exatamente o mesmo de onboardar um desenvolvedor humano. E a solução também.

O problema que todo dev conhece

Quando Brendan começou a usar o Claude Code no navegador, funcionava bem para problemas isolados, mas, nas palavras dele, "ficava muito trabalhoso quando as mudanças ficavam mais incrementais". Cada sessão começava do zero — o Claude não sabia nada sobre o projeto, sobre as convenções do time, sobre os padrões de arquitetura que levaram 17 anos para amadurecer. Parece familiar?

Na minha visão, esse é o gargalo mais subestimado das ferramentas de IA para código. Todo mundo foca em "o modelo é inteligente o suficiente?", quando a pergunta real deveria ser: "o modelo tem contexto suficiente?"

Contexto como artefato versionado

A virada de chave veio quando Brendan tratou o contexto de IA como um artefato de projeto — não como um prompt descartável. Ele criou o repositório pwiz-ai, separado do codebase principal, que armazena toda a documentação, regras e conhecimento necessários para o Claude Code operar no projeto Skyline. Isso muda completamente a dinâmica: o contexto não morre quando a sessão termina.

O CLAUDE.md na raiz do projeto configura o ambiente e aponta para a documentação. Mas a mágica real está nas skills — elas seguem o princípio de "referenciar, não incorporar", apontando para uma base de conhecimento central em vez de duplicar conteúdo. É exatamente o oposto de jogar um prompt de 10 mil tokens no inicio de cada conversa.

A biblioteca de skills que mudou o jogo

O laboratório construiu skills especializadas que transformaram o Claude Code de um assistente genérico em um membro do time de fato. A skill skyline-development orienta sobre arquitetura e padrões do projeto. A skill version-control define convenções de commit e PR. E a skill debugging força análise de causa raiz antes de qualquer correção — com um gatilho explícito que diz "sempre carregue quando investigar bugs".

O mais interessante? A skill de debugging força o Claude a entender a causa raiz antes de sugerir qualquer correção. Isso não é só uma boa prática — é a aplicação direta de 17 anos ensinando novos desenvolvedores a não sair chutando código. Essa abordagem de skills modulares me lembrou muito o conceito do Caveman Mode, que também usa skills especializadas para cortar 65% dos tokens — a modularização do conhecimento é um padrão que está se consolidando.

MCP: onde contexto encontra dados reais

Mas contexto não é só documentação. Brendan levou a abordagem um passo além com integrações MCP. O Claude escreveu servidores MCP em C# e Python que acessam dados reais: resultados de testes automatizados, relatórios de exceção em produção e threads de suporte dos usuários do Skyline. O resultado? Um resumo diário gerado automaticamente que chega no email de Brendan antes do expediente.

Na minha opinião, essa é a camada que separa o amador do profissional na hora de integrar IA em um projeto de verdade. Não basta documentar — é preciso conectar o agente aos dados vivos do sistema. O artigo original da Anthropic explica isso em detalhes: Onboarding Claude Code like a new developer.

Resultados que falam por si

Os números são difíceis de ignorar. O painel Files View, que estava parado há mais de um ano por falta de tempo e contexto disponível, foi concluído em duas semanas usando Claude Code. O módulo de gerenciamento de testes noturnos, sem atualizações por três anos, ganhou funcionalidades novas em menos de um dia. Uma extensão de mobilogram pane foi construída e entregue por um desenvolvedor que antes era cético em relação a IA.

Mas o dado mais revelador para mim foi este: os desenvolvedores do laboratório hoje "mal escrevem código diretamente, instruindo o Claude Code em vez disso". Eles se tornaram orquestradores, não operadores. Isso muda completamente o que significa ser dev em um projeto de 700 mil linhas.

Por que isso importa para você

Três lições que tirei dessa história e que você pode aplicar no seu projeto hoje:

(1) Contexto não se improvisa. Se você quer produtividade real com IA, precisa investir em construir e manter uma base de conhecimento — exatamente como faria ao onboardar um novo desenvolvedor. (2) Skills são o formato certo. Em vez de um único prompt gigante, divida o conhecimento em módulos especializados que o agente carrega sob demanda. (3) Conecte o agente aos dados vivos. Servidores MCP não são buzzword — são a diferença entre um Claude que apenas "acha" e um que realmente "sabe".

Se você trabalha com codebases legados ou monorepos, essa história tem um valor prático imenso — porque o que funcionou para o Skyline, um dos maiores codebases acadêmicos do mundo, muito provavelmente vai funcionar para você também.

Conclusão

A frase que Brendan usou e que não sai da minha cabeça é simples e profunda: "contexto é só mais um artefato para manter e cultivar". Para codebases legacy, monorepos ou projetos open source, essa talvez seja a lição mais valiosa de 2026 sobre engenharia de software com IA. O Claude Code não é mágica — mas com o contexto certo, chega bem perto.