Tutorial

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:

  1. Un riepilogo della qualità del codice: Evidenzia problemi di manutenibilità, complessità e stile nell'intera codebase.
  2. Un audit delle dipendenze: Segnala pacchetti di terze parti obsoleti, vulnerabili o inutilizzati.
  3. Una valutazione del debito tecnico: Cataloga scorciatoie, workaround e aree che necessitano di refactoring.
  4. Documentazione di conformità: Registra i risultati rispetto agli standard normativi o organizzativi pertinenti.
  5. 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

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-travels

Questo 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.

/init

Se 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:

  1. Elimina la directory docs/audit/, che contiene i cinque report generati.
  2. Se non vuoi mantenere il contesto del progetto che Bob ha generato, elimina il file AGENTS.md e la cartella .bob/ che il comando /init ha creato.
  3. Elimina la directory galaxium-travels che hai clonato in Configura il tuo workspace.

Prossimi passi

In questo tutorial, hai usato IBM Bob per:

  • Inizializzare il contesto del progetto con /init in 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:

Come valuti questo argomento?