Generuj raporty audytowe i dokumentację zgodności
Użyj IBM Bob do analizy bazy kodu Galaxium Travels i tworzenia ustrukturyzowanych raportów audytowych obejmujących jakość kodu, stan zależności, dług techniczny i postawę zgodności. Dowiedz się, jak tworzyć dokumentację gotową dla interesariuszy z analizy wspomaganej przez AI.
Audyty oprogramowania dostarczają dowodów dokumentacyjnych, na których polegają zespoły inżynieryjne, recenzenci bezpieczeństwa i interesariusze zgodności przed wysyłką, nabyciem lub certyfikacją systemu.
W tym samouczku używasz Boba do systematycznej analizy bazy kodu Galaxium Travels i generowania pięciu ustrukturyzowanych artefaktów:
- Podsumowanie jakości kodu: Podkreśla problemy z utrzymywalnością, złożonością i stylem w całej bazie kodu.
- Audyt zależności: Oznacza przestarzałe, podatne lub nieużywane pakiety zewnętrzne.
- Ocena długu technicznego: Kataloguje skróty, obejścia i obszary wymagające refaktoryzacji.
- Dokumentacja zgodności: Rejestruje ustalenia w odniesieniu do odpowiednich standardów regulacyjnych lub organizacyjnych.
- Skonsolidowany raport audytowy dla interesariuszy łączący wszystkie ustalenia: Konsoliduje powyższe w jeden dokument do udostępnienia.
Strukturujesz swoje prompty, aby uzyskać szczegółowe, poparte dowodami ustalenia bez sugestii naprawczych.
Pod koniec tego samouczka będziesz mieć zestaw dokumentów audytowych, które możesz udostępnić interesariuszom i wykorzystać jako punkt odniesienia do planowania naprawy.
W tym samouczku wyniki Boba mogą różnić się od przykładów w zależności od bieżącego stanu bazy kodu. Użyj wygenerowanych raportów jako punktu wyjścia i dopracuj ustalenia przed przekazaniem ich interesariuszom.
Kluczowe funkcje, których się nauczysz
- Context mentions: Odwołuj się do
konkretnych plików i folderów w swoich promptach za pomocą symbolu
@. Context mentions pozwalają Bobowi dokładnie wiedzieć, które pliki analizować, aby uzyskać dokładne, poparte dowodami ustalenia. - Tryb Agent: Pozwól Bobowi autonomicznie zapisywać pliki, aby utrwalić wygenerowane artefakty w swoim projekcie.
- Inżynieria promptów dla ustrukturyzowanego wyjścia: Ustrukturyzuj swój prompt, aby zawierał pożądany format wyjściowy i uzyskać dokumenty gotowe dla interesariuszy zamiast narracyjnej prozy.
Wymagania wstępne
IBM Bob IDE
Pobierz i zainstaluj IBM Bob w wersji 2.x lub nowszej.
Git
Git jest wymagany do sklonowania przykładowego repozytorium.
Skonfiguruj swój obszar roboczy
Sklonuj repozytorium Galaxium Travels
W swoim terminalu uruchom następujące polecenie, aby sklonować przykładowe repozytorium Galaxium Travels:
git clone https://github.com/IBM/galaxium-travelsTen samouczek używa gałęzi main repozytorium, a nie bob-learning-path-branch.
Usługa hold Java i inne komponenty, do których odnosi się ten samouczek, są obecne
tylko na main.
Uruchom IBM Bob
Uruchom IDE IBM Bob na swoim komputerze.
Otwórz przykładowy projekt
W IDE Boba otwórz folder galaxium-travels, który sklonowałeś. Jeśli Bob zapyta
"Czy ufasz autorom plików w tym folderze?", kliknij Tak, ufam autorom.
Przejrzyj plik README.md w katalogu głównym, aby uzyskać przegląd architektury
aplikacji. Galaxium Travels to system rezerwacji podróży kosmicznych full-stack z
backendem Python FastAPI, frontendem React/TypeScript i usługą hold inwentarza Java
Spring Boot.
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 używa trybu Agent przy uruchomieniu. Jeśli zmieniłeś tryb, przełącz się na tryb Agent przed uruchomieniem polecenia inicjalizacji. Bob musi zapisywać pliki, aby skonfigurować kontekst projektu. Ten samouczek używa domyślnych możliwości trybu Agent zamiast ograniczać uprawnienia dla każdego zadania, więc Bob może odczytywać i zapisywać pliki bez dodatkowej konfiguracji.
Wprowadź polecenie /init w polu wprowadzania interfejsu czatu.
/initJeśli automatyczne zatwierdzanie jest wyłączone, Bob poprosi o pozwolenie przed
odczytaniem plików i zapisaniem zmian. Zatwierdź te monity, gdy się pojawią — dotyczy
to polecenia /init i każdego raportu, który Bob zapisze później w samouczku.
Bob odczytuje odpowiednie pliki w projekcie i generuje główny plik AGENTS.md w
katalogu głównym wraz z folderem .bob/ zawierającym pliki AGENTS.md specyficzne
dla trybu. Sprawdź, czy AGENTS.md i folder .bob/ pojawiają się w katalogu głównym
projektu przed kontynuowaniem. Przejrzyj wygenerowane pliki, aby zrozumieć, co Bob
wywnioskował o strukturze projektu, stosie technologicznym i kluczowych wzorcach. Ten
kontekst bezpośrednio poprawia jakość analizy w kolejnych promptach.
Wygeneruj podsumowanie jakości kodu
Podsumowanie jakości kodu daje inżynierom i recenzentom ustrukturyzowany widok problemów w całej bazie kodu: antywzorce, brakujące zabezpieczenia, luki w pokryciu testami i niespójności, które gromadzą się przez cały czas życia projektu. W przeciwieństwie do raportu lintera, podsumowanie jakości wygenerowane przez Boba syntetyzuje ustalenia w różnych językach i warstwach z czytelnymi dla człowieka wyjaśnieniami i kontekstem ważności.
Baza kodu Galaxium Travels obejmuje trzy różne stosy: Python (backend), TypeScript (frontend) i Java (usługa hold). Ustrukturyzuj swój prompt, aby analizować każdą usługę niezależnie, a następnie utworzyć ujednoliconą tabelę ustaleń. Użyj context mentions, aby dać Bobowi precyzyjny zakres plików, zamiast pozwalać Bobowi zgadywać, które pliki są istotne.
Rozpocznij nowe zadanie
Kliknij przycisk +, aby rozpocząć nowe zadanie. Rozpoczęcie od nowa utrzymuje
kontekst tego promptu ograniczony do plików, które tutaj wymieniasz, zamiast przenosić
wszystko, co Bob przeczytał podczas /init.
Wygeneruj podsumowanie jakości kodu
W trybie Agent wprowadź następujący prompt w polu wprowadzania czatu:
Analyze the code quality of the Galaxium Travels application across all three
services.
For the Python backend, examine @booking_system_backend/server.py,
@booking_system_backend/models.py, @booking_system_backend/services, and
@booking_system_backend/tests.
For the TypeScript frontend, examine @booking_system_frontend/src.
For the Java hold service, examine
@booking_system_inventory_hold_service/src/main/java/com/galaxium/holdservice.
Produce a structured Markdown file named `docs/audit/code-quality-summary.md`.
The content should include the following sections:
1. An overview table listing each component, language, files analyzed, and
issue count by severity (Critical, High, Medium, Low).
2. Per-component findings, each with: severity label, issue title, file and
approximate line reference, description, and impact.
Focus on: missing input validation, inconsistent error handling, authentication
and credential storage patterns, test coverage gaps, type safety, and logging
practices. Do not suggest fixes — only report findings with evidence from the
source files.Bob analizuje trzy usługi, tworzy katalog docs/audit/, jeśli jeszcze nie istnieje,
tworzy plik Markdown i wyświetla podsumowanie w interfejsie czatu. Raport zawiera
sekcje i strukturę, które określiłeś, z ustaleniami odwołującymi się do konkretnych
plików i linii kodu jako dowodu.
Zweryfikuj raport
Otwórz docs/audit/code-quality-summary.md w eksploratorze plików Boba, aby potwierdzić,
że plik został utworzony z tabelą przeglądową i ustaleniami dla każdego komponentu przed
kontynuowaniem.
Przeprowadź audyt zależności
Audyt zależności ustala, czy biblioteki, od których zależy projekt, są przypięte do znanych dobrych wersji, czy strategie przypinania są spójne w całym stosie poliglotycznym i czy jakiekolwiek praktyki konfiguracji zależności wprowadzają niekontrolowane ryzyko aktualizacji. To różni się od skanowania CVE: oceniasz dyscyplinę zarządzania wersjami, a nie tylko znane podatności.
Projekt Galaxium Travels ma trzy manifesty zależności:
booking_system_backend/requirements.txt (Python),
booking_system_frontend/package.json (Node.js) i
booking_system_inventory_hold_service/pom.xml (Java/Maven). Uwzględnij wszystkie trzy
w swoich context mentions.
Rozpocznij nowe zadanie
Kliknij przycisk +, aby rozpocząć nowe zadanie.
Wygeneruj audyt zależności
W trybie Agent wprowadź następujący prompt w polu wprowadzania czatu:
Audit the dependency manifests for all three services in the Galaxium Travels
repository.
Analyze @booking_system_backend/requirements.txt,
@booking_system_frontend/package.json, and
@booking_system_inventory_hold_service/pom.xml.
Produce a structured Markdown file named `docs/audit/dependency-audit.md`.
The content should include these sections:
1. Per-manifest findings table: package name, declared version or range,
pinning status (exact, caret/tilde range, or unpinned), and a brief
finding note.
2. Cross-cutting findings: consistency issues, missing tooling (lock files,
audit CI steps, vulnerability scanners), and version drift risks.
3. Findings that require immediate attention before a production deployment,
listed with rationale.
Report findings only. Do not generate upgrade commands or patch suggestions.Bob analizuje manifesty i zapisuje raport. Zawiera tabelę statusu przypinania i sekcję ustaleń przekrojowych.
Zweryfikuj raport
Otwórz docs/audit/dependency-audit.md, aby potwierdzić, że tabele dla każdego manifestu
i sekcja ustaleń przekrojowych są obecne przed kontynuowaniem.
Oceń dług techniczny
Ocena długu technicznego ocenia decyzje strukturalne, architektoniczne i operacyjne, które gromadzą koszty w czasie. Ustrukturyzuj swój prompt, aby oddzielić dług na architekturę, bezpieczeństwo, gotowość operacyjną i jakość kodu oraz ocenić ważność i wysiłek naprawczy każdego elementu, aby kierownictwo mogło ustalić priorytety.
Następujący prompt zawiera AGENTS.md w context mentions, aby dać Bobowi wgląd w
wywnioskowaną architekturę i wzorce operacyjne, co może informować ocenę długu
architektonicznego i operacyjnego. Polecenie /init, które uruchomiłeś w sekcji
Zainicjuj kontekst projektu, utworzyło plik AGENTS.md.
Rozpocznij nowe zadanie
Kliknij przycisk +, aby rozpocząć nowe zadanie.
Wygeneruj ocenę długu technicznego
W trybie Agent wprowadź następujący prompt w polu wprowadzania czatu:
Conduct a technical debt assessment of the Galaxium Travels application.
Analyze the full codebase across all three services:
@booking_system_backend, @booking_system_frontend, and
@booking_system_inventory_hold_service.
Also review @docker-compose.yml and @AGENTS.md for infrastructure and
operational context.
Produce a structured Markdown file named `docs/audit/technical-debt-assessment.md`.
The content should include these sections: Architecture Debt, Security Debt, Operational Readiness Debt, and Code Quality Debt.
For each debt item include:
- A severity label: [CRITICAL], [HIGH], [MEDIUM], or [LOW]
- An effort-to-resolve label: [DAYS], [WEEKS], or [MONTHS]
- A title
- The affected files or components
- A description of the debt and why it matters
- The consequence of leaving it unaddressed
Conclude with a summary table: category, count by severity, and total items.
Report findings only. Do not generate implementation plans or code.Bob analizuje bazę kodu i zapisuje raport, oznaczając każdy element długu szacunkami ważności i wysiłku.
Zweryfikuj raport
Otwórz docs/audit/technical-debt-assessment.md, aby potwierdzić, że cztery kategorie
długu i tabela podsumowująca są obecne przed kontynuowaniem.
Wygeneruj dokumentację zgodności
Dokumentacja zgodności mapuje bieżący stan bazy kodu względem kontroli, których regulatorzy, audytorzy i zespoły bezpieczeństwa przedsiębiorstwa oczekują w systemie produkcyjnym. Dla interesariuszy, którzy nie są inżynierami, ten dokument odpowiada na pytanie: "Co ten system robi z wrażliwymi danymi, jak kontrolowany jest dostęp i gdzie są luki?"
Ustrukturyzuj swój prompt, aby obejmował klasyfikację danych, uwierzytelnianie i kontrolę dostępu, ochronę danych, pokrycie ścieżki audytu i zgodność licencji.
Rozpocznij nowe zadanie
Kliknij przycisk +, aby rozpocząć nowe zadanie.
Wygeneruj dokumentację zgodności
W trybie Agent wprowadź następujący prompt w polu wprowadzania czatu:
Generate compliance documentation for the Galaxium Travels application,
suitable for sharing with security reviewers and compliance stakeholders.
Analyze the following files and directories:
@booking_system_backend/models.py,
@booking_system_backend/server.py,
@booking_system_backend/services,
@booking_system_backend/requirements.txt,
@booking_system_inventory_hold_service/src/main/java/com/galaxium/holdservice/domain,
@booking_system_inventory_hold_service/pom.xml,
@booking_system_frontend/src,
@booking_system_frontend/package.json,
@LICENSE.
Produce a structured Markdown file named `docs/audit/compliance-documentation.md`. The content should include these sections:
1. Data Classification — table of data elements, classification tier, storage
location, and retention policy.
2. Authentication and Access Control — table of controls, implementation status
(Implemented / Partial / Not Implemented), and a source reference or gap note.
3. Data Protection — table of controls, implementation status, and notes.
4. Audit Trail Coverage — what is logged, what is not, and where audit records
are stored.
5. License Compliance — table of key dependencies (Python, Node, and Java) with
their license and a compliance note.
6. Regulatory Applicability — brief assessment of GDPR, SOC 2, and PCI DSS
applicability given the data the system handles.
Use neutral, factual language. Do not recommend remediations.Bob analizuje pliki źródłowe i zapisuje raport, mapując każdą kontrolę na status implementacji z odniesieniem do kodu.
Zweryfikuj raport
Otwórz docs/audit/compliance-documentation.md, aby potwierdzić, że wszystkie sześć
sekcji jest obecnych przed kontynuowaniem.
Skompiluj raport audytowy dla interesariuszy
Po zakończeniu czterech oddzielnych analiz poproś Boba, aby zebrał je w jeden raport audytowy skierowany do kadry kierowniczej. Raport dla interesariuszy różni się od analiz tematycznych: zaczyna się od podsumowania ustaleń, priorytetyzuje najbardziej wykonalne elementy i zapewnia zalecaną kolejność naprawy, na podstawie której mogą działać czytelnicy nietechniczni.
Prompt używa context mentions do załadowania czterech raportów, które Bob zapisał na dysku w poprzednich sekcjach. Bob odczytuje te pliki i syntetyzuje je w jeden dokument zamiast ponownie analizować kod źródłowy, więc wynik odzwierciedla ustalenia, które już przejrzałeś.
Rozpocznij nowe zadanie
Kliknij przycisk +, aby rozpocząć nowe zadanie.
Wygeneruj raport audytowy dla interesariuszy
W trybie Agent wprowadź następujący prompt w polu wprowadzania czatu:
Using @docs/audit/code-quality-summary.md, @docs/audit/dependency-audit.md,
@docs/audit/technical-debt-assessment.md,
and @docs/audit/compliance-documentation.md, compile a consolidated
stakeholder audit report for the Galaxium Travels application.
The audience is engineering leadership and security reviewers who need to
assess the system's production readiness and compliance posture without
reading four separate documents.
Structure the report as follows:
1. Executive Summary: 2-3 paragraphs covering overall state, most critical
risks, and the highest-priority remediation categories.
2. Production Readiness Scorecard: a table scoring the system against six
dimensions (Authentication, Data Protection, Observability, Dependency
Health, Test Coverage, Operational Readiness) with a RAG status
(Red / Amber / Green) and a one-line rationale for each.
3. Critical and High Findings: a consolidated table of all Critical and High
severity findings from all four analyses, with category, finding title,
affected component, and effort to resolve.
4. Recommended Remediation Sequence: an ordered list of the top 5 items to
address first, with a brief rationale for the ordering.
5. Positive Findings: a brief section acknowledging controls and practices
that are already well-implemented.
Do not repeat all findings in full. Reference the detailed documents for
complete findings. Save the report as `docs/audit/stakeholder-audit-report.md`.Bob odczytuje cztery zapisane raporty, syntetyzuje ich ustalenia i tworzy
docs/audit/stakeholder-audit-report.md. Ponieważ Bob pracuje z raportów, które już
przejrzałeś, zamiast ponownie analizować kod źródłowy, skonsolidowany raport pozostaje
spójny ze szczegółowymi ustaleniami.
Zweryfikuj raport
Otwórz docs/audit/stakeholder-audit-report.md, aby potwierdzić, że podsumowanie
wykonawcze, karta wyników i pięć sekcji są obecne. Masz teraz kompletny zestaw dokumentów
audytowych w docs/audit/ do udostępnienia interesariuszom i wykorzystania jako punkt
odniesienia do planowania naprawy.
Rozwiązywanie problemów
Analiza Boba pomija usługę lub plik
Jeśli w wynikach Boba brakuje ustaleń dla komponentu, który spodziewałeś się zobaczyć, najbardziej prawdopodobną przyczyną jest to, że prompt nie zawierał pliku lub katalogu w context mention lub okno kontekstu było zbyt pełne, aby Bob mógł przeczytać całą zawartość, do której się odwołano, w jednym przebiegu.
Sprawdź swoje context mentions
Sprawdź, czy wzmianka @ w twoim prompcie rozwiązuje się do prawidłowej ścieżki. W
interfejsie czatu Boba Bob może wskazać, czy context mention został rozwiązany. Jeśli
Bob nie rozpoznaje wzmianki, ścieżka może być błędnie napisana lub katalog może nie
istnieć w twoim lokalnym klonie.
W przypadku katalogów z wieloma plikami Bob może odczytać tylko podzbiór. Zawęź zakres do najbardziej odpowiedniego podkatalogu lub wylicz konkretne pliki zamiast odwoływać się do całego folderu.
Podziel analizę na ukierunkowane prompty
Zamiast jednego promptu obejmującego wszystkie trzy usługi, uruchom trzy oddzielne prompty, po jednym na usługę, a następnie poproś Boba o połączenie ustaleń. Na przykład, oto trzeci ukierunkowany prompt po zakończeniu przebiegów Python i TypeScript:
The code quality analysis we ran earlier covered the Python backend and
TypeScript frontend. Run the same analysis for the Java hold service only,
using @booking_system_inventory_hold_service/src. Use the same output format
and severity labels as the earlier reports.Po zakończeniu każdej ukierunkowanej analizy poproś Boba o ich połączenie:
Combine the three per-service code quality analyses into a single unified
report using the same format we used for the initial report.Raporty zawierają sprzeczne ustalenia w różnych promptach
Podczas prowadzenia sesji wielopromptowej późniejsze prompty mogą generować ustalenia, które wydają się przeczyć wcześniejszym. Może się to zdarzyć, jeśli Bob wyciąga różne wnioski z różnych odczytów plików lub jeśli wcześniejsze ustalenie było nieprecyzyjne.
Zidentyfikuj sprzeczne twierdzenia
Zacytuj oba ustalenia w nowym prompcie i poproś Boba o rozwiązanie rozbieżności z konkretnym odniesieniem do pliku. Na przykład:
In the code quality summary you stated that error handling in server.py is
inconsistent. In the technical debt assessment you described the same issue
as absent error handling. Review @booking_system_backend/server.py and clarify
which description is more accurate, with a specific line reference.Zaktualizuj dotknięty raport
Po tym, jak Bob wygeneruje autorytatywne ustalenie, poproś Boba o zaktualizowanie konkretnej sekcji w zapisanym pliku raportu. Na przykład, jeśli ocena długu technicznego jest bardziej dokładna, poproś Boba o zaktualizowanie podsumowania jakości kodu:
Update the error handling finding in docs/audit/code-quality-summary.md to
use the corrected description. Do not change any other section.Bob dodaje nieproszonych rekomendacji do analizy
Gdy prompt prosi Boba o "analizę" lub "ocenę" bez wyraźnych ograniczeń, Bob często zawiera sugestie naprawcze obok ustaleń. W przypadku raportu zgodności lub audytu nieproszone rekomendacje mogą być problematyczne: mogą być nieprawidłowe, mogą odzwierciedlać założenia dotyczące środowiska docelowego i mogą dezorientować interesariuszy, którzy oczekują dokumentu zawierającego tylko ustalenia.
Dodaj instrukcję "Report findings only. Do not generate implementation plans, code, or remediation suggestions." do każdego promptu analitycznego, gdzie to ma znaczenie. Jeśli Bob już wygenerował raport z mieszaną zawartością, poproś Boba o usunięcie rekomendacji. Na przykład, jeśli podsumowanie jakości kodu zawiera rekomendacje, wprowadź następujący prompt:
Remove all remediation suggestions, implementation guidance, and code examples
from docs/audit/code-quality-summary.md. Keep all finding descriptions,
severity labels, file references, and impact statements exactly as written.Czyszczenie
Aby usunąć artefakty utworzone w tym samouczku:
- Usuń katalog
docs/audit/, który zawiera pięć wygenerowanych raportów. - Jeśli nie chcesz zachować kontekstu projektu wygenerowanego przez Boba, usuń plik
AGENTS.mdi folder.bob/, które utworzyło polecenie/init. - Usuń katalog
galaxium-travels, który sklonowałeś w Skonfiguruj swój obszar roboczy.
Następne kroki
W tym samouczku użyłeś IBM Bob do:
- Zainicjowania kontekstu projektu za pomocą
/init, aby analiza Boba odzwierciedlała strukturę projektu i stos technologiczny - Wygenerowania czterech ukierunkowanych artefaktów audytowych: podsumowania jakości kodu, audytu zależności, oceny długu technicznego i dokumentacji zgodności. Każdy poparty dowodami z plików źródłowych
- Skompilowania czterech analiz w jeden raport audytowy dla interesariuszy z kartą wyników gotowości produkcyjnej i zalecaną sekwencją naprawy
- Użycia trybu Agent i context mentions do utrwalenia każdego raportu na dysku, utrzymując analizy samodzielne i wydajne pod względem tokenów
Kontynuuj z następującymi zasobami:
- Postępuj zgodnie z Audit code and generate reports, aby wytworzyć artefakty SARIF i OSCAL czytelne maszynowo, na których mogą działać narzędzia deweloperskie i agenci AI.
- Użyj ustaleń jako punktu odniesienia, a następnie postępuj zgodnie z Generate secure code with an actor-critic workflow, aby naprawić bez ponownego wprowadzania problemów ujawnionych przez ten audyt.
- Przeczytaj Bob best practices, aby poznać bardziej efektywne strategie promptowania.
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.
Planuj i implementuj złożone funkcje
Użyj trybu Plan IBM Bob, aby określić zakres, przejrzeć i zaimplementować złożone funkcje z agentem kodującym AI. Dowiedz się, jak napisać prompt planowania, udoskonalić wygenerowany plan i uruchomić implementację w trybie Agent.