Génère des rapports d'audit et de la documentation de conformité
Utilise IBM Bob pour analyser la base de code Galaxium Travels et produire des rapports d'audit structurés couvrant la qualité du code, l'état des dépendances, la dette technique et la posture de conformité. Apprends à assembler une documentation prête pour les parties prenantes à partir d'une analyse assistée par IA.
Les audits logiciels produisent les preuves documentaires sur lesquelles s'appuient les équipes d'ingénierie, les réviseurs de sécurité et les parties prenantes de conformité avant d'expédier, d'acquérir ou de certifier un système.
Dans ce tutoriel, tu utilises Bob pour analyser systématiquement la base de code Galaxium Travels et générer cinq artefacts structurés :
- Un résumé de qualité de code : Met en évidence les problèmes de maintenabilité, de complexité et de style dans toute la base de code.
- Un audit des dépendances : Signale les packages tiers obsolètes, vulnérables ou inutilisés.
- Une évaluation de la dette technique : Catalogue les raccourcis, les solutions de contournement et les zones nécessitant une refactorisation.
- Documentation de conformité : Enregistre les constatations par rapport aux normes réglementaires ou organisationnelles pertinentes.
- Un rapport d'audit consolidé pour les parties prenantes qui combine toutes les constatations : Consolide ce qui précède dans un seul document partageable.
Tu structures tes prompts pour obtenir des constatations détaillées et étayées par des preuves sans suggestions de remédiation.
À la fin de ce tutoriel, tu as un ensemble de documents d'audit que tu peux partager avec les parties prenantes et utiliser comme base pour la planification de la remédiation.
Dans ce tutoriel, la sortie de Bob peut différer des exemples en fonction de l'état actuel de la base de code. Utilise les rapports générés comme point de départ et affine les constatations avant de les distribuer aux parties prenantes.
Fonctionnalités clés que tu apprends
- Context mentions : Référence des
fichiers et dossiers spécifiques dans tes prompts en utilisant le symbole
@. Les context mentions permettent à Bob de savoir exactement quels fichiers analyser pour des constatations précises et étayées par des preuves. - Mode Agent : Laisse Bob écrire des fichiers de manière autonome pour persister les artefacts générés dans ton projet.
- Ingénierie de prompt pour une sortie structurée : Structure ton prompt pour inclure le format de sortie souhaité afin d'obtenir des documents prêts pour les parties prenantes plutôt qu'une prose narrative.
Prérequis
IBM Bob IDE
Télécharge et installe IBM Bob v2.x ou ultérieur.
Git
Git est nécessaire pour cloner le dépôt d'exemple.
Configure ton espace de travail
Clone le dépôt Galaxium Travels
Dans ton terminal, exécute la commande suivante pour cloner le dépôt d'exemple Galaxium Travels :
git clone https://github.com/IBM/galaxium-travelsCe tutoriel utilise la branche main du dépôt, pas bob-learning-path-branch.
Le service de retenue Java et d'autres composants auxquels ce tutoriel fait
référence ne sont présents que sur main.
Lance IBM Bob
Lance l'IDE IBM Bob sur ton ordinateur.
Ouvre le projet d'exemple
Dans l'IDE Bob, ouvre le dossier galaxium-travels que tu as cloné. Si Bob demande
"Fais-tu confiance aux auteurs des fichiers dans ce dossier ?", clique sur Oui,
je fais confiance aux auteurs.
Consulte le fichier README.md dans le répertoire racine pour obtenir un aperçu
de l'architecture de l'application. Galaxium Travels est un système de réservation
de voyages spatiaux full-stack avec un backend Python FastAPI, un frontend
React/TypeScript et un service de retenue d'inventaire Java Spring Boot.
Ouvre l'interface de chat Bob
Si l'interface de chat n'est pas déjà ouverte, clique sur l'icône Bob dans la barre de navigation ou utilise le raccourci Option + Command + B (Mac) ou Ctrl + Alt + B (Windows).
Initialise le contexte du projet
Bob utilise le mode Agent par défaut au démarrage. Si tu as changé de mode, passe au mode Agent avant d'exécuter la commande d'initialisation. Bob doit écrire des fichiers pour configurer le contexte du projet. Ce tutoriel utilise les capacités par défaut du mode Agent plutôt que de limiter les permissions par tâche, donc Bob peut lire et écrire des fichiers sans configuration supplémentaire.
Entre la commande /init dans le champ de saisie de l'interface de chat.
/initSi l'approbation automatique est désactivée, Bob demande ta permission avant de lire
des fichiers et d'écrire des modifications. Approuve ces invites lorsqu'elles
apparaissent — cela s'applique à la commande /init et à chaque rapport que Bob
écrit plus tard dans le tutoriel.
Bob lit les fichiers pertinents dans le projet et génère le fichier principal
AGENTS.md dans le répertoire racine, ainsi qu'un dossier .bob/ contenant des
fichiers AGENTS.md spécifiques au mode. Vérifie que AGENTS.md et un dossier
.bob/ apparaissent à la racine du projet avant de continuer. Consulte les fichiers
générés pour comprendre ce que Bob a déduit sur la structure du projet, la pile
technologique et les modèles clés. Ce contexte améliore directement la qualité de
l'analyse dans les prompts suivants.
Génère un résumé de qualité de code
Un résumé de qualité de code donne aux ingénieurs et aux réviseurs une vue structurée des problèmes dans toute la base de code : anti-patterns, protections manquantes, lacunes de couverture de tests et incohérences qui s'accumulent au cours de la vie d'un projet. Contrairement à un rapport de linter, un résumé de qualité généré par Bob synthétise les constatations à travers les langages et les couches avec des explications lisibles par l'homme et un contexte de gravité.
La base de code Galaxium Travels couvre trois piles distinctes : Python (backend), TypeScript (frontend) et Java (service de retenue). Structure ton prompt pour analyser chaque service indépendamment puis produire un tableau de constatations unifié. Utilise les context mentions pour donner à Bob une portée de fichier précise plutôt que de laisser Bob deviner quels fichiers sont pertinents.
Démarre une nouvelle tâche
Clique sur le bouton + pour démarrer une nouvelle tâche. Repartir de zéro
maintient le contexte de ce prompt limité aux fichiers que tu mentionnes ici, plutôt
que de transporter tout ce que Bob a lu pendant /init.
Génère le résumé de qualité de code
En mode Agent, entre le prompt suivant dans le champ de saisie du 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 analyse les trois services, crée le répertoire docs/audit/ s'il n'existe pas
déjà, crée le fichier Markdown et génère un résumé dans l'interface de chat. Le
rapport contient les sections et la structure que tu as spécifiées, avec des
constatations qui référencent des fichiers spécifiques et des lignes de code comme
preuve.
Vérifie le rapport
Ouvre docs/audit/code-quality-summary.md dans l'explorateur de fichiers Bob pour
confirmer que le fichier a été créé avec le tableau de synthèse et les constatations
par composant avant de continuer.
Exécute un audit des dépendances
Un audit des dépendances établit si les bibliothèques dont dépend un projet sont épinglées à des versions connues comme bonnes, si les stratégies d'épinglage sont cohérentes dans toute la pile polyglotte et si des pratiques de configuration de dépendances introduisent un risque de mise à niveau non contrôlé. Ceci est distinct d'un scan CVE : tu évalues la discipline de gestion des versions, pas seulement les vulnérabilités connues.
Le projet Galaxium Travels a trois manifestes de dépendances :
booking_system_backend/requirements.txt (Python),
booking_system_frontend/package.json (Node.js) et
booking_system_inventory_hold_service/pom.xml (Java/Maven). Inclus les trois dans
tes context mentions.
Démarre une nouvelle tâche
Clique sur le bouton + pour démarrer une nouvelle tâche.
Génère l'audit des dépendances
En mode Agent, entre le prompt suivant dans le champ de saisie du 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 analyse les manifestes et écrit le rapport. Il inclut un tableau d'état d'épinglage et une section de constatations transversales.
Vérifie le rapport
Ouvre docs/audit/dependency-audit.md pour confirmer que les tableaux par manifeste
et la section de constatations transversales sont présents avant de continuer.
Évalue la dette technique
Une évaluation de la dette technique évalue les décisions structurelles, architecturales et opérationnelles qui accumulent des coûts au fil du temps. Structure ton prompt pour séparer la dette en architecture, sécurité, préparation opérationnelle et qualité du code, et pour évaluer la gravité et l'effort de remédiation de chaque élément afin que la direction puisse le prioriser.
Le prompt suivant inclut AGENTS.md dans les context mentions pour donner à Bob
un aperçu de l'architecture déduite et des modèles opérationnels, ce qui peut
informer l'évaluation de la dette architecturale et opérationnelle. La commande
/init que tu as exécutée dans la section Initialise le contexte du projet
a créé le fichier AGENTS.md.
Démarre une nouvelle tâche
Clique sur le bouton + pour démarrer une nouvelle tâche.
Génère l'évaluation de la dette technique
En mode Agent, entre le prompt suivant dans le champ de saisie du 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 analyse la base de code et écrit le rapport, en étiquetant chaque élément de dette avec des estimations de gravité et d'effort.
Vérifie le rapport
Ouvre docs/audit/technical-debt-assessment.md pour confirmer que les quatre
catégories de dette et le tableau récapitulatif sont présents avant de continuer.
Génère la documentation de conformité
La documentation de conformité mappe l'état actuel d'une base de code par rapport aux contrôles que les régulateurs, les auditeurs et les équipes de sécurité d'entreprise s'attendent à trouver dans un système de production. Pour les parties prenantes qui ne sont pas des ingénieurs, ce document répond à la question : "Que fait ce système avec les données sensibles, comment l'accès est-il contrôlé et où sont les lacunes ?"
Structure ton prompt pour couvrir la classification des données, l'authentification et le contrôle d'accès, la protection des données, la couverture de la piste d'audit et la conformité des licences.
Démarre une nouvelle tâche
Clique sur le bouton + pour démarrer une nouvelle tâche.
Génère la documentation de conformité
En mode Agent, entre le prompt suivant dans le champ de saisie du 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 analyse les fichiers source et écrit le rapport, en mappant chaque contrôle à un statut d'implémentation avec une référence de code.
Vérifie le rapport
Ouvre docs/audit/compliance-documentation.md pour confirmer que les six sections
sont présentes avant de continuer.
Compile un rapport d'audit pour les parties prenantes
Avec quatre analyses distinctes terminées, demande à Bob de les assembler en un seul rapport d'audit orienté vers les dirigeants. Un rapport pour les parties prenantes diffère des analyses par sujet : il commence par un résumé des constatations, priorise les éléments les plus actionnables et fournit un ordre de remédiation recommandé sur lequel les lecteurs non techniques peuvent agir.
Le prompt utilise des context mentions pour charger les quatre rapports que Bob a écrits sur le disque dans les sections précédentes. Bob lit ces fichiers et les synthétise en un seul document plutôt que de réanalyser le code source, donc la sortie reflète les constatations que tu as déjà examinées.
Démarre une nouvelle tâche
Clique sur le bouton + pour démarrer une nouvelle tâche.
Génère le rapport d'audit pour les parties prenantes
En mode Agent, entre le prompt suivant dans le champ de saisie du 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 lit les quatre rapports enregistrés, synthétise leurs constatations et crée
docs/audit/stakeholder-audit-report.md. Parce que Bob travaille à partir des
rapports que tu as déjà examinés plutôt que de réanalyser le code source, le rapport
consolidé reste cohérent avec les constatations détaillées.
Vérifie le rapport
Ouvre docs/audit/stakeholder-audit-report.md pour confirmer que le résumé exécutif,
le tableau de bord et les cinq sections sont présents. Tu as maintenant un ensemble
complet de documents d'audit dans docs/audit/ à partager avec les parties prenantes
et à utiliser comme base pour la planification de la remédiation.
Dépannage
L'analyse de Bob omet un service ou un fichier
Si la sortie de Bob manque de constatations pour un composant que tu t'attendais à voir couvert, la cause la plus probable est que le prompt n'incluait pas le fichier ou le répertoire dans le context mention, ou la fenêtre de contexte était trop pleine pour que Bob lise tout le contenu référencé en un seul passage.
Vérifie tes context mentions
Vérifie que la mention @ dans ton prompt se résout au bon chemin. Dans l'interface
de chat Bob, Bob peut indiquer si un context mention a été résolu. Si Bob ne reconnaît
pas la mention, le chemin peut être mal orthographié ou le répertoire peut ne pas
exister dans ton clone local.
Pour les répertoires avec de nombreux fichiers, Bob peut ne lire qu'un sous-ensemble. Réduis la portée au sous-répertoire le plus pertinent ou énumère des fichiers spécifiques plutôt que de référencer tout le dossier.
Divise l'analyse en prompts ciblés
Au lieu d'un seul prompt couvrant les trois services, exécute trois prompts séparés, un par service, puis demande à Bob de fusionner les constatations. Par exemple, voici le troisième prompt ciblé après avoir terminé les passes Python et 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.Après que chaque analyse ciblée soit terminée, demande à Bob de les fusionner :
Combine the three per-service code quality analyses into a single unified
report using the same format we used for the initial report.Les rapports contiennent des constatations contradictoires entre les prompts
Lors de l'exécution d'une session multi-prompts, les prompts ultérieurs peuvent produire des constatations qui semblent contredire les précédentes. Cela peut se produire si Bob tire différentes inférences de différentes lectures de fichiers, ou si une constatation antérieure était imprécise.
Identifie les affirmations contradictoires
Cite les deux constatations dans un nouveau prompt et demande à Bob de résoudre la divergence avec une référence de fichier spécifique. Par exemple :
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.Mets à jour le rapport concerné
Après que Bob ait produit la constatation faisant autorité, demande à Bob de mettre à jour la section spécifique dans le fichier de rapport enregistré. Par exemple, si l'évaluation de la dette technique est plus précise, demande à Bob de mettre à jour le résumé de qualité de code :
Update the error handling finding in docs/audit/code-quality-summary.md to
use the corrected description. Do not change any other section.Bob ajoute des recommandations non sollicitées à l'analyse
Lorsqu'un prompt demande à Bob d'"analyser" ou d'"évaluer" sans contraintes explicites, Bob inclut souvent des suggestions de remédiation aux côtés des constatations. Pour un rapport de conformité ou d'audit, les recommandations non sollicitées peuvent être problématiques : elles peuvent être incorrectes, elles peuvent refléter des hypothèses sur l'environnement cible et elles peuvent confondre les parties prenantes qui s'attendent à un document de constatations uniquement.
Ajoute l'instruction "Report findings only. Do not generate implementation plans, code, or remediation suggestions." à tout prompt d'analyse où cela compte. Si Bob a déjà généré un rapport avec un contenu mixte, demande à Bob de supprimer les recommandations. Par exemple, si le résumé de qualité de code contient des recommandations, entre le prompt suivant :
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.Nettoyage
Pour supprimer les artefacts créés dans ce tutoriel :
- Supprime le répertoire
docs/audit/, qui contient les cinq rapports générés. - Si tu ne veux pas conserver le contexte du projet que Bob a généré, supprime le
fichier
AGENTS.mdet le dossier.bob/que la commande/inita créés. - Supprime le répertoire
galaxium-travelsque tu as cloné dans Configure ton espace de travail.
Prochaines étapes
Dans ce tutoriel, tu as utilisé IBM Bob pour :
- Initialiser le contexte du projet avec
/initafin que l'analyse de Bob reflète la structure et la pile technologique du projet - Générer quatre artefacts d'audit ciblés : un résumé de qualité de code, un audit des dépendances, une évaluation de la dette technique et une documentation de conformité. Chacun étayé par des preuves des fichiers source
- Compiler les quatre analyses en un seul rapport d'audit pour les parties prenantes avec un tableau de bord de préparation à la production et une séquence de remédiation recommandée
- Utiliser le mode Agent et les context mentions pour persister chaque rapport sur le disque, en gardant les analyses autonomes et efficaces en tokens
Continue avec les ressources suivantes :
- Suis Audit code and generate reports pour produire des artefacts SARIF et OSCAL lisibles par machine sur lesquels les outils de développement et les agents IA peuvent agir.
- Utilise les constatations comme base, puis suis Generate secure code with an actor-critic workflow pour remédier sans réintroduire les problèmes que cet audit a révélés.
- Lis Bob best practices pour des stratégies de prompting plus efficaces.
Générer des diagrammes d'architecture
Utilise IBM Bob pour analyser la base de code Galaxium Travels et générer des diagrammes de classes UML Mermaid, des diagrammes de séquence et des diagrammes de cas d'utilisation. Apprends à utiliser les mentions de contexte en mode Ask pour explorer le code et le mode Agent pour enregistrer les résultats dans ton dépôt.
Planifier et implémenter des fonctionnalités complexes
Utilise le mode Plan d'IBM Bob pour définir la portée, réviser et implémenter des fonctionnalités complexes avec un agent de codage IA. Apprends à écrire un prompt de planification, affiner le plan généré et exécuter l'implémentation en mode Agent.