Claude Code para integração em bases de código: use prompts de perguntas e respostas para mapear módulos, fluxos principais e riscos, e transforme as notas em um curto documento de integração.
Ler arquivos aleatoriamente parece lento porque a maioria das bases de código não está organizada como uma história. Você abre uma pasta, vê dez nomes que parecem importantes, clica em um e acaba em helpers, configs e casos de borda. Depois de uma hora, tem muitos detalhes mas ainda não consegue explicar como o app funciona.
Um objetivo melhor para o Claude Code durante o onboarding é construir um mapa mental simples. Esse mapa deve responder três perguntas:
Onboarding suficiente em 1–2 dias não é "eu consigo explicar cada classe." É mais parecido com isto:
Algumas coisas podem esperar. Refatorações profundas, entendimento perfeito de cada abstração e ler código antigo que ninguém toca raramente trazem o retorno mais rápido.
Pense no onboarding como construir um mapa, não decorar ruas. Seus prompts devem sempre voltar a: "Onde estou no sistema, o que acontece a seguir e o que pode dar errado aqui?" Uma vez que você tenha isso, os detalhes ficam fáceis de aprender sob demanda.
Antes de começar a fazer perguntas, colete o básico que você normalmente precisa no primeiro dia. Claude Code funciona melhor quando pode reagir a arquivos reais, configuração real e comportamento que você pode reproduzir.
Comece com acesso e uma execução funcionando. Garanta que você consegue clonar o repo, instalar dependências e rodar o app (ou pelo menos uma parte pequena) localmente. Se o setup local for difícil, obtenha acesso a um ambiente de staging e ao local onde os logs ficam, para que você possa verificar o que o código realmente faz.
Em seguida, encontre os docs que servem como "fonte da verdade". Procure o que a equipe realmente atualiza quando as coisas mudam: um README, uma nota de arquitetura curta, uma pasta de ADRs, um runbook ou uma nota de deploy. Mesmo que estejam bagunçados, eles dão nomes a módulos e fluxos, o que torna o Q&A muito mais preciso.
Decida o escopo cedo. Muitos repositórios contêm múltiplos apps, serviços e pacotes compartilhados. Escolha limites como "apenas a API e o worker de billing" ou "apenas o web app e seu fluxo de auth." Escopo claro evita desvios intermináveis.
Escreva suposições que você não quer que o assistente adivinhe. Isso parece pequeno, mas evita modelos mentais errados que desperdiçam horas depois.
Aqui está uma simples checklist de preparação:
Se algo estiver faltando, registre como uma pergunta para um colega. Não "dê um jeitinho" no contexto faltante com palpites.
Um mapa mental é um pequeno conjunto de notas que responde: quais são as partes principais deste app, como elas conversam entre si e onde as coisas podem dar errado. Feito bem, o onboarding vira menos sobre navegar arquivos e mais sobre construir uma imagem que você pode reutilizar.
Comece definindo seus resultados. Você quer uma lista de módulos prática, não perfeita. Para cada módulo, capture o que ele faz, quem o mantém (time ou pessoa, se souber), e suas dependências chave (outros módulos, serviços, bancos, APIs externas). Anote também pontos de entrada principais: rotas UI, endpoints API, jobs em background e tarefas agendadas.
Em seguida, escolha algumas jornadas de usuário que importam. Três a cinco é suficiente. Escolha fluxos que envolvam dinheiro, permissões ou alterações de dados. Exemplos: cadastro e verificação de email, criação de um plano pago ou compra, uma ação administrativa que altera acesso de usuário e um fluxo crítico de uso diário que a maioria dos usuários depende.
Decida como você vai rotular risco antes de começar a coletar notas. Mantenha categorias simples para poder escanear depois. Um conjunto útil é segurança, integridade de dados, disponibilidade e custo. Quando você marcar algo como arriscado, adicione uma frase explicando por quê, além do que provaria que está seguro (um teste, um log, uma checagem de permissão).
Use um formato consistente para que você possa transformar as notas em um doc de integração sem reescrever tudo:
Exemplo: se Checkout chama Billing que grava em payments e invoices, marque como integridade de dados e custo. Então anote onde os retries acontecem e o que evita cobranças duplas.
Quando você entra em um novo repo, quer orientação rápida, não entendimento perfeito. Esses prompts ajudam você a construir um mapa mental em passos pequenos e seguros.
Comece dando ao assistente a árvore do repo (ou um subconjunto colado) e peça um tour. Mantenha cada rodada focada e termine com uma pergunta que diga o que ler em seguida.
1) Repo tour
"Here is the top-level folder list: <paste>. Explain what each folder likely contains and which ones matter for core product behavior."
2) Entry points
"Find the app entry points and boot process. What files start the app, set up routing, configure DI/env, and start background jobs? Name the exact files and what they do."
3) Module index
"Create a module index: module name, purpose, key files, and important external dependencies. Keep it to the modules that affect user-facing behavior."
4) Data model hints
"Based on migrations/models, list the key tables/entities, critical fields, and relationships. Call out fields that look security-sensitive or used for billing/permissions."
5) Flow trace
"Trace this flow end-to-end: <flow>. Where does the request/event start, where does it end, and what does it call in between? List the main functions/files in order."
6) Next inspection
"What should I inspect next and why? Give me 3 options: fastest clarity, riskiest area, and best long-term payoff."
Um exemplo concreto: se você está mapeando "usuário se cadastra e cria o primeiro projeto", peça o handler da rota da API, validação, gravação no BD e qualquer job assíncrono que envie emails ou provisione recursos. Em seguida, rode de novo o trace para "usuário deleta projeto" para achar lacunas de limpeza.
Para manter respostas acionáveis, peça artefatos específicos, não apenas resumos:
O maior ganho no onboarding é transformar Q&A disperso em notas que outro desenvolvedor pode reutilizar. Se as notas só fizerem sentido para você, você vai refazer a mesma investigação depois.
Uma estrutura simples vence páginas longas. Depois de cada sessão de exploração, salve as respostas em cinco artefatos pequenos (um arquivo ou doc basta): uma tabela de módulos, um glossário, fluxos chave, desconhecidos e um registro de riscos.
Aqui está um template compacto que você pode colar nas suas notas e preencher conforme avança:
Module table
- Module:
Owns:
Touches:
Entry points:
Glossary
- Term:
Meaning:
Code name(s):
Key flow (name)
1.
2.
3.
Unknowns
- Question:
Best person to ask:
Where to look next:
Risk register
- Risk:
Location:
Why it matters:
How to verify:
Mantenha os fluxos curtos de propósito. Exemplo: 1) usuário faz login, 2) backend cria uma sessão, 3) cliente carrega o dashboard, 4) API busca dados, 5) UI renderiza e trata erros. Se não couber em cinco passos, separe (login vs carregamento do dashboard).
Ao usar Claude Code, adicione uma linha a cada resposta: "How would I test this?" Essa única linha transforma notas passivas em um checklist que você pode rodar depois, especialmente quando desconhecidos e riscos se sobrepõem.
Se você está construindo em uma plataforma de vibe-coding como Koder.ai, esse tipo de anotação também ajuda a ver onde mudanças geradas podem ter efeitos colaterais. Módulos com muitos pontos de contato tendem a ser ímãs de mudanças.
Risco em uma base de código raramente é aleatório. Ele se concentra onde o app decide quem você é, altera dados, fala com outros sistemas ou executa trabalho em background. Você pode encontrá-lo com perguntas direcionadas e algumas buscas focadas.
Comece pela identidade. Pergunte onde a autenticação ocorre (login, sessão, tokens) e onde as decisões de autorização vivem (checagens de role, feature flags, regras de propriedade). Uma armadilha comum é checagens espalhadas entre UI, handlers da API e consultas ao banco sem uma fonte única de verdade.
Depois, mapeie os caminhos de escrita. Encontre endpoints ou funções que criam, atualizam ou deletam registros, além das migrations que remodelam dados ao longo do tempo. Inclua jobs em background também. Muitos bugs misteriosos vêm de workers assíncronos escrevendo valores inesperados bem depois de uma requisição terminar.
Prompts que surfacem risco rapidamente:
Depois verifique configuração e tratamento de segredos. Procure por environment variables, arquivos de configuração em runtime e valores padrão. Defaults são úteis, mas arriscados quando escondem mau-config (por exemplo, usar uma chave de dev em produção porque um valor faltou).
Um exemplo rápido: em um backend Go com PostgreSQL, você pode achar um job de "enviar email" que faz retries em falha. Se fizer retries sem uma chave de idempotência, usuários podem receber emails duplicados. Se falhas só são logadas como aviso e não há alerta, quebra silenciosamente. Essa é uma área de alto risco que vale documentar e testar cedo.
Use um fluxo real para construir seu primeiro fio de ponta a ponta pelo sistema. Login é um bom começo porque toca roteamento, validação, sessões ou tokens e leituras de banco.
Cenário: um app React chama uma API em Go, e a API lê e escreve no PostgreSQL. Seu objetivo não é entender cada arquivo. É responder: "Quando um usuário clica em Login, que código roda em seguida, que dados se movem e o que pode quebrar?" Isso mantém o onboarding concreto.
Comece na UI e ande para frente, um hop por vez. Peça nomes de arquivos, funções e shapes de request/response.
Depois de cada resposta, escreva uma linha curta no seu mapa mental: "UI component -> API endpoint -> handler -> service -> DB query -> response." Inclua os nomes, não apenas "uma função."
Quando tiver o caminho, verifique com um teste pequeno. Você está checando que o caminho de código que mapeou é o que o app realmente usa.
Observe requisições de rede nas dev tools do navegador (path, código de status, body da resposta). Adicione ou habilite logs no servidor ao redor do handler e da chamada ao DB (request ID, se disponível). Consulte o PostgreSQL para mudanças esperadas (no login, talvez last_login_at, sessions ou linhas de auditoria). Force uma falha (senha errada, campo faltando) e anote onde a mensagem de erro é criada e onde é exibida. Registre respostas esperadas para sucesso e falha (códigos de status e campos chave), para que o próximo desenvolvedor possa checar rapidamente.
Esse único fluxo frequentemente expõe limites de ownership: o que a UI confia, o que a API impõe e onde erros desaparecem ou são tratados em duplicidade.
Quando tiver um mapa mental decente, congele-o em uma nota de 1–2 páginas. O objetivo não é ser completo. É ajudar o próximo desenvolvedor a responder: o que é este app, onde eu procuro primeiro e o que tem mais probabilidade de quebrar?
Se estiver usando Claude Code, trate o documento como o resultado do seu Q&A: claro, concreto e fácil de escanear.
Mantenha o doc previsível para que as pessoas encontrem coisas rápido. Uma boa estrutura é:
Para "Onde as coisas ficam", inclua apontamentos como "Auth começa em X, lógica de sessão em Y, rotas UI em Z." Evite despejar a árvore completa. Escolha só o que as pessoas vão tocar.
Para "Fluxos chave", escreva 4–7 passos por fluxo: gatilho, controller/handler, módulo central, chamada ao banco e o efeito externo (email enviado, estado atualizado, job enfileirado). Adicione nomes de arquivos em cada passo.
Para "Áreas de risco", nomeie o modo de falha e a checagem de segurança mais rápida (um teste específico, um smoke run ou um log para observar).
Termine com uma pequena lista de primeiras tarefas para que alguém contribua com segurança:
A forma mais rápida de desperdiçar um assistente é pedir "uma explicação completa de todo o repo." Você recebe um resumo longo que parece confiante mas permanece vago. Em vez disso, escolha uma fatia pequena que importa (um módulo mais um fluxo de usuário), depois expanda.
Um segundo erro comum é não dizer quais jornadas importam. Se você não disser "checkout," "login" ou "edição admin", as respostas escorregam para arquétipos genéricos. Comece cada sessão com um objetivo concreto: "Me ajude a entender o fluxo de signup de ponta a ponta, incluindo validação, estados de erro e onde os dados são armazenados."
Outra armadilha é deixar o assistente chutar. Quando algo não estiver claro, force-o a rotular a incerteza. Peça para separar o que pode provar no código do que está inferindo.
Use uma regra simples nas suas notas: toda afirmação deve ser marcada como uma destas categorias:
Notas também desandam quando são coletadas sem estrutura. Um monte de trechos de chat é difícil de transformar em um mapa mental. Mantenha um template consistente: módulos envolvidos, ponto de entrada, funções e arquivos chave, dados tocados, efeitos colaterais, caminhos de erro e testes a rodar.
Mesmo com Claude Code, trate a saída como rascunho. Verifique fluxos chave no app em execução, especialmente as partes que podem quebrar produção: auth, pagamentos, permissões, jobs em background e migrations.
Um exemplo prático: se o assistente diz "reset de senha envia email via X," confirme acionando um reset em ambiente dev e checando logs ou sandbox de email. Essa checagem evita que você entre em um onboarding baseado em uma história que não é verdadeira.
Você não precisa memorizar o repo. Precisa de confiança suficiente para fazer uma mudança segura, depurar um problema real e explicar o sistema para a próxima pessoa.
Antes de se declarar onboarded, assegure que consegue responder sem chutes:
Se faltar um item, faça uma passada focada em vez de uma busca ampla. Escolha um fluxo, siga-o até a fronteira do banco, então pare e escreva o que aprendeu. Quando algo estiver incerto, capture como pergunta, não um parágrafo. "Onde a role X é criada?" é mais útil que "auth está confuso."
Um bom teste final: imagine que pediram para você adicionar uma pequena feature atrás de uma flag. Se você consegue nomear os arquivos que tocaria, os testes que executaria e os modos de falha que observaria, você está suficientemente onboarded para contribuir com responsabilidade.
Um mapa mental só é útil enquanto corresponder à realidade. Trate-o como um artefato vivo, não uma tarefa única. A forma mais fácil de mantê-lo honesto é atualizá-lo logo após mudanças que afetam comportamento.
Uma rotina leve vence grandes reescritas. Vincule atualizações ao trabalho que já está fazendo:
Mantenha o doc de integração próximo ao código e versionado com a mesma disciplina do código. Diffs pequenos são lidos. Rewrites grandes geralmente são ignorados.
Quando deploys são arriscados, escreva o que ajudaria o próximo a recuperar rápido: o que mudou, o que observar e como reverter. Se sua plataforma suporta snapshots e rollback, adicione o nome do snapshot, motivo e como "bom" parece depois do conserto.
Se você construir com Koder.ai (koder.ai), o modo de planejamento pode ajudar a rascunhar um mapa de módulos e uma nota de onboarding consistente a partir do seu Q&A, e a exportação de código-fonte dá aos revisores uma forma limpa de validar o resultado.
Finalmente, defina uma checklist de handoff que o próximo desenvolvedor possa seguir sem adivinhar:
Feito direito, Claude Code para integração em bases de código vira hábito: cada mudança deixa um mapa mais claro para a próxima pessoa.
Almeje um mapa mental utilizável, não compreensão total.
Um resultado sólido em 1–2 dias é:
Forneça artefatos concretos para que o assistente aponte para código real em vez de chutar:
Escolha um recorte estreito com limites claros.
Um escopo padrão bom é:
Escreva o que está explicitamente fora do escopo (outros serviços, módulos legados, features raramente usadas) para evitar desvios do assistente.
Comece por gatilhos conhecidos e ande para frente:
Peça caminhos com nomes de arquivos e funções em ordem, e termine com: “Como eu testaria isso rapidamente?”
Olhe onde o sistema decide quem é o usuário ou altera estado:
Use um sistema simples de rótulos e anexe um passo de verificação.
Exemplo de formato:
Force o assistente a separar evidência de inferência.
Peça para marcar cada afirmação como:
Quando algo for desconhecido, transforme em pergunta para um colega (“Onde a role X é definida?”) em vez de preencher com um chute.
Mantenha uma nota leve com cinco seções:
Faça uma checagem rápida e real:
Isso valida que você mapeou o caminho que o app realmente usa.
Use recursos da plataforma para diminuir riscos e manter revisões claras.
Práticas recomendadas:
Pergunte: “O que pode quebrar silenciosamente, e como notaríamos?”
Mantenha curto para atualizar conforme aprende.
Adicione uma linha a cada fluxo: “Como eu testaria isso?” para virar um checklist.
Isso funciona bem para tarefas de integração como “adicionar um guardrail”, “apertar validação” ou “melhorar uma mensagem de erro”.