Genera report di audit e documentazione di conformità
Usa IBM Bob per analizzare la codebase di Galaxium Travels e produrre report di audit strutturati che coprono qualità del codice, stato delle dipendenze, debito tecnico e postura di conformità. Impara ad assemblare documentazione pronta per gli stakeholder dall'analisi assistita da IA.
Gli audit software producono le prove documentali su cui si basano i team di ingegneria, i revisori della sicurezza e gli stakeholder di conformità prima di spedire, acquisire o certificare un sistema.
In questo tutorial, usi Bob per analizzare sistematicamente la codebase di Galaxium Travels e generare cinque artefatti strutturati:
- Un riepilogo della qualità del codice: Evidenzia problemi di manutenibilità, complessità e stile nell'intera codebase.
- Un audit delle dipendenze: Segnala pacchetti di terze parti obsoleti, vulnerabili o inutilizzati.
- Una valutazione del debito tecnico: Cataloga scorciatoie, workaround e aree che necessitano di refactoring.
- Documentazione di conformità: Registra i risultati rispetto agli standard normativi o organizzativi pertinenti.
- Un report di audit consolidato per gli stakeholder che combina tutti i risultati: Consolida quanto sopra in un unico documento condivisibile.
Strutturi i tuoi prompt per ottenere risultati dettagliati e supportati da prove senza suggerimenti di rimedio.
Alla fine di questo tutorial, hai un set di documenti di audit che puoi condividere con gli stakeholder e utilizzare come base per la pianificazione del rimedio.
In questo tutorial, l'output di Bob può differire dagli esempi a seconda dello stato attuale della codebase. Usa i report generati come punto di partenza e affina i risultati prima di distribuirli agli stakeholder.
Funzionalità chiave che impari
- Context mentions: Fai riferimento a
file e cartelle specifici nei tuoi prompt usando il simbolo
@. I context mentions permettono a Bob di sapere esattamente quali file analizzare per risultati precisi e supportati da prove. - Modalità Agent: Lascia che Bob scriva file in modo autonomo per persistere gli artefatti generati nel tuo progetto.
- Ingegneria dei prompt per output strutturato: Struttura il tuo prompt per includere il formato di output desiderato per ottenere documenti pronti per gli stakeholder invece di prosa narrativa.
Prerequisiti
IBM Bob IDE
Scarica e installa IBM Bob v2.x o successivo.
Git
Git è necessario per clonare il repository di esempio.
Configura il tuo workspace
Clona il repository Galaxium Travels
Nel tuo terminale, esegui il seguente comando per clonare il repository di esempio Galaxium Travels:
git clone https://github.com/IBM/galaxium-travelsQuesto tutorial usa il branch main del repository, non bob-learning-path-branch.
Il servizio di hold Java e altri componenti a cui fa riferimento questo tutorial
sono presenti solo su main.
Avvia IBM Bob
Avvia l'IDE IBM Bob sul tuo computer.
Apri il progetto di esempio
Nell'IDE Bob, apri la cartella galaxium-travels che hai clonato. Se Bob chiede
"Ti fidi degli autori dei file in questa cartella?", clicca su Sì, mi fido degli
autori.
Rivedi il file README.md nella directory root per ottenere una panoramica
dell'architettura dell'applicazione. Galaxium Travels è un sistema di prenotazione
di viaggi spaziali full-stack con un backend Python FastAPI, un frontend
React/TypeScript e un servizio di hold dell'inventario Java Spring Boot.
Apri l'interfaccia chat di Bob
Se l'interfaccia chat non è già aperta, clicca sull'icona Bob nella barra di navigazione o usa la scorciatoia Option + Command + B (Mac) o Ctrl + Alt + B (Windows).
Inizializza il contesto del progetto
Bob usa la modalità Agent per impostazione predefinita all'avvio. Se hai cambiato modalità, passa alla modalità Agent prima di eseguire il comando di inizializzazione. Bob deve scrivere file per configurare il contesto del progetto. Questo tutorial usa le capacità predefinite della modalità Agent invece di limitare i permessi per attività, quindi Bob può leggere e scrivere file senza configurazione aggiuntiva.
Inserisci il comando /init nel campo di input dell'interfaccia chat.
/initSe l'approvazione automatica è disabilitata, Bob chiede il tuo permesso prima di
leggere file e scrivere modifiche. Approva questi prompt quando appaiono — questo
si applica al comando /init e a ogni report che Bob scrive più avanti nel tutorial.
Bob legge i file rilevanti nel progetto e genera il file principale AGENTS.md nella
directory root, insieme a una cartella .bob/ contenente file AGENTS.md specifici
della modalità. Verifica che AGENTS.md e una cartella .bob/ appaiano nella root
del progetto prima di continuare. Rivedi i file generati per capire cosa Bob ha
dedotto sulla struttura del progetto, lo stack tecnologico e i pattern chiave. Questo
contesto migliora direttamente la qualità dell'analisi nei prompt successivi.
Genera un riepilogo della qualità del codice
Un riepilogo della qualità del codice fornisce a ingegneri e revisori una vista strutturata dei problemi nell'intera codebase: anti-pattern, salvaguardie mancanti, lacune nella copertura dei test e incoerenze che si accumulano nel corso della vita di un progetto. A differenza di un report di linter, un riepilogo di qualità generato da Bob sintetizza i risultati attraverso linguaggi e livelli con spiegazioni leggibili dall'uomo e contesto di gravità.
La codebase di Galaxium Travels copre tre stack distinti: Python (backend), TypeScript (frontend) e Java (servizio di hold). Struttura il tuo prompt per analizzare ogni servizio indipendentemente e poi produrre una tabella di risultati unificata. Usa i context mentions per dare a Bob uno scope di file preciso invece di lasciare che Bob indovini quali file sono rilevanti.
Avvia una nuova attività
Clicca sul pulsante + per avviare una nuova attività. Ricominciare da capo
mantiene il contesto di questo prompt limitato ai file che menzioni qui, invece di
trasportare tutto ciò che Bob ha letto durante /init.
Genera il riepilogo della qualità del codice
In modalità Agent, inserisci il seguente prompt nel campo di input della chat:
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 analizza i tre servizi, crea la directory docs/audit/ se non esiste già, crea
il file Markdown e genera un riepilogo nell'interfaccia chat. Il report contiene le
sezioni e la struttura che hai specificato, con risultati che fanno riferimento a
file specifici e righe di codice come prova.
Verifica il report
Apri docs/audit/code-quality-summary.md nell'esploratore file di Bob per confermare
che il file sia stato creato con la tabella di panoramica e i risultati per componente
prima di continuare.
Esegui un audit delle dipendenze
Un audit delle dipendenze stabilisce se le librerie da cui dipende un progetto sono fissate a versioni note come buone, se le strategie di pinning sono coerenti in tutto lo stack poliglotta e se qualsiasi pratica di configurazione delle dipendenze introduce rischio di aggiornamento non controllato. Questo è distinto da una scansione CVE: stai valutando la disciplina di gestione delle versioni, non solo le vulnerabilità note.
Il progetto Galaxium Travels ha tre manifest di dipendenze:
booking_system_backend/requirements.txt (Python),
booking_system_frontend/package.json (Node.js) e
booking_system_inventory_hold_service/pom.xml (Java/Maven). Includi tutti e tre
nei tuoi context mentions.
Avvia una nuova attività
Clicca sul pulsante + per avviare una nuova attività.
Genera l'audit delle dipendenze
In modalità Agent, inserisci il seguente prompt nel campo di input della chat:
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 analizza i manifest e scrive il report. Include una tabella di stato di pinning e una sezione di risultati trasversali.
Verifica il report
Apri docs/audit/dependency-audit.md per confermare che le tabelle per manifest e
la sezione di risultati trasversali siano presenti prima di continuare.
Valuta il debito tecnico
Una valutazione del debito tecnico valuta decisioni strutturali, architetturali e operative che accumulano costi nel tempo. Struttura il tuo prompt per separare il debito in architettura, sicurezza, prontezza operativa e qualità del codice, e per valutare la gravità e lo sforzo di rimedio di ogni elemento in modo che la leadership possa dare priorità.
Il seguente prompt include AGENTS.md nei context mentions per dare a Bob
informazioni sull'architettura dedotta e sui pattern operativi, che possono informare
la valutazione del debito architetturale e operativo. Il comando /init che hai
eseguito nella sezione Inizializza il contesto del progetto
ha creato il file AGENTS.md.
Avvia una nuova attività
Clicca sul pulsante + per avviare una nuova attività.
Genera la valutazione del debito tecnico
In modalità Agent, inserisci il seguente prompt nel campo di input della chat:
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 analizza la codebase e scrive il report, etichettando ogni elemento di debito con stime di gravità e sforzo.
Verifica il report
Apri docs/audit/technical-debt-assessment.md per confermare che le quattro
categorie di debito e la tabella di riepilogo siano presenti prima di continuare.
Genera documentazione di conformità
La documentazione di conformità mappa lo stato attuale di una codebase rispetto ai controlli che regolatori, auditor e team di sicurezza aziendale si aspettano di trovare in un sistema di produzione. Per gli stakeholder che non sono ingegneri, questo documento risponde alla domanda: "Cosa fa questo sistema con i dati sensibili, come viene controllato l'accesso e dove sono le lacune?"
Struttura il tuo prompt per coprire classificazione dei dati, autenticazione e controllo degli accessi, protezione dei dati, copertura della traccia di audit e conformità delle licenze.
Avvia una nuova attività
Clicca sul pulsante + per avviare una nuova attività.
Genera la documentazione di conformità
In modalità Agent, inserisci il seguente prompt nel campo di input della chat:
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 analizza i file sorgente e scrive il report, mappando ogni controllo a uno stato di implementazione con un riferimento al codice.
Verifica il report
Apri docs/audit/compliance-documentation.md per confermare che tutte e sei le
sezioni siano presenti prima di continuare.
Compila un report di audit per gli stakeholder
Con quattro analisi separate completate, chiedi a Bob di assemblarle in un unico report di audit orientato agli executive. Un report per gli stakeholder differisce dalle analisi per argomento: inizia con un riepilogo dei risultati, dà priorità agli elementi più attuabili e fornisce un ordine di rimedio raccomandato su cui i lettori non tecnici possono agire.
Il prompt usa context mentions per caricare i quattro report che Bob ha scritto su disco nelle sezioni precedenti. Bob legge quei file e li sintetizza in un unico documento invece di rianalizzare il codice sorgente, quindi l'output riflette i risultati che hai già esaminato.
Avvia una nuova attività
Clicca sul pulsante + per avviare una nuova attività.
Genera il report di audit per gli stakeholder
In modalità Agent, inserisci il seguente prompt nel campo di input della chat:
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 legge i quattro report salvati, sintetizza i loro risultati e crea
docs/audit/stakeholder-audit-report.md. Poiché Bob lavora dai report che hai già
esaminato invece di rianalizzare il codice sorgente, il report consolidato rimane
coerente con i risultati dettagliati.
Verifica il report
Apri docs/audit/stakeholder-audit-report.md per confermare che il riepilogo
esecutivo, la scorecard e le cinque sezioni siano presenti. Ora hai un set completo
di documenti di audit in docs/audit/ da condividere con gli stakeholder e usare
come base per la pianificazione del rimedio.
Risoluzione dei problemi
L'analisi di Bob omette un servizio o un file
Se l'output di Bob manca di risultati per un componente che ti aspettavi di vedere coperto, la causa più probabile è che il prompt non includeva il file o la directory nel context mention, o la finestra di contesto era troppo piena perché Bob potesse leggere tutto il contenuto referenziato in un singolo passaggio.
Verifica i tuoi context mentions
Verifica che la menzione @ nel tuo prompt si risolva nel percorso corretto.
Nell'interfaccia chat di Bob, Bob può indicare se un context mention è stato risolto.
Se Bob non riconosce la menzione, il percorso potrebbe essere scritto male o la
directory potrebbe non esistere nel tuo clone locale.
Per directory con molti file, Bob potrebbe leggere solo un sottoinsieme. Restringi lo scope alla sottodirectory più rilevante o enumera file specifici invece di referenziare l'intera cartella.
Dividi l'analisi in prompt focalizzati
Invece di un singolo prompt che copre tutti e tre i servizi, esegui tre prompt separati, uno per servizio, e poi chiedi a Bob di unire i risultati. Ad esempio, ecco il terzo prompt focalizzato dopo aver completato i passaggi Python e 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.Dopo che ogni analisi focalizzata è completa, chiedi a Bob di unirle:
Combine the three per-service code quality analyses into a single unified
report using the same format we used for the initial report.I report contengono risultati contrastanti tra i prompt
Quando esegui una sessione multi-prompt, i prompt successivi possono produrre risultati che sembrano contraddire quelli precedenti. Questo può accadere se Bob trae inferenze diverse da diverse letture di file, o se un risultato precedente era impreciso.
Identifica le affermazioni contrastanti
Cita entrambi i risultati in un nuovo prompt e chiedi a Bob di risolvere la discrepanza con un riferimento file specifico. Ad esempio:
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.Aggiorna il report interessato
Dopo che Bob ha prodotto il risultato autorevole, chiedi a Bob di aggiornare la sezione specifica nel file di report salvato. Ad esempio, se la valutazione del debito tecnico è più accurata, chiedi a Bob di aggiornare il riepilogo della qualità del codice:
Update the error handling finding in docs/audit/code-quality-summary.md to
use the corrected description. Do not change any other section.Bob aggiunge raccomandazioni non richieste all'analisi
Quando un prompt chiede a Bob di "analizzare" o "valutare" senza vincoli espliciti, Bob spesso include suggerimenti di rimedio insieme ai risultati. Per un report di conformità o audit, le raccomandazioni non richieste possono essere problematiche: possono essere errate, possono riflettere assunzioni sull'ambiente target e possono confondere gli stakeholder che si aspettano un documento di soli risultati.
Aggiungi l'istruzione "Report findings only. Do not generate implementation plans, code, or remediation suggestions." a qualsiasi prompt di analisi dove questo conta. Se Bob ha già generato un report con contenuto misto, chiedi a Bob di rimuovere le raccomandazioni. Ad esempio, se il riepilogo della qualità del codice contiene raccomandazioni, inserisci il seguente 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.Pulizia
Per rimuovere gli artefatti creati in questo tutorial:
- Elimina la directory
docs/audit/, che contiene i cinque report generati. - Se non vuoi mantenere il contesto del progetto che Bob ha generato, elimina il
file
AGENTS.mde la cartella.bob/che il comando/initha creato. - Elimina la directory
galaxium-travelsche hai clonato in Configura il tuo workspace.
Prossimi passi
In questo tutorial, hai usato IBM Bob per:
- Inizializzare il contesto del progetto con
/initin modo che l'analisi di Bob rifletta la struttura e lo stack tecnologico del progetto - Generare quattro artefatti di audit focalizzati: un riepilogo della qualità del codice, un audit delle dipendenze, una valutazione del debito tecnico e documentazione di conformità. Ognuno supportato da prove dai file sorgente
- Compilare le quattro analisi in un unico report di audit per gli stakeholder con una scorecard di prontezza alla produzione e una sequenza di rimedio raccomandata
- Usare la modalità Agent e i context mentions per persistere ogni report su disco, mantenendo le analisi autonome ed efficienti in termini di token
Continua con le seguenti risorse:
- Segui Audit code and generate reports per produrre artefatti SARIF e OSCAL leggibili da macchina su cui gli strumenti di sviluppo e gli agenti IA possono agire.
- Usa i risultati come base, poi segui Generate secure code with an actor-critic workflow per rimediare senza reintrodurre i problemi che questo audit ha rivelato.
- Leggi Bob best practices per strategie di prompting più efficaci.
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.
Pianifica e implementa funzionalità complesse
Usa la modalità Plan di IBM Bob per definire l'ambito, rivedere e implementare funzionalità complesse con un agente di codifica AI. Impara a scrivere un prompt di pianificazione, perfezionare il piano generato ed eseguire l'implementazione in modalità Agent.