Poznawanie nieznanej bazy kodu
Użyj IBM Bob, aby szybko zrozumieć nieznaną aplikację — jej cel, strukturę projektu, architekturę, stos technologiczny, kluczowe komponenty, pokrycie testami i model wdrożenia. Możesz to zrobić bez polegania na nieaktualnej dokumentacji lub czekania na pomoc kolegów.
Osiągnięcie produktywności w nieznanej bazie kodu zazwyczaj oznacza godziny czytania kodu, szukania dokumentacji i proszenia kolegów o kontekst. W tym tutorialu używasz Boba w trybie Ask, aby systematycznie zbadać bazę kodu Galaxium Travels i zebrać pełny obraz aplikacji: jej cel i architekturę, stos technologiczny, kluczowe komponenty, pokrycie testami jednostkowymi i integracyjnymi oraz model wdrożenia. Następnie przełączasz się do trybu Agent, aby zapisać wszystko, co Bob odkrył, do trwałego pliku Markdown, z którego może korzystać cały zespół.
Galaxium Travels to celowo złożona aplikacja w stylu rzeczywistego projektu, która posiada frontend w React, backend w Python FastAPI oraz serwis inwentaryzacyjny w Java Spring Boot. Dzięki temu jest idealnym kandydatem do tego workflow.
Wyniki Boba różnią się w zależności od aktualnego stanu bazy kodu. Traktuj przykłady w tym tutorialu jako reprezentatywne punkty startowe, a nie dokładne transkrypty. Używaj ich do kalibrowania własnych promptów i udoskonalania wyników.
Kluczowe funkcje, których się uczysz
- Tryb Ask: Eksploruj i analizuj kod bez modyfikowania plików przez Boba.
- Tryb Agent: Pozwól Bobowi autonomicznie zapisywać pliki, aby utrwalić wygenerowane artefakty w projekcie.
- Wzmianki kontekstowe: Odwołuj się do
konkretnych plików i folderów za pomocą
@, aby nadać Bobowi precyzyjny zakres analizy. /init: Zainicjuj kontekst projektu, aby Bob poznał konwencje bazy kodu przed rozpoczęciem zadawania pytań.
Wymagania wstępne
Aby ukończyć ten tutorial, potrzebujesz:
- Zainstalowanego Bob IDE.
- Zainstalowanego lokalnie Gita.
- Podstawowej znajomości obsługi Boba. Jeśli dopiero zaczynasz z Bobem, najpierw ukończ tutorial Quickstart.
Konfiguracja workspace
Sklonuj repozytorium Galaxium Travels
W terminalu sklonuj przykładowe repozytorium:
git clone https://github.com/IBM/galaxium-travels.gitOtwórz przykładowy projekt
W Bob IDE otwórz folder galaxium-travels, który właśnie sklonowałeś(-aś). Jeśli Bob zapyta
"Do you trust the authors of the files in the folder?", kliknij Yes, I trust
the authors.
Otwórz interfejs czatu Boba
Jeśli interfejs czatu nie jest jeszcze otwarty, kliknij ikonę Boba na pasku nawigacji lub użyj skrótu Option + Command + B (Mac) lub Ctrl + Alt + B (Windows).
Zainicjuj kontekst projektu
Bob domyślnie uruchamia się w trybie Agent. Przed przełączeniem trybów uruchom polecenie
/init, aby Bob odczytał projekt i wygenerował pliki kontekstowe AGENTS.md, których
używa w kolejnych interakcjach.
/initJeśli automatyczne zatwierdzanie jest wyłączone, Bob poprosi o pozwolenie na odczyt plików
i zapis plików AGENTS.md. Zatwierdź każde żądanie. Bob tworzy AGENTS.md na poziomie
głównym oraz folder .bob/ z konfiguracją specyficzną dla trybu.
Przejrzyj wygenerowany plik AGENTS.md, aby upewnić się, że Bob poprawnie zidentyfikował
strukturę wielousługową repozytorium.
Przełącz się do trybu Ask
Wybierz Ask w selektorze trybu poniżej pola wprowadzania czatu lub wpisz /ask,
aby przełączyć tryb. Tryb Ask jest ściśle tylko do odczytu. Bob analizuje pliki, ale nie
może niczego tworzyć ani modyfikować, co czyni go właściwym trybem do wszelkich prac
eksploracyjnych w tym tutorialu.
Zrozumienie celu aplikacji i struktury projektu
Zacznij od najszerszego pytania: co robi ta aplikacja i jak jest zorganizowana baza kodu?
Bob odczytuje strukturę projektu i kluczowe pliki, takie jak README.md, package.json,
requirements.txt, pliki budowania oraz inne pliki konfiguracyjne. Bob syntetyzuje
zwięzłe podsumowanie bez konieczności ręcznego przeglądania każdego katalogu.
W trybie Ask wprowadź następujący 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 odczytuje drzewo plików i kluczowe punkty wejścia, a następnie generuje wyniki zawierające:
- Cel aplikacji
- Odpowiedzialności katalogów najwyższego poziomu
- Streszczenie zawartości każdego katalogu najwyższego poziomu
- Diagram architektury wysokiego poziomu
Analiza stosu technologicznego
Gdy struktura wysokiego poziomu jest jasna, zagłęb się w konkretne technologie. Ten prompt jest przydatny, gdy trzeba zrozumieć narzędzia do budowania, ocenić wybory zależności lub oszacować zakres aktualizacji.
W trybie Ask wprowadź następujący 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 sprawdza pliki zależności i konfiguracji każdego serwisu i generuje wyniki zawierające:
- Szczegółową analizę stosu technologicznego dla każdego serwisu
- Identyfikację frameworka testów end-to-end
- Dodatkowe narzędzia ze stosu CI/CD i skryptów wdrożeniowych
- Diagram „Stack at a Glance" wizualnie podsumowujący stos technologiczny wszystkich serwisów i warstw
Mapowanie kluczowych komponentów
Znajomość stosu technologicznego mówi ci, czego używa baza kodu; znajomość kluczowych komponentów mówi ci, jak ona działa. Ten prompt prosi Boba o prześledzenie granic komponentów i przepływów danych we wszystkich trzech serwisach, co jest szczególnie przydatne przed wprowadzaniem zmian przekraczających granice serwisów.
W trybie Ask wprowadź następujący prompt z wzmiankami kontekstowymi wskazującymi Bobowi najważniejsze pliki:
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 śledzi łańcuch interakcji i generuje wyniki zawierające:
- Szczegółowe odpowiedzialności frontendu, API backendu, warstwy bazy danych i serwisu hold w Javie
- Diagram dwóch przepływów cyklu życia rezerwacji z zaznaczonymi interakcjami komponentów
- Podsumowanie pięciu kontraktów między serwisami, które musisz znać przed wprowadzaniem zmian
- Mapę interakcji komponentów
Ocena pokrycia testami jednostkowymi
Przed dodaniem funkcji lub refaktoryzacją musisz wiedzieć, co obejmuje istniejący zestaw testów i gdzie są luki. Ten prompt prosi Boba o odczytanie plików testowych i wygenerowanie oceny pokrycia bez uruchamiania testów.
W trybie Ask wprowadź następujący 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 odczytuje pliki testowe i generuje szczegółową analizę zestawu testów zawierającą:
- Framework testowy, klasy objęte testami, liczbę testów na klasę i co jest weryfikowane na klasę — dla każdego serwisu
- Krytyczne luki w testach
- Brakujące pokrycie testami dla krytycznej logiki biznesowej
Ocena pokrycia testami integracyjnymi i end-to-end
Testy jednostkowe mówią ci, czy poszczególne komponenty działają w izolacji; testy integracyjne i end-to-end mówią ci, czy serwisy działają poprawnie razem. Jest to szczególnie ważne w przypadku Galaxium Travels, ponieważ przepływ potwierdzenia rezerwacji obejmuje wszystkie trzy serwisy.
W trybie Ask wprowadź następujący 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 odczytuje zestaw testów end-to-end i generuje szczegółową analizę pokrycia zawierającą:
- Infrastrukturę testową i wymagania do uruchomienia zestawu
- Testy smoke
- Kluczowe decyzje infrastrukturalne
- Przepływy między serwisami objęte i nieobjęte testami
- Asercje testowe na poziomie granic
Przegląd modelu wdrożenia
Zrozumienie sposobu wdrażania aplikacji (docelowych platform, strategii konteneryzacji i automatyzacji infrastruktury) jest niezbędne przed dołączeniem jako kontrybutor lub przed uruchomieniem aplikacji gdzieś poza własnym laptopem.
W trybie Ask wprowadź następujący 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 odczytuje artefakty wdrożeniowe i generuje analizę modelu wdrożenia zawierającą:
- Obsługiwane cele wdrożenia
- Strategię konteneryzacji dla każdego serwisu
- Szczegóły provisioningu infrastruktury
- Przepływy CI/CD
- Kluczowe ograniczenia i luki wdrożeniowe
Zapisywanie wyników do repozytorium
Analiza przeprowadzona w trybie Ask istnieje tylko w sesji czatu. Przełącz się do trybu Agent, aby poprosić Boba o zapisanie trwałego dokumentu referencyjnego onboardingowego do repozytorium, dzięki czemu przyszli kontrybutorzy będą mogli skorzystać z tej pracy.
Przełącz się do trybu Agent
Wybierz Agent w selektorze trybu lub wpisz /agent w polu wprowadzania czatu.
Utwórz dokument referencyjny onboardingowy
Poproś Boba o zebranie wszystkiego, co odkrył, w jednym pliku Markdown. Bob ma pełny kontekst rozmowy i syntetyzuje wyniki bez ponownego odczytywania wszystkich plików.
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 zapisuje plik. Jeśli automatyczne zatwierdzanie jest wyłączone, kliknij Approve,
gdy Bob poprosi o pozwolenie na zapis docs/ONBOARDING.md.
Zweryfikuj wynik
Otwórz docs/ONBOARDING.md w edytorze, aby potwierdzić, że dokument zawiera
wszystkie oczekiwane treści. Możesz też poprosić Boba o podgląd:
Show me a preview of docs/ONBOARDING.mdBob renderuje Markdown w interfejsie czatu. Sprawdź treść pod kątem dokładności i kompletności przed commitem.
Zatwierdź plik
Użyj preferowanego workflow Git, aby zacommitować docs/ONBOARDING.md do
repozytorium. Dokument jest teraz dostępny dla każdego kontrybutora i dla samego
Boba w przyszłych sesjach.
Rozwiązywanie problemów
Analiza Boba jest powierzchowna lub pomija serwisy
Domyślnie Bob odczytuje strukturę projektu i wybór kluczowych plików. Jeśli w wynikach brakuje serwisu lub są one mniej szczegółowe niż oczekiwano, dodaj wyraźne wzmianki kontekstowe, aby zawęzić fokus Boba.
Na przykład, jeśli serwis hold w Javie nie jest uwzględniony w analizie stosu
technologicznego, dodaj @booking_system_inventory_hold_service/pom.xml do promptu:
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 nie może znaleźć plików testowych
Jeśli Bob informuje, że nie może znaleźć plików testowych, użyj wzmianki kontekstowej, aby wskazać bezpośrednio katalogi testowe:
Analyze the test coverage in @booking_system_backend/tests and
@tests_e2e. List every test file and summarize what each one covers.Analiza wdrożenia Boba pomija cel wdrożenia
Artefakty wdrożeniowe AWS, IBM Cloud i lokalne są rozrzucone po wielu katalogach najwyższego poziomu. Jeśli podsumowanie wdrożenia Boba jest niekompletne, wskaż mu konkretne katalogi:
Review @deployment_scripts/aws, @terraform, @deployment_scripts/ibm, and
@.github/workflows. Update the deployment model summary to include all three
deployment targets./init generuje pusty lub niepoprawny AGENTS.md
W katalogu głównym workspace polecenie /init buduje kontekst projektu przez odczytanie
plików kotwiczących, takich jak README.md, package.json, requirements.txt, pom.xml,
Makefile i podobnych manifestów. Jeśli żaden z tych plików nie istnieje w katalogu
głównym lub katalog główny workspace jest ustawiony na podkatalog, Bob widzi tylko
fragment projektu i generuje rzadki lub niepoprawny AGENTS.md.
Jeśli wygenerowany AGENTS.md nie odzwierciedla struktury wielousługowej, sprawdź:
- Katalog główny workspace: Upewnij się, że
galaxium-travels/, a nie podkatalog taki jakbooking_system_backend/, jest otwarty jako katalog główny workspace. Wszystkie trzy katalogi serwisów muszą być widoczne na najwyższym poziomie. - Brakujące pliki kotwiczące: Jeśli w katalogu głównym brakuje
README.mdlub innego manifestu,/initma mało do odczytania. DodajREADME.mdna poziomie głównym z krótkim opisem projektu, a następnie uruchom ponownie/init.
Po poprawieniu katalogu głównego uruchom ponownie /init, aby zregenerować pliki AGENTS.md.
Standaryzacja zachowania Boba
Standaryzuj zachowanie Boba w swoim zespole, używając plików reguł na poziomie projektu, które instruują Boba, aby dokumentował swój kod i pamiętał swoje poprzednie działania.
Generowanie diagramów architektury
Użyj IBM Bob do analizy bazy kodu Galaxium Travels i wygenerowania diagramów klas UML Mermaid, diagramów sekwencji i diagramów przypadków użycia. Dowiedz się, jak używać wzmianek kontekstowych w trybie Ask do eksploracji kodu oraz trybu Agent do zapisywania wyników w repozytorium.