Uma das coisas mais difíceis no nosso dia a dia é entender código que já existe, especialmente quando você entra em um repositório grande sem documentação e, em poucos minutos, percebe que não entendeu quase nada.
Foi assim que comecei a usar IA de forma prática, para construir meus próprios “learning docs” enquanto exploro o código. Em vez de sair lendo arquivo por arquivo sem direção, você usa a IA para montar um mapa do sistema, aos poucos.
Aqui vai uma sequência de prompts que tenho usado e que funciona bem em IDEs como Cursor.
Comece pela visão geral:
👉 “Analise a estrutura deste repositório. Qual é o propósito do projeto, quais são as principais tecnologias usadas e como os diretórios estão organizados? Salve a resposta em /learning-docs/structure.md”
Isso já te dá um mapa inicial.
Depois, avance para arquitetura e fluxo principal:
👉 “Qual é a arquitetura geral do projeto? Identifique os pontos de entrada (entry points), os módulos principais e como eles se conectam. Salve a resposta em /learning-docs/architecture.md”
Aqui você começa a enxergar como o sistema funciona de verdade.
Na sequência, entenda o modelo de dados:
👉 “Quais são as principais entidades/modelos de dados do projeto? Mostre os relacionamentos entre eles. Salve a resposta em /learning-docs/datamodel.md”
Se você entende o domínio, metade do problema já foi resolvido.
Agora, olhe para dependências e configuração:
👉 “Quais são as dependências externas mais importantes e qual é o papel de cada uma? Como o projeto é configurado (env vars, configs)? Salve a resposta em /learning-docs/config.md”
Até aqui, você já tem mais contexto do que muita gente que trabalha no projeto.
Depois, vá para padrões e convenções:
👉 “Quais design patterns e convenções de código este projeto segue? Há algo incomum ou não convencional? Salve a resposta em /learning-docs/patterns.md”
Em seguida, dê atenção aos testes:
👉 “Como os testes estão organizados? Qual é a estratégia de testes (unit, integration, e2e)? Há áreas com pouca cobertura? Salve a resposta em /learning-docs/tests.md”
Com esse panorama, vá fundo no que importa:
👉 “Explique em detalhe o módulo X. Qual é a sua responsabilidade, quais são suas classes/funções principais e como ele interage com o resto do sistema? Salve a resposta em /learning-docs/modules/X.md”
E, por fim:
👉 “Trace o fluxo completo de ‘funcionalidade X’ desde o ponto de entrada até o banco de dados ou resposta. Mostre cada arquivo e função envolvida. Salve a resposta em /learning-docs/traces/X.md”
Esse mapa não vai sair perfeito, e está tudo bem. O ponto é aprender mais rápido, ajustar ao longo do caminho e, no fim, deixar de se sentir perdido e passar a saber onde mexer.
É exatamente esse tipo de abordagem que tenho trabalhado na minha mentoria de arquitetura de software com ênfase em IA.