Esplorare una codebase sconosciuta
Usa IBM Bob per comprendere rapidamente un'applicazione sconosciuta, come il suo scopo, la struttura del progetto, l'architettura, il tech stack, i componenti chiave, la copertura dei test e il modello di distribuzione. Senza dover dipendere da documentazione obsoleta o aspettare i tuoi colleghi.
Diventare produttivi in una codebase sconosciuta richiede di solito ore di lettura del codice, ricerca di documentazione e domande ai colleghi. In questo tutorial, usi Bob in modalità Ask per interrogare sistematicamente la codebase di Galaxium Travels e ricavare un quadro completo dell'applicazione: scopo e architettura, tech stack, componenti chiave, copertura dei test unitari e di integrazione, e il modello di distribuzione. Poi passi alla modalità Agent per salvare tutto ciò che Bob ha scoperto in un riferimento Markdown persistente che tutto il tuo team può utilizzare.
Galaxium Travels è un'applicazione intenzionalmente complessa, in stile reale, con un frontend React, un backend Python FastAPI e un servizio di inventario Java Spring Boot. Questo la rende un candidato ideale per questo workflow.
L'output di Bob varia a seconda dello stato attuale della codebase. Considera gli esempi in questo tutorial come punti di partenza rappresentativi, non come trascrizioni esatte. Usali per calibrare i tuoi prompt e affinare i risultati.
Funzionalità chiave che imparerai
- Modalità Ask: Esplorare e analizzare il codice senza che Bob modifichi alcun file.
- Modalità Agent: Lasciare che Bob scriva file in modo autonomo per salvare gli artefatti generati nel tuo progetto.
- Context mentions: Referenziare file e
cartelle specifici con
@per dare a Bob un ambito preciso per l'analisi. /init: Inizializzare il contesto del progetto in modo che Bob comprenda le convenzioni della codebase prima di iniziare a fare domande.
Prerequisiti
Per completare questo tutorial, hai bisogno di:
- Bob IDE installato.
- Git installato localmente.
- Familiarità con le basi di Bob. Se sei nuovo su Bob, completa prima il tutorial di avvio rapido.
Configurare il workspace
Clonare il repository di Galaxium Travels
Nel tuo terminale, clona il repository di esempio:
git clone https://github.com/IBM/galaxium-travels.gitAprire il progetto di esempio
Nel Bob IDE, apri la cartella galaxium-travels appena clonata. Se Bob chiede
"Do you trust the authors of the files in the folder?", clicca su Yes, I trust
the authors.
Aprire l'interfaccia di chat di Bob
Se l'interfaccia di chat non è già aperta, clicca sull'icona di Bob nella barra di navigazione o usa la scorciatoia Option + Command + B (Mac) o Ctrl + Alt + B (Windows).
Inizializzare il contesto del progetto
Bob usa la modalità Agent come impostazione predefinita all'avvio. Prima di cambiare
modalità, esegui il comando /init in modo che Bob legga il progetto e generi i file
di contesto AGENTS.md che usa nelle interazioni successive.
/initSe l'approvazione automatica è disabilitata, Bob chiede il permesso di leggere file e
scrivere i file AGENTS.md. Approva ogni richiesta. Bob crea un AGENTS.md a livello
radice e una cartella .bob/ con la configurazione specifica per ogni modalità.
Esamina l'AGENTS.md generato per confermare che Bob abbia identificato correttamente
la struttura multi-servizio del repository.
Passare alla modalità Ask
Seleziona Ask nel selettore di modalità sotto il campo di input della chat, o digita
/ask per cambiare modalità. La modalità Ask è strettamente in sola lettura. Bob analizza
i file ma non può creare o modificare nulla, rendendola la modalità giusta per tutto il
lavoro di esplorazione in questo tutorial.
Comprendere lo scopo dell'applicazione e la struttura del progetto
Inizia con la domanda più ampia: cosa fa questa applicazione e come è organizzata la
codebase? Bob legge la struttura del progetto e i file chiave, come README.md,
package.json, requirements.txt, file di build e altri file di configurazione. Bob
sintetizza un riassunto conciso senza che tu debba tracciare manualmente ogni directory.
In modalità Ask, inserisci il seguente 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.Bob legge l'albero dei file e i principali punti di ingresso, quindi produce un output che include:
- Scopo dell'applicazione
- Responsabilità delle directory di primo livello
- Un riepilogo dei contenuti di ogni directory di primo livello
- Diagramma dell'architettura ad alto livello
Analizzare il tech stack
Con la struttura ad alto livello chiara, approfondisci le tecnologie esatte in uso. Questo prompt è utile quando devi comprendere gli strumenti di build, valutare le scelte delle dipendenze o stimare la portata degli aggiornamenti.
In modalità Ask, inserisci il seguente 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.Bob ispeziona i file di dipendenze e configurazione per ogni servizio e produce un output che include:
- Analisi dettagliata del tech stack per ogni servizio
- Identificazione del framework di test end-to-end
- Strumenti aggiuntivi dallo stack CI/CD e dagli script di distribuzione
- Un diagramma "Stack at a Glance" che riassume visivamente il tech stack su tutti i servizi e livelli
Mappare i componenti chiave
Comprendere il tech stack dice cosa usa una codebase; comprendere i componenti chiave dice come funziona. Questo prompt chiede a Bob di tracciare i confini dei componenti e i flussi di dati tra tutti e tre i servizi, il che è particolarmente utile prima di apportare modifiche che attraversano i confini dei servizi.
In modalità Ask, inserisci il seguente prompt con le context mentions per puntare Bob verso i file più pertinenti:
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.Bob traccia la catena di interazione e produce un output che contiene:
- Responsabilità dettagliate del frontend, dell'API backend, del layer database e del servizio hold Java
- Un diagramma dei due flussi del ciclo di vita della prenotazione con le interazioni dei componenti annotate
- Un riepilogo dei cinque contratti tra servizi da conoscere prima di apportare modifiche
- Una mappa di interazione dei componenti
Valutare la copertura dei test unitari
Prima di aggiungere funzionalità o di effettuare il refactoring, devi sapere cosa copre la suite di test esistente e dove sono le lacune. Questo prompt chiede a Bob di leggere i file di test e produrre una valutazione della copertura senza eseguire i test.
In modalità Ask, inserisci il seguente 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.Bob legge i file di test e produce un'analisi dettagliata della suite di test che include:
- Framework di test, classi testate, numero di test per classe e cosa viene verificato per classe per ogni servizio
- Lacune critiche nei test
- Copertura di test mancante per la logica di business critica
Valutare la copertura dei test di integrazione ed end-to-end
I test unitari indicano se i singoli componenti funzionano in isolamento; i test di integrazione ed end-to-end indicano se i servizi funzionano correttamente insieme. Questo è particolarmente importante per Galaxium Travels perché il flusso di conferma della prenotazione si estende su tutti e tre i servizi.
In modalità Ask, inserisci il seguente 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.Bob legge la suite di test end-to-end e genera un'analisi dettagliata della copertura che include:
- Infrastruttura di test e requisiti per eseguire la suite
- Smoke test
- Decisioni chiave sull'infrastruttura
- Flussi tra servizi coperti e non coperti
- Asserzioni dei test a livello di confine
Esaminare il modello di distribuzione
Capire come viene distribuita un'applicazione (le piattaforme di destinazione, la strategia di containerizzazione e l'automazione dell'infrastruttura) è essenziale prima di entrare come contributore o prima di eseguire l'applicazione in ambienti diversi dal tuo computer.
In modalità Ask, inserisci il seguente 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.Bob legge gli artefatti di distribuzione e produce un'analisi del modello di distribuzione. L'analisi include:
- Target di distribuzione supportati
- Strategia di containerizzazione per ogni servizio
- Dettagli di provisioning dell'infrastruttura
- Workflow CI/CD
- Vincoli e lacune chiave della distribuzione
Salvare i risultati nel repository
L'analisi prodotta in modalità Ask esiste solo nella sessione di chat. Passa alla modalità Agent per chiedere a Bob di scrivere un documento di riferimento di onboarding persistente nel repository, in modo che i futuri contributori possano beneficiare di questo lavoro.
Passare alla modalità Agent
Seleziona Agent nel selettore di modalità, o digita /agent nel campo di input
della chat.
Creare il riferimento di onboarding
Chiedi a Bob di consolidare tutto ciò che ha scoperto in un unico file Markdown. Bob ha il contesto completo della conversazione e sintetizza i risultati senza rileggere tutti i file.
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.Bob scrive il file. Se l'approvazione automatica è disabilitata, clicca su Approve
quando Bob chiede il permesso di scrivere docs/ONBOARDING.md.
Verificare l'output
Apri docs/ONBOARDING.md nell'editor per confermare che il documento contenga tutto il
contenuto che ti aspetti di vedere. Puoi anche chiedere a Bob di mostrarne un'anteprima:
Show me a preview of docs/ONBOARDING.mdBob visualizza il Markdown nell'interfaccia di chat. Verifica il contenuto per accuratezza e completezza prima di fare il commit.
Fare il commit del file
Usa il tuo flusso di lavoro Git preferito per fare il commit di docs/ONBOARDING.md nel
tuo repository. Il documento è ora disponibile per ogni contributore e per Bob stesso
nelle sessioni future.
Risoluzione dei problemi
L'analisi di Bob è superficiale o non rileva alcuni servizi
Per impostazione predefinita, Bob legge la struttura del progetto e una selezione di file chiave. Se nell'output manca un servizio o è meno dettagliato del previsto, aggiungi context mentions esplicite per affinare il focus di Bob.
Ad esempio, se il servizio hold Java non compare nell'analisi del tech stack, aggiungi
@booking_system_inventory_hold_service/pom.xml al 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.Bob non riesce a trovare i file di test
Se Bob segnala di non riuscire a trovare i file di test, usa una context mention per puntare direttamente alle directory dei test:
Analyze the test coverage in @booking_system_backend/tests and
@tests_e2e. List every test file and summarize what each one covers.L'analisi di distribuzione di Bob omette un target
Gli artefatti di distribuzione AWS, IBM Cloud e locali sono distribuiti su più directory di primo livello. Se il riepilogo della distribuzione di Bob è incompleto, indicagli le directory specifiche:
Review @deployment_scripts/aws, @terraform, @deployment_scripts/ibm, and
@.github/workflows. Update the deployment model summary to include all three
deployment targets./init genera un AGENTS.md vuoto o errato
Nella radice del workspace, il comando /init costruisce il contesto del progetto
leggendo file di ancoraggio come README.md, package.json, requirements.txt,
pom.xml, Makefile e manifesti simili. Se nessuno di questi file esiste alla radice,
o se la radice del workspace è impostata su una sottodirectory, Bob vede solo una parte
del progetto e genera un AGENTS.md scarno o errato.
Se l'AGENTS.md generato non riflette la struttura multi-servizio, verifica quanto
segue:
- Radice del workspace: Conferma che
galaxium-travels/, non una sottodirectory comebooking_system_backend/, sia aperta come radice del workspace. Tutte e tre le directory dei servizi devono essere visibili al primo livello. - File di ancoraggio mancanti: Se la radice non ha un
README.mdo altro manifesto,/initha poco da leggere. Aggiungi unREADME.mda livello radice con una breve descrizione del progetto, quindi riesegui/init.
Dopo aver corretto la radice, riesegui /init per rigenerare i file AGENTS.md.
Standardizzare il comportamento di Bob
Standardizza il comportamento di Bob nel tuo team utilizzando file di regole a livello di progetto che indicano a Bob di documentare il suo codice e ricordare le sue azioni precedenti.
Generare diagrammi di architettura
Usa IBM Bob per analizzare la codebase di Galaxium Travels e generare diagrammi di classi UML Mermaid, diagrammi di sequenza e diagrammi dei casi d'uso. Impara a usare le menzioni di contesto in modalità Ask per esplorare il codice e la modalità Agent per salvare i risultati nel tuo repository.