Claude Code para integração em bases de código: prompts que mapeiam seu app

O que você está tentando aprender (e o que pode esperar)

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:

• Quais são os módulos principais?
• Quais são os fluxos-chave que os usuários disparam?
• Onde estão as áreas de risco que podem quebrar produção ou causar bugs?

Onboarding suficiente em 1–2 dias não é "eu consigo explicar cada classe." É mais parecido com isto:

• Você consegue nomear os 5–8 módulos que importam e o que cada um possui.
• Você consegue traçar 2–3 fluxos reais de usuário de ponta a ponta (da entrada pela UI ou API até o banco e de volta).
• Você conhece os riscos principais (pagamentos, auth, gravações de dados, jobs em background) e onde eles ficam.
• Você consegue fazer uma pequena mudança com segurança porque sabe o que testar e quem perguntar.

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.

Trabalho de preparação: obter contexto sem fritar o oceano

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:

• Confirme acesso ao repo, permissões necessárias e como rodar os testes.
• Colete notas de setup do ambiente (env vars, seeds, feature flags) e onde logs e métricas são visualizados.
• Identifique os arquivos que são a verdade atual (README, notas de arquitetura, ADRs, runbooks).
• Defina o que está no escopo e o que está explicitamente fora do escopo para esta passagem de onboarding.
• Estabeleça regras de segurança: nunca cole segredos, chaves de API, tokens, dados privados de clientes ou logs de produção com detalhes sensíveis.

Se algo estiver faltando, registre como uma pergunta para um colega. Não "dê um jeitinho" no contexto faltante com palpites.

O mapa mental: o que capturar enquanto explora

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:

• Módulos: propósito, pontos de entrada, dependências, dono
• Fluxos chave: gatilho, passos, dados escritos, pontos de falha
• Dados: tabelas ou coleções tocadas, campos importantes, restrições
• Riscos: categoria, pior impacto, como monitorar, como reverter
• Perguntas em aberto: o que você ainda não sabe, quem perguntar

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.

Prompts passo a passo de Q&A para explorar uma base de código

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:

• Caminhos de arquivo e nomes de função
• Suposições e desconhecidos claramente apontados
• Dependências formuladas como "Se eu mudar X, o que quebra?"
• Uma pequena tarefa de leitura que você pode fazer em 10 minutos

Como capturar respostas para que sigam úteis

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.

Encontrando áreas de risco rápido (sem ler cada arquivo)

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:

• "List every place that enforces permissions for [resource X]. Which one is the final gate?"
• "Show the full path for writing [table/entity X]: API handler -> service -> DB call. Where are validations?"
• "What external integrations exist (payments, email, webhooks, third-party APIs)? Where are retries and timeouts set?"
• "Where can work run twice (queues, goroutines, cron)? What makes it idempotent?"
• "What can break silently, and how would we notice (logs, metrics, alerts, dashboards)?"

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.

Exemplo prático: mapeando um fluxo real de usuário

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.

Mapeie o fluxo do navegador até o banco

Comece na UI e ande para frente, um hop por vez. Peça nomes de arquivos, funções e shapes de request/response.

• "Find the React route or page for the login screen. What component renders it, and what action fires on submit?"
• "Where is the API client call made (fetch/axios/etc.)? What exact URL path, method, headers, and body does it send?"
• "On the Go side, where is the handler for that path registered? Show the router setup and the handler function."
• "Inside the handler, where does input validation happen (frontend, backend, both)? What rules exist, and where do errors get formatted?"
• "What database query runs for login? Point to the repository/SQL file, list touched tables/columns, and note any transactions or locks."

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."

Confirme com uma execução rápida

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.

Transforme o mapa mental em um documento curto de onboarding

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.

Estrutura simples de 1–2 páginas

Mantenha o doc previsível para que as pessoas encontrem coisas rápido. Uma boa estrutura é:

• Propósito: o que o app faz, quem o usa e o que significa "done"
• Resumo da arquitetura: serviços principais, stores de dados e como requisições atravessam o sistema
• Como rodar: pré-requisitos, o comando para iniciar e o comando para rodar testes
• Onde as coisas ficam: pastas que importam, mais os 5–10 arquivos que atuam como pontos de entrada
• Fluxos e riscos chave: traços curtos de jornadas importantes e o que validar após mudanças

Torne acionável, não acadêmico

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:

• Atualizar um ajuste de texto ou regra de validação em uma tela bem contida
• Adicionar um pequeno teste unitário em um helper complicado que você identificou
• Corrigir um bug de baixo risco com um repro claro e resultado esperado
• Adicionar uma guardrail: mensagem de erro melhor, checagem de input ou timeout
• Perguntar quem é o dono dos deploys de produção e quem acionar para dúvidas de domínio

Erros comuns e como evitá-los

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.

Mantenha os desconhecidos visíveis (para poder resolvê-los)

Use uma regra simples nas suas notas: toda afirmação deve ser marcada como uma destas categorias:

• Confirmado no código
• Confirmado rodando o app
• Suposição (precisa verificação)
• Desconhecido (contexto faltando)

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.

Não trate saídas como fatos

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.

Checklist rápido antes de dizer “estou onboarded”

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:

• Consegue explicar as cinco áreas mais importantes do código e o que cada uma possui (por exemplo: UI, camada API, jobs em background, acesso a dados, integrações)?
• Consegue caminhar por dois fluxos de alto valor de ponta a ponta e apontar o primeiro arquivo ou função que inicia cada jornada?
• Consegue apontar onde a autenticação é aplicada e onde roles ou permissões são definidas e checadas?
• Consegue nomear as gravações de banco mais arriscadas (dinheiro, permissões, deleção, transições de estado) e descrever como testaria cada mudança com segurança?
• Consegue entregar a um novo desenvolvedor uma nota curta de onboarding que possa ser lida em menos de 10 minutos e mostrar por onde começar?

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.

Próximos passos: manter o mapa atual e facilitar handoffs

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:

• Depois de cada feature: atualize a lista de módulos e os fluxos principais que ela tocou
• Depois de cada incidente: adicione o gatilho, impacto e o local exato do conserto
• Depois de cada refactor arriscado: note o que mudou e o que permaneceu compatível
• Antes de um release: re-cheque as 3 áreas de risco principais e caminhos de teste
• Uma vez por mês: delete notas obsoletas e confirme donos para módulos chave

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:

• O que ler primeiro (2–3 arquivos ou docs) e por quê
• O que rodar localmente (comandos, env vars, seed data)
• O que verificar (um happy path e um caso de falha)
• Onde estão as arestas vivas (módulos de risco, testes instáveis, configs delicadas)
• Quem perguntar sobre o quê (donos para fluxos chave)

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.