Explorar uma base de código desconhecida
Use o IBM Bob para entender rapidamente uma aplicação desconhecida — seu propósito, estrutura do projeto, arquitetura, stack tecnológica, componentes principais, cobertura de testes e modelo de implantação. Tudo isso sem depender de documentação desatualizada ou esperar por colegas.
Ganhar produtividade em uma base de código desconhecida normalmente significa horas lendo código, procurando documentação e pedindo contexto para colegas. Neste tutorial, você usa o Bob no modo Ask para interrogar sistematicamente a base de código do Galaxium Travels e extrair uma visão completa da aplicação: seu propósito e arquitetura, stack tecnológica, componentes principais, cobertura de testes unitários e de integração, e modelo de implantação. Em seguida, você troca para o modo Agent para salvar tudo que o Bob descobriu em uma referência Markdown persistente que toda a equipe pode usar.
O Galaxium Travels é uma aplicação intencionalmente complexa no estilo de um projeto real, com um frontend em React, um backend em Python FastAPI e um serviço de inventário em Java Spring Boot. Isso o torna um candidato ideal para este workflow.
A saída do Bob varia dependendo do estado atual da base de código. Trate os exemplos neste tutorial como pontos de partida representativos, não como transcrições exatas. Use-os para calibrar seus próprios prompts e refinar os resultados.
Funcionalidades principais que você aprende
- Modo Ask: Explore e analise código sem que o Bob modifique nenhum arquivo.
- Modo Agent: Deixe o Bob escrever arquivos de forma autônoma para persistir os artefatos gerados no seu projeto.
- Menções de contexto: Referencie
arquivos e pastas específicos com
@para dar ao Bob um escopo preciso de análise. /init: Inicialize o contexto do projeto para que o Bob entenda as convenções da base de código antes de você começar a fazer perguntas.
Pré-requisitos
Para concluir este tutorial, você precisa do seguinte:
- Bob IDE instalado.
- Git instalado localmente.
- Familiaridade com o básico do uso do Bob. Se você é novo no Bob, conclua primeiro o tutorial de início rápido.
Configurar seu workspace
Clonar o repositório Galaxium Travels
No terminal, clone o repositório de exemplo:
git clone https://github.com/IBM/galaxium-travels.gitAbrir o projeto de exemplo
No Bob IDE, abra a pasta galaxium-travels que você acabou de clonar. Se o Bob perguntar
"Do you trust the authors of the files in the folder?", clique em Yes, I trust
the authors.
Abrir a interface de chat do Bob
Se a interface de chat ainda não estiver aberta, clique no ícone do Bob na barra de navegação ou use o atalho Option + Command + B (Mac) ou Ctrl + Alt + B (Windows).
Inicializar o contexto do projeto
O Bob inicia no modo Agent por padrão. Antes de trocar de modo, execute o comando
/init para que o Bob leia o projeto e gere os arquivos de contexto AGENTS.md que
ele usa nas interações seguintes.
/initSe a aprovação automática estiver desativada, o Bob pedirá permissão para ler arquivos e
gravar os arquivos AGENTS.md. Aprove cada solicitação. O Bob cria um AGENTS.md na
raiz e uma pasta .bob/ com configuração específica por modo.
Revise o AGENTS.md gerado para confirmar que o Bob identificou corretamente a estrutura
de múltiplos serviços do repositório.
Trocar para o modo Ask
Selecione Ask no seletor de modo abaixo do campo de entrada do chat, ou digite /ask
para trocar de modo. O modo Ask é estritamente somente leitura. O Bob analisa arquivos, mas
não pode criar nem modificar nada, tornando-o o modo certo para todo o trabalho de exploração
neste tutorial.
Entender o propósito da aplicação e a estrutura do projeto
Comece com a pergunta mais abrangente: o que esta aplicação faz e como a base de código
está organizada? O Bob lê a estrutura do projeto e os arquivos principais, como
README.md, package.json, requirements.txt, arquivos de build e outros
arquivos de configuração. O Bob sintetiza um resumo conciso sem que você precise
rastrear manualmente cada diretório.
No modo Ask, insira o seguinte prompt:
What is the purpose of this application? Describe the project structure,
the high-level architecture, and the main responsibilities of each top-level
directory.O Bob lê a árvore de arquivos e os principais pontos de entrada, depois produz uma saída que inclui:
- Propósito da aplicação
- Responsabilidades dos diretórios de nível superior
- Uma sinopse do conteúdo de cada diretório de nível superior
- Diagrama de arquitetura de alto nível
Analisar a stack tecnológica
Com a estrutura de alto nível clara, aprofunde-se nas tecnologias exatas em uso. Este prompt é útil quando você precisa entender as ferramentas de build, avaliar escolhas de dependências ou estimar o escopo de atualizações.
No modo Ask, insira o seguinte prompt:
Analyze the tech stack for the entire application. For each service, list the
programming language, runtime version requirements, framework, key libraries,
database, and build/test tooling.O Bob inspeciona os arquivos de dependência e configuração de cada serviço e produz uma saída que inclui:
- Análise detalhada da stack tecnológica para cada serviço
- Identificação do framework de testes end-to-end
- Ferramentas adicionais do stack de CI/CD e scripts de implantação
- Um diagrama "Stack at a Glance" que resume visualmente a stack tecnológica em todos os serviços e camadas
Mapear os componentes principais
Entender a stack tecnológica diz o que uma base de código usa; entender os componentes principais diz como ela funciona. Este prompt pede ao Bob para rastrear os limites dos componentes e os fluxos de dados em todos os três serviços, o que é especialmente útil antes de fazer mudanças que cruzam limites de serviço.
No modo Ask, insira o seguinte prompt com menções de contexto para apontar o Bob aos arquivos mais relevantes:
Identify the key components of this application and explain how they interact.
Reference @booking_system_frontend/src/services,
@booking_system_backend/server.py,
@booking_system_backend/services,
@booking_system_backend/models.py,
and @booking_system_inventory_hold_service/src/main/java/com/galaxium/holdservice.
Describe the component responsibilities, the data flow for the booking
lifecycle, and any cross-service contracts I need to know before modifying
the codebase.O Bob rastreia a cadeia de interação e produz uma saída que contém:
- Responsabilidades detalhadas do frontend, API backend, camada de banco de dados e serviço hold em Java
- Um diagrama dos dois fluxos do ciclo de vida de reserva com interações de componentes anotadas
- Um resumo dos cinco contratos entre serviços que você deve conhecer antes de fazer mudanças
- Um mapa de interação de componentes
Avaliar a cobertura de testes unitários
Antes de adicionar funcionalidades ou refatorar, você precisa saber o que o conjunto de testes existente cobre e onde estão as lacunas. Este prompt pede ao Bob para ler os arquivos de teste e produzir uma avaliação de cobertura sem executar os testes.
No modo Ask, insira o seguinte prompt:
Analyze the unit test suites across all three services. Reference
@booking_system_backend/tests,
@booking_system_inventory_hold_service/src/test,
and @booking_system_frontend/src.
For each service, describe what is tested, which testing framework is used,
what the test structure looks like, and identify any obvious gaps where
critical logic appears to be untested.O Bob lê os arquivos de teste e produz uma análise detalhada do conjunto de testes que inclui:
- Framework de teste, classes testadas, número de testes por classe e o que é verificado por classe — para cada serviço
- Lacunas críticas nos testes
- Cobertura de testes ausente para lógica de negócios crítica
Avaliar a cobertura de testes de integração e end-to-end
Testes unitários dizem se os componentes individuais funcionam isoladamente; testes de integração e end-to-end dizem se os serviços funcionam corretamente juntos. Isso é especialmente importante para o Galaxium Travels porque o fluxo de confirmação de reserva abrange todos os três serviços.
No modo Ask, insira o seguinte prompt:
Analyze the end-to-end and integration test coverage. Reference
@tests_e2e and any cross-service test fixtures you can identify.
Describe which cross-service flows are covered, which are not, what test
infrastructure is required to run the suite, and what the tests assert
at the boundary level.O Bob lê o conjunto de testes end-to-end e gera uma análise detalhada de cobertura que inclui:
- Infraestrutura de teste e requisitos para executar o conjunto
- Testes de smoke
- Decisões de infraestrutura principais
- Fluxos entre serviços cobertos e não cobertos
- Asserções de teste no nível de fronteira
Revisar o modelo de implantação
Entender como uma aplicação é implantada (suas plataformas alvo, estratégia de containerização e automação de infraestrutura) é essencial antes de você se integrar como contribuidor ou antes de executar a aplicação em qualquer lugar além do seu laptop.
No modo Ask, insira o seguinte prompt:
Analyze the deployment model for this application. Reference
@docker-compose.yml, @deployment_scripts, @terraform, @.github/workflows,
and the deployment documentation in @docs.
Describe the supported deployment targets, how each service is containerized,
what infrastructure is provisioned, and how CI/CD is configured.O Bob lê os artefatos de implantação e produz uma análise do modelo de implantação. A análise inclui:
- Alvos de implantação suportados
- Estratégia de containerização para cada serviço
- Detalhes de provisionamento de infraestrutura
- Workflows de CI/CD
- Restrições e lacunas principais de implantação
Salvar suas descobertas no repositório
A análise produzida no modo Ask existe apenas na sessão de chat. Troque para o modo Agent para pedir ao Bob que grave um documento de referência de onboarding persistente no repositório, para que contribuidores futuros possam se beneficiar deste trabalho.
Trocar para o modo Agent
Selecione Agent no seletor de modo, ou digite /agent no campo de entrada do chat.
Criar a referência de onboarding
Peça ao Bob para consolidar tudo que descobriu em um único arquivo Markdown. O Bob tem o contexto completo da conversa e sintetiza as descobertas sem reler todos os arquivos.
Create a file called docs/ONBOARDING.md.
Create one section for each of these topics:
1. Application overview: purpose, project structure, high-level architecture, and the main responsibilities of each top-level directory.
2. Tech stack analysis, including a "Stack at a Glance" diagram.
3. Key components and their interactions, including a component interaction map.
4. Unit test coverage analysis.
5. End-to-end test coverage analysis.
6. Deployment model analysis.
Populate each section with everything you discovered in this session.
Use clear headings, Mermaid diagrams, and tables where appropriate. Keep the tone concise and technical.O Bob grava o arquivo. Se a aprovação automática estiver desativada, clique em Approve
quando o Bob solicitar permissão para gravar docs/ONBOARDING.md.
Verificar a saída
Abra docs/ONBOARDING.md no editor para confirmar que o documento contém todo
o conteúdo que você espera ver. Você também pode pedir ao Bob para visualizá-lo:
Show me a preview of docs/ONBOARDING.mdO Bob renderiza o Markdown na interface de chat. Revise o conteúdo quanto à precisão e completude antes de fazer o commit.
Fazer o commit do arquivo
Use seu workflow Git preferido para fazer o commit de docs/ONBOARDING.md no seu
repositório. O documento agora está disponível para todos os contribuidores e para
o próprio Bob em sessões futuras.
Resolução de problemas
A análise do Bob é superficial ou perde serviços
Por padrão, o Bob lê a estrutura do projeto e uma seleção de arquivos principais. Se a saída estiver faltando um serviço ou for menos detalhada do que o esperado, adicione menções de contexto explícitas para restringir o foco do Bob.
Por exemplo, se o serviço hold em Java não estiver refletido na análise da stack
tecnológica, adicione @booking_system_inventory_hold_service/pom.xml ao prompt:
Analyze the tech stack for @booking_system_inventory_hold_service/pom.xml
and add the Java hold service to the tech stack summary you produced earlier.O Bob não consegue encontrar arquivos de teste
Se o Bob relatar que não consegue encontrar arquivos de teste, use uma menção de contexto para apontar diretamente para os diretórios de teste:
Analyze the test coverage in @booking_system_backend/tests and
@tests_e2e. List every test file and summarize what each one covers.A análise de implantação do Bob omite um alvo
Os artefatos de implantação AWS, IBM Cloud e local estão espalhados por vários diretórios de nível superior. Se o resumo de implantação do Bob estiver incompleto, aponte-o para os diretórios específicos:
Review @deployment_scripts/aws, @terraform, @deployment_scripts/ibm, and
@.github/workflows. Update the deployment model summary to include all three
deployment targets./init gera um AGENTS.md vazio ou incorreto
Na raiz do workspace, o comando /init cria o contexto do projeto lendo arquivos
âncora como README.md, package.json, requirements.txt, pom.xml,
Makefile e manifestos similares. Se nenhum desses arquivos existir na raiz,
ou se a raiz do workspace estiver definida como um subdiretório, o Bob vê apenas
um fragmento do projeto e gera um AGENTS.md esparso ou incorreto.
Se o AGENTS.md gerado não refletir a estrutura de múltiplos serviços, verifique:
- Raiz do workspace: Confirme que
galaxium-travels/, e não um subdiretório comobooking_system_backend/, está aberto como raiz do workspace. Todos os três diretórios de serviço devem estar visíveis no nível superior. - Arquivos âncora ausentes: Se a raiz não tiver um
README.mdou outro manifesto, o/inittem pouco para ler. Adicione umREADME.mdna raiz com uma breve descrição do projeto e execute/initnovamente.
Após corrigir a raiz, execute /init novamente para regenerar os arquivos AGENTS.md.
Padronizar o comportamento do Bob
Padronize o comportamento do Bob em sua equipe usando arquivos de regras em nível de projeto que instruem o Bob a documentar seu código e lembrar de suas ações anteriores.
Gerar diagramas de arquitetura
Use o IBM Bob para analisar a base de código do Galaxium Travels e gerar diagramas de classes UML Mermaid, diagramas de sequência e diagramas de casos de uso. Aprenda a usar menções de contexto no modo Ask para explorar código e o modo Agent para salvar os resultados no seu repositório.