--- title: Entendendo código existente description: Usando Verdent para explorar, analisar e entender bases de código existentes --- Verdent for VS Code ajuda você a entender bases de código desconhecidas por meio de perguntas em linguagem natural e exploração automatizada. O subagente Explorer integrado encontra rapidamente arquivos, pesquisa padrões de código e responde a perguntas sobre arquitetura sem consumir sua janela de contexto principal. ### O que você vai aprender - Explorar bases de código desconhecidas usando o subagente Explorer - Fazer perguntas sobre a estrutura e a implementação do código - Obter explicações detalhadas de funções, classes e módulos - Gerar documentação a partir de código existente - Entender a arquitetura do projeto e o fluxo de dados - Integrar novos membros da equipe de forma eficiente ### Pré-requisitos Antes de usar Verdent para entender código: - Visual Studio Code com a extensão Verdent instalada - Uma base de código ou espaço de trabalho de projeto aberto no VS Code - Assinatura ativa do Verdent com créditos disponíveis --- ## Explorando bases de código desconhecidas Quando você faz perguntas sobre a estrutura da base de código ou solicita buscas de arquivos, Verdent delega automaticamente ao **subagente Explorer** (`@Explorer`), um especialista eficiente em tokens otimizado para a exploração rápida de bases de código. O subagente Explorer rapidamente: - Encontra arquivos que correspondem a padrões ou nomes - Pesquisa código por palavras-chave ou funções específicas - Responde a perguntas sobre arquitetura da base de código - Identifica onde uma funcionalidade está implementada **Exemplos de perguntas de exploração:** ``` What is the structure of this project? ``` ``` Where is user authentication handled? ``` ``` Find all API endpoint definitions ``` ``` Show me where database queries are defined ``` O Explorer trabalha de forma eficiente em segundo plano, fornecendo respostas rápidas sem consumir sua janela de contexto principal. Verdent apresenta os resultados com caminhos de arquivos relevantes e trechos de código. **Exploração paralela para tarefas complexas:** Para tarefas de exploração complexas, vários agentes Explorer podem ser executados em paralelo para economizar tempo, cada um investigando aspectos diferentes da base de código simultaneamente. Verdent então sintetiza os resultados em um resumo coerente. **Exemplo:** ``` Use the Explorer agent to find all places where we manually validate email addresses ``` Isso garante que Verdent descubra cada local sistematicamente, sem perder instâncias ao longo da base de código. --- ## Fazendo perguntas sobre seu código Verdent responde praticamente qualquer pergunta sobre sua base de código usando linguagem natural. A IA entende o contexto e fornece explicações, análises e insights detalhados. Pergunte como uma funcionalidade específica funciona: ``` Explain how authentication works in this project ``` ``` What does the calculateTotal function do? ``` ``` How are API requests handled? ``` Verdent analisa o código relevante, rastreia fluxos de execução e explica a implementação com referências a arquivos e números de linha específicos. Entenda o panorama geral do seu aplicativo: ``` What is the overall architecture of this application? ``` ``` How do the components communicate with each other? ``` ``` What design patterns are used in this codebase? ``` Verdent examina a estrutura do seu projeto, identifica padrões e explica decisões de arquitetura. Obtenha insights sobre decisões técnicas: ``` Why do you think Redux was chosen instead of Context API for state management? ``` ``` What would happen if I changed the API timeout from 30s to 60s? ``` ``` Is this validateUserInput function redundant? ``` Verdent analisa o contexto do código e fornece explicações fundamentadas com base nos padrões do seu projeto e nas melhores práticas do setor. Encontre funcionalidades ou dependências específicas: ``` Where is user data validated? ``` ``` Show me all database queries in the project ``` ``` What dependencies does this project have? ``` O subagente Explorer realiza buscas eficientes usando ferramentas como grep (busca de conteúdo) e glob (correspondência de padrões de arquivos), retornando resultados relevantes sem consumir o contexto principal. Entenda algoritmos e padrões: ``` How does the quicksort algorithm work in the sortItems function? ``` ``` What are the best practices for error handling in React components? ``` ``` Explain the Observer pattern implementation in the EventEmitter class ``` Verdent fornece explicações claras com referências a implementações específicas na sua base de código. --- ## Explicando funções e classes Verdent fornece explicações detalhadas de funções ou classes específicas, analisando sua implementação, parâmetros, valores de retorno e uso ao longo da base de código. **Exemplos:** ``` Explain the UserAuth class ``` ``` What does the processPayment function do? ``` ``` Break down the ApiService class methods ``` **O que Verdent explica:** - **Propósito**: o que a função ou classe realiza - **Parâmetros**: tipos de entrada, valores esperados e restrições - **Tipos de retorno**: tipos de saída e possíveis valores de retorno - **Lógica interna**: como a implementação funciona passo a passo - **Dependências**: módulos, funções ou serviços externos utilizados - **Exemplos de uso**: como a função/classe é usada em outras partes do seu código Verdent rastreia o fluxo de execução do código, identifica casos extremos e explica o raciocínio por trás das escolhas de implementação. --- ## Gerando documentação Verdent gera documentação em vários formatos, incluindo comentários inline no código (JSDoc, docstrings Python etc.), arquivos README, documentação de API e guias de arquitetura. #### Usando Plan Mode para documentação No Plan Mode, Verdent pode: - Analisar sua documentação existente para reproduzir seu estilo e densidade - Fazer perguntas para esclarecer preferências de formatação (estilo de comentário, nível de detalhe, inclusão de exemplos) - Analisar a base de código para entender os padrões de documentação atuais - Apresentar um plano de documentação mostrando o que será documentado e em que estilo **Exemplo:** ``` Generate JSDoc comments for all functions in the utils folder ``` Verdent examina os comentários JSDoc existentes no seu projeto, faz perguntas sobre preferências (descrições de parâmetros, inclusão de exemplos de uso) e então gera documentação que segue as convenções já estabelecidas. **Formatos de documentação suportados:** - **Comentários inline**: JSDoc, docstrings Python, Javadoc, comentários de documentação XML - **Arquivos README**: visões gerais do projeto, instruções de configuração, guias de uso - **Documentação de API**: descrições de endpoints, formatos de requisição/resposta, detalhes de autenticação - **Guias de arquitetura**: explicações de design do sistema, relações entre componentes, diagramas de fluxo de dados Use Plan Mode ao gerar documentação extensa. Verdent vai revisar o estilo da sua documentação existente e fazer perguntas para garantir que os documentos gerados sigam as convenções do seu projeto. Use Plan Mode ao gerar documentação para vários arquivos; revise a estrutura da documentação antes de fazer o commit. --- ## Resumindo arquivos e módulos Verdent analisa e resume arquivos ou módulos lendo o código, entendendo sua estrutura e explicando seu propósito em linguagem simples. **Exemplos:** ``` Summarize what the authMiddleware.js file does ``` ``` Explain the purpose of the UserService module ``` ``` What's the main responsibility of the PaymentController? ``` **O que Verdent fornece:** - **Propósito principal**: o que o arquivo/módulo realiza no sistema - **Funções principais**: funções ou métodos primários e seus papéis - **Dependências**: módulos e serviços externos utilizados - **Exports**: API públicas e o que outras partes do sistema podem acessar - **Padrões**: padrões de design ou abordagens de arquitetura utilizados - **Pontos de integração**: como ele se conecta a outras partes do projeto Verdent lê o arquivo, identifica funções-chave, rastreia dependências e explica como o código se encaixa na arquitetura geral do projeto. --- ## Entendendo a arquitetura Verdent explica a arquitetura por meio de descrições textuais detalhadas, relações entre componentes e explicações de fluxo de dados. Embora não gere diagramas gráficos diretamente, ele pode criar diagramas em ASCII art ou código de diagrama Mermaid que você pode renderizar. **Exemplo:** ``` Explain the architecture of this application and show component relationships ``` Verdent pode produzir uma representação em ASCII: ``` Frontend (React) ↓ API Layer (Express) ↓ Service Layer (Business Logic) ↓ Database Layer (PostgreSQL) ``` Ou gerar código Mermaid para renderização: ```mermaid graph TD A[React Frontend] --> B[API Gateway] B --> C[Auth Service] B --> D[User Service] C --> E[Database] D --> E ``` **As explicações de arquitetura incluem:** - **Interações entre componentes**: como diferentes partes do sistema se comunicam - **Fluxo de dados**: como as informações se movem pelo aplicativo - **Padrões de arquitetura**: MVC, microsserviços, arquitetura em camadas etc. - **Stack tecnológica**: frontend, backend, banco de dados, serviços externos - **Pontos de integração**: APIs, filas de mensagens, webhooks, serviços de terceiros - **Padrões de escalabilidade**: balanceamento de carga, cache, sharding de banco de dados Verdent analisa a estrutura do seu projeto, rastreia imports e dependências, identifica padrões e explica as decisões de arquitetura por trás do design do seu sistema. --- ## Integrando novos membros da equipe Verdent ajuda a integrar novos membros da equipe respondendo a perguntas sobre a base de código, explicando decisões de arquitetura, identificando arquivos e padrões importantes e gerando documentação adaptada para ajudar os recém-chegados a entender a estrutura e as convenções do projeto. **No Plan Mode**, Verdent pode fazer perguntas para esclarecer quais aspectos da base de código são mais relevantes para a função do novo membro da equipe antes de criar um guia de integração personalizado. **Exemplos de perguntas de integração:** ``` What's the best starting point for understanding this codebase? ``` ``` How does data flow from the API to the frontend? ``` ``` Where should I look to understand the authentication system? ``` ``` What are the naming conventions and code style guidelines used here? ``` **Verdent pode gerar:** - **Guias de integração**: passo a passo da arquitetura da base de código - **Mapas de componentes**: guias visuais ou textuais mostrando como os componentes se relacionam - **Padrões comuns**: documentação de padrões e convenções usados com frequência - **Instruções de configuração**: como configurar o ambiente de desenvolvimento e executar o projeto - **Primeiras tarefas**: sugestões de primeiras contribuições simples para ganhar familiaridade Novos membros da equipe podem explorar a base de código de forma conversacional, obtendo respostas imediatas sem precisar interromper desenvolvedores seniores ou passar horas lendo código. O subagente Explorer do Verdent torna a descoberta da base de código eficiente para recém-chegados. Eles podem fazer perguntas amplas como "Mostre-me todos os componentes React" ou consultas específicas como "Onde o registro de erros está implementado?" e obter respostas imediatas e precisas. --- ## Melhores práticas Comece com perguntas de alto nível como "Qual é a arquitetura?" antes de mergulhar em implementações específicas. Isso constrói o contexto progressivamente. Para buscas completas em toda a base de código, mencione explicitamente o agente Explorer para garantir que nenhuma instância seja perdida: "Use o Explorer para encontrar todas as verificações de autenticação." Entender o raciocínio por trás das decisões costuma ser mais valioso do que entender a implementação. Pergunte "Por que esse padrão foi escolhido?" junto com "O que esse código faz?" Ao gerar documentação, use Plan Mode para revisar a abordagem do Verdent, garantir que ela corresponda ao seu estilo e refinar o plano antes da execução. Referencie arquivos específicos quando quiser explicações detalhadas: "@components/UserProfile.tsx explique este componente" garante que Verdent foque no código certo. Antes de fazer modificações, peça ao Verdent para explicar a implementação atual. Isso ajuda Verdent a fazer sugestões melhores e alinhadas com os padrões existentes. Verdent mantém o contexto da conversa, então você pode fazer perguntas de esclarecimento, solicitar explicações mais profundas ou explorar tópicos relacionados sem repetir o contexto. --- ## Veja também Aprenda a escrever novos recursos e componentes com Verdent Melhore e refatore código existente com segurança com a ajuda da IA